---
read_when:
    - شما یک راهنمای گام‌به‌گام و مناسب برای مبتدیان دربارهٔ TUI می‌خواهید
    - به فهرست کامل قابلیت‌ها، فرمان‌ها و میان‌برهای TUI نیاز دارید
summary: 'رابط کاربری ترمینال (TUI): اتصال به Gateway یا اجرای محلی در حالت تعبیه‌شده'
title: TUI
x-i18n:
    generated_at: "2026-07-12T11:01:58Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: d7181ea88643a129532f698908fd3dd3d93078b7e33b0ab1166dcfca2ecc2abd
    source_path: web/tui.md
    workflow: 16
---

## شروع سریع

### حالت Gateway

1. Gateway را راه‌اندازی کنید.

```bash
openclaw gateway
```

2. TUI را باز کنید.

```bash
openclaw tui
```

3. پیامی تایپ کنید و Enter را فشار دهید.

Gateway راه‌دور:

```bash
openclaw tui --url ws://<host>:<port> --token <gateway-token>
```

اگر Gateway شما از احراز هویت با گذرواژه استفاده می‌کند، از `--password` استفاده کنید.

### حالت محلی

TUI را بدون Gateway اجرا کنید:

```bash
openclaw chat
# یا
openclaw tui --local
```

- `openclaw chat` و `openclaw terminal` نام‌های مستعار `openclaw tui --local` هستند.
- `--local` را نمی‌توان با `--url`، `--token` یا `--password` ترکیب کرد.
- حالت محلی مستقیماً از محیط اجرای عامل تعبیه‌شده استفاده می‌کند. بیشتر ابزارهای محلی کار می‌کنند، اما قابلیت‌های مختص Gateway در دسترس نیستند.
- دستور سادهٔ `openclaw` (بدون زیردستور) مقصد را به‌طور خودکار انتخاب می‌کند: نصب پیکربندی‌نشده فرایند آغازین استنتاج را اجرا می‌کند؛ پیکربندی نامعتبر راهنمای کلاسیک Doctor را باز می‌کند؛ یک Gateway پیکربندی‌شده و در دسترس، این پوستهٔ TUI را در حالت Gateway باز می‌کند؛ در غیر این صورت، یک مدل محلی پیکربندی‌شده آن را در حالت محلی باز می‌کند.

## آنچه می‌بینید

- سرصفحه: نشانی اتصال، عامل فعلی، نشست فعلی.
- گزارش گفت‌وگو: پیام‌های کاربر، پاسخ‌های دستیار، اعلان‌های سیستم و کارت‌های ابزار.
- خط وضعیت: وضعیت اتصال/اجرا (در حال اتصال، در حال اجرا، در حال پخش جریانی، بیکار، خطا).
- پابرگ: عامل + نشست + مدل + وضعیت هدف + تفکر/سریع/پرحرف/ردیابی/استدلال + شمار توکن‌ها + تحویل. وقتی `tui.footer.showRemoteHost` فعال باشد، اتصال‌های Gateway راه‌دور میزبان اتصال را نیز نشان می‌دهند.
- ورودی: ویرایشگر متن با تکمیل خودکار.

## مدل ذهنی: عامل‌ها + نشست‌ها

- عامل‌ها شناسه‌های یکتایی هستند (برای مثال `main` و `research`). Gateway فهرست آن‌ها را ارائه می‌کند.
- نشست‌ها به عامل فعلی تعلق دارند.
- کلیدهای نشست به‌شکل `agent:<agentId>:<sessionKey>` ذخیره می‌شوند.
  - اگر `/session main` را وارد کنید، TUI آن را به `agent:<currentAgent>:main` گسترش می‌دهد.
  - اگر `/session agent:other:main` را وارد کنید، صریحاً به نشست آن عامل جابه‌جا می‌شوید.
- دامنهٔ نشست:
  - `per-sender` (پیش‌فرض): هر عامل نشست‌های متعددی دارد.
  - `global`: ‏TUI همیشه از نشست `global` استفاده می‌کند (ممکن است انتخاب‌گر خالی باشد).
