وكلاء ACP — الإعداد

للاطلاع على النظرة العامة ودليل تشغيل المشغّل والمفاهيم، راجع وكلاء ACP.

تتناول هذه الصفحة إعداد حاضنة acpx، وإعداد Plugin لجسور MCP، وإعداد الأذونات.

استخدم هذه الصفحة فقط عند إعداد مسار ACP/acpx. لإعداد وقت تشغيل خادم تطبيق Codex الأصلي، استخدم حاضنة Codex. ولمفاتيح OpenAI API أو إعداد موفّر النماذج عبر Codex OAuth، استخدم OpenAI.

لدى Codex مساران في OpenClaw:

فضّل المسار الأصلي ما لم تكن بحاجة صريحة إلى سلوك ACP/acpx.

دعم حاضنة acpx (الحالي)

الأسماء المستعارة المضمنة لحاضنة acpx (من تبعية acpx المثبّتة):

يُحلّ الاسمان factory-droid وfactorydroid أيضًا إلى محوّل droid المضمن.

عندما يستخدم OpenClaw الواجهة الخلفية acpx، فضّل هذه القيم لـagentId ما لم يعرّف إعداد acpx أسماء مستعارة مخصصة للوكلاء. إذا كان تثبيت Cursor المحلي لديك لا يزال يتيح ACP بالأمر agent acp، فتجاوز أمر وكيل cursor في إعداد acpx بدلًا من تغيير القيمة الافتراضية المضمنة.

يمكن أيضًا لاستخدام acpx CLI المباشر استهداف محوّلات عشوائية عبر --agent <command>، لكن منفذ التجاوز الخام هذا ميزة في acpx CLI (وليس مسار agentId المعتاد في OpenClaw).

يعتمد التحكم في النموذج على إمكانات المحوّل. يطبّع OpenClaw مراجع نماذج Codex ACP قبل بدء التشغيل. تحتاج الحاضنات الأخرى إلى إمكانات ACP ‏models ودعم session/set_model؛ وإذا لم تعرض الحاضنة إمكانات ACP هذه ولا خيار بدء تشغيل خاصًا بها لتحديد النموذج، فلن يستطيع OpenClaw/acpx فرض اختيار نموذج.

الإعداد المطلوب

الخط الأساسي لـACP في النواة:

