01Kimi Code 是什么

Kimi Code CLI 是一个运行在终端中的 AI Agent：读写代码、执行 Shell 命令、搜索抓取网页，并在执行中自主规划和调整方案。整套 CLI 以 TypeScript 编写，通过 npm 分发，运行在 Node.js 之上。

✍️ 编写和修改代码

实现新功能、修复 Bug、完成重构，AI 自动读代码、写代码并验证。

🔍 理解项目

探索陌生代码库，解答架构和实现层面的问题，快速上手新项目。

⚙️ 自动化任务

批量处理文件、运行构建与测试、串联多个脚本，也能做调研和数据分析。

💡 开始前准备：macOS / Linux / Windows（PowerShell） + Kimi 会员订阅（或可用的 API Key）。推荐在支持真彩色的现代终端（如 Kitty、Ghostty、Windows Terminal）中运行。

02安装 · 升级 · 卸载

两种安装方式：官方脚本（推荐，无需预装 Node.js）或 npm 全局安装（需要 Node.js ≥ 22.19.0）。

方式一：脚本安装（推荐）

macOS / Linux：

Bash
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

Windows（PowerShell）：

PowerShell
irm https://code.kimi.com/kimi-code/install.ps1 | iex

macOS / Linux 也可以用 Homebrew：

Bash
brew install kimi-code
⚠️ Windows 用户首次启动前需安装 Git for Windows（CLI 使用其 Git Bash 作为 Shell 环境）。若 Git Bash 装在非标准路径，把环境变量 KIMI_SHELL_PATH 设为 bash.exe 的绝对路径。

方式二：npm 安装

已安装 Node.js 22.19.0+ 时：

Bash
npm install -g @moonshot-ai/kimi-code
Bash (pnpm)
pnpm add -g @moonshot-ai/kimi-code

验证 / 升级 / 卸载

Bash
# 验证安装
kimi --version

# 升级（交互式检查并安装最新版）
kimi upgrade

# 或直接用包管理器升级
npm install -g @moonshot-ai/kimi-code@latest

# npm 安装的卸载方式（脚本安装的删掉 kimi 可执行文件即可）
npm uninstall -g @moonshot-ai/kimi-code
💡 安装后找不到 kimi 命令？重启终端，或执行 source ~/.bashrc（zsh 用户 source ~/.zshrc），并确认 ~/.local/bin 在 PATH 中。macOS 首次运行较慢是 Gatekeeper 安全检查，属正常现象。

03启动与首次登录

Bash
# 进入项目目录，启动交互界面
cd your-project
kimi

# 不进入交互界面，只执行一条指令
kimi -p "帮我总结一下这个项目的结构"

# 继续上一次会话
kimi -c

首次登录 /login

首次启动需要配置 API 来源，在交互界面输入 /login，两种方式任选：

  • Kimi Code（OAuth）—— 验证码流程：在任意设备打开链接、登录、输入验证码即完成授权（走会员订阅额度）。
  • Kimi Platform API 密钥—— 输入来自 platform.kimi.com 或 platform.kimi.ai 的 API Key。
交互界面内输入
/login

退出登录用 /logout 清除当前凭证。想接入 Anthropic / OpenAI / Google 等其他供应商，直接编辑 ~/.kimi-code/config.toml 配置密钥。

生成项目说明书 /init

交互界面内输入
/init

自动扫描项目结构并生成 AGENTS.md，为 AI 提供项目背景、构建步骤、代码规范等上下文，让后续回答更懂你的项目。

第一个对话

登录完成后直接用自然语言描述任务：

示例 prompt
帮我看一下这个项目的目录结构，简单介绍一下每个目录是做什么的

只读操作默认自动执行；涉及改文件、执行 Shell 命令时，会先征求你的确认。输入 /help 可随时打开内置命令与快捷键面板，输入 /exit（或连按两次 Ctrl-C）退出。

04斜杠命令大全

在交互界面输入 / 会自动弹出可用命令列表。以下按用途分组整理：

🔐 账户与配置

