---
read_when:
    - تريد شرحًا تفصيليًا مناسبًا للمبتدئين عن TUI
    - تحتاج إلى القائمة الكاملة لميزات TUI وأوامره واختصاراته.
summary: 'واجهة الطرفية (TUI): الاتصال بـ Gateway أو التشغيل محليًا في الوضع المضمّن'
title: TUI
x-i18n:
    generated_at: "2026-06-27T18:48:48Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: ed02875ea5dcb8cef987d16fe11701eba11160525caf9791f74c610b1b6bec6e
    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>
```

استخدم `--password` إذا كان Gateway لديك يستخدم مصادقة كلمة المرور.

### الوضع المحلي

شغّل 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 + أعداد الرموز + التسليم. عند تفعيل `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
  ```

  لا تعرض اتصالات الاسترجاع والاتصالات المحلية المضمّنة تسمية مضيف أبدًا.

- إذا كانت للجلسة [هدف](/ar/tools/goal)، يعرض التذييل حالته المضغوطة
  مثل `Pursuing goal` أو `Goal paused (/goal resume)` أو
  `Goal achieved`.
- عند البدء دون `--session`، يستأنف TUI في وضع Gateway آخر جلسة محددة لنفس Gateway والوكيل ونطاق الجلسة إذا كانت تلك الجلسة لا تزال موجودة. يظل تمرير `--session` أو `/session` أو `/new` أو `/reset` صريحًا.

## الإرسال + التسليم

- تُرسل الرسائل إلى Gateway؛ التسليم إلى المزوّدين متوقف افتراضيًا.
- TUI سطح مصدر داخلي مثل WebChat، وليس قناة صادرة عامة. يمكن لحزم الاختبار التي تتطلب `tools.message` للردود المرئية تلبية دورة TUI النشطة باستخدام `message.send` بلا هدف؛ لا يزال التسليم الصريح إلى المزوّد يستخدم القنوات العادية المضبوطة ولا يعود أبدًا إلى `lastChannel`.
- تفعيل التسليم:
  - `/deliver on`
  - أو لوحة الإعدادات
  - أو ابدأ باستخدام `openclaw tui --deliver`

## المنتقيات + الطبقات

- منتقي النموذج: اسرد النماذج المتاحة واضبط تجاوز الجلسة.
- منتقي الوكيل: اختر وكيلًا مختلفًا.
- منتقي الجلسة: يعرض حتى 50 جلسة للوكيل الحالي حُدّثت خلال آخر 7 أيام. استخدم `/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|reset>` (`reset`/`inherit`/`clear`/`default` يمسح تجاوز الجلسة)
- `/goal [status] | /goal start <objective> | /goal pause|resume|complete|block|clear`
- `/elevated <on|off|ask|full>` (اسم بديل: `/elev`)
- `/activation <mention|always>`
- `/deliver <on|off>`

دورة حياة الجلسة:

- `/new` أو `/reset` (إعادة تعيين الجلسة)
- `/abort` (إجهاض التشغيل النشط)
- `/settings`
- `/exit`

الوضع المحلي فقط:

- `/auth [provider]` يفتح تدفق مصادقة/تسجيل دخول المزوّد داخل TUI.

تُمرَّر أوامر Gateway الأخرى ذات الشرطة المائلة (مثل `/context`) إلى Gateway وتُعرض كمخرجات نظام. راجع [أوامر الشرطة المائلة](/ar/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>"` في فهرس الوثائق الحي من الجهاز نفسه.
- يكون `openclaw config validate --json` مفيدًا عندما تريد أخطاء مخطط منظمة وأخطاء SecretRef/قابلية الحل.

## مخرجات الأدوات

- تظهر استدعاءات الأدوات كبطاقات مع الوسائط + النتائج.
- يبدّل Ctrl+O بين العروض المطوية/الموسّعة.
- أثناء تشغيل الأدوات، تُبث التحديثات الجزئية إلى البطاقة نفسها.

## ألوان الطرفية

- يحافظ TUI على نص متن المساعد بلون المقدمة الافتراضي في الطرفية لديك حتى تبقى الطرفيات الداكنة والفاتحة مقروءة.
- إذا كانت طرفيتك تستخدم خلفية فاتحة وكان الاكتشاف التلقائي خاطئًا، فاضبط `OPENCLAW_THEME=light` قبل تشغيل `openclaw tui`.
- لفرض اللوحة الداكنة الأصلية بدلًا من ذلك، اضبط `OPENCLAW_THEME=dark`.

## السجل + البث

- عند الاتصال، يحمّل TUI أحدث سجل (الافتراضي 200 رسالة).
- تُحدَّث الردود المتدفقة في مكانها حتى تكتمل.
- يستمع 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` عندما يكون النطاق عامًا)
- `--deliver`: تسليم ردود المساعد إلى المزوّد (متوقف افتراضيًا)
- `--thinking <level>`: تجاوز مستوى التفكير للإرسال
- `--message <text>`: إرسال رسالة أولية بعد الاتصال
- `--timeout-ms <ms>`: مهلة الوكيل بالمللي ثانية (تفترض افتراضيًا `agents.defaults.timeoutSeconds`)
- `--history-limit <n>`: إدخالات السجل المراد تحميلها (الافتراضي `200`)

<Warning>
عند ضبط `--url`، لا يعود TUI إلى بيانات اعتماد الإعدادات أو البيئة. مرّر `--token` أو `--password` صراحةً. غياب بيانات الاعتماد الصريحة خطأ. في الوضع المحلي، لا تمرر `--url` أو `--token` أو `--password`.
</Warning>

## استكشاف الأخطاء وإصلاحها

لا توجد مخرجات بعد إرسال رسالة:

- شغّل `/status` في TUI للتأكد من أن Gateway متصل وخامل/مشغول.
- تحقق من سجلات Gateway: `openclaw logs --follow`.
- تأكد من أن الوكيل قادر على التشغيل: `openclaw status` و`openclaw models status`.
- إذا كنت تتوقع رسائل في قناة محادثة، ففعّل التسليم (`/deliver on` أو `--deliver`).

## استكشاف أخطاء الاتصال وإصلاحها

- `disconnected`: تأكد من أن Gateway قيد التشغيل وأن `--url/--token/--password` صحيحة.
- لا يوجد وكلاء في المنتقي: تحقق من `openclaw agents list` وإعدادات التوجيه لديك.
- منتقي الجلسات فارغ: قد تكون في النطاق العام أو ليس لديك جلسات بعد.

## ذات صلة

- [واجهة التحكم](/ar/web/control-ui) — واجهة تحكم قائمة على الويب
- [الإعدادات](/ar/cli/config) — فحص `openclaw.json` والتحقق منه وتحريره
- [Doctor](/ar/cli/doctor) — فحوصات إصلاح وترحيل موجّهة
- [مرجع CLI](/ar/cli) — المرجع الكامل لأوامر CLI