- عامل و نشست فعلی همیشه در پابرگ دیده می‌شوند.
- برای نمایش میزبان Gateway در اتصال‌های غیرمحلی مبتنی بر URL، با دستور زیر آن را فعال کنید:

  ```bash
  openclaw config set tui.footer.showRemoteHost true
  ```

  مقدار پیش‌فرض `false` است. اتصال‌های local loopback و محلی تعبیه‌شده هرگز برچسب میزبان را نشان نمی‌دهند.

- اگر نشست یک [هدف](/fa/tools/goal) داشته باشد، پابرگ وضعیت فشردهٔ آن را نشان می‌دهد:
  `در حال پیگیری هدف`، `هدف متوقف شده است (/goal resume)`، `هدف مسدود شده است (/goal resume)` یا `هدف محقق شده است`.
- وقتی TUI حالت Gateway بدون `--session` آغاز شود، اگر آخرین نشست انتخاب‌شده برای همان Gateway، عامل و دامنهٔ نشست همچنان وجود داشته باشد، آن را از سر می‌گیرد. استفاده از `--session`، ‏`/session`، ‏`/new` یا `/reset` همچنان صریح است.

## ارسال + تحویل

- پیام‌ها همیشه به Gateway (یا در حالت محلی به محیط اجرای تعبیه‌شده) می‌روند؛ تحویل پاسخ دستیار به یک ارائه‌دهندهٔ گفت‌وگو مرحله‌ای جداگانه است که به‌طور پیش‌فرض غیرفعال است.
- TUI مانند WebChat یک سطح مبدأ داخلی است، نه یک کانال خروجی عمومی. چارچوب‌هایی که برای پاسخ‌های قابل‌مشاهده به `tools.message` نیاز دارند، می‌توانند نوبت فعال TUI را با `message.send` بدون مقصد پاسخ دهند؛ تحویل صریح به ارائه‌دهنده همچنان از کانال‌های معمول پیکربندی‌شده استفاده می‌کند و هرگز به `lastChannel` بازنمی‌گردد.
- وضعیت تحویل هنگام راه‌اندازی برای کل نشست TUI ثابت می‌شود: برای فعال‌کردن آن، با `openclaw tui --deliver` شروع کنید. هیچ دستور اسلش `/deliver` یا کلید Settings برای تغییر آن در میانهٔ نشست وجود ندارد؛ برای تغییرش TUI را دوباره راه‌اندازی کنید.

## انتخاب‌گرها + لایه‌های رویی

- انتخاب‌گر مدل: مدل‌های موجود را فهرست می‌کند و مقدار بازنویسی مدل نشست را تنظیم می‌کند.
- انتخاب‌گر عامل: عامل دیگری را انتخاب می‌کند.
- انتخاب‌گر نشست: حداکثر ۵۰ نشست عامل فعلی را که در ۷ روز گذشته به‌روزرسانی شده‌اند نشان می‌دهد. برای رفتن به یک نشست قدیمی شناخته‌شده، از `/session <key>` استفاده کنید.
- تنظیمات (`/settings`): بازشدن خروجی ابزار و نمایش تفکر را تغییر می‌دهد. این پنل تحویل را کنترل نمی‌کند.

## میان‌برهای صفحه‌کلید

- Enter: ارسال پیام
- Esc: لغو اجرای فعال
- Ctrl+C: پاک‌کردن ورودی (برای خروج دو بار فشار دهید)
- Ctrl+D: خروج
- Ctrl+L: انتخاب‌گر مدل
- Ctrl+G: انتخاب‌گر عامل
- Ctrl+P: انتخاب‌گر نشست
- Ctrl+O: تغییر وضعیت بازشدن خروجی ابزار
- Ctrl+T: تغییر وضعیت نمایش تفکر (تاریخچه را دوباره بارگذاری می‌کند)

## دستورهای اسلش

هسته:

- `/help`
- `/status` (به Gateway ارسال می‌شود؛ خلاصهٔ نشست/مدل را نشان می‌دهد)
- `/gateway-status` (نام مستعار `/gwstatus`؛ وضعیت اتصال Gateway را مستقیماً نشان می‌دهد)
- `/agent <id>` (یا `/agents`)
- `/session <key>` (یا `/sessions`)
- `/model <provider/model>` (یا `/models`)

کنترل‌های نشست:

- `/think <off|minimal|low|medium|high>` (بسته به مدل، سطوح بالاتر ممکن است گزینه‌هایی مانند `xhigh`/`max` را اضافه کنند)
- `/fast <status|auto|on|off>`
- `/verbose <on|full|off>`
- `/trace <on|off>`
- `/reasoning <on|off|stream>`
- `/usage <off|tokens|full|reset>` (گزینه‌های `reset`/`inherit`/`clear`/`default` مقدار بازنویسی نشست را پاک می‌کنند)
- `/goal [status] | /goal start <objective> | /goal edit <objective> | /goal pause|resume|complete|block|clear`
- `/elevated <on|off|ask|full>` (نام مستعار: `/elev`)
- `/activation <mention|always>`

چرخهٔ عمر نشست:

- `/new` (یک نشست تازه و مجزا با کلیدی جدید ایجاد می‌کند؛ بر دیگر کارخواه‌های TUI در نشست قدیمی اثری ندارد)
- `/reset` (کلید نشست فعلی را در جای خود بازنشانی می‌کند)
- `/abort` (اجرای فعال را لغو می‌کند)
- `/settings`
- `/exit` (یا `/quit`)

فقط حالت محلی:

- `/auth [provider]` فرایند احراز هویت/ورود ارائه‌دهنده را درون TUI باز می‌کند.

Crestodian:

- `/crestodian [request]` از TUI عادی عامل به گفت‌وگوی راه‌اندازی/تعمیر [Crestodian](#crestodian-setup-and-repair-helper) بازمی‌گردد و در صورت ارائه، یک درخواست را نیز منتقل می‌کند.

سایر دستورهای اسلش Gateway (برای مثال `/context`) به Gateway ارسال می‌شوند و به‌صورت خروجی سیستم نمایش داده می‌شوند. [دستورهای اسلش](/fa/tools/slash-commands) را ببینید.

## دستورهای پوستهٔ محلی

- برای اجرای یک دستور پوستهٔ محلی روی میزبان TUI، ابتدای خط `!` بگذارید.
- TUI در هر نشست یک‌بار برای اجازهٔ اجرای محلی سؤال می‌کند؛ ردکردن درخواست، `!` را در آن نشست غیرفعال نگه می‌دارد.
- دستورها در یک پوستهٔ تازه و غیرتعاملی در پوشهٔ کاری TUI اجرا می‌شوند (`cd`/محیط ماندگار نیست).
- دستورهای پوستهٔ محلی متغیر `OPENCLAW_SHELL=tui-local` را در محیط خود دریافت می‌کنند.
- یک `!` تنها به‌صورت پیام عادی ارسال می‌شود؛ فاصله‌های ابتدایی اجرای محلی را فعال نمی‌کنند.

## دستیار راه‌اندازی و تعمیر Crestodian

Crestodian دستیار راه‌اندازی/تعمیر سطح صفر است که پس از موفقیت مدل پیش‌فرض پیکربندی‌شده در یک بررسی زندهٔ استنتاج، با `openclaw crestodian` ارائه می‌شود. اگر استنتاج در دسترس نباشد، اجرای تعاملی به فرایند آغازین استنتاج بازمی‌گردد و خودکارسازی با راهنمای تعمیر شکست می‌خورد. این دستیار در همان پوستهٔ محلی TUI مربوط به `openclaw tui --local` اجرا می‌شود و یک عامل هوش مصنوعی پشتیبان آن است که به عملیات نوع‌دار و نیازمند تأیید Crestodian محدود شده است:

```bash
openclaw crestodian                       # شروع تعاملی
openclaw crestodian -m "status"           # اجرای یک درخواست و خروج
openclaw crestodian -m "set default model openai/gpt-5.2" --yes   # اعمال نوشتن پیکربندی
```

- نوشتن ماندگار پیکربندی نیازمند تأیید است: یا به‌صورت تعاملی تأیید کنید یا `--yes` را وارد کنید.
- `--json` به‌جای آغاز گفت‌وگو، نمای کلی راه‌اندازی را به‌صورت JSON چاپ می‌کند.
- درون Crestodian، درخواست `open-tui` (برای مثال درخواست گفت‌وگو با یک عامل عادی) از Crestodian خارج می‌شود و TUI عادی عامل را باز می‌کند؛ برای بازگشت از آنجا از `/crestodian` استفاده کنید.

وقتی پیکربندی فعلی از قبل معتبر است و می‌خواهید عامل تعبیه‌شده آن را روی همان دستگاه بررسی کند، با مستندات مقایسه کند و بدون وابستگی به Gateway در حال اجرا به رفع ناهم‌خوانی کمک کند، از حالت محلی استفاده کنید.

اگر `openclaw config validate` از قبل شکست می‌خورد، ابتدا با `openclaw configure` یا `openclaw doctor --fix` شروع کنید؛ `openclaw chat` نیز برای آغاز به یک پیکربندی قابل‌بارگذاری نیاز دارد.

چرخهٔ معمول:

1. حالت محلی را آغاز کنید:

```bash
openclaw chat
```

2. از عامل بخواهید مورد دلخواهتان را بررسی کند، برای مثال:

```text
پیکربندی احراز هویت Gateway من را با مستندات مقایسه کن و کوچک‌ترین اصلاح را پیشنهاد بده.
```

3. برای شواهد و اعتبارسنجی دقیق از دستورهای پوستهٔ محلی استفاده کنید:

```text
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
```

4. تغییرات محدود را با `openclaw config set` یا `openclaw configure` اعمال کنید، سپس `!openclaw config validate` را دوباره اجرا کنید.
5. اگر Doctor یک مهاجرت یا تعمیر خودکار را توصیه کرد، آن را بررسی و `!openclaw doctor --fix` را اجرا کنید.

نکات:

- به‌جای ویرایش دستی `openclaw.json`، ‏`openclaw config set` یا `openclaw configure` را ترجیح دهید.
- `openclaw docs "<query>"` نمایهٔ زندهٔ مستندات را از همان دستگاه جست‌وجو می‌کند.
- وقتی خطاهای ساختاریافتهٔ شِما و SecretRef/قابلیت حل‌شدن را می‌خواهید، `openclaw config validate --json` مفید است.

## خروجی ابزار

- فراخوانی‌های ابزار به‌صورت کارت‌هایی شامل آرگومان‌ها + نتایج نمایش داده می‌شوند.
- Ctrl+O بین نماهای جمع‌شده/بازشده جابه‌جا می‌شود.
- هنگام اجرای ابزارها، به‌روزرسانی‌های جزئی به‌صورت جریانی در همان کارت نمایش داده می‌شوند.

## رنگ‌های پایانه

- TUI متن اصلی دستیار را با رنگ پیش‌زمینهٔ پیش‌فرض پایانه نگه می‌دارد تا هم در پایانه‌های تیره و هم روشن خوانا بماند.
- اگر پایانهٔ شما پس‌زمینهٔ روشن دارد و تشخیص خودکار اشتباه است، پیش از اجرای `openclaw tui` مقدار `OPENCLAW_THEME=light` را تنظیم کنید.
- برای اجبار پالت تیرهٔ اصلی، به‌جای آن `OPENCLAW_THEME=dark` را تنظیم کنید.

## تاریخچه + پخش جریانی

- هنگام اتصال، TUI جدیدترین تاریخچه را بارگذاری می‌کند (پیش‌فرض ۲۰۰ پیام).
- پاسخ‌های جریانی تا نهایی‌شدن در جای خود به‌روزرسانی می‌شوند.
- TUI همچنین برای نمایش کارت‌های غنی‌تر ابزار، به رویدادهای ابزار عامل گوش می‌دهد.

## جزئیات اتصال

- TUI با شناسهٔ کارخواه `openclaw-tui` در حالت کلی کارخواه `ui` متصل می‌شود (همان حالتی که Control UI و WebChat برای سیاست Gateway استفاده می‌کنند).
- اتصال‌های مجدد یک پیام سیستمی نشان می‌دهند؛ وقفه‌های رویداد در گزارش نمایان می‌شوند.

## گزینه‌ها

- `--local`: اجرا با محیط اجرای عامل تعبیه‌شدهٔ محلی
- `--url <url>`: نشانی WebSocket مربوط به Gateway (به‌طور پیش‌فرض `gateway.remote.url` از پیکربندی، یا `ws://127.0.0.1:<port>` روی local loopback)
- `--token <token>`: توکن Gateway (در صورت نیاز)
- `--password <password>`: گذرواژهٔ Gateway (در صورت نیاز)
- `--tls-fingerprint <sha256>`: اثرانگشت مورد انتظار گواهی TLS برای یک Gateway با `wss://` سنجاق‌شده
- `--session <key>`: کلید نشست (پیش‌فرض: `main`، یا وقتی دامنه سراسری است `global`)
- `--deliver`: تحویل پاسخ‌های دستیار به ارائه‌دهنده (پیش‌فرض غیرفعال)
- `--thinking <level>`: بازنویسی سطح تفکر برای ارسال‌ها
- `--message <text>`: ارسال یک پیام اولیه پس از اتصال
- `--timeout-ms <ms>`: مهلت زمانی عامل بر حسب میلی‌ثانیه (مقدار پیش‌فرض `agents.defaults.timeoutSeconds`)
- `--history-limit <n>`: تعداد ورودی‌های تاریخچه برای بارگذاری (پیش‌فرض `200`)

<Warning>
وقتی `--url` را تنظیم می‌کنید، TUI به اعتبارنامه‌های پیکربندی یا محیط بازنمی‌گردد. `--token` یا `--password` را صریحاً وارد کنید و اگر مقصد از گواهی سنجاق‌شده استفاده می‌کند، `--tls-fingerprint` را نیز اضافه کنید. نبود اعتبارنامه‌های صریح خطا محسوب می‌شود. در حالت محلی، `--url`، ‏`--token`، ‏`--password` یا `--tls-fingerprint` را وارد نکنید.
</Warning>

## عیب‌یابی

نبود خروجی پس از ارسال پیام:

- برای تأیید اتصال Gateway و وضعیت بیکار/مشغول آن، `/status` را در TUI اجرا کنید.
- گزارش‌های Gateway را بررسی کنید: `openclaw logs --follow`.
- مطمئن شوید عامل قابل اجرا است: `openclaw status` و `openclaw models status`.
- اگر انتظار دارید پیام‌ها در یک کانال گفت‌وگو ظاهر شوند، مطمئن شوید TUI با `--deliver` آغاز شده است (فعال‌کردن آن بعداً بدون راه‌اندازی مجدد ممکن نیست).

## عیب‌یابی اتصال

- `disconnected`: مطمئن شوید Gateway در حال اجرا است و `--url/--token/--password` شما درست هستند.
- نبود عامل در انتخاب‌گر: `openclaw agents list` و پیکربندی مسیریابی خود را بررسی کنید.
- انتخاب‌گر نشست خالی: ممکن است در دامنهٔ سراسری باشید یا هنوز نشستی نداشته باشید.

## مرتبط

- [Control UI](/fa/web/control-ui) — رابط کنترل مبتنی بر وب
- [پیکربندی](/fa/cli/config) — بررسی، اعتبارسنجی و ویرایش `openclaw.json`
- [Doctor](/fa/cli/doctor) — بررسی‌های هدایت‌شدهٔ تعمیر و مهاجرت
- [مرجع CLI](/fa/cli) — مرجع کامل دستورهای CLI