Kimi Code CLI 上手指南：安装、迁移，以及第一次安全运行
以有光 · 2026-07-21
搜索结果落后于迁移事实，这本身就是个信号
这周 Kimi CLI 登上了 GitHub Trending。我去看了一眼，发现了一件有点烦躁的事：搜索结果里同时出现"Kimi CLI"和"Kimi Code CLI"，点进旧项目的 README，顶部已经挂出迁移通知，告诉你这个项目正在逐步退出，请移步 Kimi Code CLI。
这不是又发了一个模型，也不是改了个名字。如果你要找的是模型与 API，而不是终端工具，请看单独的 Kimi K2 指南。旧版本从 Python/uv 运行时切换到了 TypeScript/Node.js，本地数据目录变了，终端界面变了，迁移流程也是新的。如果你从旧名字的搜索结果进来，你面对的已经是一套不同的工具链。
这篇文章就从这个矛盾出发，走一遍安装、迁移和第一次安全运行的路径。我会说清楚哪些东西能搬过去、哪些要手动重建、哪些权限需要你主动做决定，而不是等工具替你做掉。
先说清楚：新旧产品是什么关系
旧版：Kimi CLI（原项目）——Python/uv 运行时，本地数据在 ~/.kimi/，目前正在逐步停止维护。
新版：Kimi Code CLI（接替项目）——TypeScript/Node.js 运行时，本地数据默认在 ~/.kimi-code/，官方提供二进制安装脚本，也可以通过 npm 安装（需要 Node.js 22.19.0 或以上）。
两者不是同一工具的大版本升级，而是运行时、目录结构、插件体系都发生了变化的替代关系。这意味着"升级"这个词并不准确——更接近的描述是"搬工作间"：工具和笔记能搬，但钥匙和信任关系不能自动搬过去。
第一步：安装，并且验证命令可用
选择安装方式
官方提供两条路径：
二进制脚本安装（macOS/Linux）
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
二进制脚本安装（Windows PowerShell）
irm https://code.kimi.com/kimi-code/install.ps1 | iex
这两种方式不要求你预先安装 Node.js，安装包自带运行时。
npm 安装
npm install -g @moonshot-ai/kimi-code
npm 方式需要本地已有 Node.js 22.19.0 或更高版本。如果你的环境里 Node 版本混乱，建议先用二进制脚本路径，少踩一个坑。
验证安装
安装完成后，运行：
kimi --version
2026-07-21 我在隔离环境里用 pnpm dlx @moonshot-ai/[email protected] 检查了 0.28.1，这条命令能正常返回版本号。这是第一个检查点——如果连版本都拿不到，后面不用继续。
然后运行：
kimi doctor
doctor 会校验配置文件（config.toml / tui.toml）；配置文件不存在时会跳过并使用内置默认值。它不能证明网络连接、登录状态或模型调用均可用，只是配置层面的快速检查。如果你的配置有问题，doctor 通常会给出具体提示。
说明边界：以上测试在隔离环境中通过 npm 包直接运行，只验证了包能启动、版本能返回、配置校验能结束，未验证官方二进制安装脚本。登录后的模型调用、编码任务的实际响应质量，我还没有测试，本文不会做这方面的描述。
第二步：处理本地数据——迁移之前先看清楚
如果你之前用过旧版 Kimi CLI，在登录新工具之前，有几件事值得先搞清楚。
旧数据在哪里
旧版 Kimi CLI 的本地数据在：
~/.kimi/
新版 Kimi Code CLI 的默认目录是：
~/.kimi-code/
如果你想把新版数据放到别的地方，可以设置环境变量：
export KIMI_CODE_HOME=/your/custom/path
迁移命令
官方提供了迁移命令：
kimi migrate
重要的是：迁移不会修改或删除旧的 ~/.kimi/ 数据，也可以重复执行。这意味着你不需要害怕"跑了迁移之后旧数据就没了"。
哪些能迁移，哪些不能
下面这张表是本文最重要的部分之一。很多工具的迁移指南会说"一键迁移"，但不说清楚什么东西是例外。
| 类别 | 能否迁移 | 说明 |
|---|---|---|
| 配置文件 | ✅ 能迁移 | 工具本身的设置 |
| MCP server 配置 | ✅ 能迁移 | 连接定义可以带过去 |
| 输入历史 | ✅ 能迁移 | 之前的命令输入记录 |
| 用户选择的会话 | ✅ 能迁移 | 你主动标记保留的对话 |
| OAuth 登录凭据 | ❌ 不迁移 | 需要重新登录 |
| MCP 服务授权 | ❌ 不迁移 | 需要重新授权各个 MCP 服务 |
| 旧版插件 | ❌ 不迁移 | 插件体系已变，需要重新适配 |
把这张表当作迁移前的检查清单。 特别是 MCP 服务授权——如果你之前配置了外部工具接入，迁移之后需要逐一重新授权，这不是 bug，是有意为之的设计边界。新环境的信任关系需要你重新建立。
迁移后更新工具本身
如果后续需要更新 Kimi Code CLI，命令是：
kimi upgrade
第三步：登录
Kimi Code CLI 支持两种登录方式：
- Kimi Code OAuth：适合直接使用 Kimi 账号的用户
- Kimi Platform API key：适合需要程序化调用或精细控制额度的用户
首次登录时工具会引导你选择。其他模型提供方（如果你想接入第三方模型）需要单独配置，不在本文展开。
第四步：先跑一个只读任务
安装、迁移、doctor 都通过之后，进入一个你熟悉的、本地的、可信的代码仓库：
cd /your/trusted/project
kimi
然后做一件事：让它解释目录结构，不做任何写操作。
比如：
"帮我描述一下这个项目的目录结构和主要入口文件，不要修改任何东西。"
这个任务的意义不是测试模型有多聪明。这是让你观察工具的行为：它会访问哪些文件、它的响应格式是什么样的、它在你的环境里是否正常工作。只读操作默认会自动执行，你不需要每次确认，这很合理。
如果这一步有问题，比如找不到文件、读取权限报错，先在这里解决，不要带着问题进入修改操作。
关于权限和执行模式——你需要主动做的决定
这是整篇文章我最想说清楚的部分。
Kimi Code CLI 有几个执行模式，它们的权限边界不同。关于 Agent 沙箱、Workspace 写入与 Host trust 之间更完整的边界，可以继续看 Coding Agent 沙箱安全指南：
| 模式 | 行为 | 适合场景 |
|---|---|---|
| 默认（普通确认） | 只读自动执行；修改文件和运行 shell 命令请求确认 | 首次使用、不熟悉项目时 |
Plan 模式（kimi --plan） | 先出计划，再执行；你可以在执行前检查和拒绝 | 任何修改操作的首选方式 |
| YOLO 模式 | 跳过普通确认 | 明确知道要做什么、已经充分验证过的重复任务 |
| Auto 模式 | 自动处理所有确认 | 完全理解风险后的高度自动化场景 |
我的建议是：第一次修改文件，用 Plan 模式。
kimi --plan
Plan 模式会先给你一份执行计划，你可以在它动手之前看清楚它打算做什么。这在你刚开始用新工具、或者对某个任务不太确定的时候，是最好的工作方式。交互界面中也可以输入 /plan 或按 Shift-Tab 切换。
YOLO 和 Auto 不是新手默认值，是你在充分验证之后可以选择的提速工具。把"先放弃确认权"当作目标本身，是把工具的效率优化和安全判断的顺序搞反了。
关于 --continue 标志
kimi --continue
--continue 用于恢复当前目录最近一次会话。如果你中途断开、想接着之前的上下文继续工作，用这个。
第一次修改：一个具体的路径
如果你已经做完了上面的只读任务，想进行第一次真正的修改，建议按这个顺序走：
- 确认你在一个有版本控制的目录（有 git 的仓库）；如果还不熟悉检查点、diff review 和验证流程，先看 AI 编程 Agent 新手路线
- 用 Plan 模式启动：
kimi --plan - 描述一个范围明确、影响面小的任务（比如"给这个函数加注释"，而不是"重构整个模块"）
- 查看 Plan 输出，确认它的修改范围符合你的预期
- 批准执行
- 用
git diff检查实际改动
这个流程看起来比直接交出自动执行权要慢，但你实际上在用这个流程建立对工具行为的理解。等你清楚它会怎么做、不会怎么做，再考虑是否调整权限级别。
在开放自动执行之前，可以直接检查的清单
以下是你在给工具更多权限之前，值得逐项确认的事情：
-
kimi --version返回了正确的版本号 -
kimi doctor完成配置校验，没有未解决的配置错误 - 旧版
~/.kimi/目录仍然完整（迁移不删旧数据，但确认一下没有坏处） - 清楚 OAuth 凭据和 MCP 服务授权是需要手动重建的
- 已经用只读任务验证了工具在你的项目里能正常工作
- 已经用 Plan 模式完成了至少一次有修改的任务
- 清楚 YOLO 和 Auto 的含义，有意识地选择它们，而不是因为文档里提到了就默认开启
这个清单没有技术门槛，但它要求你在每个步骤都确认过，而不是一路 y 下来。
一些注意事项
关于版本：本文基于 0.28.1 的测试，CLI 工具更新较快。安装后请用 kimi --version 和 kimi upgrade 确认你用的是最新版本。
关于费用和额度：本文不包含任何价格、免费额度、地区可用性的信息。这些内容变化较快，且我没有在发布前核实，请直接查看 Kimi 官方网站或平台控制台。
关于模型质量：我没有测试登录后的编码任务。本文不对响应质量、速度、token 消耗或与其他工具的比较做任何判断。
参考资料
- Kimi Code CLI 官方 README
- Kimi Code CLI 官方文档（中文）
- 迁移指南
- 旧版 Kimi CLI README 迁移通知
本文写于 2026-07-21，基于 Kimi Code CLI 0.28.1 的无登录隔离测试，以及官方文档中的公开信息。