命令说明
/login登录授权（OAuth 验证码 或 API Key 两种方式）
/logout退出登录，清除当前凭证
/model切换当前使用的模型与 Thinking 模式
/config快速打开配置文件进行编辑
/help打开内置帮助面板（命令 + 快捷键，↑/↓ 翻看，Esc 关闭）

💬 会话管理

命令说明
/new开启新会话，清空当前上下文（无需退出程序）
/sessions浏览历史会话列表并选择恢复（别名 /resume；列表中按 Ctrl-A 切换「当前目录 / 所有目录」）
/title <text>为当前会话设置自定义标题，方便后续查找
/fork派生当前会话：保留历史记录，独立分支继续
/undo回退一步（退出时会自动生成续接命令）
/add-dir把额外目录加入工作区（效果同启动参数 --add-dir）

🧠 上下文管理

命令说明
/clear清空当前会话所有上下文，重新开始（别名 /reset）
/compact手动压缩上下文，释放 token；可附带说明，如 /compact 重点保留数据库设计部分
/export把当前会话完整对话导出为 Markdown 文件，可指定输出路径
/import从文件（Markdown / 代码 / 配置等）或指定会话 ID 导入上下文

🛠 项目与退出

命令说明
/init扫描项目并生成 AGENTS.md 项目上下文文件
/exit退出 CLI（也可连按两次 Ctrl-C，或输入框为空时按 Ctrl-D）
💡 不知道能做什么时，先输入 /help——它是最全的内置速查表。

05快捷键大全

快捷键作用
Esc中断流式输出 / 关闭弹窗
Ctrl-C中断当前输出；空闲时连按两次退出 CLI
Ctrl-D输入框为空时退出 CLI
Shift-Tab切换 Plan 模式（先出计划再执行，适合复杂任务）
Ctrl-S在 AI 输出中途插入消息，无需等待回复结束
Ctrl-O折叠 / 展开工具输出，保持界面清爽
Ctrl-J插入换行，进行多行输入（适合长 prompt、多行代码）
Ctrl-V从剪贴板粘贴文本或图片（截图、设计稿、报错图可直接理解）
↑ / ↓翻阅历史输入 / 帮助面板选项
Enter发送消息 / 确认结构化选项
Ctrl-A在 /sessions 列表中切换「仅当前目录 ↔ 所有目录」范围

06会话与上下文管理

CLI 自动保存对话历史与运行状态，随时可以继续之前的工作。

续接会话的 4 种方式

Bash
# 1. 继续最近一次会话
kimi -c          # 或 kimi --continue

# 2. 恢复指定会话 ID
kimi --session <session-id>
  1. 命令行续接：如上，-c 或 --session <id>；
  2. 列表切换：交互界面输入 /sessions，显示标题和最后更新时间，选中即恢复；
  3. 退出时复制提示：会话退出（正常退出、Ctrl-C、/undo、/fork、切换会话）时会自动打印一条 kimi --session ... 续接命令，复制保存即可。

恢复会话时会回放历史对话，并自动还原：YOLO 开关、「本会话允许」的审批、Plan 模式状态、子 Agent 实例、--add-dir 添加的目录——无需重新配置。

上下文清理与压缩

交互界面内输入
# 彻底清空，重新开始
/clear

# 压缩上下文，保留关键信息
/compact

# 压缩时告诉 AI 重点保留什么
/compact 请重点保留登录模块的设计决策和待办事项
💡 底部状态栏实时显示 context 使用率。占用偏高时及时 /compact，避免重要信息被自动压缩时丢失。

导出与导入

交互界面内输入
# 导出当前会话为 Markdown
/export
/export ./notes/session-backup.md

# 从文件导入上下文（Markdown / 代码 / 配置文件等）
/import ./docs/design.md

# 从另一个会话导入完整历史
/import <session-id>
⚠️ 导出的文件可能包含代码片段、文件路径等敏感信息，分享前记得检查。

07交互与输入技巧

@ 引用文件 / 目录

输入 @ 会自动补全文件和目录路径，AI 会读取被引用内容作为上下文：

