ACP

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

สิ่งที่ไม่ใช่

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

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

​

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

​

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

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

​

การใช้งาน

openclaw acp

# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>

# Remote Gateway (token from file)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Attach to an existing session key
openclaw acp --session agent:main:main

# Attach by label (must already exist)
openclaw acp --session-label "support inbox"

# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session

​

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

openclaw acp client

# Point the spawned bridge at a remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Override the server command (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

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

​

การทดสอบ smoke ของโปรโตคอล

{
  "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"]
}

​

วิธีใช้สิ่งนี้

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

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

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

​

การเลือก agents

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

​

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

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

# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."

{
  "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"
    }
  }
}

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

​

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

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

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

​

การจับคู่เซสชัน

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

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

​

ตัวเลือก

• --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 อื่นใช้:
  • โหมด local: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> ใช้ gateway.remote.* เป็น fallback เฉพาะเมื่อไม่ได้ตั้งค่า gateway.auth.* (SecretRefs ภายในเครื่องที่กำหนดค่าไว้แต่แก้ค่าไม่ได้จะล้มเหลวแบบปิด)
  • โหมด remote: gateway.remote.* พร้อม fallback ของ env/config ตามกฎลำดับความสำคัญของ remote
  • --url แทนที่ได้อย่างปลอดภัยและจะไม่ใช้ข้อมูลประจำตัว config/env โดยนัยซ้ำ; ให้ส่ง --token/--password อย่างชัดเจน (หรือรูปแบบไฟล์)
• โปรเซสลูกของแบ็กเอนด์รันไทม์ ACP จะได้รับ OPENCLAW_SHELL=acp ซึ่งสามารถใช้กับกฎ shell/profile เฉพาะบริบทได้
• openclaw acp client ตั้งค่า OPENCLAW_SHELL=acp-client บนโปรเซสบริดจ์ที่สปอว์นขึ้น

​

ตัวเลือก acp client

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

​

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

• อ้างอิง CLI
• Agent ACP