diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 780eed4452a..b5f74710069 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -56,6 +56,7 @@ const config = withMermaid(defineConfig({ { text: '会话与上下文', link: '/zh/guides/sessions' }, { text: '在 IDE 中使用', link: '/zh/guides/ides' }, { text: '在网页中使用', link: '/zh/guides/web' }, + { text: '远程控制', link: '/zh/guides/remote-control' }, ], }, ], @@ -134,6 +135,7 @@ const config = withMermaid(defineConfig({ { text: 'Sessions and Context', link: '/en/guides/sessions' }, { text: 'Using in IDEs', link: '/en/guides/ides' }, { text: 'Using Kimi Code in the browser', link: '/en/guides/web' }, + { text: 'Remote Control', link: '/en/guides/remote-control' }, ], }, ], diff --git a/docs/en/guides/remote-control.md b/docs/en/guides/remote-control.md new file mode 100644 index 00000000000..c4aa62f14d7 --- /dev/null +++ b/docs/en/guides/remote-control.md @@ -0,0 +1,162 @@ +# Remote Control + +Start Kimi Code CLI with remote control enabled by running `kimi rc` in a terminal — it generates a link that can remotely control this machine. Scan the QR code with your phone to open the link, or visit it directly on another device. After opening the link, log in with the same Kimi account as in your local Kimi Code CLI to check on task progress, handle approvals, continue conversations, or start new sessions. Tasks always run on your machine — the web page is just a remote window. + +> Remote Control is currently an experimental feature and requires an environment variable to enable; the interface and behavior are subject to the final release. + +## Getting started + +### Prerequisites + +Before turning on Remote Control, make sure your machine meets the following conditions: + +- **Kimi Code CLI installed**: see [Getting started](../guides/getting-started.md) +- **Logged in to your Kimi account with a paid membership**: Remote Control requires a paid membership and is not available to free users +- **Machine stays awake and online**: Remote Control depends on a persistent connection between your machine and the Kimi service; remote sessions are unavailable after shutdown, sleep, or network loss +- **Experimental flag enabled**: set the environment variable with `export` (or use `KIMI_CODE_EXPERIMENTAL_FLAG=1` to enable all experimental features): + + ```sh + export KIMI_CODE_EXPERIMENTAL_REMOTE_CONTROL=1 + # or enable all experimental features + export KIMI_CODE_EXPERIMENTAL_FLAG=1 + ``` + + The `export` above only applies to the current terminal session. If you use Remote Control regularly, persist it in your shell configuration file (e.g. `~/.zshrc`): + + ```sh + echo 'export KIMI_CODE_EXPERIMENTAL_REMOTE_CONTROL=1' >> ~/.zshrc + ``` + +### Step 1: Start Remote Control + +Start it on your machine in any of the following ways — they are equivalent: each starts a foreground process and prints the remote access info. + +- **`kimi rc`** (alias `kimi remote`): start Remote Control directly +- **`kimi web --remote-control`**: equivalent to `kimi rc` — starts the local web interface and exposes it to the public internet at the same time +- **`/remote-control`** (alias `/rc`): use while already in a CLI session to hand the current session over to the remote interface + +Once started, the terminal prints the access URL (like `https://code-rc.kimi.com/devices//`), a QR code, and the device name (the machine's hostname), and the default browser opens the URL automatically (use `--no-open` to skip). Besides the terminal rendering, the QR code is also saved as a PNG file (the path is printed in the startup output) — if the QR code doesn't render properly in your terminal, open that file instead. + +![Terminal output after starting kimi rc: QR code and connection status](../../media/kimi-rc-banner.jpg) + +::: warning Note +The Remote Control link is a remote control entry point to this machine — anyone who has it may control your sessions and files. Do not share it with others or post it anywhere public. +::: + +Two limitations: + +- Only one Remote Control instance can run per machine. Starting it again reports the existing instance and prints the link already in use — see [How to turn off Remote Control](#how-to-turn-off-remote-control) for how to stop the old one +- Remote Control cannot be combined with `--dangerous-bypass-auth`, and it only binds to the loopback address (`--host` LAN sharing is not supported — remote access goes through the Kimi relay service) + +### Step 2: Connect from another device + +1. Open the access URL from the startup output in a browser on your phone or another computer — on a phone, you can also scan the QR code in the terminal directly. +2. Log in with the same Kimi account as on the machine. +3. After logging in, pick this machine in the device list (shown by its hostname) to see its sessions and start working. + +Remote Control works in the browser. + +::: info Device limit +Each account currently supports up to about **3 devices**. +::: + +### How to turn off Remote Control + +Remote Control is a foreground process; how you stop it depends on whether you can find the terminal that started it: + +- **The terminal is still there**: press `Ctrl+C` in that terminal (or just close the window) — the device immediately goes offline from the remote list +- **Can't find the terminal**: the single-instance lock file `~/.kimi-code/server/rc.json` records the process pid and the link in use (the error from starting a second instance prints both as well) — run `kill ` +- **The process already died** (power loss, crash, …): the stale lock file is cleaned up automatically on the next start — nothing to delete by hand + +To start a fresh instance, stop the old one in any of the ways above and run `kimi rc` again — there is no dedicated restart command. The device ID is derived from the machine's data directory, so the device and its access URL stay the same. The web-side device management and revocation UI is subject to the final release. + +## What you can do in a remote session + +Remote sessions have essentially the same capabilities as local ones: + +- **Send new tasks**: describe what you need; the task runs on your machine +- **Watch progress**: execution steps and tools in use are shown in real time +- **Continue the conversation**: follow up on existing sessions +- **Inspect tool calls**: expand the input and output of each tool execution +- **Handle approvals**: approve or deny file edits, Shell execution, and other confirmation requests right in the web page +- **Interrupt or stop tasks**: stop the running task at any time +- **Check subagent / workflow status**: track subagents or workflows dispatched by the task in the task panel + +## What happens on your machine + +Remote Control is only a remote window — all computation and file operations still happen on your machine. The boundaries: + +| Content | Happens locally | +| --- | --- | +| Reading project files | Yes | +| Modifying project files | Yes | +| Running Shell commands | Yes | +| Using local MCP | Yes | +| Phone or browser UI | No | +| Session sync | Via the Kimi service | + +## Disconnects, sleep, and recovery + +- **Closing the browser**: the task keeps running on your machine. Reopen the access URL to get the session view back +- **Machine loses network**: while offline, the remote UI disconnects and becomes unusable. The Remote Control process and the local server keep running, but an in-flight task may stall or fail because model requests can't get out. Once the network is back, the machine reconnects to the relay automatically — just refresh the remote page, no restart needed +- **Machine sleeps**: the Remote Control connection drops and tasks may pause or fail. Set the computer to never sleep in system settings, or keep it awake while in use +- **Local process exits**: pressing `Ctrl+C` or closing the terminal stops Remote Control and takes the device off the remote list. Restart it to recover +- **End the remote connection but keep the local task**: just close the web page — the local task is unaffected + +## What's the difference between Remote Control and Kimi Code Web? + +[Kimi Code Web](../guides/web.md) is the graphical interface on your machine or LAN; Remote Control extends it to any device on the public internet: + +| | Kimi Code Web | Remote Control | +| --- | --- | --- | +| Access scope | `localhost`, or the LAN with `--host` | Any device on the public internet (via the Kimi relay) | +| How to start | Run `kimi web` in a terminal | `kimi rc`, `kimi web --remote-control`, or `/remote-control` in the CLI | +| Authentication | Local token | Log in with the same Kimi account | +| Where data and execution live | Your machine | Your machine (the web page is just a remote window) | +| Typical scenario | GUI in a local browser | Following up remotely from a phone, tablet, or another computer | + +For the web interface's features, see [Using Kimi Code in the browser](../guides/web.md). + +## Security and permissions + +### How remote devices authenticate + +A remote device must log in with the same Kimi account as the machine to view and control sessions. Your devices are never exposed to other accounts, and there is no public link that works without logging in. + +### Does the access URL contain sensitive information + +The access URL itself contains no session data or local token — everything is shown per account permissions after login. But it is a remote control entry point to this machine, and the startup output also warns you not to share it. + +## FAQ + +### The link won't open from inside WeChat — what do I do? + +WeChat's in-app browser restricts some external webpages under its own security policies, so the Remote Control access URL (`https://code-rc.kimi.com/…`) opened directly in WeChat may be blocked with a "web page access stopped" notice. + +The fix: tap the "…" menu in the top-right corner and open the page in your default browser, or copy the link and paste it into a system browser such as Safari or Chrome. The same applies when scanning the startup QR code with WeChat's scanner — open it in a browser to get the full session functionality. + +### Does the task stop when I close the browser? + +No. The browser is just a window — the task runs on your machine. Closing the page doesn't affect it; reopen the link to get the view back. + +### Can I keep going after closing the local terminal? + +No. Remote Control depends on the Remote Control process on your machine staying alive; once the process exits, the remote connection drops. Restart it to recover. + +### Can a phone access local files directly? + +No. The phone has no direct channel to your machine's file system: what you see on the phone is the content rendered inside the session interface (such as diffs and file cards after the AI edits files), while all file reads/writes and command execution happen on the machine. The phone cannot browse, open, or download local files outside of a session. + +### How to troubleshoot a failed remote connection + +Check in this order: + +1. **Wake state**: make sure the machine is awake and hasn't gone to sleep +2. **Network connectivity**: can the machine reach the internet +3. **Process status**: is the Remote Control process running on the machine +4. **Account match**: is the web side logged in with the same Kimi account +5. **Firewall and proxy**: is your corporate network or proxy blocking `code-rc.kimi.com` + +## Next steps + +- [Using Kimi Code in the browser](../guides/web.md) — Remote Control opens the same web interface; learn what the interface itself can do diff --git a/docs/en/guides/web.md b/docs/en/guides/web.md index 511a30bbeab..18c97a81cbe 100644 --- a/docs/en/guides/web.md +++ b/docs/en/guides/web.md @@ -93,3 +93,4 @@ Make sure you started with `--host` (bare is fine), and use the LAN URL from the - [Server API](../reference/server-api.md) — REST / WebSocket APIs for scripts and third-party integrations (experimental) - [kimi command](../reference/kimi-command.md#kimi-web) — all `kimi web` command-line options +- [Remote Control](./remote-control.md) — remotely view and take over local sessions from any device over the public internet diff --git a/docs/media/kimi-rc-banner.jpg b/docs/media/kimi-rc-banner.jpg new file mode 100644 index 00000000000..37bc025f4df Binary files /dev/null and b/docs/media/kimi-rc-banner.jpg differ diff --git a/docs/zh/guides/remote-control.md b/docs/zh/guides/remote-control.md new file mode 100644 index 00000000000..39bb5f0537e --- /dev/null +++ b/docs/zh/guides/remote-control.md @@ -0,0 +1,162 @@ +# 远程控制 + +在终端里使用 `kimi rc` 命令启动 Kimi Code CLI 并开启远程控制后,会自动生成一个可以远程控制本机的链接。你可以使用手机扫描二维码打开链接,或在其他设备上直接访问该链接。打开链接后,登录和本地 Kimi Code CLI 中相同的 Kimi 账号,就能远程查看任务进度、处理权限确认、继续对话,或新建会话。任务始终在本机执行,网页只是一个远程窗口。 + +> 远程控制(Remote Control)目前是实验性功能,需要通过环境变量开启,界面与行为以最终发布版本为准。 + +## 开始使用 + +### 使用前准备 + +开启远程控制前,请确认本机满足以下条件: + +- **已安装 Kimi Code CLI**:安装见 [开始使用](../guides/getting-started.md) +- **已登录 Kimi 账号且为付费会员**:远程控制需要会员权限,免费用户无法使用 +- **本机保持唤醒并联网**:远程控制依赖本机与 Kimi 服务保持连接,关机、休眠或断网后远程会话不可用 +- **已开启实验开关**:用 `export` 设置环境变量(或用 `KIMI_CODE_EXPERIMENTAL_FLAG=1` 开启全部实验特性): + + ```sh + export KIMI_CODE_EXPERIMENTAL_REMOTE_CONTROL=1 + # 或者开启全部实验特性 + export KIMI_CODE_EXPERIMENTAL_FLAG=1 + ``` + + 上面的 `export` 只对当前终端会话有效。如果经常使用,建议写入 shell 配置文件(如 `~/.zshrc`)持久化: + + ```sh + echo 'export KIMI_CODE_EXPERIMENTAL_REMOTE_CONTROL=1' >> ~/.zshrc + ``` + +### 第一步:启动远程控制 + +在本机用以下任一方式启动,效果相同:启动一个前台进程并打印远程访问信息。 + +- **`kimi rc`**(别名 `kimi remote`):直接启动远程控制 +- **`kimi web --remote-control`**:与 `kimi rc` 等价,在启动本地网页界面的同时把它暴露到公网 +- **`/remote-control`**(别名 `/rc`):已在 CLI 会话中时使用,把当前会话直接交给远程界面 + +启动成功后,终端会打印访问链接(形如 `https://code-rc.kimi.com/devices/<设备 ID>/`)、二维码和本机设备名(主机名),同时默认浏览器会自动打开该链接(加 `--no-open` 可关闭)。二维码除了显示在终端里,还会保存为 PNG 文件(路径见启动信息),终端里无法正常显示二维码时,可以直接打开该文件。 + +![kimi rc 启动后的终端输出:二维码与连接状态](../../media/kimi-rc-banner.jpg) + +::: warning 注意 +远程控制链接是这台机器的远程控制入口,获得链接的人可能控制你的会话和文件,请勿分享给他人或发布到公开渠道。 +::: + +两个使用限制: + +- 一台机器同时只能运行一个远程控制实例。重复启动会提示已有实例在运行,并给出在用的链接;停止旧实例的方法见 [如何关闭远程控制](#如何关闭远程控制) +- 远程控制不能与 `--dangerous-bypass-auth` 同时使用,也只绑定本机回环地址(不能用 `--host` 做局域网共享,远程访问统一走 Kimi 中转服务) + +### 第二步:从其他设备连接 + +1. 在手机或另一台电脑的浏览器中打开启动信息里的访问链接,手机也可以直接扫终端里的二维码。 +2. 使用与本机相同的 Kimi 账号登录。 +3. 登录后在设备列表中选择这台机器(显示主机名),即可看到它的会话列表并开始操作。 + +远程控制通过浏览器访问。 + +::: info 设备数量限制 +当前每个账号最多支持约 **3 台**设备。 +::: + +### 如何关闭远程控制 + +远程控制是前台进程,停止方式取决于你能否找到启动它的终端: + +- **终端还在**:在该终端按 `Ctrl+C`(或直接关闭该终端窗口),设备会立即从远程列表中下线 +- **找不到终端**:单实例锁文件 `~/.kimi-code/server/rc.json` 里记录着进程 pid 和在用的链接(重复启动时的报错也会打印这两个信息),执行 `kill ` 即可 +- **进程已异常退出**(断电、崩溃等):残留的锁文件会在下次启动时自动清理,无需手动删除 + +想新开一个实例时,先把旧的按上面任一方式停掉再重新 `kimi rc` 即可。设备 ID 按本机数据目录生成,重开后设备和访问链接都不变。网页端设备管理与撤销的具体入口以最终发布版本为准。 + +## 远程会话中可以做什么 + +远程会话与本地会话能力基本一致,支持: + +- **发送新的任务**:直接向 AI 描述需求,任务在本机执行 +- **查看当前进度**:实时展示执行步骤和正在使用的工具 +- **继续对话**:在已有会话基础上追加指令 +- **查看工具调用**:展开每次工具执行的输入与结果 +- **处理权限确认**:文件修改、Shell 执行等确认请求,可直接在网页上批准或拒绝 +- **中断或停止任务**:随时停止当前任务 +- **查看子 Agent / workflow 状态**:任务派发的子 Agent 或 workflow,可在任务面板中查看进度 + +## 本地电脑上发生什么 + +远程控制只是一个远程窗口,所有计算和文件操作仍在本机完成。边界如下: + +| 内容 | 是否在本地完成 | +| --- | --- | +| 读取项目文件 | 是 | +| 修改项目文件 | 是 | +| 执行 Shell 命令 | 是 | +| 使用本地 MCP | 是 | +| 手机或浏览器界面 | 否 | +| 会话同步 | 通过 Kimi 服务完成 | + +## 断线、休眠和恢复 + +- **关闭浏览器**:任务在本机继续执行,不会中断。重新打开访问链接即可恢复会话视图 +- **本机断网**:断网期间远程界面断开,无法操作。本机的远程控制进程和本地服务保持运行,但执行中的任务可能因模型请求发不出去而暂停或失败;网络恢复后本机会自动重连中转服务,刷新远程页面即可,无需重启 +- **电脑休眠**:休眠后远程控制连接断开,任务可能暂停或失败。建议在系统设置中将电脑设为永不休眠,或在使用期间保持唤醒 +- **本地进程退出**:按 `Ctrl+C` 或关闭终端后远程控制停止,设备从远程列表中下线。重新启动后可恢复 +- **结束远程连接但保留本地任务**:直接关闭网页即可,本机任务不受影响 + +## 远程控制和 Kimi Code 网页版有什么区别? + +[Kimi Code 网页版](../guides/web.md) 是本机或局域网里的图形界面,远程控制把它延伸到了公网任意设备: + +| 对比项 | Kimi Code 网页版 | 远程控制 | +| --- | --- | --- | +| 访问范围 | 本机 `localhost`,或 `--host` 开启的局域网 | 公网任意设备(经 Kimi 中转) | +| 启动方式 | 终端运行 `kimi web` | `kimi rc`、`kimi web --remote-control` 或 CLI 中 `/remote-control` | +| 鉴权方式 | 本地 token | 登录同一个 Kimi 账号 | +| 数据与执行位置 | 本机 | 本机(网页只是远程窗口) | +| 典型场景 | 本机浏览器图形界面操作 | 手机、平板、另一台电脑远程跟进 | + +网页界面的详细功能见 [在网页中使用](../guides/web.md)。 + +## 安全与权限 + +### 远程设备如何鉴权 + +远程设备必须登录与本机相同的 Kimi 账号,才能查看和控制会话。不会向其他账号暴露你的设备,也不存在无需登录即可访问的公开链接。 + +### 访问链接是否包含敏感信息 + +访问链接本身不包含会话数据或本地 token,所有内容都需要登录后按账号权限展示。但它是这台机器的远程控制入口,启动信息中也会提示不要分享给他人。 + +## 常见问题 + +### 从微信里访问链接,无法打开怎么办? + +微信内置浏览器会基于自身安全策略限制部分外部网页的应用内访问,远程控制的访问链接(`https://code-rc.kimi.com/…`)在微信中直接打开可能被拦截,出现"已停止访问该网页"等提示。 + +解决方式:点击页面右上角"…"菜单并选择"在浏览器中打开",或将链接复制到 Safari、Chrome 等系统浏览器中访问。使用微信"扫一扫"扫描启动二维码时同理,扫码后请选择在浏览器中打开,即可获得完整的会话功能。 + +### 关闭浏览器后任务会停止吗? + +不会。浏览器只是窗口,任务在本机执行。关闭网页不影响本机继续运行,重新打开链接即可恢复视图。 + +### 关闭本地终端后还能继续吗? + +不能。远程控制依赖本机的远程控制进程保持运行,进程退出后远程连接即断开。重新启动后可恢复。 + +### 手机能直接访问本地文件吗? + +不能。手机端没有直接访问本机文件系统的通道:你在手机上看到的是会话界面里展示的内容(例如 AI 修改文件后的 diff 和文件卡片),但文件的读写和命令执行都发生在本机。手机无法脱离会话,直接浏览、打开或下载本机文件。 + +### 远程连接失败如何排查? + +按以下顺序检查: + +1. **唤醒状态**:确认本机处于唤醒状态,没有进入休眠 +2. **网络连通性**:本机能否正常访问互联网 +3. **进程状态**:本机的远程控制进程是否正在运行 +4. **账号一致性**:网页端登录的 Kimi 账号与本机是否一致 +5. **防火墙与代理**:公司网络或代理是否拦截了 `code-rc.kimi.com` + +## 下一步 + +- [在网页中使用](../guides/web.md) — 远程控制打开的就是网页界面,了解界面本身的功能与操作 diff --git a/docs/zh/guides/web.md b/docs/zh/guides/web.md index 340e5f9a5ef..7dc4c623d34 100644 --- a/docs/zh/guides/web.md +++ b/docs/zh/guides/web.md @@ -95,3 +95,4 @@ Web 里的斜杠命令与 CLI 不完全一致,支持常用指令 `/new`、`/go - [服务 API](../reference/server-api.md) — 面向脚本与第三方集成的 REST / WebSocket 接口(实验性) - [kimi 命令](../reference/kimi-command.md#kimi-web) — `kimi web` 的全部命令行选项 +- [远程控制](./remote-control.md) — 从公网任意设备远程查看和接管本机会话