configuration reference

配置参考

全部旋钮都在一个 agents.json 里，CLI 只有两组旗标。这页列出每个字段的类型、默认值与可选取值，以及 codex 沙箱/审批的取舍指南。

modes

模式与命令

一条命令、两种模式，共用同一份配置文件：

命令	做什么
`agent-bridge serve`	默认模式。每个配置条目起一个桥，各自监听自己的端口（HTTP+SSE，可选加 WS 的 `/acp`）。
`agent-bridge acp <条目名>`	把单个条目变成 stdio 上的 ACP 智能体，供编辑器 spawn。stdout 只走协议，日志走 stderr，不开端口。

CLI 旗标只有这些：

旗标	适用	说明
`--config FILE`	两者	配置文件路径，默认 `./agents.json`（相对启动目录）。
`--bind ADDR`	仅 serve	监听地址，默认 `127.0.0.1`。绑定非回环地址时，所有条目必须填 `apiKey`，否则拒绝启动。在 acp 模式出现会被拒绝。
`--name NAME`	仅 acp	等价于位置参数 `<条目名>`。
`--help` / `-h`	两者	打印用法。

file

配置文件

JSON 格式，顶层是一个 bridges 数组，至少一条。每条就是一个桥：

agents.json

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

这是官方起步配置（agents.example.json，两种安装方式都自带）。name 只能取注册表里的名字：codex、claude、pi、gemini——长尾智能体在 agents-registry.mjs 加一行即可，不用放宽配置校验。

fields

字段总表

取值非法的字段会拒绝启动并逐条报错。未在表中的字段会被忽略。

字段	类型	默认	可取值	说明
身份与端口
name	string	—	codex claude pi gemini	必填。桥的身份，决定用哪个适配器；只能取注册表里的名字。
port	integer	—	1–65535	serve 模式必填，每桥唯一。只用于 `acp` 模式的条目可省略。
apiKey	string	—	任意字符串	空串或省略 = 免密（仅限回环监听）。绑定非回环地址时所有条目必填。
cwd	path	启动目录	路径	智能体的工作目录。支持 `~`；相对路径按 bridge 启动位置解析。
env	object	—	{VAR: 字符串}	合并进 daemon 环境传给被 spawn 的智能体；条目 env 覆盖注册表默认。
客户端门
acp	boolean	false	true false	`true` 时在此桥端口开启 WebSocket 上的 ACP 门 `ws://…/acp`。
corsOrigin	string	回环同源	"*"	默认只反射回环来源。`"*"` 是显式放开跨域的唯一取值——请与 `apiKey` 成对使用。
command	string[]	注册表默认	非空字符串数组	覆盖 ACP 壳的启动命令（如 `["npx","-y","@agentclientprotocol/claude-agent-acp"]`）。codex 不适用——它走原生适配器，请用 `codexBin`。
codex 调优仅 codex
codexBin	string	"codex"	路径或命令名	codex 可执行文件位置。
codexHome	string	codex 默认	路径	给 codex 进程设置 `CODEX_HOME`——用于多套 codex 配置/登录态并存。
sandbox	enum	read-only	read-only workspace-write danger-full-access	codex 沙箱档位，决定文件写入与联网的边界。见下节。
network	boolean	false	true false	`workspace-write` 档位下是否允许联网。只对这一档生效。
approval	enum	never	never on-request untrusted	审批策略——什么时候向你要确认。见下节。

codex · sandbox & approval

codex 沙箱与审批

这两个字段一起决定「codex 能自己做什么」和「什么时候弹卡问你」。都是在建会话时原样传给 codex 的（thread/start 的 sandbox 与 approvalPolicy），由 codex 自己执行边界。

sandbox — 沙箱档位

取值	文件写入	网络	适合
`read-only`	不允许	无	默认。纯阅读/分析/问答——任何写入或联网命令都算越界。
`workspace-write`	工作区内允许	仅当 `network: true`	日常开发推荐。改代码没问题，联网要显式开。
`danger-full-access`	任意位置	有	完全访问。风险自担——适合封闭环境或完全信任的自动化。

