ACP

پل پروتکل مشتری عامل (ACP) را اجرا کنید که با یک OmeniaClaw Gateway گفتگو می‌کند.

این فرمان ACP را از طریق stdio برای IDEها صحبت می‌کند و اعلان‌ها را از طریق WebSocket به Gateway ارسال می‌کند. این فرمان نشست‌های ACP را به کلیدهای نشست Gateway نگاشت‌شده نگه می‌دارد.

OmeniaClaw acp یک پل ACP متکی بر Gateway است، نه یک runtime ویرایشگر کاملا بومی ACP. تمرکز آن روی مسیریابی نشست، تحویل اعلان، و به‌روزرسانی‌های پایه‌ی streaming است.

اگر می‌خواهید یک مشتری MCP خارجی به‌جای میزبانی یک نشست harness مربوط به ACP مستقیما با گفتگوهای کانال OmeniaClaw صحبت کند، از OmeniaClaw mcp serve استفاده کنید.

این چه چیزی نیست

این صفحه اغلب با نشست‌های harness مربوط به ACP اشتباه گرفته می‌شود.

OmeniaClaw acp یعنی:

• OmeniaClaw به‌عنوان سرور ACP عمل می‌کند
• یک IDE یا مشتری ACP به OmeniaClaw وصل می‌شود
• OmeniaClaw آن کار را به یک نشست Gateway ارسال می‌کند

این با عامل‌های ACP فرق دارد، جایی که OmeniaClaw یک harness خارجی مانند Codex یا Claude Code را از طریق acpx اجرا می‌کند.

قاعده‌ی سریع:

• ویرایشگر/مشتری می‌خواهد با ACP با OmeniaClaw صحبت کند: از OmeniaClaw acp استفاده کنید
• OmeniaClaw باید Codex/Claude/Gemini را به‌عنوان harness مربوط به ACP اجرا کند: از /acp spawn و عامل‌های ACP استفاده کنید

ماتریس سازگاری

محدودیت‌های شناخته‌شده

• loadSession می‌تواند تاریخچه‌ی کامل ledger رویداد ACP را فقط برای نشست‌های ساخته‌شده توسط پل بازپخش کند. نشست‌های قدیمی‌تر/بدون ledger همچنان از fallback transcript استفاده می‌کنند و فراخوانی‌های تاریخی ابزار یا اعلان‌های سیستم را بازسازی نمی‌کنند.
• اگر چند مشتری ACP یک کلید نشست Gateway یکسان را به‌اشتراک بگذارند، مسیریابی رویداد و cancel best-effort است، نه کاملا ایزوله به‌ازای هر مشتری. وقتی به نوبت‌های تمیز محلی ویرایشگر نیاز دارید، نشست‌های ایزوله‌ی پیش‌فرض acp:<uuid> را ترجیح دهید.
• وضعیت‌های stop در Gateway به دلایل stop در ACP ترجمه می‌شوند، اما آن نگاشت از یک runtime کاملا بومی ACP کم‌بیان‌تر است.
• کنترل‌های اولیه‌ی نشست در حال حاضر زیرمجموعه‌ای متمرکز از knobهای Gateway را ارائه می‌کنند: سطح فکر، میزان جزئیات ابزار، استدلال، جزئیات مصرف، و اقدام‌های elevated. انتخاب مدل و کنترل‌های exec-host هنوز به‌عنوان گزینه‌های پیکربندی ACP ارائه نشده‌اند.
• session_info_update و usage_update از snapshotهای نشست Gateway مشتق می‌شوند، نه حسابداری runtime زنده‌ی بومی ACP. مصرف تقریبی است، داده‌ی هزینه ندارد، و فقط وقتی صادر می‌شود که Gateway داده‌ی مجموع token را تازه علامت‌گذاری کند.
• داده‌ی همراه ابزار best-effort است. پل می‌تواند مسیرهای فایلی را که در args/results شناخته‌شده‌ی ابزار ظاهر می‌شوند نمایش دهد، اما هنوز ترمینال‌های ACP یا diffهای ساختاریافته‌ی فایل را صادر نمی‌کند.
• انتقال تایید exec به نوبت فعال اعلان ACP محدود است؛ تاییدیه‌های نشست‌های دیگر Gateway نادیده گرفته می‌شوند.

استفاده