示例 prompt
解释一下 @src/utils/auth.ts 里 token 刷新的逻辑，并参考 @docs/api.md 检查是否一致

Thinking 模式

用 /model 切换模型与 Thinking 模式，或启动时加 --thinking 直接开启。复杂问题（架构设计、疑难 Bug）建议开启。

Plan 模式

按 Shift-Tab 切换。开启后 AI 先输出执行计划供你审阅，确认后再动手——适合影响面大的重构、迁移类任务。

审批确认

AI 要修改文件或执行 Shell 命令时，会弹出三个选项：

选项含义
允许仅允许本次操作
本会话允许同类操作在当前会话内不再询问（恢复会话后仍有效）
拒绝拒绝本次操作

YOLO 模式（高风险）

Bash
kimi --yolo
⚠️ YOLO 模式下 AI 自动执行所有操作、跳过全部确认。仅在可控的开发环境 / 沙箱 / Docker 中使用，生产环境勿开。

其他实用细节

  • 多行输入：Ctrl-J 换行，长 prompt 不分段发送；
  • 贴图提问：Ctrl-V 直接粘贴截图 / 设计稿 / 报错图，AI 能看懂图片；
  • 结构化问答：AI 给出选项时，方向键选择 + Enter 确认；
  • 中途插话：Ctrl-S 在输出过程中插入补充消息。

08命令行启动参数

在终端里直接跟在 kimi 后面的参数，完整列表可随时运行 kimi --help 查看。

参数 / 子命令说明
kimi启动交互式界面
kimi -p "指令"单条指令模式：不进入交互界面，执行完即退出（适合脚本调用）
kimi -c / --continue继续最近一次会话
kimi --session <id>恢复指定 ID 的会话
kimi --thinking启动时直接开启 Thinking 深度思考模式
kimi --add-dir <路径>把额外目录加入工作区（会话内对应 /add-dir）
kimi --system-prompt "..."启动时指定自定义 system prompt（优先级最高）
kimi --yoloYOLO 模式：跳过所有审批确认（谨慎使用）
kimi upgrade检查并升级到最新版本
kimi acp启动 ACP 适配层，供 IDE（Zed / JetBrains 等）接入
kimi --version查看当前版本号
kimi --help查看全部启动参数说明

09配置与环境变量

配置文件与数据目录

  • 配置文件：~/.kimi-code/config.toml（支持 TOML / JSON），可配置模型供应商、API 地址、密钥、默认模型、超时与并发等；会话内输入 /config 快速打开。
  • 数据目录：~/.kimi-code/，存放配置、会话记录、日志和更新缓存；用 KIMI_CODE_HOME 环境变量可迁移到别的路径。

AGENTS.md：项目级上下文

在项目根目录放置 AGENTS.md，写入项目背景、构建步骤、代码规范、注意事项，AI 会自动加载。三层自定义 system prompt 的优先级：

  1. --system-prompt 启动参数（最高）
  2. 项目根目录 AGENTS.md（仅当前项目）
  3. 全局 ~/.kimi/AGENTS.md（对所有项目生效）

环境变量

变量说明
KIMI_API_KEYAPI 密钥
KIMI_BASE_URL自定义 API 地址
KIMI_MODEL默认模型名称
KIMI_MAX_TOKENS最大输出 token 数
KIMI_CODE_HOME自定义数据目录（替代 ~/.kimi-code/）
KIMI_SHELL_PATHWindows 下指定 Git Bash 的 bash.exe 绝对路径

环境变量优先级高于配置文件，适合 CI/CD 或脚本场景。

MCP 扩展

支持 Model Context Protocol，可在 ~/.kimi-code/config.toml 或项目级配置中添加 MCP 服务器，让 AI 调用外部工具与数据源；部分常用 MCP 工具已内置。

两套 API 体系，别混用！

平台Base URL计费Key 入口
Kimi CodeOpenAI 兼容 https://api.kimi.com/coding/v1
Anthropic 兼容 https://api.kimi.com/coding/		会员订阅含额度Kimi Code 控制台
Kimi 开放平台https://api.moonshot.cn/v1按量付费开放平台官网

