---
read_when:
    - راهنمای گام‌به‌گام و مناسب مبتدیان برای TUI می‌خواهید
    - به فهرست کامل قابلیت‌ها، فرمان‌ها و میان‌برهای TUI نیاز دارید
summary: 'رابط کاربری ترمینال (TUI): اتصال به Gateway یا اجرای محلی در حالت تعبیه‌شده'
title: TUI
x-i18n:
    generated_at: "2026-07-27T16:01:01Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: dc4dc5e2a408b5097b3615283b5a4590e8b55bccb15c26d8e38ab2c84b902f4a
    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 باز می‌کند؛ در غیر این صورت، یک مدل محلی پیکربندی‌شده آن را در حالت محلی باز می‌کند.

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

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

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

- عامل‌ها نامک‌های یکتا هستند (برای مثال `main`، `research`). Gateway فهرست را ارائه می‌کند.
- نشست‌ها به عامل فعلی تعلق دارند.
- کلیدهای نشست به‌شکل `agent:<agentId>:<sessionKey>` ذخیره می‌شوند.
  - اگر `/session main` را تایپ کنید، TUI آن را به `agent:<currentAgent>:main` گسترش می‌دهد.
  - اگر `/session agent:other:main` را تایپ کنید، صراحتاً به نشست آن عامل جابه‌جا می‌شوید.
- دامنهٔ نشست:
  - `per-sender` (پیش‌فرض): هر عامل نشست‌های متعددی دارد.
  - `global`: TUI همیشه از نشست `global` استفاده می‌کند (ممکن است انتخاب‌گر خالی باشد).
- عامل و نشست فعلی همیشه در پاورقی قابل مشاهده‌اند.
- اگر نشست یک [هدف](/fa/tools/goal) داشته باشد، پاورقی وضعیت فشردهٔ آن را نشان می‌دهد:
  `Pursuing goal`، `Goal paused (/goal resume)`، `Goal blocked (/goal resume)` یا `Goal achieved`.
- وقتی TUI حالت Gateway بدون `--session` آغاز شود، اگر آخرین نشست انتخاب‌شده برای همان Gateway، عامل و دامنهٔ نشست همچنان وجود داشته باشد، آن را از سر می‌گیرد. ارسال `--session`، `/session`، `/new` یا `/reset` همچنان انتخابی صریح است.

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

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

## انتخاب‌گرها + پوشش‌ها

- انتخاب‌گر مدل: مدل‌های موجود را فهرست می‌کند و بازنویسی نشست را تنظیم می‌کند.
- انتخاب‌گر عامل: عامل دیگری را انتخاب کنید.
- انتخاب‌گر نشست: حداکثر 50 نشست عامل فعلی را که در 7 روز گذشته به‌روزرسانی شده‌اند نشان می‌دهد. برای رفتن به یک نشست قدیمی و شناخته‌شده از `/session <key>` استفاده کنید.
- Settings ‏(`/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>`
- `/queue <steer|followup|collect|interrupt> [debounce:<duration>] [cap:<n>] [drop:<summarize|old|new>]`
- `/queue default` (یا `/queue reset`) بازنویسی نشست را پاک می‌کند

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

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

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

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

حالت محلی همان حالت‌های صف را در زمان‌اجرای تعبیه‌شده پیاده‌سازی می‌کند. یک
درخواست در میانهٔ اجرا از سیاست `/queue` نشست پیروی می‌کند: `steer` زمانی تزریق می‌شود که
زمان‌اجرا بتواند آن را بپذیرد، `followup` برای نوبتی جداگانه منتظر می‌ماند، `collect` درخواست‌های
در انتظار را ترکیب می‌کند و `interrupt` پیش از شروع درخواست جدید، اجرای فعلی را
متوقف می‌کند. `/steer <message>` صریح فقط مختص Gateway است؛ در حالت محلی از `/queue steer` به‌همراه یک
پیام عادی استفاده کنید.

OpenClaw:

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

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

## فرمان‌های پوستهٔ محلی

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

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

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

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

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

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

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

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

## رنگ‌های ترمینال

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

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

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

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

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

## گزینه‌ها

- `--local`: اجرا در برابر زمان‌اجرای محلی و تعبیه‌شده عامل
- `--url <url>`: نشانی WebSocket مربوط به Gateway (پیش‌فرض: `gateway.remote.url` از پیکربندی، یا `ws://127.0.0.1:<port>` در 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>`: مهلت زمانی عامل برحسب ms (پیش‌فرض: `agents.defaults.timeoutSeconds`)
- `--history-limit <n>`: تعداد ورودی‌های تاریخچه برای بارگذاری (پیش‌فرض: `200`)

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

## عیب‌یابی

پس از ارسال پیام هیچ خروجی‌ای نمایش داده نمی‌شود:

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

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

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

## مرتبط

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