wire protocol · adapters · three doors

把本地 CLI 编码智能体，接到任何客户端

一个零依赖的 Node 守护进程：客户端只需实现一次，任何本地编码智能体（codex、claude、pi、gemini……）都通过适配器到达。会话、审批、断线中断由智能体自己持久化——bridge 只做翻译，不做聊天窗。

配置参考 → GitHub 上查看源码

v1 线协议（冻结） ACP 门（opt-in）智能体侧原生协议

three doors

三扇门，都通向同一批智能体

内置 HTTP+SSE（v1）

POST /turns · GET /sessions · SSE

极简线协议，随 bridge 始终开启。浏览器扩展、脚本、任何能发 HTTP 的东西都能接。协议已冻结，只增不改。

始终开启 · 每桥一个端口

WebSocket 上的 ACP

ws://host:port/acp

面向 ACP 生态的公开大门：acpx、acp-ui、移动端客户端直接连，不必学 v1。按桥开启。

条目写 "acp": true

stdio 上的 ACP agent

agent-bridge acp <条目名>

把单个配置条目变成一个可被 spawn 的 ACP 智能体——Zed、vscode-acp 这类编辑器把智能体当本地命令启动。

无端口 · stdout 只走协议

quick start

四步跑起来

安装

全局装 npm 包；或 clone 源码后用 node cli.mjs 替代 agent-bridge（零依赖，无构建）。
```
npm i -g @xiaohuzai/agent-bridge
```
建配置

在启动目录放一份 agents.json。没有配置时跑一次 agent-bridge serve，它会打印出对应你这次安装的复制命令：
```
cp /path/to/agents.example.json agents.json
```

启动

每个配置条目一个桥、一个端口。Ctrl+C 全停。

$ agent-bridge serve
agent-bridge serve: 4 bridges on http://127.0.0.1
  codex      :3948  (no api key — loopback only)
  claude     :3949  (no api key — loopback only)
  pi         :3950  (no api key — loopback only)
  gemini     :3951  (no api key — loopback only)
Point any wire-protocol client at these addresses.

接入客户端

把 v1 客户端指向打印的地址；编辑器则 spawn agent-bridge acp claude——没有配置文件也能跑（自动用内置默认命令启动智能体）。

agent 本身要先装好

bridge 不替你安装智能体：codex、claude、pi、gemini 各自安装并登录后，bridge 只负责把它们接到你的客户端。缺智能体的桥照常启动、照常回答 /health，第一个回合才报错并给出安装提示（含确切命令）。

npm i -g @openai/codex                                       # codex
npm i -g @anthropic-ai/claude-code @agentclientprotocol/claude-agent-acp  # claude
npm i -g pi-acp                                              # pi(壳;本体走官方自安装)
npm i -g @google/gemini-cli                                  # gemini

configuration

配置只有一个文件

全部旋钮都在 agents.json 里：端口、apiKey、运行目录、codex 的沙箱与审批策略、ACP 门的开关…… CLI 只有两组旗标，其余全是配置字段。

{
  "bridges": [
    { "name": "codex",  "port": 3948, "apiKey": "",
      "sandbox": "workspace-write", "approval": "on-request" },
    { "name": "claude", "port": 3949, "apiKey": "" },
    { "name": "pi",     "port": 3950, "apiKey": "" },
    { "name": "gemini", "port": 3951, "apiKey": "" }
  ]
}

完整配置参考列出每个字段的类型、默认值、可选取值，以及 codex 沙箱/审批的取舍指南（包括「想让 codex 少问多做」该配哪一行）。