---
read_when:
    - یک راهنمای گام‌به‌گام مناسب مبتدیان برای TUI می‌خواهید
    - به فهرست کامل قابلیت‌ها، دستورها و میانبرهای TUI نیاز دارید
summary: 'رابط کاربری ترمینال (TUI): به Gateway متصل شوید یا در حالت تعبیه‌شده به‌صورت محلی اجرا کنید'
title: TUI
x-i18n:
    generated_at: "2026-05-05T11:46:59Z"
    model: gpt-5.5
    provider: openai
    source_hash: 2b517ff434cc440aeffd8698df75d4d85c22a19e59b38a1f2383e58e1b4084ff
    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` ترکیب کرد.
- حالت محلی مستقیما از زمان اجرای جاسازی‌شده عامل استفاده می‌کند. بیشتر ابزارهای محلی کار می‌کنند، اما قابلیت‌های فقط مخصوص Gateway در دسترس نیستند.
- `openclaw` و `openclaw crestodian` نیز از همین پوسته TUI استفاده می‌کنند و Crestodian به‌عنوان پشتانه گفت‌وگوی راه‌اندازی و تعمیر محلی عمل می‌کند.

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

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

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

- عامل‌ها شناسه‌های یکتای 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 ارسال می‌شوند؛ تحویل به ارائه‌دهندگان به‌صورت پیش‌فرض خاموش است.
- تحویل را روشن کنید:
  - `/deliver on`
  - یا پنل تنظیمات
  - یا شروع با `openclaw tui --deliver`

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

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

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

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

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

هسته:

- `/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]` جریان احراز هویت/ورود ارائه‌دهنده را داخل TUI باز می‌کند.

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

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

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

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

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

اگر `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 یک مهاجرت یا تعمیر خودکار پیشنهاد می‌کند، آن را بازبینی کنید و `!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 آخرین تاریخچه را بارگذاری می‌کند (پیش‌فرض ۲۰۰ پیام).
- پاسخ‌های استریم‌شده تا نهایی شدن درجا به‌روزرسانی می‌شوند.
- TUI همچنین برای کارت‌های ابزار غنی‌تر به رویدادهای ابزار عامل گوش می‌دهد.

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

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

## گزینه‌ها

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

<Warning>
وقتی `--url` را تنظیم می‌کنید، TUI به پیکربندی یا اعتبارنامه‌های محیطی fallback نمی‌کند. `--token` یا `--password` را صراحتا ارسال کنید. نبود اعتبارنامه‌های صریح خطا است. در حالت محلی، `--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) — بررسی‌های هدایت‌شده تعمیر و مهاجرت
- [مرجع CLI](/fa/cli) — مرجع کامل دستورهای CLI