network 只在 workspace-write 下有意义：danger-full-access 天然带网络，read-only 忽略此字段。

approval — 审批策略

取值	什么时候弹卡
`never`	从不。越界动作直接失败，不打断你。
`on-request`	动作超出沙箱/策略给的权限时弹卡——最常见的「approve」卡片。
`untrusted`	最严：几乎所有命令执行都先问。

approve cards

审批卡多？配方在这

先说机制：bridge 不决定什么时候弹卡——是 codex 发起询问，bridge 原样转发给你的客户端。卡片变多，是「命令行为」与「sandbox / network / approval 三个字段的组合」不匹配的信号。

approval · command · codex

/bin/bash -lc "curl -L --fail --max-time 15 -s 'https://…' | rg -m 12 '…'"

once always deny

会触发卡片的三种情况：

命令要写入沙箱外的位置（比如 read-only 下装依赖、写日志）；
命令要联网但档位没开网络（workspace-write 且 network 不为 true 时，一个 curl 就中招）；
approval 策略要求确认（untrusted 几乎条条都问）。

想要「少问多做」的配方

完全访问——文件、网络、命令全部放开，codex 没有东西可问：

{ "name": "codex", "port": 3948,
  "sandbox": "danger-full-access", "approval": "never" }

折中方案——工作区可写 + 联网，日常够用且仍有边界：

{ "name": "codex", "port": 3948,
  "sandbox": "workspace-write", "network": true, "approval": "never" }

改动后对已有会话不生效

沙箱与审批策略在建会话时定下。改完 agents.json 记得重启 bridge 并开新会话，老会话还带着老策略。

for client implementers

审批线协议

给客户端作者的：审批在 v1 线协议里是一问一答。智能体发来一个 approval 事件（SSE 或 WS 帧），你把它渲染成卡片，用户拍板后回一个 HTTP 请求：

智能体 → 客户端（SSE data 帧）

{"type":"approval","requestId":"…","tool":"command","command":"…","cwd":"…"}

客户端 → bridge

POST /approvals/<requestId>
{ "choice": "once" | "always" | "deny" }   // → {"ok":true}

once 放行这一次，always 放行同类后续，deny 拒绝。requestId 必须原样回传——它可能是字符串。

security

安全边界

默认只听回环。--bind 绑非回环时，每个条目都必须有 apiKey（Bearer token），否则启动被拒。
Host 头白名单（防 DNS-rebinding）只对回环绑定生效；远程绑定靠 token 把关。
CORS 默认只反射回环来源；跨域要显式 "corsOrigin": "*"，并与 apiKey 成对。
配置文件含密钥：bridge 启动时发现 agents.json 权限过宽会警告——chmod 600 agents.json。
明文 HTTP：TLS 归反代（nginx/caddy）；bridge 已发 X-Accel-Buffering: no，SSE 过反代不缓冲。

fixed limits

固定限制

这些是刻意固定的协议常量，不可配置：

常量	值	为什么
请求体上限	`4 MB`	约束内联 base64 图片的体量。
图片数组上限	`8` 张	同上。
SSE 心跳	`15 s`	静默期发 `: ka` 注释帧保活。
断连语义	断连 = 中断	客户端掉线即中断当前回合，不留无人看的长任务。
回合回放	无	回合只直播；离开的回合不补发。
会话存活	跨 bridge 重启	会话由智能体自己持久化，重启后 resume 继续。

zero-setup

零配置回退

acp 模式有三级配置解析：显式 --config → 启动目录下的 agents.json → 注册表内置默认。最后这条让 agent-bridge acp claude 什么都不配就能跑（ACP Registry 的自动安装走的就是它）：直接用注册表里的默认命令启动智能体，并在 stderr 打印一行说明。