Kimi Code Web 完全指南:在浏览器中运行与操控 Kimi Code CLI
Kimi Code Web 完全指南:在浏览器中运行与操控 Kimi Code CLI
Kimi Code Web 是 Kimi Code CLI 内置的浏览器图形界面:在终端执行 kimi web,即可在浏览器中新建会话、对话、处理审批、查看文件改动与后台任务进度,界面更易读,而会话与数据仍然完全保存在本机。本文以官方指南 docs/en/guides/web.md 为主体,结合仓库源码与命令参考,系统讲解启动方式、启动选项、斜杠命令、与 CLI 的能力对照、安全配置以及常见故障排查,帮助你在本机或局域网内以图形化方式完整操控 Kimi Code。
开始使用:三步在浏览器中打开 Kimi Code
kimi web 是 CLI 的内置命令,未安装 CLI 时不可用。安装与登录见 开始使用指南。
- 安装并登录 Kimi Code CLI —— 确保
kimi命令可用且已通过 CLI 完成登录。 - 在终端运行
kimi web—— 如果你已经处于 CLI 交互界面中,也可以直接输入/web,把当前会话"交接到"浏览器。从源码看,/web的实现(apps/kimi-code/src/tui/commands/web.ts)会先停止 TUI,再在当前进程中以前台方式启动服务器,并在服务就绪后自动打开带会话深链(/sessions/<sessionId>#token=...)的浏览器地址。 - 服务就绪后自动用默认浏览器打开 Web 界面 —— 启动横幅(ready banner)会打印访问地址;若浏览器没有自动打开,手动复制该地址访问即可:
Local: http://127.0.0.1:58627/#token=...
Token: ...
Stop: Ctrl+C
[!warning] 地址中的
#token=片段是访问凭证,请勿外发;停止服务请在终端按Ctrl+C。服务器始终以前台进程方式挂在这个终端上(见 run.ts),并会监听SIGINT/SIGTERM优雅关闭。
启动选项
kimi web 的常用启动选项如下(对应源码中的命令行定义见 run.ts,默认值解析见 shared.ts):
| 选项 | 说明 | 源码依据 |
|---|---|---|
--port <port> |
绑定端口;默认 58627,被占用时自动 +1 重试 |
DEFAULT_SERVER_PORT = 58627,parsePort 校验范围 0–65535 |
--host [host] |
让同一局域网下的手机、平板或其他电脑都能用 web 地址访问;也可指定具体 IP,如 --host 192.168.1.10 |
裸写 --host 等价于绑定 0.0.0.0(DEFAULT_LAN_HOST),省略则默认仅本机 127.0.0.1 |
--no-open |
就绪后不自动打开浏览器 | 通过 commander 的 --no-open 默认置 true 实现 |
--log-level <level> |
按所选级别开启服务日志;默认不输出(silent) | 合法级别:fatal、error、warn、info、debug、trace、silent |
--allowed-host <host...> |
额外放行 DNS 重绑定检查的 Host 头值,可重复或逗号分隔;前导点匹配域名后缀(如 .example.com) |
parseAllowedHostArgs 会按逗号拆分并 trim |
--insecure-no-tls |
允许非回环绑定不经过 TLS 终结反代(默认 true,仅对非回环绑定有意义) |
— |
--allow-remote-shutdown |
非回环绑定时保持 POST /api/v1/shutdown 可用(默认关闭,路由返回 404) |
— |
--dangerous-bypass-auth |
关闭所有 REST/WebSocket 路由的 bearer token 鉴权,详见下文安全注意 | disableAuth 透传给 kap-server |
--debug-endpoints |
挂载 /api/v1/debug/* 路由供测试内省,默认关闭 |
— |
--web-title <title> |
设置该实例的浏览器标签页标题(默认 ` |
Kimi Code`) |
--rc, --remote-control |
通过 Kimi Remote Control 公网暴露 Web UI | 另提供独立的 kimi rc / kimi remote 别名命令(index.ts) |
启动横幅与访问地址的生成逻辑
横幅中的地址由 access-urls.ts 计算:绑定通配地址(0.0.0.0/::)时同时打印 Local:(localhost)与每张网卡对应的 Network: 行;仅回环绑定(127.0.0.1/localhost/::1)时只打印一行 Local:;指定具体主机时打印一行 URL:。浏览器自动打开时,通配绑定会被改写为 http://localhost:<port>(browserOpenOrigin),因为 0.0.0.0 本身不可导航。
常用斜杠命令
Web 界面内支持以下常用斜杠命令(与 CLI 的命令集不完全一致):
| 斜杠命令 | 说明 |
|---|---|
/new |
新开会话 |
/goal |
进入目标模式,跨轮次持续推进同一目标 |
/compact |
压缩当前会话上下文 |
/tower |
Tower 多 Agent 协作(实验功能);/tower <base-branch> 指定基准分支 |
/export |
导出会话内容与故障排查日志为 ZIP |
/remote-control |
开启远程控制,从远程访问本地 Web 会话 |
与 CLI 的关系
Web 界面和 CLI 共享同一份登录态、配置(config.toml)和会话数据。Web 支持的斜杠命令见上文;部分 CLI 指令在 Web 里有对应的图形入口(设置页、模型选择器、账户菜单、任务面板)。
两端能力对照如下:
| 功能 | CLI | Web | 说明 |
|---|---|---|---|
| 流式对话 | ✓ | ✓ | Web 为富格式增量渲染(表格、代码高亮、diff、工具卡片) |
| 会话管理 | ✓ | ✓ | Web 可把不常用的会话归档收起,在已归档页按时间排序、随时恢复;Open / Done / Workspaces 标签页为 Lab 实验特性,默认关闭,需在设置的 Lab 页开启 |
| 审批处理 | ✓ | ✓ | Web 可在图形页面中点击处理,无需指令 |
| 后台任务 | ✓ | ✓ | Web 为任务面板实时展示进度 |
| 文件与改动 | ✓ | ✓ | Web 有改动文件摘要卡与逐文件 diff |
| 设置 | ✓ | ✓ | Web 另有图形化设置页(供应商、账号与用量、Lab 实验特性) |
| 全局搜索 | — | ✓ | Web 可实现跨会话、跨工作区搜索 |
| 移动端适配 | — | ✓ | --host 开启局域网共享后,可实现在同一局域网下的手机浏览器中使用 |
底层:kimi web 命令的实现结构
从源码看,kimi web 命令树定义在 apps/kimi-code/src/cli/sub/web/index.ts,核心流程在 run.ts 的 handleWebCommand 中:先解析服务器选项,然后调用 startServerForeground 在当前进程内启动 kap-server(REST + WebSocket + 内置 web UI),onReady 回调负责读取持久 token、打印横幅并打开浏览器。值得注意的几点实现事实:
- token 持久化:服务器首次启动会在
<KIMI_CODE_HOME>/server.token(权限 0600)写入持久 bearer token 并跨重启复用(shared.ts),因此重启服务后 token 不变、浏览器无需重新粘贴。 - token 走 URL 片段:token 通过
#token=<token>携带,属于客户端片段,永远不会发送给服务器,因此不会出现在服务器访问日志或代理日志中(run.ts)。Web UI 在页面加载后从location.hash读取。 - 多实例并存:多个
kimi web实例可共享同一 home 目录,各自注册到实例注册表并自动占用下一个空闲端口(见 run.ts 注释)。 /web深链:从 TUI 输入/web时,会生成/sessions/<sessionId>#token=...深链,让浏览器直接定位到当前会话(apps/kimi-code/src/tui/commands/web.ts)。
安全注意
- 建议设置并列凭证:绑定局域网地址(使用
--host)后,额外设置KIMI_CODE_PASSWORD环境变量,服务端会对鉴权失败自动限流。 - 不要彻底关闭鉴权:
--dangerous-bypass-auth会关闭所有鉴权,任何能访问该端口的人都能控制你的会话、文件系统和 shell。仅在可信网络或自有鉴权代理之后使用。完整命令参考见 kimi 命令参考。
源码层面的佐证:使用 --dangerous-bypass-auth 时,启动横幅会以红色醒目字体打印三条 DANGER 警告(run.ts);同时该选项与 --remote-control 互斥(二者组合会直接报错),且远程控制要求回环绑定(run.ts)。鉴权关闭后 token 不再展示或携带在 URL 中(run.ts)。命令参考还强调:--dangerous-bypass-auth 关闭鉴权后,任何能触达端口的人都可获得会话、文件系统与 shell 的完整访问权,使用完毕应立即 Ctrl+C 停止服务(docs/en/reference/kimi-command.md)。
常见问题
端口被占用了怎么办
不用处理。kimi web 会自动用下一个端口重试(58628、58629……),以启动横幅里实际打印的地址为准。默认端口常量与逐次递增逻辑见 shared.ts。
浏览器打不开地址
先确认终端里的服务还在运行(它前台挂在这个终端上)。地址必须完整复制,包含 #token= 部分;只输 http://127.0.0.1:58627 会停在输入 token 的页面,手动粘贴横幅里的 Token 值也可以进入。
token 失效了怎么恢复
运行 kimi web rotate-token 生成新 token,然后用启动横幅里的新地址重新打开。所有运行中的实例会自动换用新 token,无需重启。其实现位于 rotate-token.ts:命令原子重写 <KIMI_CODE_HOME>/server.token(0600),旧 token 立即失效;运行中的服务器在下一次鉴权检查时重新读取该文件,因此轮换即时生效。命令还会通过实例注册表读取正在运行的服务器宿主与端口,重新打印带新 token 的访问链接便于立即重连(rotate-token.ts)。
同一 WiFi 下其他设备访问不到
确认启动时带了 --host(裸写即可),并用横幅中局域网地址(形如 http://192.168.x.x:58627/#token=...)访问。仍不通时检查电脑防火墙是否放行了该端口,以及两台设备是否真的在同一网段(访客 WiFi、VPN、4G/5G 热点切换都会造成隔离)。
