الانتقال إلى المحتوى الرئيسي
للحصول على النظرة العامة، ودليل تشغيل المشغّل، والمفاهيم، راجع وكلاء ACP. تغطي الأقسام أدناه إعداد acpx harness، وإعداد Plugin لجسور MCP، وإعداد الأذونات. استخدم هذه الصفحة فقط عند إعداد مسار ACP/acpx. لإعدادات وقت تشغيل خادم تطبيق Codex الأصلية، استخدم Codex harness. ولمفاتيح OpenAI API أو إعداد موفّر النماذج Codex OAuth، استخدم OpenAI. لدى Codex مساران في OpenClaw:
المسارالإعداد/الأمرصفحة الإعداد
خادم تطبيق Codex الأصلي/codex ..., openai/gpt-* agent refsCodex harness
محوّل Codex ACP الصريح/acp spawn codex, runtime: "acp", agentId: "codex"هذه الصفحة
فضّل المسار الأصلي ما لم تكن تحتاج صراحة إلى سلوك ACP/acpx.

​
دعم acpx harness (الحالي)

أسماء acpx built-in harness المستعارة الحالية:
  • claude
  • codex
  • copilot
  • cursor (Cursor CLI: cursor-agent acp)
  • droid
  • gemini
  • iflow
  • kilocode
  • kimi
  • kiro
  • openclaw
  • opencode
  • qwen
عندما يستخدم OpenClaw خلفية acpx، فضّل هذه القيم لـ agentId ما لم يعرّف إعداد acpx لديك أسماء وكلاء مستعارة مخصصة. إذا كان تثبيت Cursor المحلي لديك لا يزال يعرّض ACP باسم agent acp، فتجاوز أمر وكيل cursor في إعداد acpx بدل تغيير الإعداد الافتراضي المضمّن. يمكن لاستخدام acpx CLI المباشر أيضًا استهداف محوّلات عشوائية عبر --agent <command>، لكن منفذ الهروب الخام هذا ميزة في acpx CLI (وليس مسار agentId العادي في OpenClaw). يعتمد التحكم في النموذج على قدرات المحوّل. يطبّع OpenClaw مراجع نماذج Codex ACP قبل بدء التشغيل. تحتاج harnesses الأخرى إلى ACP models إضافة إلى دعم session/set_model؛ وإذا لم يعرّض harness تلك القدرة في ACP ولا علم نموذج بدء التشغيل الخاص به، فلن يستطيع OpenClaw/acpx فرض اختيار نموذج.

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

خط أساس ACP الأساسي: 
{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "openclaw",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}
إعداد ربط الخيوط خاص بمحوّل القناة. مثال لـ Discord: 
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnSessions: true,
      },
    },
  },
}
إذا لم يعمل إنشاء ACP المربوط بخيط، فتحقق أولًا من علامة ميزة المحوّل:
  • Discord: channels.discord.threadBindings.spawnSessions=true
لا تتطلب روابط المحادثة الحالية إنشاء خيط فرعي. إنها تتطلب سياق محادثة نشطًا ومحوّل قناة يعرّض روابط محادثات ACP. راجع مرجع الإعدادات.

​
إعداد Plugin لخلفية acpx

تستخدم التثبيتات المعبأة Plugin وقت التشغيل الرسمي @openclaw/acpx لـ ACP. ثبّته وفعّله قبل استخدام جلسات ACP harness: 
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
يمكن لنسخ المصدر أيضًا استخدام Plugin مساحة العمل المحلية بعد pnpm install. ابدأ بـ: 
/acp doctor
إذا عطّلت acpx، أو رفضته عبر plugins.allow / plugins.deny، أو أردت الرجوع إلى Plugin المعبأ، فاستخدم مسار الحزمة الصريح: 
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
تثبيت مساحة العمل المحلية أثناء التطوير: 
openclaw plugins install ./path/to/local/acpx-plugin
ثم تحقق من صحة الخلفية: 
/acp doctor

​
إعداد أمر وإصدار acpx

افتراضيًا، يسجّل Plugin acpx خلفية ACP المضمّنة أثناء بدء تشغيل Gateway وينتظر مسبار بدء تشغيل وقت التشغيل المضمّن قبل إشارة ready الخاصة بالبوابة. عيّن OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 أو OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 فقط للسكربتات أو البيئات التي تبقي مسبار بدء التشغيل معطّلًا عمدًا. شغّل /acp doctor لإجراء مسبار صريح عند الطلب. تجاوز الأمر أو الإصدار في إعداد Plugin: 
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}
  • يقبل command مسارًا مطلقًا، أو مسارًا نسبيًا (يُحل من مساحة عمل OpenClaw)، أو اسم أمر.
  • يعطّل expectedVersion: "any" مطابقة الإصدار الصارمة.
  • تعطّل مسارات command المخصصة التثبيت التلقائي المحلي للـ Plugin.
