ACP

เรียกใช้บริดจ์ Agent Client Protocol (ACP) ที่สื่อสารกับ OpenClaw Gateway

openclaw acp สื่อสารด้วย ACP ผ่าน stdio สำหรับ IDE และส่งต่อพรอมต์ไปยัง Gateway ผ่าน WebSocket โดยคงการแมปเซสชัน ACP กับคีย์เซสชันของ Gateway ไว้ บริดจ์นี้เป็นบริดจ์ ACP ที่มี Gateway เป็นระบบเบื้องหลัง ไม่ใช่รันไทม์เอดิเตอร์แบบ ACP-native เต็มรูปแบบ โดยมุ่งเน้นการกำหนดเส้นทางเซสชัน การส่งพรอมต์ และการสตรีมการอัปเดต

หากต้องการให้ไคลเอนต์ MCP ภายนอกสื่อสารโดยตรงกับบทสนทนาในช่องทางของ OpenClaw แทนการโฮสต์เซสชัน ACP harness ให้ใช้ openclaw mcp serve แทน

สิ่งที่เครื่องมือนี้ไม่ใช่

openclaw acp หมายถึง OpenClaw ทำหน้าที่เป็นเซิร์ฟเวอร์ ACP กล่าวคือ IDE หรือไคลเอนต์ ACP จะเชื่อมต่อกับ OpenClaw และ OpenClaw จะส่งต่องานนั้นเข้าสู่เซสชัน Gateway

สิ่งนี้แตกต่างจาก เอเจนต์ ACP ซึ่ง OpenClaw จะเรียกใช้ harness ภายนอก เช่น Codex หรือ Claude Code ผ่าน acpx

กฎโดยย่อ:

• เอดิเตอร์/ไคลเอนต์ต้องการสื่อสารด้วย ACP กับ OpenClaw: ใช้ openclaw acp
• OpenClaw ต้องเรียกใช้ Codex/Claude/Gemini เป็น ACP harness: ใช้ /acp spawn และ เอเจนต์ ACP

ตารางความเข้ากันได้

ข้อจำกัดที่ทราบ

• loadSession เล่นประวัติบัญชีเหตุการณ์ ACP ทั้งหมดซ้ำได้เฉพาะเซสชันที่สร้างโดยบริดจ์ เซสชันเก่าหรือไม่มีบัญชีเหตุการณ์จะใช้ทรานสคริปต์สำรอง และจะไม่สร้างการเรียกใช้เครื่องมือหรือประกาศจากระบบในอดีตขึ้นใหม่
• หากไคลเอนต์ ACP หลายตัวใช้คีย์เซสชัน Gateway เดียวกันร่วมกัน การกำหนดเส้นทางเหตุการณ์และการยกเลิกจะเป็นแบบพยายามให้ดีที่สุด แทนที่จะแยกตามไคลเอนต์อย่างเคร่งครัด ควรใช้เซสชัน acp-bridge:<uuid> แบบแยกที่เป็นค่าเริ่มต้นเมื่อต้องการเทิร์นเฉพาะเอดิเตอร์ที่สะอาด
• สถานะหยุดของ Gateway จะถูกแปลงเป็นเหตุผลการหยุดของ ACP แต่การแมปนี้ถ่ายทอดรายละเอียดได้น้อยกว่ารันไทม์แบบ ACP-native เต็มรูปแบบ
• ตัวควบคุมเซสชันเปิดเผยเฉพาะชุดย่อยที่เจาะจงของตัวปรับแต่ง Gateway ได้แก่ ระดับการคิด ความละเอียดของเครื่องมือ การให้เหตุผล รายละเอียดการใช้งาน และการดำเนินการแบบยกระดับ การเลือกโมเดลและตัวควบคุมโฮสต์การเรียกใช้คำสั่งจะไม่เปิดเผยเป็นตัวเลือกการกำหนดค่า ACP
• session_info_update และ usage_update มาจากสแนปช็อตเซสชัน Gateway ไม่ใช่การบัญชีรันไทม์แบบ ACP-native แบบสด การใช้งานเป็นค่าประมาณ ไม่มีข้อมูลค่าใช้จ่าย และจะส่งเฉพาะเมื่อ Gateway ระบุว่าข้อมูลโทเค็นรวมเป็นข้อมูลล่าสุด
• ข้อมูลติดตามเครื่องมือเป็นแบบพยายามให้ดีที่สุด โดยบริดจ์จะเปิดเผยพาธไฟล์ที่ปรากฏในอาร์กิวเมนต์/ผลลัพธ์ของเครื่องมือที่รู้จัก แต่จะไม่ส่งเทอร์มินัล ACP หรือ diff ไฟล์แบบมีโครงสร้าง
• การส่งต่อการอนุมัติการเรียกใช้คำสั่งมีขอบเขตเฉพาะเทิร์นพรอมต์ ACP ที่ทำงานอยู่ โดยจะละเว้นการอนุมัติจากเซสชัน Gateway อื่น