10IDE 与工具集成

通过 ACP（Agent Client Protocol）把 Kimi Code 接进编辑器，复用终端的登录状态，无需重复授权。

Zed 编辑器

在 ~/.config/zed/settings.json 添加：

JSON
{
  "agent_servers": {
    "Kimi Code CLI": {
      "type": "custom",
      "command": "kimi",
      "args": ["acp"],
      "env": {}
    }
  }
}

JetBrains 系列（IDEA / PyCharm / WebStorm…）

AI 聊天面板菜单 → Configure ACP agents，添加同上配置；command 必须填绝对路径（终端运行 which kimi 获取）。无 JetBrains AI 订阅时，可在注册表（连按两次 Shift 搜 Registry）启用 llm.enable.mock.response 打开 AI 聊天面板。

VS Code 与 Paseo

  • VS Code：扩展市场搜索安装官方 Kimi Code 扩展，登录即用；
  • Paseo：在 ACP provider 目录选择 Kimi Code CLI，或写入 ~/.paseo/config.json；注意先在终端完成 /login，否则报 Authentication required。

Zsh 快速唤起插件

Bash (Oh My Zsh)
git clone https://github.com/MoonshotAI/zsh-kimi-cli.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/kimi-cli
# 然后在 ~/.zshrc 的 plugins 列表加入 kimi-cli，重载配置：
source ~/.zshrc

装好后在终端按 Ctrl-X 即可快速切入 Kimi Code CLI。

💡 排障：IDE 提示 "agent exited" 多为路径错误或未登录——先在终端跑一次 kimi acp 验证；提示 "auth required" 则回终端完成 /login。macOS 下 GUI 启动的子进程不继承终端 PATH，务必用绝对路径。

11常见使用案例（Prompt 模板）

✨ 实现新功能

prompt
给用户模块加一个「导出 CSV」功能：在设置页加入口，导出当前用户的全部订单数据，带上loading状态和错误提示

🐛 修复 Bug

prompt
线上报这个错（粘贴堆栈）：TypeError: Cannot read properties of undefined...
帮我定位根因并修复，修完跑一下相关测试确认没引入新问题

📖 理解陌生项目

prompt
我刚接手这个项目，帮我梳理：1) 整体架构和模块划分 2) 核心数据流怎么走 3) 登录鉴权是怎么实现的

🤖 自动化小任务

prompt
把 src 下所有 .js 文件里的 var 批量替换成 let/const，替换后跑一遍 lint 确认没有报错
prompt
给 @src/api/user.ts 里的所有公开函数补充 JSDoc 注释，并为 generateToken 写单元测试

📊 不限于编程的通用任务

prompt
把这个目录下的 200 张图片按 EXIF 拍摄日期整理到「年-月」子文件夹里，重名文件自动加序号
💡 用好 Kimi Code 的心法：说清目标 + 给出约束 + 让它自验证（跑测试 / lint）。大任务先开 Plan 模式审计划，长会话勤用 /compact。

12常见问题 FAQ

Q：填了 API Key 提示鉴权失败？

A：Key 和 Base URL 必须属于同一平台。api.kimi.com（Kimi Code，会员额度）和 api.moonshot.cn（开放平台，按量付费）是两套独立账号体系，Key 互不通用——对照第 09 节的表检查。

Q：安装后找不到 kimi 命令？

A：重启终端或 source ~/.bashrc / source ~/.zshrc；仍不行就检查 ~/.local/bin 是否在 PATH 里。

Q：/login 后浏览器没弹出来？

A：远程服务器 / 无图形界面环境下，终端会直接显示一个 URL，手动复制到浏览器打开完成授权即可。

Q：macOS 首次启动特别慢？

A：是 Gatekeeper 安全检查。在「系统设置 → 隐私与安全性 → 开发者工具」中添加你的终端应用，后续启动会快很多。

Q：上下文快满了怎么办？

A：看底部状态栏的 context 使用率，先 /compact 保留关键决策 压缩；开新任务就直接 /new 或 /clear。