@tunnelbox/qoder

English · 简体中文

官网： www.tunnelbox.top

tunnelbox Qoder 适配器（独立进程）： 用手机远程驱动电脑上的 Qoder CLI —— 会话、流式（含思考）、工具审批、结构化提问 / 计划审批、中止。它驱动 Qoder CLI 的 ACP 模式（qoder --acp），并且只向中继出站连接（无需公网 IP、无需端口映射）。

手机 App ──WSS──► relay ──WSS──► tunnelbox-qoder（本适配器）
                                      └─ qoder --acp   （Agent Client Protocol，JSON-RPC over stdio）

状态： Qoder 官方 ACP 文档声明支持 ACP，且权限 ask 走 requestPermission，但未逐项公布能力矩阵，故本适配器按标准 ACP 编写、为实验性。请用 npm run probe 对真机校正。详见 DEV.md。

快速开始

第 0 步 —— 准备手机

从官网安装 tunnelbox App（Android / iOS）：https://www.tunnelbox.top

第 1 步 —— 在电脑上安装适配器

前置条件：Node.js ≥ 22，且已安装并登录 Qoder CLI。

npm install -g @qoder-ai/qodercli   # Qoder CLI（如尚未安装）
qoder login                          # 或设置 QODER_PERSONAL_ACCESS_TOKEN
npm install -g @tunnelbox/qoder

第 2 步 —— 运行

tunnelbox-qoder

首次启动会连接中继，并在终端打印配对二维码 + 配对码。

第 3 步 —— 与手机配对

在手机 App 中点「扫一扫配对」，扫描终端二维码（或手动输入配对码）。配对码一次性有效，约 10 分钟。

• 想随时获取新码？运行 tunnelbox-qoder --pair。
• 先用 tunnelbox-qoder --check 做环境自检。

第 4 步 —— 在手机上使用

在 App 中打开这台电脑，即可新建会话、发送消息、查看流式输出（含思考）、批准或拒绝工具调用、回答问题 / 计划审批，以及中止正在运行的会话。

配置

| 环境变量 | 默认值 | 说明 | |---|---|---| | TUNNELBOX_RELAY_URL | 已保存的中继地址 | 中继地址 | | TUNNELBOX_CWD | process.cwd() | 默认工作区 | | TUNNELBOX_QODER_BIN | qoder | Qoder CLI 可执行名 / 绝对路径 | | TUNNELBOX_QODER_ACP_ARGS | — | 追加到 --acp 之后的参数 | | TUNNELBOX_QODER_MODE | Qoder 默认 | 会话模式（session/set_config_option configId=mode 或 session/set_mode） | | TUNNELBOX_QODER_MODEL | Qoder 默认 | 模型 id（session/set_config_option configId=model 或 session/set_model） | | TUNNELBOX_QODER_PERMISSION_MODE | 不设置 | 启动期 --permission-mode（default/accept_edits/auto/plan/bypass_permissions/dont_ask）。不设置即保持手机审批 fail-closed | | TUNNELBOX_QODER_REASONING_EFFORT | 不设置 | 启动期 --reasoning-effort（如 high） | | TUNNELBOX_QODER_AUTH | 不设置 | 可选 ACP authenticate methodId（默认跳过；用 qoder login / QODER_PERSONAL_ACCESS_TOKEN 登录） | | QODER_PERSONAL_ACCESS_TOKEN | 透传 | 传给 CLI 用于认证 | | TUNNELBOX_LANG | 系统 locale | 界面语言（8 种） |

TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_QODER_PERMISSION_MODE=auto tunnelbox-qoder

能力

按标准 ACP 假设；请用 npm run probe 对真机校正。

| 能力 | 值 | 说明 | |---|---|---| | streaming | ✅ | session/update 块（agent_message_chunk 增量） | | thinking | ✅ | agent_thought_chunk 增量（提供时） | | permission | ✅ | session/request_permission → 手机审批卡；fail-closed | | questions | ✅ | 选项型 session/request_permission → 选择卡；elicitation/create（form）→ 选择/确认卡 | | commands | ✅ | /new、/help | | abort | ✅ | session/cancel | | workspaces | ✅ | 会话 cwd（session/new） |

权限与审批

• Qoder 官方：ACP 下权限 ask 作为 requestPermission RPC 发给客户端；AskUserQuestion 与 Plan 始终请求确认。适配器推送手机审批卡并等待决定。
• fail-closed：离线、120s 超时、中继断开、进程退出或中止，一律回拒绝 / cancelled，绝不自动放行。
• TUNNELBOX_QODER_PERMISSION_MODE=bypass_permissions（或 --yolo）会让 Qoder 自动放行并绕过手机审批卡。除非清楚风险，否则不要开启。

选择与计划审批

• 选择：选项型 session/request_permission → 手机选择卡；所选标签映射回 ACP optionId。
• 计划：计划型 session/request_permission（ExitPlanMode）→ 手机计划审批卡。
• 结构化输入：适配器声明 clientCapabilities.elicitation.form；若 Qoder 下发 elicitation/create，enum 字段 → 选择卡，自由文本 → 输入，空 schema → 确认卡。

会话

• 会话为本地镜像（~/.tunnelbox/qoder-sessions/<uuid>/）：每个流式部件/用户消息即时落盘，供列表/历史/删除。
• 续聊：ACP sessionId 存入镜像 meta，优先 session/resume（能力声明时），否则 session/load。
• 状态文件：~/.tunnelbox/remote-state.qoder.json。

安全说明

• 默认受门控的工具调用一律走手机审批（fail-closed）。
• 请勿在不受信目录开启 bypass_permissions/--yolo。
• 请勿把敏感项目暴露给不可信的手机。

多语言

用户可见输出支持 8 种语言（zh-CN / zh-TW / en-US / ja-JP / ko-KR / fr-FR / de-DE / es-ES）。解析顺序：TUNNELBOX_LANG > 已保存的 remote-state.qoder.json.lang > 系统 locale > en-US。

故障排查

| 问题 | 处理 | |---|---| | 屏幕没有二维码 / 配对码 | 运行 tunnelbox-qoder --pair 打印新码 | | 已绑定但手机连不上 | 确认双方用同一中继；查看 ~/.tunnelbox/tunnelbox.log | | 未登录 | 运行 qoder login，或设置 QODER_PERSONAL_ACCESS_TOKEN | | --acp 不支持 | 升级 Qoder CLI | | ACP 行为与预期不符 | 运行 npm run probe -- "prompt" 并上报原始帧 | | 使用自建中继 | 以 TUNNELBOX_RELAY_URL=wss://<your-relay> 启动 |

状态文件

• ~/.tunnelbox/remote-state.qoder.json — agentID（+ 语言）
• ~/.tunnelbox/qoder-sessions/ —— 本地会话镜像
• ~/.tunnelbox/tunnelbox.log —— 适配器日志

卸载

npm uninstall -g @tunnelbox/qoder

仅当你不再使用任何 tunnelbox 适配器时，才删除 ~/.tunnelbox（所有适配器共享状态）。

开发

实现细节（协议映射、探针门禁）见 DEV.md。离线 ACP 测试：npm run e2e；真机探针：npm run probe -- "prompt"。