acp

Chạy ACP (Agent Client Protocol) bridge để kết nối với OpenClaw Gateway.

Lệnh này giao tiếp ACP qua stdio cho các IDE và chuyển tiếp prompt tới Gateway qua WebSocket. Nó giữ mapping giữa ACP session và Gateway session key.

Cách dùng

openclaw acp

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

# Attach vào một session key đã có
openclaw acp --session agent:main:main

# Attach theo label (phải tồn tại trước)
openclaw acp --session-label "support inbox"

# Reset session key trước prompt đầu tiên
openclaw acp --session agent:main:main --reset-session

ACP client (debug)

Dùng ACP client tích hợp sẵn để kiểm tra bridge mà không cần IDE. Nó sẽ spawn ACP bridge và cho phép các bạn nhập prompt tương tác.

openclaw acp client

# Trỏ bridge tới remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token <token>

# Override lệnh server (mặc định: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

Cách sử dụng

Dùng ACP khi IDE (hoặc client khác) hỗ trợ Agent Client Protocol và các bạn muốn nó điều khiển một OpenClaw Gateway session.

Đảm bảo Gateway đang chạy (local hoặc remote).
Cấu hình Gateway target (qua config hoặc flags).
Trỏ IDE của các bạn chạy openclaw acp qua stdio.

Ví dụ config (lưu vĩnh viễn):

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

Ví dụ chạy trực tiếp (không ghi config):

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

Chọn agent

ACP không chọn agent trực tiếp. Nó routing theo Gateway session key.

Dùng agent-scoped session key để target một agent cụ thể:

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

Mỗi ACP session map tới một Gateway session key duy nhất. Một agent có thể có nhiều session; ACP mặc định tạo session riêng biệt acp:<uuid> trừ khi các bạn override key hoặc label.

Thiết lập Zed editor

Thêm custom ACP agent vào ~/.config/zed/settings.json (hoặc dùng Settings UI của Zed):

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

Để target một Gateway hoặc agent cụ thể:

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

Trong Zed, mở Agent panel và chọn “OpenClaw ACP” để bắt đầu một thread.

Session mapping

Mặc định, ACP session sẽ có một Gateway session key riêng biệt với prefix acp:. Để dùng lại một session đã biết, truyền session key hoặc label:

--session <key>: dùng một Gateway session key cụ thể.
--session-label <label>: resolve một session đã có theo label.
--reset-session: tạo session id mới cho key đó (cùng key, transcript mới).

Nếu ACP client của các bạn hỗ trợ metadata, các bạn có thể override theo từng session:

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

Tìm hiểu thêm về session key tại /concepts/session.

Tùy chọn

--url <url>: Gateway WebSocket URL (mặc định là gateway.remote.url khi đã cấu hình).
--token <token>: Gateway auth token.
--password <password>: Gateway auth password.
--session <key>: session key mặc định.
--session-label <label>: session label mặc định để resolve.
--require-existing: fail nếu session key/label không tồn tại.
--reset-session: reset session key trước khi dùng lần đầu.
--no-prefix-cwd: không thêm working directory vào đầu prompt.
--verbose, -v: bật verbose logging ra stderr.

Tùy chọn `acp client`

--cwd <dir>: working directory cho ACP session.
--server <command>: lệnh ACP server (mặc định: openclaw).
--server-args <args...>: tham số bổ sung truyền cho ACP server.
--server-verbose: bật verbose logging trên ACP server.
--verbose, -v: bật verbose client logging.

acp