@tunnelbox/kimi

English · 简体中文

官网： www.tunnelbox.top

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

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

Kimi Code CLI（MoonshotAI/kimi-code）是 Kimi CLI（MoonshotAI/kimi-cli）的继任者；两者都用同一 kimi acp 子命令，本适配器均可用。

快速开始（安装 → 运行 → 配对 → 使用）

在已安装并登录 Kimi Code CLI 的电脑上执行一次即可。

第 0 步 —— 准备手机

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

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

前置条件：Node.js ≥ 22，且已安装并登录 Kimi Code CLI。按官方文档安装（https://moonshotai.github.io/kimi-code/），然后运行一次 kimi 并发送 /login（Kimi Code OAuth 或 Moonshot API Key）。ACP 复用该登录态，无需再次登录。

npm install -g @tunnelbox/kimi

第 2 步 —— 运行

tunnelbox-kimi

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

第 3 步 —— 与手机配对

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

• 绑定后，后续启动会打印「已绑定账号」，不再刷新配对码。
• 想随时获取新码？运行 tunnelbox-kimi --pair。
• 先用 tunnelbox-kimi --check 做环境自检。

第 4 步 —— 在手机上使用

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

配置

| 环境变量 | 默认值 | 说明 | |---|---|---| | TUNNELBOX_RELAY_URL | 已保存的中继地址 | 中继地址 | | TUNNELBOX_CWD | process.cwd() | 默认工作区（agent 在此运行） | | TUNNELBOX_KIMI_BIN | kimi | Kimi CLI 可执行名 / 绝对路径 | | TUNNELBOX_KIMI_ACP_ARGS | — | 追加到 acp 之后的参数 | | TUNNELBOX_KIMI_MODE | Kimi 默认 | 会话模式（session/set_config_option configId=mode 或 session/set_mode） | | TUNNELBOX_KIMI_MODEL | Kimi 默认 | 模型 id（session/set_config_option configId=model 或 session/set_model） | | TUNNELBOX_KIMI_AUTH | login | ACP authenticate 的 methodId（Kimi 为非交互，用于探测登录态） | | TUNNELBOX_LANG | 系统 locale | 界面语言（8 种） |

TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_KIMI_MODE=plan tunnelbox-kimi

能力

| 能力 | 值 | 说明 | |---|---|---| | 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） |

权限与审批

• Kimi 官方将 session/request_permission 定义为工具审批与提问的共用通道：工具需要授权时，适配器推送手机审批卡并等待决定（allow-once / allow-always / allow-session / reject-once / reject-always）。
• fail-closed：离线、120s 超时、中继断开、进程退出或中止，一律回拒绝 / cancelled，绝不自动放行。

选择与计划审批

• 选择：选项型 session/request_permission → 手机选择卡；所选标签映射回 ACP optionId。
• 计划：计划型 session/request_permission（ExitPlanMode）→ 手机计划审批卡（展示计划文本）。
• 结构化输入：适配器声明 clientCapabilities.elicitation.form，因此 Kimi 可下发 elicitation/create。enum 字段 → 选择卡；自由文本 → 输入；空 schema → 确认卡。回包 {action:"accept",content} / decline / cancel。（Kimi 未实现 elicitation/complete，过期卡片靠超时回收。）

会话

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

安全说明

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

多语言

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

故障排查

| 问题 | 处理 | |---|---| | 屏幕没有二维码 / 配对码 | 运行 tunnelbox-kimi --pair 打印新码 | | 已绑定但手机连不上 | 确认双方用同一中继；查看 ~/.tunnelbox/tunnelbox.log | | 提示「Kimi 未登录」 | 运行一次 kimi 并发送 /login，或配置 Moonshot API Key | | kimi acp 不支持 | 升级 Kimi Code CLI | | 使用自建中继 | 以 TUNNELBOX_RELAY_URL=wss://<your-relay> 启动 |

状态文件

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

卸载

npm uninstall -g @tunnelbox/kimi

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

开发

实现细节（协议映射、源码结构、决策记录、待实测项）见本包旁的 DEV.md。离线 ACP 测试：npm run e2e；真机探针：npm run probe -- "prompt"。