{  acp: {    enabled: true,    // اختياري. القيمة الافتراضية true؛ اضبطها على false لإيقاف توجيه ACP مؤقتًا مع إبقاء عناصر تحكم /acp.    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "codex",    allowedAgents: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "qwen",    ],    maxConcurrentSessions: 8,    stream: {      // القيم الافتراضية هي coalesceIdleMs: 350 وmaxChunkChars: 1800؛ وهي معروضة هنا صراحةً.      coalesceIdleMs: 350,      maxChunkChars: 1800,    },    runtime: {      ttlMinutes: 120,    },  },}

إعداد ربط سلاسل المحادثات خاص بمحوّل القناة. مثال لـDiscord:

{  session: {    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },  },  channels: {    discord: {      threadBindings: {        enabled: true,        // القيمة الافتراضية true بالفعل؛ وهي معروضة هنا صراحةً.        spawnSessions: true,      },    },  },}

إذا لم يعمل إنشاء جلسة ACP مرتبطة بسلسلة محادثة، فتحقق أولًا من علامة ميزة المحوّل:

• Discord: ‏channels.discord.threadBindings.spawnSessions=true

لا تتطلب عمليات الربط بالمحادثة الحالية إنشاء سلسلة محادثة فرعية. بل تتطلب سياق محادثة نشطًا ومحوّل قناة يتيح روابط محادثات ACP.

راجع مرجع الإعداد.

إعداد Plugin للواجهة الخلفية acpx

تستخدم عمليات التثبيت المجمّعة Plugin وقت التشغيل الرسمي @openclaw/acpx لـACP. ثبّته وفعّله قبل استخدام جلسات حاضنة ACP:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

يمكن لنسخ الشيفرة المصدرية أيضًا استخدام Plugin مساحة العمل المحلية بعد pnpm install.

ابدأ باستخدام:

/acp doctor

إذا عطّلت acpx، أو منعته عبر plugins.allow / plugins.deny، أو أردت العودة إلى Plugin المجمّع، فاستخدم مسار الحزمة الصريح:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

تثبيت مساحة العمل المحلية أثناء التطوير:

openclaw plugins install ./path/to/local/acpx-plugin

ثم تحقق من سلامة الواجهة الخلفية:

/acp doctor

فحص بدء تشغيل وقت تشغيل acpx

يدمج Plugin ‏acpx وقت تشغيل ACP مباشرةً (من دون ملف acpx تنفيذي منفصل أو إصدار يلزم إعداده). وهو يسجّل الواجهة الخلفية المضمنة افتراضيًا أثناء بدء تشغيل Gateway وينتظر فحص بدء التشغيل قبل إشارة ready الخاصة بـGateway. اضبط OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 أو OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 فقط للبرامج النصية أو البيئات التي تُبقي فحص بدء التشغيل معطّلًا عمدًا. شغّل /acp doctor لإجراء فحص صريح عند الطلب.

تجاوز أمر وكيل ACP فردي باستخدام وسائط منظّمة عندما يجب أن يبقى المسار أو قيمة العلامة رمز argv واحدًا:

{  "plugins": {    "entries": {      "acpx": {        "enabled": true,        "config": {          "agents": {            "claude": {              "command": "node",              "args": ["/path/to/custom adapter.mjs", "--verbose"]            }          }        }      }    }  }}

• agents.<id>.command هو الملف التنفيذي أو سلسلة الأمر الحالية لوكيل ACP ذاك.
• agents.<id>.args اختياري. يُقتبس كل عنصر في المصفوفة وفق قواعد الصدفة قبل أن يمرّره OpenClaw عبر سجل سلاسل أوامر acpx الحالي.

راجع Plugins.

التنزيل التلقائي للمحوّلات

ينزّل acpx محوّلات ACP تلقائيًا (مثل جسري Claude وCodex لـACP) عبر npx عند أول استخدام. لا تحتاج إلى تثبيت حزم المحوّلات يدويًا، ولا توجد خطوة منفصلة بعد التثبيت لـOpenClaw نفسه. إذا فشل تنزيل محوّل أو إنشاؤه، فسيبلّغ /acp doctor عن الفشل.

جسر MCP لأدوات Plugin

افتراضيًا، لا تتيح جلسات ACPX أدوات OpenClaw المسجّلة بواسطة Plugins لحاضنة ACP.

إذا أردت أن تستدعي وكلاء ACP مثل Codex أو Claude Code أدوات Plugins المثبّتة في OpenClaw، مثل استرجاع الذاكرة/تخزينها، ففعّل الجسر المخصص:

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

ما يفعله هذا:

• يحقن خادم MCP مضمنًا باسم openclaw-plugin-tools في تمهيد جلسة ACPX.
• يتيح أدوات Plugins المسجّلة بالفعل بواسطة Plugins OpenClaw المثبّتة والمفعّلة.
• يُبقي الميزة صريحة ومعطّلة افتراضيًا.

ملاحظات الأمان والثقة:

• يوسّع هذا نطاق أدوات حاضنة ACP.
• لا يحصل وكلاء ACP إلا على إمكانية الوصول إلى أدوات Plugins النشطة بالفعل في Gateway.
• تعامل مع هذا باعتباره حد الثقة نفسه الذي ينطبق على السماح لتلك Plugins بالتنفيذ داخل OpenClaw نفسه.
• راجع Plugins المثبّتة قبل تفعيله.

تستمر mcpServers المخصصة في العمل كما كانت من قبل. جسر أدوات Plugins المضمن وسيلة راحة إضافية اختيارية، وليس بديلًا عن إعداد خادم MCP العام.

جسر MCP لأدوات OpenClaw

افتراضيًا، لا تتيح جلسات ACPX أيضًا أدوات OpenClaw المضمنة عبر MCP. فعّل جسر أدوات النواة المنفصل عندما يحتاج وكيل ACP إلى أدوات مضمنة محددة مثل cron:

openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true

ما يفعله هذا:

• يحقن خادم MCP مضمنًا باسم openclaw-tools في تمهيد جلسة ACPX.
• يتيح أدوات OpenClaw المضمنة المحددة. يتيح الخادم الأولي cron.
• يُبقي إتاحة أدوات النواة صريحة ومعطّلة افتراضيًا.

إعداد مهلة عمليات وقت التشغيل

يمنح Plugin ‏acpx عمليات بدء تشغيل وقت التشغيل المضمن والتحكم فيه مهلة افتراضية قدرها 120 ثانية. يمنح هذا الحاضنات الأبطأ مثل Gemini CLI وقتًا كافيًا لإكمال بدء تشغيل ACP وتهيئته. تجاوزها إذا كان مضيفك يحتاج إلى حد مختلف للعملية:

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

تستخدم دورات وقت التشغيل مهل الوكيل/التشغيل في OpenClaw، بما في ذلك /acp timeout. لا يقبل sessions_spawn تجاوزات للمهلة لكل استدعاء؛ ومسار المشغّل هو agents.defaults.subagents.runTimeoutSeconds. أعد تشغيل Gateway بعد تغيير timeoutSeconds.

إعداد وكيل فحص السلامة

عندما يفحص /acp doctor أو فحص بدء التشغيل الواجهة الخلفية، يختبر Plugin ‏acpx المجمّع وكيل حاضنة واحدًا. إذا ضُبط acp.allowedAgents، فسيستخدم الوكيل الأول المسموح به افتراضيًا؛ وإلا فسيستخدم codex. إذا كان نشرك يحتاج إلى وكيل ACP مختلف لفحوصات السلامة، فاضبط وكيل الفحص صراحةً:

openclaw config set plugins.entries.acpx.config.probeAgent claude

أعد تشغيل Gateway بعد تغيير هذه القيمة.

إعداد الأذونات

تعمل جلسات ACP بصورة غير تفاعلية — فلا توجد TTY للموافقة على مطالبات أذونات كتابة الملفات وتنفيذ أوامر الصدفة أو رفضها. يوفّر Plugin ‏acpx مفتاحي إعداد يتحكمان في كيفية معالجة الأذونات:

أذونات حاضنة ACPX هذه منفصلة عن موافقات التنفيذ في OpenClaw، ومنفصلة عن علامات تجاوز المورّد الخاصة بالواجهة الخلفية لـCLI مثل --permission-mode bypassPermissions في Claude CLI. يمثّل approve-all في ACPX مفتاح الطوارئ على مستوى الحاضنة لجلسات ACP.

للاطلاع على مقارنة أوسع بين tools.exec.mode في OpenClaw وموافقات Codex Guardian وأذونات حاضنة ACPX، راجع أوضاع الأذونات.

permissionMode

يتحكم في العمليات التي يمكن لوكيل الحاضنة تنفيذها من دون مطالبة.

nonInteractivePermissions

يتحكم في ما يحدث عندما يُفترض عرض مطالبة إذن، ولكن لا تتوفر TTY تفاعلية (وهذا هو الحال دائمًا في جلسات ACP).

الإعداد

اضبط القيم عبر إعدادات Plugin:

openclaw config set plugins.entries.acpx.config.permissionMode approve-allopenclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

أعِد تشغيل Gateway بعد تغيير هذه القيم.

ذو صلة

• وكلاء ACP — نظرة عامة، دليل تشغيل للمشغّل، المفاهيم
• الوكلاء الفرعيون
• توجيه متعدد الوكلاء