botmux 通过适配器桥接不同的 CLI / Agent，在 bots.json 里用 cliId 选择即可一键切换。本地适配器各自运行独立进程（默认 tmux 后端下可 tmux attach 进入真实进程；显式 pty/zellij/herdr 后端另说）；少数 Agent（如 Mira、riff）经 API / 远端接入，不是本地进程。
两类场景不需要新适配器：
- Codex 严格兼容发行版 —— 复用
codex协议适配器，用cliRuntime声明发行版身份（见下文）。 - 套 wrapper / 网关（ccr、aiden x claude 等）——
cliId仍填底层真实 CLI，用cliPathOverride指向 wrapper 脚本。
cliId 列表
当前内置适配器如下（cliId 的权威事实源是 src/adapters/cli/registry.ts，随版本增减）：
cliId | CLI / Agent | 接入方式 | 支持 model |
|---|---|---|---|
claude-code | Claude Code（默认） | 本地进程 | ✅ |
codex | Codex CLI | 本地进程 | ✅ |
codex-app | Codex App（app-server 协议） | 本地进程 | |
gemini | Gemini | 本地进程 | ✅ |
cursor | Cursor（cursor-agent） | 本地进程 | ✅ |
opencode | OpenCode | 本地进程 | ✅ |
antigravity | Antigravity（agy） | 本地进程 | |
copilot | GitHub Copilot | 本地进程 | ✅ |
grok | Grok（grok-cli） | 本地进程 | ✅ |
kimi | Kimi Code | 本地进程 | ✅ |
kiro-cli | Kiro | 本地进程 | |
pi | Pi | 本地进程 | |
oh-my-pi | Oh-My-Pi（Pi fork） | 本地进程 | ✅ |
aiden | Aiden | 本地进程 | |
coco | CoCo / Trae（需 ≥ 0.120.32） | 本地进程 | ✅ |
traex | TRAE CLI（traex） | 本地进程 | ✅ |
mtr | MTR | 本地进程 | |
hermes | Hermes | 本地进程 | |
genius | Genius | 本地进程 | ✅ |
seed | Seed（Claude Code fork） | 本地进程 | ✅ |
relay | Relay（Seed 新版） | 本地进程 | ✅ |
reasonix | Reasonix | 本地进程 | ✅ |
mira | Mira APP | API / 远端 | |
mir | Mir CLI（本地 mircli + MCP bridge） | 本地进程 | |
riff | riff | 云 Agent（API） |
model字段只对标记 ✅ 的适配器生效，其余忽略。配置字段详见 bots-json。
Mir CLI 与 MCP Bridge
botmux setup 选择 Mira → Mir CLI（本地 mircli） 后，机器人使用 cliId: "mir"，通过本机 mircli -p --lean 执行。要求运行 daemon 的同一系统用户已完成 Mir CLI 登录与初始化（DevBox、本地 macOS、其它 Linux 机器规则相同）：
mircli能被 botmux 找到，或用cliPathOverride指向其绝对路径；~/.mira/config.json已有device_id（首次经mircli mcp --device-id <id>或 Mir CLI 初始化流程写入）；miramcp在标准位置（如~/.local/bin/miramcp、~/.local/bin/mira_cli），或用MIRAMCP_BIN指向可执行文件。
cliId: "mir" 会话启动收到消息时，botmux 会在调用 mircli 前 best-effort 拉起 MCP Bridge：miramcp run --device-id <device_id>。它先检查 ~/.mira/miramcp/miramcp.pid 与本机 9801 端口，已运行则不重复启动。用 mircli mcp status 确认状态。禁用自动拉起：bots.json 配 {"auto_start_bridge": false}，或进程级 MIRCLI_AUTO_START_MIRAMCP=0 botmux start。
Codex 兼容发行版（cliRuntime）
botmux 把「协议能力」与「发行版身份」分开：cliId: "codex" 选择 Codex 协议适配器，cliRuntime 声明真正运行的独立发版二进制。兼容分支因此可复用模型参数、resume、空闲检测与受控 RPC，且不会被当成官方 Codex 检查版本。
适合 cliRuntime 的必须是严格兼容分支：接受 botmux 传给 Codex 的参数，保留相同的交互状态和 rollout / resume 语义，使用兼容的认证 / home 布局。若修改了参数、TUI 状态机、会话存储或协议，应贡献真实适配器而非声明兼容。
完整配置字段与 update.provider 语义见 bots-json 的 Codex 兼容发行版章节。Dashboard 的 Bot 默认设置也可配置并预检 runtime。旧 cliPathOverride 继续兼容，但不会自动开启需要明确兼容声明的 Codex RPC 能力。
套 wrapper / 网关接入
套网关 / 路由（内网代理 + SSO、模型路由，如 ccr、ttadk、aiden x claude、aiden x codex）时不需要新适配器：cliId 仍填底层真实 CLI（claude-code / codex …），只把启动入口换成 wrapper 脚本，用 cliPathOverride 指过去（setup 编辑机器人时的「CLI 可执行文件路径覆盖」即填它）。
通用四步：
- 先登录网关（一次性）：用跑 daemon 的同一系统用户完成 SSO 登录，token 缓存在该用户家目录。token 过期会弹交互登录卡住 PTY，注意保持登录态。
- 写 wrapper 脚本放
~/.botmux/bin/，把 botmux 传入参数透传给真实 CLI（有的网关拒收 botmux 注入的--settings，需在脚本里剥掉）。 chmod +x加可执行位（最容易漏）—— botmux 用 node-pty 直接 exec 脚本，无可执行位会EACCES、CLI 起来即退、bot 崩溃重启。- 直接执行脚本验证（
~/.botmux/bin/xxx --version，别用bash xxx测——走 bash 不需可执行位，会掩盖第 3 步问题）。然后在 bots.json 配cliPathOverride（写绝对路径，别用~），botmux restart生效。
各网关的具体 wrapper 脚本随上游更新，以对应 CLI / 网关团队文档为准。已知要点：
- aiden × claude / aiden × codex — aiden×codex 需用
script强套 PTY； - ttadk — 注意 wrapper 参数透传和登录态；
- MTR — 社区贡献，
npm i -g @metamove-code/mtr-cli@latest。
排查 wrapper 问题通用手法：
botmux logs找Spawning fresh CLI:一行，复制完整命令在本地手动跑一遍即可定位（权限 / 参数黑名单 / 登录态）。
添加新适配器（贡献者）
src/adapters/cli/下新建文件，实现CliAdapter接口；src/adapters/cli/types.ts的CliId联合类型加新 ID；src/adapters/cli/registry.ts加 import / switch case / export；src/worker.ts的CLI_DISPLAY_NAMES、card-builder.ts的cliDisplayNames加显示名；src/cli.tssetup 交互菜单加选项；- 更新 README。
适配器层的源码结构见 adapters；会话后端（tmux / pty / zellij / herdr）的行为差异见 tmux。