راه‌اندازی عامل‌های ACP

برای نمای کلی، راهنمای عملیاتی اپراتور و مفاهیم، به عامل‌های ACP مراجعه کنید.

این صفحه پیکربندی هارنس acpx، راه‌اندازی Plugin برای پل‌های MCP و پیکربندی مجوزها را پوشش می‌دهد.

فقط زمانی از این صفحه استفاده کنید که در حال راه‌اندازی مسیر ACP/acpx هستید. برای پیکربندی زمان اجرای بومی app-server در Codex، از هارنس Codex استفاده کنید. برای کلیدهای API در OpenAI یا پیکربندی ارائه‌دهنده مدل با OAuth در Codex، به OpenAI مراجعه کنید.

Codex دو مسیر در OpenClaw دارد:

مگر اینکه صراحتاً به رفتار ACP/acpx نیاز داشته باشید، مسیر بومی را ترجیح دهید.

پشتیبانی فعلی هارنس acpx

نام‌های مستعار داخلی هارنس acpx (از وابستگی سنجاق‌شده acpx):

factory-droid و factorydroid نیز به آداپتور داخلی droid نگاشت می‌شوند.

هنگامی که OpenClaw از بک‌اند acpx استفاده می‌کند، این مقادیر را برای agentId ترجیح دهید، مگر اینکه پیکربندی acpx شما نام‌های مستعار سفارشی برای عامل‌ها تعریف کرده باشد. اگر نصب محلی Cursor شما همچنان ACP را به‌صورت agent acp ارائه می‌کند، به‌جای تغییر مقدار پیش‌فرض داخلی، فرمان عامل cursor را در پیکربندی acpx خود بازنویسی کنید.

استفاده مستقیم از CLI در acpx همچنین می‌تواند با --agent <command> آداپتورهای دلخواه را هدف قرار دهد، اما این راه گریز خام، قابلیتی از CLI در acpx است و مسیر معمول agentId در OpenClaw نیست.

کنترل مدل به قابلیت‌های آداپتور وابسته است. ارجاع‌های مدل ACP در Codex پیش از راه‌اندازی توسط OpenClaw عادی‌سازی می‌شوند. سایر هارنس‌ها به models در ACP به‌همراه پشتیبانی از session/set_model نیاز دارند؛ اگر یک هارنس نه این قابلیت ACP و نه پرچم راه‌اندازی مدل مختص خود را ارائه کند، OpenClaw/acpx نمی‌تواند انتخاب مدل را تحمیل کند.

پیکربندی الزامی

خط مبنای اصلی ACP:

