---
read_when:
    - عند إعداد تكاملات IDE المستندة إلى ACP
    - عند تصحيح توجيه جلسات ACP إلى البوابة
summary: تشغيل جسر ACP لتكاملات IDE
title: acp
x-i18n:
    generated_at: "2026-04-05T12:38:02Z"
    model: gpt-5.4
    provider: openai
    source_hash: 2461b181e4a97dd84580581e9436ca1947a224decce8044132dbcf7fb2b7502c
    source_path: cli/acp.md
    workflow: 15
---

# acp

شغّل جسر [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) الذي يتحدث إلى بوابة OpenClaw.

يتحدث هذا الأمر بروتوكول ACP عبر stdio لبيئات IDE ويعيد توجيه المطالبات إلى البوابة
عبر WebSocket. ويحافظ على ربط جلسات ACP بمفاتيح جلسات البوابة.

إن `openclaw acp` هو جسر ACP مدعوم بالبوابة، وليس بيئة تشغيل تحرير
أصلية كاملة لـ ACP. وهو يركز على توجيه الجلسات، وتسليم المطالبات، وتحديثات
البث الأساسية.

إذا كنت تريد أن يتحدث عميل MCP خارجي مباشرةً إلى محادثات قنوات OpenClaw
بدلًا من استضافة جلسة harness لـ ACP، فاستخدم
[`openclaw mcp serve`](/cli/mcp) بدلًا من ذلك.

## ما الذي لا يمثله هذا

غالبًا ما يختلط هذا الصفحة بجلسات harness الخاصة بـ ACP.

يعني `openclaw acp` ما يلي:

- يعمل OpenClaw كخادم ACP
- يتصل IDE أو عميل ACP بـ OpenClaw
- يعيد OpenClaw توجيه هذا العمل إلى جلسة في البوابة

وهذا يختلف عن [ACP Agents](/tools/acp-agents)، حيث يشغّل OpenClaw
حزامًا خارجيًا مثل Codex أو Claude Code من خلال `acpx`.

قاعدة سريعة:

- إذا كان المحرر/العميل يريد التحدث عبر ACP إلى OpenClaw: استخدم `openclaw acp`
- إذا كان ينبغي على OpenClaw تشغيل Codex/Claude/Gemini كـ ACP harness: استخدم `/acp spawn` و[ACP Agents](/tools/acp-agents)

## مصفوفة التوافق