การใช้งาน

openclaw acp # Gateway ระยะไกลopenclaw acp --url wss://gateway-host:18789 --token <token> # Gateway ระยะไกล (โทเค็นจากไฟล์)openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # เชื่อมต่อกับคีย์เซสชันที่มีอยู่openclaw acp --session agent:main:main # เชื่อมต่อด้วยป้ายกำกับ (ต้องมีอยู่แล้ว)openclaw acp --session-label "support inbox" # รีเซ็ตคีย์เซสชันก่อนพรอมต์แรกopenclaw acp --session agent:main:main --reset-session

ไคลเอนต์ ACP (การดีบัก)

ใช้ไคลเอนต์ ACP ในตัวเพื่อตรวจสอบความสมเหตุสมผลของบริดจ์โดยไม่ต้องใช้ IDE ไคลเอนต์จะสร้างกระบวนการบริดจ์ ACP และให้คุณพิมพ์พรอมต์แบบโต้ตอบได้

openclaw acp client # ให้บริดจ์ที่สร้างขึ้นชี้ไปยัง Gateway ระยะไกลopenclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # แทนที่คำสั่งเซิร์ฟเวอร์ (ค่าเริ่มต้น: openclaw)openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

โมเดลสิทธิ์ (โหมดดีบักไคลเอนต์):

• การอนุมัติอัตโนมัติอิงตามรายการที่อนุญาต และใช้กับรหัสเครื่องมือหลักที่เชื่อถือได้เท่านั้น
• การอนุมัติ read อัตโนมัติมีขอบเขตเฉพาะไดเรกทอรีทำงานปัจจุบัน (--cwd เมื่อตั้งค่า)
• ACP จะอนุมัติอัตโนมัติเฉพาะคลาสแบบอ่านอย่างเดียวที่จำกัด ได้แก่ การเรียก read ที่อยู่ภายใต้ cwd ที่ใช้งานอยู่ รวมถึงเครื่องมือค้นหาแบบอ่านอย่างเดียว (search, web_search, memory_search) เครื่องมือที่ไม่รู้จัก/ไม่ใช่เครื่องมือหลัก การอ่านนอกขอบเขต เครื่องมือที่สามารถเรียกใช้คำสั่ง เครื่องมือส่วนควบคุม เครื่องมือที่แก้ไขข้อมูล และโฟลว์แบบโต้ตอบ ต้องได้รับการอนุมัติพรอมต์อย่างชัดแจ้งเสมอ
• toolCall.kind ที่เซิร์ฟเวอร์ให้มาจะถือเป็นเมทาดาทาที่ไม่น่าเชื่อถือ ไม่ใช่แหล่งที่มาของการให้สิทธิ์
• นโยบายบริดจ์ ACP นี้แยกจากสิทธิ์ของ ACPX harness หากเรียกใช้ OpenClaw ผ่านแบ็กเอนด์ acpx ค่า plugins.entries.acpx.config.permissionMode=approve-all คือสวิตช์ฉุกเฉิน "yolo" สำหรับเซสชัน harness นั้น

การทดสอบเบื้องต้นของโปรโตคอล

สำหรับการดีบักระดับโปรโตคอล ให้เริ่ม Gateway ด้วยสถานะแบบแยก และควบคุม openclaw acp ผ่าน stdio ด้วยไคลเอนต์ ACP JSON-RPC โดยครอบคลุม initialize, session/new, session/list พร้อม cwd แบบสัมบูรณ์, session/resume, session/close, การปิดซ้ำ และการดำเนินการต่อที่ไม่มีอยู่

หลักฐานควรประกอบด้วยความสามารถด้านวงจรชีวิตที่ประกาศ แถวเซสชันที่มี Gateway เป็นระบบเบื้องหลัง การแจ้งเตือนการอัปเดต และบันทึก 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"]}

หลีกเลี่ยงการใช้ openclaw gateway call sessions.list เป็นหลักฐาน ACP เพียงอย่างเดียว เส้นทาง CLI นี้อาจร้องขอการยกระดับขอบเขตผู้ปฏิบัติงานด้วยโทเค็นใหม่ ความถูกต้องของบริดจ์ ACP พิสูจน์ได้ด้วยเฟรม ACP ผ่าน stdio ร่วมกับบันทึก sessions.list ของ Gateway

วิธีใช้