{  acp: {    enabled: true,    // اختیاری است. مقدار پیش‌فرض true است؛ برای توقف ارسال ACP در حالی که کنترل‌های /acp حفظ می‌شوند، آن را false کنید.    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

نصب‌های بسته‌بندی‌شده برای ACP از Plugin رسمی زمان اجرای @openclaw/acpx استفاده می‌کنند. پیش از استفاده از نشست‌های هارنس ACP، آن را نصب و فعال کنید:

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

نسخه‌های دریافت‌شده از منبع نیز می‌توانند پس از pnpm install از Plugin فضای کاری محلی استفاده کنند.

با این مورد شروع کنید:

/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 برای پیکربندی وجود ندارد. به‌طور پیش‌فرض، این Plugin هنگام راه‌اندازی Gateway بک‌اند تعبیه‌شده را ثبت می‌کند و پیش از سیگنال ready در Gateway، منتظر یک کاوش راه‌اندازی می‌ماند. فقط برای اسکریپت‌ها یا محیط‌هایی که عمداً کاوش راه‌اندازی را غیرفعال نگه می‌دارند، OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 یا OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 را تنظیم کنید. برای اجرای صریح کاوش در زمان تقاضا، /acp doctor را اجرا کنید.

هنگامی که یک مسیر یا مقدار پرچم باید به‌عنوان یک توکن argv باقی بماند، فرمان یک عامل ACP را با آرگومان‌های ساخت‌یافته بازنویسی کنید:

{  "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 عبور دهد، آن عضو برای پوسته نقل‌قول‌گذاری می‌شود.

به Pluginها مراجعه کنید.

دانلود خودکار آداپتور

acpx آداپتورهای ACP، برای مثال پل‌های ACP در Claude و Codex، را هنگام نخستین استفاده از طریق npx به‌طور خودکار دانلود می‌کند. نیازی نیست بسته‌های آداپتور را دستی نصب کنید و برای خود OpenClaw نیز مرحله جداگانه‌ای پس از نصب وجود ندارد. اگر دانلود یا ایجاد یک آداپتور ناموفق باشد، /acp doctor خطا را گزارش می‌کند.

پل MCP ابزارهای Plugin

به‌طور پیش‌فرض، نشست‌های ACPX ابزارهای ثبت‌شده توسط Pluginهای OpenClaw را در اختیار هارنس ACP قرار نمی‌دهند.

اگر می‌خواهید عامل‌های ACP مانند Codex یا Claude Code بتوانند ابزارهای Plugin نصب‌شده در OpenClaw، مانند بازیابی/ذخیره حافظه، را فراخوانی کنند، پل اختصاصی را فعال کنید:

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

کارکرد این تنظیم:

• یک سرور داخلی MCP با نام openclaw-plugin-tools را به راه‌اندازی اولیه نشست ACPX تزریق می‌کند.
• ابزارهای Plugin را که از قبل توسط Pluginهای نصب‌شده و فعال OpenClaw ثبت شده‌اند، ارائه می‌کند.
• این قابلیت را صریح و به‌طور پیش‌فرض غیرفعال نگه می‌دارد.

نکات امنیتی و اعتماد:

• این کار سطح ابزار هارنس ACP را گسترش می‌دهد.
• عامل‌های ACP فقط به ابزارهای Plugin دسترسی می‌یابند که از قبل در Gateway فعال هستند.
• این مورد را هم‌مرز با اعتمادی در نظر بگیرید که برای اجازه اجرای همان Pluginها در خود OpenClaw لازم است.
• پیش از فعال‌سازی، Pluginهای نصب‌شده را بررسی کنید.

mcpServers سفارشی همچنان مانند قبل کار می‌کنند. پل داخلی ابزارهای Plugin یک امکان اختیاری و افزوده است، نه جایگزینی برای پیکربندی عمومی سرور 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 به‌طور پیش‌فرض برای عملیات راه‌اندازی و کنترل زمان اجرای تعبیه‌شده ۱۲۰ ثانیه زمان در نظر می‌گیرد. این مقدار به هارنس‌های کندتر مانند Gemini CLI زمان کافی می‌دهد تا راه‌اندازی و مقداردهی اولیه ACP را تکمیل کنند. اگر میزبان شما به محدودیت عملیاتی متفاوتی نیاز دارد، آن را بازنویسی کنید:

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

نوبت‌های زمان اجرا از مهلت‌های agent/run در OpenClaw، از جمله /acp timeout، استفاده می‌کنند. sessions_spawn بازنویسی مهلت برای هر فراخوانی را نمی‌پذیرد؛ مسیر اپراتور agents.defaults.subagents.runTimeoutSeconds است. پس از تغییر timeoutSeconds، Gateway را دوباره راه‌اندازی کنید.

پیکربندی عامل کاوش سلامت

هنگامی که /acp doctor یا کاوش راه‌اندازی بک‌اند را بررسی می‌کند، Plugin همراه acpx یکی از عامل‌های هارنس را کاوش می‌کند. اگر acp.allowedAgents تنظیم شده باشد، مقدار پیش‌فرض نخستین عامل مجاز است؛ در غیر این صورت، مقدار پیش‌فرض codex خواهد بود. اگر استقرار شما برای بررسی‌های سلامت به عامل ACP دیگری نیاز دارد، عامل کاوش را صراحتاً تنظیم کنید:

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

پس از تغییر این مقدار، Gateway را دوباره راه‌اندازی کنید.

پیکربندی مجوزها

نشست‌های ACP به‌صورت غیرتعاملی اجرا می‌شوند؛ هیچ TUI برای تأیید یا رد درخواست‌های مجوز نوشتن فایل و اجرای پوسته وجود ندارد. 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 — نمای کلی، راهنمای عملیاتی اپراتور، مفاهیم
• عامل‌های فرعی
• مسیریابی چندعاملی