Kimi Code 文档

简体中文

English

简体中文

English

Appearance

内置工具 ​

内置工具是 Kimi Code CLI 随核心引擎提供的工具集，无需安装 MCP server 即可使用。Agent 在每次对话中会根据任务需要自动选择并调用这些工具；用户可以通过权限审批界面查看每次工具调用的细节。

与 MCP 工具相比，内置工具由运行时直接管理，生命周期与会话绑定，无需外部进程。两者都遵循统一的审批机制：只读类工具（如 Read、Grep、Glob）默认自动放行，写入与执行类工具（如 Write、Edit、Bash）默认需要用户审批。YOLO 模式下普通工具调用的审批会被跳过，但 Plan 模式下的退出审批不受影响。

文件类 ​

文件类工具负责读取、写入、搜索本地文件系统，是代码分析和修改任务的基础工具。

工具默认审批说明
Read自动放行读取文本文件内容
Write需审批创建或覆盖文件
Edit需审批精确字符串替换
Grep自动放行基于 ripgrep 的全文搜索
Glob自动放行按 glob 模式查找文件
ReadMediaFile自动放行读取图片或视频文件

Read 接受文件路径（path）以及可选的 line_offset（起始行号，支持负数从末尾倒数）和 n_lines（读取行数上限）。单次最多返回 1000 行或 100 KB，超出部分会附带截断提示。如果文件是图片或视频，工具会提示改用 ReadMediaFile。

Write 接受 path、content 和可选的 mode（overwrite 或 append，默认覆盖）。父目录必须已存在；append 模式将内容追加到文件末尾，不自动添加换行。

Edit 接受 path、old_string（要替换的精确文本）和 new_string（替换后的文本）。默认只替换唯一一处匹配，若文件中存在多处相同内容会报错并提示使用 replace_all: true。old_string 与 new_string 不能相同。

Grep 调用 ripgrep 搜索文件内容，支持正则表达式（pattern）、搜索路径（path）、文件类型过滤（type，如 ts、py）、glob 过滤（glob）和输出模式（output_mode：files_with_matches / content / count_matches，默认 files_with_matches）。content 模式支持上下文行（-A、-B、-C）、忽略大小写（-i）、行号（-n，默认 true）、跨行匹配（multiline）。所有模式支持 offset + head_limit 分页，head_limit 默认 250、传 0 表示不限。.env、私钥等敏感文件会被自动过滤；include_ignored=true 可搜索被 .gitignore 忽略的文件，但敏感文件仍保持过滤。

Glob 按 glob 模式（pattern）在指定目录（path，默认工作目录）中匹配文件，结果按修改时间倒序排列，最多返回 1000 条。纯通配符模式（如 **）和含花括号扩展（{a,b,c}）的模式会被拒绝。

ReadMediaFile 将图片或视频以多模态内容发送给模型，仅接受 path，文件大小上限 100 MB。是否可用取决于当前模型的视觉能力（image_in / video_in）。

Shell ​

工具默认审批说明
Bash需审批执行 Shell 命令

Bash 是权限要求最严格的工具，也是功能最通用的工具。参数：

  • command（必填）：要执行的 Shell 命令
  • cwd：工作目录
  • timeout：超时时间（毫秒）；前台默认 60 秒、最长 5 分钟
  • run_in_background：是否以后台任务运行；后台默认 10 分钟超时
  • description：后台任务描述，run_in_background=true 时必填
  • disable_timeout：后台任务是否取消超时限制

前台模式会阻塞当前轮次，直到命令结束或超时；后台模式立即返回任务 ID，任务结束时自动通知 Agent。stdin 始终被关闭，交互式命令会立即收到 EOF。两阶段终止策略（SIGTERM → 5 秒宽限期 → SIGKILL）确保超时后进程可靠结束。Windows 平台默认使用 Git Bash。

网络类 ​

工具默认审批说明
WebSearch自动放行网络搜索
FetchURL自动放行获取指定 URL 的内容

WebSearch 接受 query（搜索词）和可选的 limit（返回结果数，1–20，默认 5）及 include_content（是否返回网页正文，默认 false）。需要宿主提供搜索实现，未注入时不会出现在工具列表中。

FetchURL 接受单个 url 参数，返回页面内容。对 HTML 页面，宿主会提取正文而非返回完整 HTML；纯文本或 Markdown 页面直接透传。同样需要宿主注入实现。

Plan 模式 ​

工具默认审批说明
EnterPlanMode自动放行进入 Plan 模式
ExitPlanMode自动放行（需用户确认计划）退出 Plan 模式并提交计划

Plan 模式是一种受约束的工作状态：进入后 Write 与 Edit 只允许写入当前的计划文件，TaskStop 被完全拦截。其余工具（包括 Bash）仍按当前权限规则处理。

EnterPlanMode 不接受任何参数，进入成功后返回工作流指引及计划文件路径。

ExitPlanMode 读取当前计划文件内容，将计划呈现给用户审批后退出 Plan 模式。可选参数 options 允许 Agent 提供 1–3 个备选方案（每项含 label 与 description，label 最长 80 字符），供用户在审批时选择；label 不能重复，也不能使用 Approve、Reject、Reject and Exit、Revise 等保留词。

状态管理 ​

工具默认审批说明
TodoList自动放行管理任务待办列表

