# cli-bridge —— 把无头 CLI Agent 挂成 hub 的 connector `codex` / `claude` 这类 CLI 只会"一问一答开一个进程",没有服务端、不会被 hub 拨号。 本目录提供一个几百行的桥接进程,把它翻译成 hub 眼里的一个 **connector Agent**: ``` hub ── ws ──> bridge 进程 ──spawn──> codex exec / claude -p / codebuddy -p(一次性子进程) │ │ └── session_key ───────┘ 同一 key 的下发自动 --resume 续上同一段对话 ``` 思考、工具调用、沙箱都是 CLI 自己的事;bridge 只做三件事:**下发变子进程、JSONL 事件翻译成 hub 事件、session_key ↔ CLI 会话 id 的映射落盘**。所以新增一家 CLI = 写一个适配器文件, hub 侧零改动。 ## 能力矩阵(本机实测,2026-10-14) | | codex | claude | workbuddy | |---|---|---|---| | `task`(下发一次对话) | ✅ | ✅ | ✅ | | 事件流(正文/推理/工具/日志/usage) | ✅ | ✅ | ✅ 工具带成败 | | 续话(同 `session_key` 自动接上) | ✅ `exec resume` | ✅ `--resume` | ✅ `--resume` | | `agent.command`(会话内下达指令) | ✅ `codex queue` | ❌ 无原生注入 | ❌ 无原生注入 | | `cancel`(hub 取消 → 杀子进程) | ✅ | ✅ | ✅ 无孤儿进程 | | `describe`(版本/模型/会话数) | ✅ | ✅ | ✅ | claude 和 workbuddy 没有 `command` 是 **CLI 的限制**,不是桥的缺陷:它们的 `deliver()` 明确回一句 "请用同一 `session_key` 再发一个 task"(`hub` 上表现为 `delivered: false` + 原因),而不是假装成功。 ## 三步接入 ### 1. hub 上注册身份(hub 机器上执行) ```bash cd /backend && .venv/bin/python -m agenthub.cli \ agent add --name codex --display-name 'codex CLI' \ --connection connector --driver connector --show-token ``` 印出来的 `agent_token`(`ag_…`)下一步要用,并且随时能从控制台「接入」页「查看凭证」或 `agenthub config` 查回来。控制台「接入」向导等价。 ### 2. Agent 机器上启动桥接进程 ```bash python3 deploy/cli-bridge/bridge.py \ --hub http://:8100 --token ag_xxx \ --name codex --cli codex --workdir ~/code/my-project ``` `--workdir` 就是 CLI 干活的目录(子进程 cwd),一次进程只服务一个目录 —— 想让同一个 CLI 管多个仓库,就起多个桥接进程、注册成 `codex-api` / `codex-web` 这样的不同名字。 `--mode` 默认 `readonly`(codex `-s read-only`、claude `--permission-mode plan`),要允许改文件 才显式给 `--mode write`。默认保守是故意的:这台机器上的 Agent 能被 hub 远程下发,就不该默认有写权限。 ### 3. 验证 ```bash curl -s -H "X-API-Key: $KEY" http://:8100/api/v1/agents | python3 -m json.tool ``` 看到 `"status": "online"` 即通。刚连上的几秒里它可能还显示 offline,等心跳追上。下发: ```bash curl -s -X POST -H "X-API-Key: $KEY" -H 'Content-Type: application/json' -d '{ "agent_id": "agt_xxx", "prompt": "读一下 README 第一行,只回复那一行", "session_key": "ops", "wait": true }' http://:8100/api/v1/tasks ``` 第二个用同 `session_key: "ops"` 的 task 会自动续在上一段对话后面。中途下达指令(仅 codex): ```bash curl -s -X POST -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \ -d '{"command":"message","args":{"session_key":"ops","text":"改成只输出 JSON"}}' \ http://:8100/api/v1/agents/codex/command ``` 实测语义:返回 `delivered: true` 只代表**排进了队列**,正在跑的那一轮看不到它,下一个 task 才开始消费。要立刻生效只能 `POST /api/v1/tasks/{id}/cancel` 再重发。 ## 常驻(macOS LaunchAgent) ```bash mkdir -p ~/Library/LaunchAgents && cat > ~/Library/LaunchAgents/com.agenthub.cli-bridge.codex.plist <<'PLIST' Labelcom.agenthub.cli-bridge.codex ProgramArguments /Users/me/nex_agenthub/backend/.venv/bin/python /Users/me/nex_agenthub/deploy/cli-bridge/bridge.py --tokenag_xxx --namecodex --clicodex --workdir/Users/me/code/my-project EnvironmentVariables PATH/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin RunAtLoadKeepAlive StandardOutPath/Users/me/Library/Logs/agenthub-cli-bridge-codex.log StandardErrorPath/Users/me/Library/Logs/agenthub-cli-bridge-codex.log PLIST launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agenthub.cli-bridge.codex.plist ``` 三个坑,都踩过: - **`PATH` 必须显式给**。launchd 的默认 PATH 里没有 `/usr/local/bin`,`codex`/`claude` 会"找不到 可执行文件",而在你终端里手测是好的。 - **日志写 `~/Library/Logs/`**,别写 `/tmp`(重启即清,正好丢掉最需要的那段现场)。 - **卸载用 `launchctl bootout gui/$(id -u)/com.agenthub.cli-bridge.codex`**,不要 `kill -9`: `KeepAlive` 会让它立刻复活,而且强杀会把正在跑的 CLI 子进程变成孤儿。 会话映射存在 `~/.agenthub/cli-bridge-.json`(`--state` 可改)。桥接进程重启续话仍然接得上; 想开一段全新对话,删掉对应 key 或直接换 `session_key`。 ## 运行环境 - **Python ≥ 3.10**(SDK 用了 `@dataclass(slots=True)`)。macOS 自带的 `/usr/bin/python3` 是 3.9, 会在 import 阶段直接 TypeError。Agent 机器上没有 venv 就用 nvm/brew 的 3.12,或者 WorkBuddy 自带的 `~/.workbuddy/binaries/python/versions/3.13.x/bin/python3.13`。除 SDK 那三个文件外只用标准库。 - CLI 路径自动探测(`which`),探不到用环境变量覆盖:`CODEX_BIN`、`CLAUDE_BIN`、`WORKBUDDY_BIN`。 WorkBuddy 的 `codebuddy` 不在 PATH 里,适配器已内置 .app 内的绝对路径,装了别的位置就给 `WORKBUDDY_BIN`。 - 桥接进程连不上 hub 时会自己指数退避重连,不需要外部守护;但正在跑的 task 会随连接断开而失败。 ## 实测踩到的 CLI 坑(适配器里已处理,别改回去) 1. `codex exec resume` **不接受 `-C` 和 `-s`**(只有 `--json/--skip-git-repo-check/-c`), 照抄新会话那套参数 → 退出码 2。沙箱在 resume 时只能 `-c sandbox_mode="read-only"`。 2. claude 和 workbuddy 的 `--add-dir ` 都是**变长参数**,会把后面的位置参数 (也就是 prompt)一起吃掉,报 `Input must be provided either through stdin`。cwd 本来就是 workdir,不需要它;末尾用 `--` 分隔,防 prompt 以 `-` 开头。 3. claude 模型报错时 `result.subtype` 仍然是 `"success"`,**只有 `is_error` 是真的**。认错了就会 把 `API Error: 402` 当成正文结果上报给 hub。 4. resume 失败且这一轮没产出任何文本 → 桥会**丢弃这个 session_key 的映射**并在错误里说明, 否则一个坏掉的会话 id 会让这个 key 从此永久失败。 ## WorkBuddy 接入要点 WorkBuddy 桌面装在 `/Applications/WorkBuddy.app`,自带 CLI `codebuddy`(**不在 PATH 里**)。它同时 提供 `--serve`(Web UI + REST + ACP)和无头 `-p --output-format stream-json` 两种被驱动方式: - **本适配器走无头 CLI**(`--cli workbuddy`):和 codex/claude 完全一样的进程模型,hub 侧零改动。 `--serve` 是它的私有 ACP,**不提供** `/v1/chat/completions`,所以 hub 想 direct 直连必须新写一个 ACP driver —— 那是 hub 的活儿,不是这里的。 - 权限档:`readonly` → `--permission-mode plan`(实测仍允许 Glob/Read 这类只读工具); `write` → `--permission-mode acceptEdits`(实测 Write 和 Bash 都真放行,`out.txt` 落盘)。 - 无头模式没人应答授权,**被拒的工具不会报错也不会重试**,只在 `result.permission_denials` 里留痕。 适配器把它折进 `log` 事件,所以任务"没干成但不报错"时先看那里。 - 它的 `codebuddy` 入口脚本会 exec 成 node(同一个 pid,不产生进程树),所以 hub cancel 之后 不会有孤儿进程 —— 实测确认。 - 注意 `acceptEdits` 下它会往 `~/.codebuddy/projects/<项目>/memory/` 写自己的记忆文件, 那是 workdir 之外的写入。想让桥接进程绝对干净,就用默认的 `readonly`。 ### 为什么 WorkBuddy 桌面端里看不到 hub 下发的会话 不是配置错,是两套会话存储根本没打通(实测 5.5.6 / CLI 2.137.1): - App 的会话列表读它自己的 sqlite 索引 `~/.workbuddy/workbuddy.db` 的 `sessions` 表,行由 **App 建会话时**写入 (title/cwd/permission_mode/use_sandbox_cli 这些都是 UI 要用的),之后 App 再通过 ACP 拉起或挂载一个 codebuddy sidecar —— 证据:会话的 `*.meta.json` 里有 `acpConnectionId`,`~/.workbuddy/sessions/*.json` 里是每个会话自带的 `http://127.0.0.1:` endpoint。 - App 主进程 `configureElectronApp()` 给**它自己的**子进程设 `CODEBUDDY_CONFIG_DIR=~/.workbuddy`;我们起的 无头 CLI 没人设这个变量,默认落 `~/.codebuddy`,App 不读那棵树。反过来无头 CLI 也从不写 App 的 DB (`codebuddy.js` 里搜不到 `workbuddy.db`)。 - deep link 只有 `workbuddy://chat/`(以及 `home`、`experts?expertId=`),只能**跳到已存在的会话**, 没有"带 prompt 新建会话"的入口。 所以:想让它出现在桌面端,只能由 App 自己发起会话,或者去伪造那行 sqlite 记录(不建议 —— App 一升级就碎, 而且它点开这条会话后会去 attach 一个并不存在的 sidecar)。无头会话的完整记录在 `~/.codebuddy/projects/<项目slug>/.jsonl`,想在终端里看:同一 workdir 下 `codebuddy --resume `。 ### 在线状态跟着桌面端开关(`host()` 钩子) 适配器可以提供 `host() -> (可用?, 原因)`,桥就跟着它走:App 没起来时**先不接入**(每 10s 探一次), App 退出时先发 `agent.deregister` 再掐掉 websocket —— hub 十几秒内从"已接入"变 offline,不会出现"桌面端都关了 hub 还亮着"。正在跑的 task 不打断(无头 CLI 不依赖 App,让它把这一轮跑完)。 桥进程本身不跟着桌面端退出,它下线后接着每 10s 探一次,WorkBuddy 一重新打开就自己接回去 —— 一次 `bridge.py` 管一整天的开关。要让开机/崩溃后也自动拉起,再配 LaunchAgent KeepAlive(见上面"常驻")。不想要这层耦合就把 `adapters/workbuddy.py` 里的 `host()` 删掉:codex/claude 没有这个钩子,行为不受影响。 ### hub 和 agent 不在一台机器上 桥接进程对 hub 是**主动出站**连接,所以 hub 放哪都行,agent 机器不用开端口: ```bash backend/.venv/bin/python deploy/cli-bridge/bridge.py \ --hub http://:8100 --token \ --cli workbuddy --name workbuddy --workdir ~/code/目标仓库 ``` `describe()` 会带上 `host` / `user` / `workdir`,随心跳进 hub 的 `capabilities`(控制台 agent 详情页 的 capabilities 面板)—— 分开部署时这是唯一能回答"这个 agent 到底在哪台机器上"的地方。 **hub 上能看到的从来不是原生会话,是事件流**:hub 只存 TaskEvent(status/reasoning/delta/tool/…, 工具输出截到 600 字,没有权限弹窗、没有 file snapshot)。真正的会话记录在 **agent 那台机器**的 `~/.codebuddy|~/.claude/projects//` 或 `~/.codex/sessions/` 里,所以要"进到那次会话" 必须回到 agent 机器、并 `cd` 到它当时的 workdir(会话按工作目录归档,站错目录 `-r` 会说找不到会话)。 这一步不用手算,交给脚本: ```bash ./scripts/attach.sh tsk_xxx # 本机直接进;agent 在别的机器就自动 ssh -t [user@]host ./scripts/attach.sh -n tsk_xxx # 只打印命令(远端路径不一样时先看清再改) HUB_URL=http://10.0.0.5:8100 HUB_KEY=ah_xxx ./scripts/attach.sh tsk_xxx # 连远端 hub ``` 它从 hub 拿 `session_id`(任务事件里最后一条非空的 `payload.session_id`)+ `capabilities` 里的 `cli/host/user/workdir`,再按各家语法拼命令:workbuddy 与 claude 是 `-r `,codex 是 `resume `。 进会话是**入站**动作,跨机器要求 agent 机器可 ssh —— 下发任务不需要,进会话需要,这个方向不对称是绕不开的。