bot/docs/cli/acp.md at fix/post-merge-test-and-build-failures

mirror of https://github.com/hanzoai/bot.git synced 2026-11-01 18:02:28 +00:00

Files

T

Vincent KocandGitHub 25136e5cd3 Exec/ACP: inject OPENCLAW_SHELL into child shell env (#31271 )

* exec: mark runtime shell context in exec env

* tests(exec): cover OPENCLAW_SHELL in gateway exec

* tests(exec): cover OPENCLAW_SHELL in pty mode

* acpx: mark runtime shell context for spawned process

* tests(acpx): log OPENCLAW_SHELL in runtime fixture

* tests(acpx): assert OPENCLAW_SHELL in runtime prompt

* docs(env): document OPENCLAW_SHELL runtime markers

* docs(exec): describe OPENCLAW_SHELL exec marker

* docs(acp): document OPENCLAW_SHELL acp marker

* docs(gateway): note OPENCLAW_SHELL for background exec

* tui: tag local shell runs with OPENCLAW_SHELL

* tests(tui): assert OPENCLAW_SHELL in local shell runner

* acp client: tag spawned bridge env with OPENCLAW_SHELL

* tests(acp): cover acp client OPENCLAW_SHELL env helper

* docs(env): include acp-client and tui-local shell markers

* docs(acp): document acp-client OPENCLAW_SHELL marker

* docs(tui): document tui-local OPENCLAW_SHELL marker

* exec: keep shell runtime env string-only for docker args

* changelog: note OPENCLAW_SHELL runtime markers

2026-03-01 20:31:06 -08:00

4.4 KiB

Raw Permalink Blame History

summary, read_when, title

summary

read_when

title

Run the ACP bridge for IDE integrations

Setting up ACP-based IDE integrations

Debugging ACP session routing to the Gateway

acp

Run the ACP (Agent Client Protocol) bridge that talks to a Hanzo Bot Gateway.

This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway over WebSocket. It keeps ACP sessions mapped to Gateway session keys.

Usage

hanzo-bot acp

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

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

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

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

ACP client (debug)

Use the built-in ACP client to sanity-check the bridge without an IDE. It spawns the ACP bridge and lets you type prompts interactively.

hanzo-bot acp client

# Point the spawned bridge at a remote Gateway
hanzo-bot acp client --server-args --url wss://gateway-host:18789 --token <token>

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

How to use this

Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want it to drive a Hanzo Bot Gateway session.

Ensure the Gateway is running (local or remote).
Configure the Gateway target (config or flags).
Point your IDE to run hanzo-bot acp over stdio.

Example config (persisted):

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

Example direct run (no config write):

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

Selecting agents

ACP does not pick agents directly. It routes by the Gateway session key.

Use agent-scoped session keys to target a specific agent:

hanzo-bot acp --session agent:main:main
hanzo-bot acp --session agent:design:main
hanzo-bot acp --session agent:qa:bug-123

Each ACP session maps to a single Gateway session key. One agent can have many sessions; ACP defaults to an isolated acp:<uuid> session unless you override the key or label.

Zed editor setup

Add a custom ACP agent in ~/.config/zed/settings.json (or use Zed’s Settings UI):

{
  "agent_servers": {
    "Hanzo Bot ACP": {
      "type": "custom",
      "command": "bot",
      "args": ["acp"],
      "env": {}
    }
  }
}

To target a specific Gateway or agent:

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

In Zed, open the Agent panel and select “Hanzo Bot ACP” to start a thread.

Session mapping

By default, ACP sessions get an isolated Gateway session key with an acp: prefix. To reuse a known session, pass a session key or label:

--session <key>: use a specific Gateway session key.
--session-label <label>: resolve an existing session by label.
--reset-session: mint a fresh session id for that key (same key, new transcript).

If your ACP client supports metadata, you can override per session:

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

Learn more about session keys at /concepts/session.

Options

--url <url>: Gateway WebSocket URL (defaults to gateway.remote.url when configured).
--token <token>: Gateway auth token.
--password <password>: Gateway auth password.
--session <key>: default session key.
--session-label <label>: default session label to resolve.
--require-existing: fail if the session key/label does not exist.
--reset-session: reset the session key before first use.
--no-prefix-cwd: do not prefix prompts with the working directory.
--verbose, -v: verbose logging to stderr.

`acp client` options

--cwd <dir>: working directory for the ACP session.
--server <command>: ACP server command (default: bot).
--server-args <args...>: extra arguments passed to the ACP server.
--server-verbose: enable verbose logging on the ACP server.
--verbose, -v: verbose client logging.

4.4 KiB Raw Permalink Blame History Unescape Escape

acp