| مجال ACP                                                              | الحالة      | ملاحظات                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialize`, `newSession`, `prompt`, `cancel`                        | مُنفّذ | تدفق الجسر الأساسي عبر stdio إلى Gateway chat/send + الإلغاء.                                                                                                                                                                                     |
| `listSessions`, أوامر slash                                           | مُنفّذ | يعمل سرد الجلسات مقابل حالة جلسات البوابة؛ ويتم الإعلان عن الأوامر عبر `available_commands_update`.                                                                                                                                              |
| `loadSession`                                                         | جزئي | يعيد ربط جلسة ACP بمفتاح جلسة في البوابة ويعيد تشغيل سجل النصوص المخزن للمستخدم/المساعد. ولا يُعاد بناء سجل الأدوات/النظام بعد.                                                                                                                |
| محتوى المطالبة (`text`, و`resource` المضمّن، والصور)                 | جزئي | يتم تسطيح النص/الموارد إلى دخل الدردشة؛ وتتحول الصور إلى مرفقات في البوابة.                                                                                                                                                                      |
| أوضاع الجلسات                                                         | جزئي | `session/set_mode` مدعوم، ويعرض الجسر عناصر تحكم أولية مدعومة بالبوابة لمستوى التفكير، وإسهاب الأدوات، والاستدلال، وتفاصيل الاستخدام، والإجراءات المرتفعة. وما تزال أسطح الأوضاع/الإعدادات الأوسع الأصلية لـ ACP خارج النطاق.                 |
| معلومات الجلسة وتحديثات الاستخدام                                    | جزئي | يصدر الجسر إشعارات `session_info_update` و`usage_update` بأفضل جهد من لقطات جلسات البوابة المخزنة مؤقتًا. والاستخدام تقريبي ولا يُرسل إلا عندما تكون مجاميع الرموز في البوابة معلّمة على أنها حديثة.                                          |
| بث الأدوات                                                            | جزئي | تتضمن أحداث `tool_call` / `tool_call_update` الإدخال/الإخراج الخام، ومحتوى النص، ومواقع الملفات بأفضل جهد عندما تكشفها وسائط/نتائج أدوات البوابة. ولا تزال الطرفيات المضمّنة ومخرجات الفروقات الأصلية الأغنى غير مكشوفة.                        |
| خوادم MCP لكل جلسة (`mcpServers`)                                    | غير مدعوم | يرفض وضع الجسر طلبات خوادم MCP لكل جلسة. قم بإعداد MCP على بوابة OpenClaw أو الوكيل بدلًا من ذلك.                                                                                                                                               |
| أساليب نظام ملفات العميل (`fs/read_text_file`, `fs/write_text_file`) | غير مدعوم | لا يستدعي الجسر أساليب نظام ملفات عميل ACP.                                                                                                                                                                                                       |
| أساليب طرفية العميل (`terminal/*`)                                   | غير مدعوم | لا ينشئ الجسر طرفيات لعميل ACP ولا يبث معرّفات الطرفيات عبر استدعاءات الأدوات.                                                                                                                                                                    |
| خطط الجلسات / بث الأفكار                                              | غير مدعوم | يصدر الجسر حاليًا نص المخرجات وحالة الأدوات، وليس تحديثات الخطط أو الأفكار الخاصة بـ ACP.                                                                                                                                                        |

## القيود المعروفة

- يعيد `loadSession` تشغيل سجل النصوص المخزن للمستخدم والمساعد، لكنه لا
  يعيد بناء استدعاءات الأدوات التاريخية أو إشعارات النظام أو أنواع الأحداث
  الأصلية الأكثر غنى في ACP.
- إذا شارك عدة عملاء ACP مفتاح جلسة البوابة نفسه، فإن توجيه الأحداث والإلغاء
  يكون بأفضل جهد بدلًا من العزل الصارم لكل عميل. ويفضَّل استخدام جلسات
  `acp:<uuid>` المعزولة افتراضيًا عندما تحتاج إلى أدوار محلية نظيفة في المحرر.
- تُترجم حالات التوقف في البوابة إلى أسباب توقف في ACP، لكن هذا الربط
  أقل تعبيرًا من بيئة تشغيل أصلية كاملة لـ ACP.
- تعرِض عناصر التحكم الأولية في الجلسات حاليًا مجموعة مركزة من مفاتيح البوابة:
  مستوى التفكير، وإسهاب الأدوات، والاستدلال، وتفاصيل الاستخدام، والإجراءات
  المرتفعة. ولم يتم بعد كشف اختيار النموذج وعناصر تحكم مضيف exec كخيارات
  إعداد في ACP.
- تُشتق `session_info_update` و`usage_update` من لقطات جلسات البوابة،
  لا من محاسبة وقت تشغيل أصلية مباشرة لـ ACP. والاستخدام تقريبي،
  ولا يتضمن بيانات تكلفة، ولا يُصدر إلا عندما تضع البوابة علامة
  "حديث" على بيانات إجمالي الرموز.
- بيانات متابعة الأدوات تعمل بأفضل جهد. يستطيع الجسر إظهار مسارات الملفات التي
  تظهر في وسائط/نتائج أدوات معروفة، لكنه لا يصدر بعد طرفيات ACP أو
  فروقات ملفات منظمة.

## الاستخدام

```bash
openclaw acp

# بوابة بعيدة
openclaw acp --url wss://gateway-host:18789 --token <token>

# بوابة بعيدة (الرمز من ملف)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# الإرفاق بمفتاح جلسة موجود
openclaw acp --session agent:main:main

# الإرفاق حسب التسمية (يجب أن تكون موجودة بالفعل)
openclaw acp --session-label "support inbox"

# إعادة تعيين مفتاح الجلسة قبل أول مطالبة
openclaw acp --session agent:main:main --reset-session
```

## عميل ACP (تصحيح)

استخدم عميل ACP المضمّن للتحقق السريع من الجسر من دون IDE.
فهو يشغّل جسر ACP ويسمح لك بكتابة المطالبات بشكل تفاعلي.

```bash
openclaw acp client

# وجّه الجسر الذي تم تشغيله إلى بوابة بعيدة
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# تجاوز أمر الخادم (الافتراضي: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001
```

نموذج الأذونات (وضع تصحيح العميل):

- تعتمد الموافقة التلقائية على قائمة سماح ولا تنطبق إلا على معرّفات الأدوات الأساسية الموثوقة.
- تقتصر الموافقة التلقائية لـ `read` على دليل العمل الحالي (`--cwd` عند ضبطه).
- يوافق ACP تلقائيًا فقط على فئات ضيقة للقراءة فقط: استدعاءات `read` ضمن cwd النشط، إضافة إلى أدوات البحث للقراءة فقط (`search`, `web_search`, `memory_search`). وتتطلب الأدوات غير المعروفة/غير الأساسية، وعمليات القراءة خارج النطاق، والأدوات القادرة على exec، وأدوات مستوى التحكم، والأدوات المعدِّلة، والتدفقات التفاعلية دائمًا موافقة صريحة عبر المطالبة.
- تُعامل `toolCall.kind` المقدمة من الخادم على أنها بيانات وصفية غير موثوقة (وليست مصدر تفويض).
- تختلف سياسة جسر ACP هذا عن أذونات ACPX harness. إذا شغّلت OpenClaw عبر الخلفية `acpx`، فإن `plugins.entries.acpx.config.permissionMode=approve-all` هو مفتاح الطوارئ "yolo" لتلك الجلسة من الـ harness.

## كيفية استخدام هذا

استخدم ACP عندما يتحدث IDE (أو عميل آخر) Agent Client Protocol وتريد
أن يدير جلسة بوابة OpenClaw.

1. تأكد من أن البوابة قيد التشغيل (محليًا أو عن بُعد).
2. اضبط هدف البوابة (بالإعداد أو العلامات).
3. وجّه IDE لديك لتشغيل `openclaw acp` عبر stdio.

مثال على الإعداد (محفوظ):

```bash
openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>
```

مثال على تشغيل مباشر (من دون كتابة إعداد):

```bash
openclaw acp --url wss://gateway-host:18789 --token <token>
# مفضّل من أجل أمان العملية المحلية
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
```

## اختيار الوكلاء

لا يختار ACP الوكلاء مباشرةً. بل يوجّه حسب مفتاح جلسة البوابة.

استخدم مفاتيح جلسات على مستوى الوكيل لاستهداف وكيل محدد:

```bash
openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123
```

تُربط كل جلسة ACP بمفتاح جلسة واحد في البوابة. ويمكن لوكيل واحد أن يملك
جلسات عديدة؛ ويستخدم ACP افتراضيًا جلسة معزولة `acp:<uuid>` ما لم تتجاوز
المفتاح أو التسمية.

لا يتم دعم `mcpServers` لكل جلسة في وضع الجسر. وإذا أرسل عميل ACP
هذه القيم أثناء `newSession` أو `loadSession`، فسيعيد الجسر خطأً
واضحًا بدلًا من تجاهلها بصمت.

إذا كنت تريد أن ترى الجلسات المدعومة بـ ACPX أدوات plugin الخاصة بـ OpenClaw، ففعّل
جسر plugin الخاص بـ ACPX على جانب البوابة بدلًا من محاولة تمرير
`mcpServers` لكل جلسة. راجع [ACP Agents](/tools/acp-agents#plugin-tools-mcp-bridge).

## الاستخدام من `acpx` (Codex وClaude وغيرهما من عملاء ACP)

إذا كنت تريد أن يتحدث وكيل برمجي مثل Codex أو Claude Code إلى
بوت OpenClaw لديك عبر ACP، فاستخدم `acpx` مع الهدف المضمّن `openclaw`.

التدفق النموذجي:

1. شغّل البوابة وتأكد من أن جسر ACP يستطيع الوصول إليها.
2. وجّه `acpx openclaw` إلى `openclaw acp`.
3. استهدف مفتاح جلسة OpenClaw الذي تريد أن يستخدمه وكيل البرمجة.

أمثلة:

```bash
# طلب لمرة واحدة إلى جلسة OpenClaw ACP الافتراضية
acpx openclaw exec "Summarize the active OpenClaw session state."

# جلسة دائمة مسماة للأدوار اللاحقة
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."
```

إذا كنت تريد أن يستهدف `acpx openclaw` بوابة ومفتاح جلسة محددين في كل
مرة، فتجاوز أمر الوكيل `openclaw` في `~/.acpx/config.json`:

```json
{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}
```

بالنسبة إلى نسخة OpenClaw محلية ضمن المستودع، استخدم نقطة دخول CLI المباشرة بدلًا من
مشغّل التطوير حتى يظل تدفق ACP نظيفًا. على سبيل المثال:

```bash
env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
```

وهذه هي أسهل طريقة لجعل Codex أو Claude Code أو أي عميل آخر مدرك لـ ACP
يسحب معلومات سياقية من وكيل OpenClaw من دون كشط طرفية.

## إعداد محرر Zed

أضف وكيل ACP مخصصًا في `~/.config/zed/settings.json` (أو استخدم واجهة إعدادات Zed):

```json
{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}
```

لاستهداف بوابة أو وكيل محدد:

```json
{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}
```

في Zed، افتح لوحة Agent واختر “OpenClaw ACP” لبدء سلسلة محادثة.

## ربط الجلسات

افتراضيًا، تحصل جلسات ACP على مفتاح جلسة معزول في البوابة مع البادئة `acp:`.
ولإعادة استخدام جلسة معروفة، مرّر مفتاح جلسة أو تسمية:

- `--session <key>`: استخدم مفتاح جلسة محددًا في البوابة.
- `--session-label <label>`: حل جلسة موجودة حسب التسمية.
- `--reset-session`: أنشئ معرّف جلسة جديدًا لذلك المفتاح (المفتاح نفسه، وسجل جديد).

إذا كان عميل ACP لديك يدعم البيانات الوصفية، فيمكنك التجاوز لكل جلسة:

```json
{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}
```

تعرّف أكثر على مفاتيح الجلسات في [/concepts/session](/concepts/session).

## الخيارات

- `--url <url>`: عنوان WebSocket URL للبوابة (يستخدم `gateway.remote.url` افتراضيًا عند إعداده).
- `--token <token>`: رمز مصادقة البوابة.
- `--token-file <path>`: قراءة رمز مصادقة البوابة من ملف.
- `--password <password>`: كلمة مرور مصادقة البوابة.
- `--password-file <path>`: قراءة كلمة مرور مصادقة البوابة من ملف.
- `--session <key>`: مفتاح الجلسة الافتراضي.
- `--session-label <label>`: تسمية الجلسة الافتراضية المراد حلها.
- `--require-existing`: يفشل إذا لم يكن مفتاح/تسمية الجلسة موجودًا.
- `--reset-session`: إعادة تعيين مفتاح الجلسة قبل أول استخدام.
- `--no-prefix-cwd`: عدم إضافة دليل العمل كبادئة للمطالبات.
- `--provenance <off|meta|meta+receipt>`: تضمين بيانات وصفية أو إيصالات provenance الخاصة بـ ACP.
- `--verbose, -v`: تسجيلات مفصلة إلى stderr.

ملاحظة أمنية:

- قد تكون `--token` و`--password` مرئيتين في قوائم العمليات المحلية على بعض الأنظمة.
- يفضَّل استخدام `--token-file`/`--password-file` أو متغيرات البيئة (`OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`).
- يتبع تحليل مصادقة البوابة العقد المشترك المستخدم من قِبل عملاء البوابة الآخرين:
  - الوضع المحلي: البيئة (`OPENCLAW_GATEWAY_*`) -> `gateway.auth.*` -> الرجوع إلى `gateway.remote.*` فقط عندما لا تكون `gateway.auth.*` مضبوطة (تفشل SecretRefs المحلية المضبوطة لكن غير المحلولة بشكل مغلق)
  - الوضع البعيد: `gateway.remote.*` مع الرجوع إلى البيئة/الإعداد وفق قواعد أسبقية الوضع البعيد
  - `--url` آمن للتجاوز ولا يعيد استخدام بيانات اعتماد ضمنية من الإعداد/البيئة؛ مرّر `--token`/`--password` صريحين (أو نُسَخ الملف)
- تتلقى العمليات الفرعية في الخلفية وقت تشغيل ACP المتغير `OPENCLAW_SHELL=acp`، ويمكن استخدامه لقواعد سياق shell/profile خاصة.
- يضبط `openclaw acp client` القيمة `OPENCLAW_SHELL=acp-client` على عملية الجسر التي يتم تشغيلها.

### خيارات `acp client`

- `--cwd <dir>`: دليل العمل لجلسة ACP.
- `--server <command>`: أمر خادم ACP (الافتراضي: `openclaw`).
- `--server-args <args...>`: وسائط إضافية تمرَّر إلى خادم ACP.
- `--server-verbose`: تمكين التسجيلات المفصلة على خادم ACP.
- `--verbose, -v`: تسجيلات مفصلة للعميل.