ใช้ ACP เมื่อ IDE (หรือไคลเอนต์อื่น) สื่อสารด้วย Agent Client Protocol และต้องการให้ไคลเอนต์นั้นควบคุมเซสชัน OpenClaw Gateway

1. ตรวจสอบว่า Gateway กำลังทำงานอยู่ (ในเครื่องหรือระยะไกล)
2. กำหนดค่าเป้าหมาย Gateway (การกำหนดค่าหรือแฟล็ก)
3. กำหนดให้ IDE เรียกใช้ openclaw acp ผ่าน stdio

ตัวอย่างการกำหนดค่า (บันทึกถาวร):

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

ตัวอย่างการเรียกใช้โดยตรง (ไม่เขียนการกำหนดค่า):

openclaw acp --url wss://gateway-host:18789 --token <token># แนะนำเพื่อความปลอดภัยของกระบวนการในเครื่องopenclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

การเลือกเอเจนต์

ACP ไม่ได้เลือกเอเจนต์โดยตรง แต่กำหนดเส้นทางตามคีย์เซสชัน Gateway ใช้คีย์เซสชันที่มีขอบเขตตามเอเจนต์เพื่อระบุเอเจนต์ที่ต้องการ:

openclaw acp --session agent:main:mainopenclaw acp --session agent:design:mainopenclaw acp --session agent:qa:bug-123

แต่ละเซสชัน ACP จะแมปกับคีย์เซสชัน Gateway หนึ่งคีย์ เอเจนต์หนึ่งตัวมีหลายเซสชันได้ โดยค่าเริ่มต้น ACP จะใช้เซสชัน acp-bridge:<uuid> แบบแยก เว้นแต่คุณจะแทนที่คีย์หรือป้ายกำกับ

ไม่รองรับ mcpServers แบบต่อเซสชันในโหมดบริดจ์ หากไคลเอนต์ ACP ส่งค่าเหล่านี้ระหว่าง newSession หรือ loadSession บริดจ์จะส่งข้อผิดพลาดที่ชัดเจนกลับไปแทนที่จะเพิกเฉยโดยไม่แจ้งให้ทราบ

หากคุณต้องการให้เซสชันที่ใช้ ACPX มองเห็นเครื่องมือ Plugin ของ OpenClaw หรือเครื่องมือในตัวที่เลือกไว้ เช่น cron ให้เปิดใช้งานบริดจ์ ACPX MCP ฝั่ง Gateway แทนการพยายามส่ง mcpServers แบบต่อเซสชัน ดู เอเจนต์ ACP และ บริดจ์ MCP สำหรับเครื่องมือ OpenClaw

การใช้งานจาก acpx (Codex, Claude และไคลเอนต์ ACP อื่น ๆ)

หากคุณต้องการให้เอเจนต์เขียนโค้ด เช่น Codex หรือ Claude Code สื่อสารกับบอต OpenClaw ของคุณผ่าน ACP ให้ใช้ acpx กับเป้าหมาย openclaw ที่มีมาให้ในตัว

ขั้นตอนทั่วไป:

1. เรียกใช้ Gateway และตรวจสอบว่าบริดจ์ ACP สามารถเชื่อมต่อถึง Gateway ได้
2. กำหนดให้ acpx openclaw ชี้ไปยัง openclaw acp
3. ระบุคีย์เซสชัน OpenClaw ที่คุณต้องการให้เอเจนต์เขียนโค้ดใช้

ตัวอย่าง:

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

หากคุณต้องการให้ acpx openclaw กำหนดเป้าหมายเป็น Gateway และคีย์เซสชันที่ระบุทุกครั้ง ให้เขียนทับคำสั่งเอเจนต์ openclaw ใน ~/.acpx/config.json:

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

สำหรับเช็กเอาต์ OpenClaw ภายในที่เก็บโค้ด ให้ใช้จุดเริ่มต้น CLI โดยตรงแทนตัวเรียกใช้สำหรับการพัฒนา เพื่อให้สตรีม ACP ไม่มีข้อมูลแทรก:

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

นี่เป็นวิธีที่ง่ายที่สุดในการให้ Codex, Claude Code หรือไคลเอนต์อื่นที่รองรับ ACP ดึงข้อมูลบริบทจากเอเจนต์ OpenClaw โดยไม่ต้องดึงข้อมูลจากเทอร์มินัล

การตั้งค่าตัวแก้ไข Zed

เพิ่มเอเจนต์ ACP แบบกำหนดเองใน ~/.config/zed/settings.json (หรือใช้ส่วนติดต่อการตั้งค่าของ Zed):

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