OmeniaClaw acp # Remote GatewayOmeniaClaw acp --url wss://gateway-host:18789 --token <token> # Remote Gateway (token from file)OmeniaClaw acp --url wss://gateway-host:18789 --token-file ~/.OmeniaClaw/gateway.token # Attach to an existing session keyOmeniaClaw acp --session agent:main:main # Attach by label (must already exist)OmeniaClaw acp --session-label "support inbox" # Reset the session key before the first promptOmeniaClaw acp --session agent:main:main --reset-session

مشتری ACP (debug)

از مشتری ACP داخلی برای sanity-check پل بدون IDE استفاده کنید. این ابزار پل ACP را spawn می‌کند و اجازه می‌دهد اعلان‌ها را به‌صورت تعاملی تایپ کنید.

OmeniaClaw acp client # Point the spawned bridge at a remote GatewayOmeniaClaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.OmeniaClaw/gateway.token # Override the server command (default: OmeniaClaw)OmeniaClaw acp client --server "node" --server-args OmeniaClaw.mjs acp --url ws://127.0.0.1:19001

مدل مجوزها (حالت debug مشتری):

• تایید خودکار مبتنی بر allowlist است و فقط برای شناسه‌های ابزار core مورد اعتماد اعمال می‌شود.
• تایید خودکار read به دایرکتوری کاری فعلی محدود است (--cwd وقتی تنظیم شده باشد).
• ACP فقط کلاس‌های readonly محدود را خودکار تایید می‌کند: فراخوانی‌های scoped read زیر cwd فعال به‌علاوه ابزارهای جست‌وجوی readonly (search, web_search, memory_search). ابزارهای ناشناخته/غیر core، خواندن‌های خارج از محدوده، ابزارهای دارای قابلیت exec، ابزارهای control-plane، ابزارهای تغییر‌دهنده، و جریان‌های تعاملی همیشه به تایید صریح اعلان نیاز دارند.
• toolCall.kind ارائه‌شده توسط سرور به‌عنوان فراداده‌ی غیرقابل اعتماد در نظر گرفته می‌شود (نه منبع authorization).
• این سیاست پل ACP از مجوزهای harness مربوط به ACPX جدا است. اگر OmeniaClaw را از طریق backend acpx اجرا می‌کنید، plugins.entries.acpx.config.permissionMode=approve-all سوئیچ اضطراری "yolo" برای آن نشست harness است.

Smoke testing پروتکل

برای debugging در سطح پروتکل، یک Gateway را با وضعیت ایزوله شروع کنید و OmeniaClaw acp را از طریق stdio با یک مشتری ACP JSON-RPC هدایت کنید. initialize، session/new، session/list با یک cwd مطلق، session/resume، session/close، close تکراری، و resume مفقود را پوشش دهید.

اثبات باید قابلیت‌های lifecycle اعلام‌شده، یک ردیف نشست متکی بر Gateway، اعلان‌های به‌روزرسانی، و log مربوط به sessions.list در Gateway را شامل شود:

{  "initialize": {    "protocolVersion": 1,    "agentCapabilities": {      "sessionCapabilities": {        "list": {},        "resume": {},        "close": {}      }    }  },  "listSessions": {    "sessions": [      {        "sessionId": "agent:main:acp-smoke",        "cwd": "/path/to/workspace",        "_meta": {          "sessionKey": "agent:main:acp-smoke",          "kind": "direct"        }      }    ],    "nextCursor": null  },  "notifications": ["session_info_update", "available_commands_update", "usage_update"],  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]}

از استفاده از OmeniaClaw gateway call sessions.list به‌عنوان تنها اثبات ACP خودداری کنید. آن مسیر CLI ممکن است ارتقای محدوده‌ی operator با token تازه درخواست کند؛ درستی پل ACP با frameهای stdio مربوط به ACP به‌علاوه log مربوط به sessions.list در Gateway اثبات می‌شود.

روش استفاده از این

وقتی یک IDE (یا مشتری دیگر) با Agent Client Protocol صحبت می‌کند و می‌خواهید یک نشست OmeniaClaw Gateway را هدایت کند، از ACP استفاده کنید.

1. مطمئن شوید Gateway اجرا شده است (محلی یا راه‌دور).
2. هدف Gateway را پیکربندی کنید (config یا flagها).
3. IDE خود را طوری تنظیم کنید که OmeniaClaw acp را از طریق stdio اجرا کند.

نمونه config (ماندگار):

