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

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

- سربرگ: نشانی اتصال، عامل فعلی، نشست فعلی.
- گزارش گفت‌وگو: پیام‌های کاربر، پاسخ‌های دستیار، اعلان‌های سیستم، کارت‌های ابزار.
- خط وضعیت: وضعیت اتصال/اجرا (در حال اتصال، در حال اجرا، در حال پخش، بیکار، خطا).
- پابرگ: عامل + نشست + مدل + وضعیت هدف + think/fast/verbose/trace/reasoning + شمار توکن‌ها + تحویل. وقتی `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` است. اتصال‌های loopback و اتصال‌های محلی تعبیه‌شده هرگز برچسب میزبان را نشان نمی‌دهند.

- اگر نشست یک [هدف](/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` یا کلیدی در تنظیمات برای تغییر آن در میانه نشست وجود ندارد؛ برای تغییر آن، TUI را دوباره راه‌اندازی کنید.

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

- انتخاب‌گر مدل: مدل‌های موجود را فهرست می‌کند و جایگزین نشست را تنظیم می‌کند.
- انتخاب‌گر عامل: عامل دیگری را انتخاب می‌کند.
- انتخاب‌گر نشست: حداکثر 50 نشست عامل فعلی را که در 7 روز گذشته به‌روزرسانی شده‌اند نشان می‌دهد. برای رفتن به یک نشست قدیمیِ شناخته‌شده، از `/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 باز می‌کند.

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>`: مهلت زمانی عامل بر حسب میلی‌ثانیه (پیش‌فرض: `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