coze-bridge

本机后台 daemon, 把云端 Agent Service 跟本地 AI agent (Claude Code / Codex / OpenClaw) 通过扩展 ACP 协议桥接起来。

前置依赖

• Node ≥ 20
• 本机至少装好 claude / codex / openclaw 中的一个

用法

# 启动 / 复用 daemon, 投递 pair
npx -y coze-bridge@latest --pat-token=<sat_xxx> --pair-code=<xxx>

# 查 daemon 状态
npx -y coze-bridge@latest --status

# 停 daemon
npx -y coze-bridge@latest --stop

# 重新探测本地 agent 路径 / 版本
npx -y coze-bridge@latest --refresh

# 卸载: 停 daemon + 删 ~/.coze
npx -y coze-bridge@latest --uninstall

配对参数

| Flag | 说明 | |---|---| | --pat-token <sat_xxx> | coze PAT token, 从 coze 平台拿 | | --pair-code <xxx> | 配对码, 从云端 UI 拿 |

支持 --name VALUE 与 --name=VALUE 两种写法。

自动 connect 某个 agent(可选)

| Flag | 说明 | |---|---| | --agent-id <id> | pair 成功后自动 connect 该 agent: 本地已有走 reconnect/revive, 没有 (需云端协议升级) 拉详情新建 |

npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --agent-id=<your-agent-id>

环境路由(可选, 联调时用)

| Flag | 说明 | |---|---| | --env <value> | ppe_* 走 x-use-ppe: 1 + x-tt-env; boe_* 仅 x-tt-env | | --handshake-url <url> | 覆盖 HTTP base, 默认 https://www.coze.cn | | --frontier-url <url> | 覆盖 Frontier WS URL, 默认 wss://frontier.coze.cn |

npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --env=ppe_xxx

行为说明

• daemon 启动自动复活 agents: ~/.coze/agents/ 里所有未被云端主动 disconnect 的 agent, daemon 启动后会自动 spawn 子进程 + 加入路由, 不需要你一个个 reconnect
• device 级 10s 批量心跳: pair 成功后每 10s 上行 1 帧 _agent/health, 装该 device 下所有 eligible agent (agents:[{agentId,status},...]), 新 agent 上线毫秒级出首帧
• deviceId 不持久化: 每次 pair 由云端 handshake 接口分配, 切环境 / 重启 daemon 都用新值
• cloud agent 跟本机 framework 解耦: _agent/create 带 _meta.cozeDeployType=cloud 时 Bridge 直接 ack 不 spawn — agent 在云端跑, 本机没装对应 framework 也行

工作目录

~/.coze/
├── bridge/                 # daemon 文件
│   ├── lib/index.js        # 固化的 dist (npx 首次执行复制过来)
│   ├── bridge.pid          # PID
│   ├── bridge.port         # IPC HTTP 端口
│   ├── bridge.token        # IPC token (mode 0600)
│   ├── bridge.log
│   └── config.json         # frameworks_cache + libVersion (不存 deviceId, 每次 pair 拿)
└── agents/<agentId>/       # 每个 agent 一个目录, daemon 重启自动复活
    ├── config.json         # mode 0600 (含 cozeIdentity / model / modelToken / sessions / ...)
    ├── workspace/          # 子进程 cwd, CLAUDE.md / AGENTS.md / SOUL.md 在这
    └── logs/

License

MIT