OmeniaClaw config set gateway.remote.url wss://gateway-host:18789OmeniaClaw config set gateway.remote.token <token>

نمونه اجرای مستقیم (بدون نوشتن config):

OmeniaClaw acp --url wss://gateway-host:18789 --token <token># preferred for local process safetyOmeniaClaw acp --url wss://gateway-host:18789 --token-file ~/.OmeniaClaw/gateway.token

انتخاب عامل‌ها

ACP عامل‌ها را مستقیما انتخاب نمی‌کند. بر اساس کلید نشست Gateway مسیریابی می‌کند.

برای هدف‌گیری یک عامل مشخص، از کلیدهای نشست با scope عامل استفاده کنید:

OmeniaClaw acp --session agent:main:mainOmeniaClaw acp --session agent:design:mainOmeniaClaw acp --session agent:qa:bug-123

هر نشست ACP به یک کلید نشست Gateway واحد نگاشت می‌شود. یک عامل می‌تواند نشست‌های زیادی داشته باشد؛ ACP به‌طور پیش‌فرض از یک نشست ایزوله‌ی acp:<uuid> استفاده می‌کند، مگر اینکه کلید یا برچسب را بازنویسی کنید.

mcpServers برای هر نشست در حالت پل پشتیبانی نمی‌شود. اگر یک سرویس‌گیرنده‌ی ACP آن‌ها را هنگام newSession یا loadSession ارسال کند، پل به‌جای نادیده گرفتن بی‌صدای آن‌ها، یک خطای روشن برمی‌گرداند.

اگر می‌خواهید نشست‌های مبتنی بر ACPX ابزارهای Plugin در OmeniaClaw یا ابزارهای داخلی منتخب مانند cron را ببینند، به‌جای تلاش برای پاس دادن mcpServers برای هر نشست، پل‌های ACPX MCP سمت Gateway را فعال کنید. ببینید عامل‌های ACP و پل MCP ابزارهای OmeniaClaw.

استفاده از acpx (Codex، Claude، سایر سرویس‌گیرنده‌های ACP)

اگر می‌خواهید یک عامل کدنویسی مانند Codex یا Claude Code از طریق ACP با بات OmeniaClaw شما صحبت کند، از acpx با هدف داخلی OmeniaClaw آن استفاده کنید.

جریان معمول:

1. Gateway را اجرا کنید و مطمئن شوید پل ACP می‌تواند به آن دسترسی پیدا کند.
2. acpx OmeniaClaw را به OmeniaClaw acp اشاره دهید.
3. کلید نشست OmeniaClaw را که می‌خواهید عامل کدنویسی استفاده کند هدف بگیرید.

مثال‌ها:

# One-shot request into your default OmeniaClaw ACP sessionacpx OmeniaClaw exec "Summarize the active OmeniaClaw session state." # Persistent named session for follow-up turnsacpx OmeniaClaw sessions ensure --name codex-bridgeacpx OmeniaClaw -s codex-bridge --cwd /path/to/repo \  "Ask my OmeniaClaw work agent for recent context relevant to this repo."

اگر می‌خواهید acpx OmeniaClaw هر بار یک Gateway و کلید نشست مشخص را هدف بگیرد، فرمان عامل OmeniaClaw را در ~/.acpx/config.json بازنویسی کنید:

{  "agents": {    "OmeniaClaw": {      "command": "env OmeniaClaw_HIDE_BANNER=1 OmeniaClaw_SUPPRESS_NOTES=1 OmeniaClaw acp --url ws://127.0.0.1:18789 --token-file ~/.OmeniaClaw/gateway.token --session agent:main:main"    }  }}

برای یک checkout محلی OmeniaClaw در مخزن، به‌جای اجراکننده‌ی توسعه از نقطه‌ورود مستقیم CLI استفاده کنید تا جریان ACP تمیز بماند. برای مثال:

env OmeniaClaw_HIDE_BANNER=1 OmeniaClaw_SUPPRESS_NOTES=1 node OmeniaClaw.mjs acp ...

این ساده‌ترین راه است تا Codex، Claude Code، یا یک سرویس‌گیرنده‌ی دیگر آگاه از ACP بتواند اطلاعات زمینه‌ای را از یک عامل OmeniaClaw بدون scraping ترمینال بیرون بکشد.

راه‌اندازی ویرایشگر Zed

یک عامل ACP سفارشی در ~/.config/zed/settings.json اضافه کنید (یا از رابط تنظیمات Zed استفاده کنید):