TodoList 在多步骤操作中维护一份可见的子任务列表，状态存储在 Agent 会话内。todos 参数接受一个数组，每项含 title 和 status（pending / in_progress / done）；省略 todos 则仅查询当前列表，传入空数组则清空列表。

协作类 ​

协作类工具负责 Agent 间协作、用户交互和 Skill 调用。

工具默认审批说明
Agent自动放行派生子 Agent 执行子任务
AskUserQuestion自动放行向用户提问以获取结构化输入
Skill自动放行调用已注册的 inline Skill

Agent 将子任务委托给子 Agent 执行。必填参数：prompt（完整任务描述）和 description（3–5 个词的简短说明）。可选参数：subagent_type（默认 coder）、resume（恢复已有 Agent 的 ID，与 subagent_type 互斥）和 run_in_background（默认 false）。Agent 任务使用固定 30 分钟超时。前台模式下父 Agent 等待子 Agent 完成再继续；后台模式立即返回任务 ID，完成时通过合成 User 消息自动回到主 Agent。子 Agent 体系细节见 Agent 与子 Agent。

AskUserQuestion 以结构化多选题的形式向用户提问，适用于需要消歧或选择方案的场景。questions 参数接受 1–4 道题，每道题需提供 question（以 ? 结尾）、options（2–4 个选项，每项含 label 和 description）以及可选的 header（最多 12 字符）和 multi_select（默认 false）。系统自动附加"其他"选项。background 为 true 时启动后台问题任务并立即返回任务 ID。宿主未实现交互式提问能力时返回失败提示，Agent 应改为在文本回复中直接提问。

Skill 允许 Agent 主动调用已注册的 inline 类型 Skill。接受 skill（Skill 名称）和可选的 args（附加参数文本）。只有 type = "inline" 的 Skill 能通过此工具调用；disableModelInvocation: true 的 Skill 会被拒绝。嵌套调用深度上限 3 层。Skill 体系细节见 Agent Skills。

后台任务 ​

后台任务工具用于管理通过 Bash、Agent 或 AskUserQuestion 启动的后台任务。任务进入终止状态时会自动把状态和末尾输出送回 Agent；如需提前检查进度，使用 TaskOutput。

工具默认审批说明
TaskList自动放行列出后台任务
TaskOutput自动放行查看后台任务的输出
TaskStop需审批停止正在运行的后台任务

TaskList 返回后台任务列表。可选参数 active_only（默认 true，仅列出运行中的任务）和 limit（默认 20，取值范围 1–100）。

TaskOutput 根据 task_id 返回任务状态与输出。内联预览最多包含最近 32 KB 的内容；完整日志保存在磁盘上，工具会一并返回 output_path 并提示通过 Read 分页读取。可选 block（默认 false）和 timeout（等待秒数，默认 30，取值范围 0–3600）参数可用于等待任务完成后再返回。

TaskStop 接受 task_id 和可选的 reason（默认 Stopped by TaskStop）。对已处于终止状态的任务也能安全调用。

定时任务 ​

定时任务工具允许 Agent 把一段 prompt 在未来某个时间重新注入到当前会话——既可以是一次性提醒，也可以是按 cron 周期触发的任务（定期巡检、每日报表、部署监控等）。计划绑定到会话，执行 kimi resume 后仍然有效，但不会带入全新的会话。单个会话最多保留 50 个生效中的定时任务。设置 KIMI_DISABLE_CRON=1 可整体禁用，详见环境变量。

工具默认审批说明
CronCreate需审批安排一个在未来时刻触发的 prompt
CronList自动放行列出已安排的定时任务
CronDelete需审批取消已安排的定时任务

CronCreate 接受 cron（用户本地时区下标准的 5 段 cron 表达式：minute hour day-of-month month day-of-week）、prompt（触发时要注入的文本，UTF-8 上限 8 KB）以及可选的 recurring（默认 true；传 false 表示一次性提醒，触发后自动删除）。成功时返回 8 位 16 进制 id、人类可读的 humanSchedule（如 every 5 minutes）和 nextFireAt（下次触发时间的 ISO 时间戳）。

为避免整批用户在整点同时触发，调度器会做确定性抖动：周期任务向后偏移 min(周期的 10%, 15 分钟)；一次性任务若恰好落在 :00 或 :30 则向前提前最多 90 秒。如果调度器错过了若干触发时刻（如笔记本合盖），唤醒后只会触发一次，prompt 会包裹在 <cron-fire> 信封里并附带 coalescedCount。周期任务存活超过 7 天后会以 stale="true" 做最后一次触发后自动删除；想继续保留时，再次调用 CronCreate 即可。

CronList 是只读工具，不接受任何参数。为每个生效中的任务返回一条记录，字段包括 id、cron、humanSchedule、nextFireAt、recurring、ageDays 和 stale。记录用 --- 分隔，按调度时间排列。

CronDelete 只接受一个 id。对周期任务，未来所有触发立即停止；对一次性任务，挂起的那次触发会被取消。已触发的一次性任务会自动删除，因此对已触发过的一次性任务调用 CronDelete 会返回 No cron job with id ...。删除不可撤销，需要还原时只能再次 CronCreate。CronDelete 在 Plan 模式下同样会被拦截。

下一步 ​