---
read_when:
    - یک راهنمای گام‌به‌گام مناسب مبتدیان برای TUI می‌خواهید
    - به فهرست کامل قابلیت‌ها، فرمان‌ها و میانبرهای TUI نیاز دارید
summary: 'رابط کاربری ترمینال (TUI): به Gateway متصل شوید یا به‌صورت محلی در حالت تعبیه‌شده اجرا کنید'
title: TUI
x-i18n:
    generated_at: "2026-05-02T12:07:56Z"
    model: gpt-5.5
    provider: openai
    source_hash: 5c13268991bf11eece9984f21eb959e7a5fab7071be6dc3a47855b525bfe80d8
    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
# or
openclaw tui --local
```

نکات:

- `openclaw chat` و `openclaw terminal` نام‌های مستعار برای `openclaw tui --local` هستند.
- `--local` را نمی‌توان با `--url`، `--token` یا `--password` ترکیب کرد.
- حالت محلی مستقیما از runtime عامل تعبیه‌شده استفاده می‌کند. بیشتر ابزارهای محلی کار می‌کنند، اما قابلیت‌های فقط مخصوص Gateway در دسترس نیستند.
- `openclaw` و `openclaw crestodian` نیز از همین پوسته TUI استفاده می‌کنند و Crestodian به‌عنوان backend گفت‌وگوی راه‌اندازی و تعمیر محلی عمل می‌کند.

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

- سرآیند: URL اتصال، عامل فعلی، نشست فعلی.
- گزارش گفت‌وگو: پیام‌های کاربر، پاسخ‌های دستیار، اعلان‌های سیستم، کارت‌های ابزار.
- خط وضعیت: وضعیت اتصال/اجرا (در حال اتصال، در حال اجرا، در حال stream، بیکار، خطا).
- پانویس: وضعیت اتصال + عامل + نشست + مدل + think/fast/verbose/trace/reasoning + شمارش token + deliver.
- ورودی: ویرایشگر متن با تکمیل خودکار.

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

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

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

- پیام‌ها به Gateway ارسال می‌شوند؛ تحویل به providerها به‌طور پیش‌فرض خاموش است.
- تحویل را روشن کنید:
  - `/deliver on`
  - یا پنل تنظیمات
  - یا شروع با `openclaw tui --deliver`

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

- انتخاب‌گر مدل: مدل‌های در دسترس را فهرست می‌کند و override نشست را تنظیم می‌کند.
- انتخاب‌گر عامل: یک عامل متفاوت انتخاب کنید.
- انتخاب‌گر نشست: فقط نشست‌های عامل فعلی را نشان می‌دهد.
- تنظیمات: deliver، گسترش خروجی ابزار و نمایان بودن thinking را تغییر دهید.

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

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

## دستورهای Slash

هسته:

- `/help`
- `/status`
- `/agent <id>` (یا `/agents`)
- `/session <key>` (یا `/sessions`)
- `/model <provider/model>` (یا `/models`)

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

- `/think <off|minimal|low|medium|high>`
- `/fast <status|on|off>`
- `/verbose <on|full|off>`
- `/trace <on|off>`
- `/reasoning <on|off|stream>`
- `/usage <off|tokens|full>`
- `/elevated <on|off|ask|full>` (نام مستعار: `/elev`)
- `/activation <mention|always>`
- `/deliver <on|off>`

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

- `/new` یا `/reset` (بازنشانی نشست)
- `/abort` (لغو اجرای فعال)
- `/settings`
- `/exit`

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

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

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

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

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

## تعمیر پیکربندی‌ها از TUI محلی

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

اگر `openclaw config validate` از قبل ناموفق است، ابتدا با `openclaw configure` یا `openclaw doctor --fix` شروع کنید. `openclaw chat` محافظ پیکربندی نامعتبر را دور نمی‌زند.

چرخه معمول:

1. حالت محلی را شروع کنید:

```bash
openclaw chat
```

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

```text
Compare my gateway auth config with the docs and suggest the smallest fix.
```

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 یک migration یا تعمیر خودکار توصیه کرد، آن را بازبینی کنید و `!openclaw doctor --fix` را اجرا کنید.

نکته‌ها:

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

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

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

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

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

## تاریخچه + stream

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

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

- TUI با Gateway به‌صورت `mode: "tui"` ثبت می‌شود.
- اتصال‌های مجدد یک پیام سیستم نشان می‌دهند؛ فاصله‌های رویداد در گزارش آشکار می‌شوند.

## گزینه‌ها

- `--local`: اجرا در برابر runtime عامل تعبیه‌شده محلی
- `--url <url>`: URL WebSocket مربوط به Gateway (پیش‌فرض از پیکربندی یا `ws://127.0.0.1:<port>`)
- `--token <token>`: token مربوط به Gateway (در صورت نیاز)
- `--password <password>`: گذرواژه Gateway (در صورت نیاز)
- `--session <key>`: کلید نشست (پیش‌فرض: `main`، یا وقتی دامنه global است `global`)
- `--deliver`: تحویل پاسخ‌های دستیار به provider (به‌طور پیش‌فرض خاموش)
- `--thinking <level>`: override سطح thinking برای ارسال‌ها
- `--message <text>`: ارسال پیام اولیه پس از اتصال
- `--timeout-ms <ms>`: timeout عامل بر حسب ms (پیش‌فرض از `agents.defaults.timeoutSeconds`)
- `--history-limit <n>`: مدخل‌های تاریخچه برای بارگیری (پیش‌فرض `200`)

<Warning>
وقتی `--url` را تنظیم می‌کنید، TUI به پیکربندی یا credentialهای محیطی fallback نمی‌کند. `--token` یا `--password` را صریحا ارسال کنید. نبود credentialهای صریح یک خطاست. در حالت محلی، `--url`، `--token` یا `--password` را ارسال نکنید.
</Warning>

## عیب‌یابی

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

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

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

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

## مرتبط

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