{  "agent_servers": {    "OmeniaClaw ACP": {      "type": "custom",      "command": "OmeniaClaw",      "args": ["acp"],      "env": {}    }  }}

برای هدف گرفتن یک Gateway یا عامل مشخص:

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

در Zed، پنل Agent را باز کنید و برای شروع یک رشته، "OmeniaClaw ACP" را انتخاب کنید.

نگاشت نشست

به‌طور پیش‌فرض، نشست‌های ACP یک کلید نشست Gateway ایزوله با پیشوند acp: دریافت می‌کنند. برای استفاده‌ی مجدد از یک نشست شناخته‌شده، یک کلید نشست یا برچسب پاس دهید:

• --session <key>: از یک کلید نشست Gateway مشخص استفاده کنید.
• --session-label <label>: یک نشست موجود را بر اساس برچسب resolve کنید.
• --reset-session: برای آن کلید یک شناسه‌ی نشست تازه mint کنید (همان کلید، transcript جدید).

اگر سرویس‌گیرنده‌ی ACP شما از فراداده پشتیبانی می‌کند، می‌توانید برای هر نشست بازنویسی کنید:

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

درباره‌ی کلیدهای نشست در /concepts/session بیشتر بیاموزید.

گزینه‌ها

• --url <url>: URL WebSocket برای Gateway (وقتی پیکربندی شده باشد، پیش‌فرض gateway.remote.url است).
• --token <token>: توکن احراز هویت Gateway.
• --token-file <path>: توکن احراز هویت Gateway را از فایل بخوانید.
• --password <password>: گذرواژه‌ی احراز هویت Gateway.
• --password-file <path>: گذرواژه‌ی احراز هویت Gateway را از فایل بخوانید.
• --session <key>: کلید نشست پیش‌فرض.
• --session-label <label>: برچسب نشست پیش‌فرض برای resolve کردن.
• --require-existing: اگر کلید/برچسب نشست وجود ندارد شکست بخور.
• --reset-session: کلید نشست را پیش از اولین استفاده reset کن.
• --no-prefix-cwd: پیشوند پوشه‌ی کاری را به promptها اضافه نکن.
• --provenance <off|meta|meta+receipt>: فراداده یا receiptهای provenance مربوط به ACP را شامل کن.
• --verbose, -v: ثبت لاگ مفصل در stderr.

نکته‌ی امنیتی:

• --token و --password در برخی سیستم‌ها می‌توانند در فهرست فرایندهای محلی قابل مشاهده باشند.
• --token-file/--password-file یا متغیرهای محیطی (OmeniaClaw_GATEWAY_TOKEN, OmeniaClaw_GATEWAY_PASSWORD) را ترجیح دهید.
• resolve احراز هویت Gateway از قرارداد مشترک استفاده‌شده توسط سایر سرویس‌گیرنده‌های Gateway پیروی می‌کند:
  • حالت محلی: env (OmeniaClaw_GATEWAY_*) -> gateway.auth.* -> fallback به gateway.remote.* فقط وقتی gateway.auth.* تنظیم نشده باشد (SecretRefهای محلی پیکربندی‌شده اما resolveنشده fail closed می‌شوند)
  • حالت remote: gateway.remote.* با fallback env/config طبق قواعد تقدم remote
  • --url برای override امن است و credentialهای ضمنی config/env را دوباره استفاده نمی‌کند؛ --token/--password صریح (یا گونه‌های فایل) را پاس دهید
• فرایندهای فرزند backend زمان اجرای ACP مقدار OmeniaClaw_SHELL=acp را دریافت می‌کنند، که می‌تواند برای قواعد shell/profile مختص زمینه استفاده شود.
• OmeniaClaw acp client مقدار OmeniaClaw_SHELL=acp-client را روی فرایند پل spawnشده تنظیم می‌کند.

گزینه‌های acp client

• --cwd <dir>: پوشه‌ی کاری برای نشست ACP.
• --server <command>: فرمان سرور ACP (پیش‌فرض: OmeniaClaw).
• --server-args <args...>: آرگومان‌های اضافی پاس‌داده‌شده به سرور ACP.
• --server-verbose: ثبت لاگ مفصل را روی سرور ACP فعال کن.
• --verbose, -v: ثبت لاگ مفصل سرویس‌گیرنده.

مرتبط

• مرجع CLI
• عامل‌های ACP