หากต้องการกำหนดเป้าหมายเป็น Gateway หรือเอเจนต์ที่ระบุ:

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

ใน Zed ให้เปิดแผง Agent แล้วเลือก "OpenClaw ACP" เพื่อเริ่มเธรด

การแมปเซสชัน

โดยค่าเริ่มต้น เซสชันบริดจ์ ACP จะได้รับคีย์เซสชัน Gateway แบบแยกเฉพาะ โดยมีคำนำหน้า acp-bridge: เซสชันบริดจ์ของโมเดลปกติเหล่านี้เป็นเซสชันสังเคราะห์และใช้แล้วทิ้ง โดยรายการที่ล้าสมัยอาจถูกลบออก และจะไม่ถือเป็นพื้นผิวการสนทนาของมนุษย์ที่ได้รับการปกป้อง หากต้องการนำเซสชันที่รู้จักกลับมาใช้ใหม่ ให้ส่งคีย์หรือป้ายกำกับเซสชัน:

• --session <key>: ใช้คีย์เซสชัน Gateway ที่ระบุ
• --session-label <label>: ค้นหาเซสชันที่มีอยู่ตามป้ายกำกับ
• --reset-session: สร้างรหัสเซสชันใหม่สำหรับคีย์นั้น (คีย์เดิม บันทึกบทสนทนาใหม่)

หากไคลเอนต์ 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>: ป้ายกำกับเซสชันเริ่มต้นสำหรับค้นหาเซสชัน
• --require-existing: ล้มเหลวหากไม่มีคีย์หรือป้ายกำกับเซสชัน
• --reset-session: รีเซ็ตคีย์เซสชันก่อนใช้งานครั้งแรก
• --no-prefix-cwd: ไม่ต้องเติมไดเรกทอรีทำงานไว้ข้างหน้าพรอมต์
• --provenance <off|meta|meta+receipt>: รวมข้อมูลเมตาหรือใบรับรองแหล่งที่มาของ ACP
• --verbose, -v: บันทึกข้อมูลโดยละเอียดไปยัง stderr

หมายเหตุด้านความปลอดภัย:

• --token และ --password อาจปรากฏในรายการกระบวนการภายในเครื่องบนบางระบบ ควรใช้ --token-file/--password-file หรือตัวแปรสภาพแวดล้อม (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD)
• การแก้ไขค่าการยืนยันตัวตนของ Gateway เป็นไปตามสัญญาร่วมที่ไคลเอนต์ Gateway อื่นใช้:
  • โหมดภายในเครื่อง: ตัวแปรสภาพแวดล้อม (OPENCLAW_GATEWAY_*) ตามด้วย gateway.auth.* และจะย้อนกลับไปใช้ gateway.remote.* เฉพาะเมื่อไม่ได้ตั้งค่า gateway.auth.* เท่านั้น (SecretRef ภายในเครื่องที่กำหนดค่าไว้แต่ไม่สามารถแก้ไขค่าได้จะล้มเหลวแบบปิด แทนที่จะย้อนกลับไปใช้ค่าอื่นโดยไม่แจ้ง)
  • โหมดระยะไกล: gateway.remote.* พร้อมการย้อนกลับไปใช้ตัวแปรสภาพแวดล้อม/การกำหนดค่าตามกฎลำดับความสำคัญของโหมดระยะไกล
  • --url สามารถเขียนทับได้อย่างปลอดภัยและจะไม่นำข้อมูลประจำตัวโดยนัยจากการกำหนดค่า/ตัวแปรสภาพแวดล้อมกลับมาใช้ใหม่ ให้ส่ง --token/--password อย่างชัดเจน (หรือรูปแบบไฟล์)

ตัวเลือก acp client

• --cwd <dir>: ไดเรกทอรีทำงานสำหรับเซสชัน ACP
• --server <command>: คำสั่งเซิร์ฟเวอร์ ACP (ค่าเริ่มต้น: openclaw)
• --server-args <args...>: อาร์กิวเมนต์เพิ่มเติมที่ส่งไปยังเซิร์ฟเวอร์ ACP
• --server-verbose: เปิดใช้งานการบันทึกข้อมูลโดยละเอียดบนเซิร์ฟเวอร์ ACP
• --verbose, -v: การบันทึกข้อมูลไคลเอนต์โดยละเอียด
• openclaw acp client ตั้งค่า OPENCLAW_SHELL=acp-client ให้กับกระบวนการบริดจ์ที่ถูกสร้างขึ้น ซึ่งสามารถใช้กับกฎเชลล์/โปรไฟล์เฉพาะบริบทได้

ที่เกี่ยวข้อง

• ข้อมูลอ้างอิง CLI
• เอเจนต์ ACP