تجاوز أمر وكيل 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 اختياري. يُقتبس كل عنصر في المصفوفة بأسلوب shell قبل أن يمرره OpenClaw عبر سجل سلاسل أوامر acpx الحالي.
راجع Plugins.

​
تثبيت التبعيات تلقائيًا

عند تثبيت OpenClaw عالميًا باستخدام npm install -g openclaw، تُثبّت تبعيات وقت تشغيل acpx (الثنائيات الخاصة بالمنصة) تلقائيًا عبر خطاف postinstall. إذا فشل التثبيت التلقائي، فسيظل Gateway يبدأ بشكل طبيعي ويبلغ عن التبعية المفقودة عبر openclaw acp doctor.

​
جسر MCP لأدوات Plugin

افتراضيًا، لا تعرّض جلسات ACPX أدوات OpenClaw المسجلة بواسطة Plugin إلى ACP harness. إذا أردت أن تستدعي وكلاء ACP مثل Codex أو Claude Code أدوات OpenClaw Plugin المثبتة مثل استدعاء/تخزين الذاكرة، ففعّل الجسر المخصص: 
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
ما يفعله هذا:
  • يحقن خادم MCP مضمّنًا باسم openclaw-plugin-tools في تمهيد جلسة ACPX.
  • يعرّض أدوات Plugin المسجلة مسبقًا بواسطة Plugins OpenClaw المثبتة والمفعّلة.
  • يبقي الميزة صريحة ومعطّلة افتراضيًا.
ملاحظات الأمان والثقة:
  • يوسّع هذا سطح أدوات ACP harness.
  • يحصل وكلاء ACP على حق الوصول فقط إلى أدوات Plugin النشطة مسبقًا في Gateway.
  • تعامل مع هذا باعتباره حد الثقة نفسه مثل السماح لتلك Plugins بالتنفيذ داخل OpenClaw نفسه.
  • راجع Plugins المثبتة قبل تفعيله.
لا تزال mcpServers المخصصة تعمل كما في السابق. جسر plugin-tools المضمّن وسيلة راحة إضافية اختيارية، وليس بديلًا لإعداد خوادم 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 ثانية افتراضيًا. يمنح ذلك harnesses الأبطأ مثل Gemini CLI وقتًا كافيًا لإكمال بدء تشغيل ACP وتهيئته. تجاوزه إذا كان مضيفك يحتاج إلى حد عمليات مختلف: 
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
تستخدم دورات وقت التشغيل مهل وكيل/تشغيل OpenClaw، بما في ذلك /acp timeout. لا يقبل sessions_spawn تجاوزات مهلة لكل استدعاء. أعد تشغيل Gateway بعد تغيير هذه القيمة.

​
إعداد وكيل مسبار الصحة

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

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

تعمل جلسات ACP بشكل غير تفاعلي — لا يوجد TTY للموافقة على مطالبات أذونات كتابة الملفات وتنفيذ أوامر shell أو رفضها. يوفر Plugin acpx مفتاحي إعداد يتحكمان في كيفية معالجة الأذونات: أذونات ACPX harness هذه منفصلة عن موافقات تنفيذ OpenClaw ومنفصلة عن أعلام تجاوز موردي خلفية CLI مثل Claude CLI --permission-mode bypassPermissions. إن ACPX approve-all هو مفتاح الطوارئ على مستوى harness لجلسات ACP. للمقارنة الأوسع بين OpenClaw tools.exec.mode، وموافقات Codex Guardian، وأذونات ACPX harness، راجع أوضاع الأذونات.

​
permissionMode

يتحكم في العمليات التي يستطيع وكيل harness تنفيذها دون مطالبة.
القيمةالسلوك
approve-allالموافقة تلقائيًا على كل عمليات كتابة الملفات وأوامر shell.
approve-readsالموافقة تلقائيًا على القراءات فقط؛ تتطلب الكتابات والتنفيذ مطالبات.
deny-allرفض كل مطالبات الأذونات.

​
nonInteractivePermissions

يتحكم فيما يحدث عندما يفترض أن تظهر مطالبة إذن لكن لا يتوفر TTY تفاعلي (وهذا هو الحال دائمًا في جلسات ACP).
القيمةالسلوك
failإجهاض الجلسة مع AcpRuntimeError. (افتراضي)
denyرفض الإذن بصمت والمتابعة (تدهور سلس).

​
الإعداد

اضبط عبر إعداد Plugin: 
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
أعد تشغيل Gateway بعد تغيير هذه القيم.
يستخدم OpenClaw افتراضيًا permissionMode=approve-reads وnonInteractivePermissions=fail. في جلسات ACP غير التفاعلية، قد يفشل أي تنفيذ كتابة أو exec يطلق مطالبة إذن برسالة AcpRuntimeError: Permission prompt unavailable in non-interactive mode.إذا كنت تحتاج إلى تقييد الأذونات، فاضبط nonInteractivePermissions على deny كي تتدهور الجلسات بسلاسة بدلًا من الانهيار.

​
ذات صلة