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

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

بخش‌های زیر پیکربندی چارچوب اجرایی acpx، راه‌اندازی Plugin برای پل‌های MCP، و پیکربندی مجوزها را پوشش می‌دهند.

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

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

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

پشتیبانی چارچوب اجرایی acpx (فعلی)

نام‌های مستعار داخلی فعلی چارچوب اجرایی acpx:

• claude
• codex
• copilot
• cursor (Cursor CLI: cursor-agent acp)
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• qwen

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

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

کنترل مدل به قابلیت آداپتور وابسته است. ارجاع‌های مدل Codex ACP پیش از راه‌اندازی توسط OpenClaw نرمال‌سازی می‌شوند. چارچوب‌های اجرایی دیگر به ACP models به‌همراه پشتیبانی session/set_model نیاز دارند؛ اگر یک چارچوب اجرایی نه آن قابلیت 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 برای backend مربوط به acpx

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

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

checkoutهای منبع نیز می‌توانند پس از 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

سپس سلامت backend را بررسی کنید:

/acp doctor

فرمان acpx و پیکربندی نسخه

به‌طور پیش‌فرض، Plugin acpx هنگام راه‌اندازی Gateway، backend توکار ACP را ثبت می‌کند و پیش از سیگنال ready مربوط به gateway منتظر probe راه‌اندازی runtime توکار می‌ماند. OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 یا OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 را فقط برای اسکریپت‌ها یا محیط‌هایی تنظیم کنید که عمدا probe راه‌اندازی را غیرفعال نگه می‌دارند. برای یک probe صریح در زمان نیاز، /acp doctor را اجرا کنید.

فرمان یا نسخه را در پیکربندی Plugin بازنویسی کنید:

{  "plugins": {    "entries": {      "acpx": {        "enabled": true,        "config": {          "command": "../acpx/dist/cli.js",          "expectedVersion": "any"        }      }    }  }}

• command یک مسیر مطلق، مسیر نسبی (که از فضای کاری OpenClaw resolve می‌شود)، یا نام فرمان را می‌پذیرد.
• expectedVersion: "any" تطبیق سخت‌گیرانه نسخه را غیرفعال می‌کند.
• مسیرهای سفارشی command نصب خودکار محلی Plugin را غیرفعال می‌کنند.

وقتی یک مسیر یا مقدار پرچم باید یک argv token باقی بماند، فرمان یک عامل 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 آن را از طریق رجیستری command-string فعلی acpx عبور دهد، به‌شکل shell-quoted درمی‌آید.

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

نصب خودکار وابستگی

وقتی OpenClaw را به‌صورت global با npm install -g openclaw نصب می‌کنید، وابستگی‌های runtime مربوط به acpx (باینری‌های مخصوص پلتفرم) به‌طور خودکار از طریق postinstall hook نصب می‌شوند. اگر نصب خودکار شکست بخورد، gateway همچنان به‌طور عادی شروع می‌شود و وابستگی گم‌شده را از طریق openclaw acp doctor گزارش می‌کند.

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

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

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

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

این کار چه می‌کند:

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

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

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

mcpServers سفارشی همچنان مثل قبل کار می‌کند. پل داخلی plugin-tools یک سهولت اختیاری اضافی است، نه جایگزینی برای پیکربندی generic MCP server.

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

به‌طور پیش‌فرض، نشست‌های ACPX همچنین ابزارهای داخلی OpenClaw را از طریق MCP ارائه نمی‌کنند. وقتی یک عامل ACP به ابزارهای داخلی منتخب مانند cron نیاز دارد، پل جداگانه core-tools را فعال کنید:

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

این کار چه می‌کند:

• یک MCP server داخلی با نام openclaw-tools را به bootstrap نشست ACPX تزریق می‌کند.
• ابزارهای داخلی منتخب OpenClaw را ارائه می‌کند. سرور اولیه cron را ارائه می‌کند.
• ارائه ابزارهای core را صریح و به‌طور پیش‌فرض خاموش نگه می‌دارد.

پیکربندی timeout عملیات runtime

Plugin acpx به‌طور پیش‌فرض برای راه‌اندازی runtime توکار و عملیات کنترلی ۱۲۰ ثانیه زمان می‌دهد. این به چارچوب‌های اجرایی کندتر مانند Gemini CLI زمان کافی می‌دهد تا راه‌اندازی و مقداردهی اولیه ACP را کامل کنند. اگر میزبان شما به محدودیت عملیات متفاوتی نیاز دارد، آن را بازنویسی کنید:

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

نوبت‌های runtime از timeoutهای agent/run در OpenClaw استفاده می‌کنند، از جمله /acp timeout. sessions_spawn بازنویسی timeout برای هر فراخوانی را نمی‌پذیرد. پس از تغییر این مقدار، gateway را restart کنید.

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

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

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

پس از تغییر این مقدار، gateway را restart کنید.

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

نشست‌های ACP به‌صورت غیرتعاملی اجرا می‌شوند — هیچ TUI برای تایید یا رد promptهای مجوز file-write و shell-exec وجود ندارد. Plugin acpx دو کلید پیکربندی ارائه می‌کند که نحوه مدیریت مجوزها را کنترل می‌کنند:

این مجوزهای چارچوب اجرایی ACPX از تاییدهای exec در OpenClaw جدا هستند و از پرچم‌های bypass مربوط به فروشنده CLI-backend مانند Claude CLI --permission-mode bypassPermissions نیز جدا هستند. ACPX approve-all کلید اضطراری سطح چارچوب اجرایی برای نشست‌های ACP است.

برای مقایسه گسترده‌تر میان OpenClaw tools.exec.mode، تاییدهای Codex Guardian، و مجوزهای چارچوب اجرایی ACPX، به حالت‌های مجوز مراجعه کنید.

permissionMode

کنترل می‌کند عامل چارچوب اجرایی کدام عملیات را بدون prompt می‌تواند انجام دهد.

nonInteractivePermissions

کنترل می‌کند وقتی قرار است prompt مجوز نمایش داده شود اما TUI تعاملی در دسترس نیست چه اتفاقی بیفتد (که برای نشست‌های ACP همیشه همین‌طور است).

پیکربندی

از طریق پیکربندی Plugin تنظیم کنید:

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

پس از تغییر این مقادیر، gateway را restart کنید.

مرتبط

• عامل‌های ACP — نمای کلی، راهنمای عملیاتی اپراتور، مفاهیم
• زیرعامل‌ها
• مسیریابی چندعاملی