内置工具

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

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

文件类

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

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

Read 接受文件路径（path）以及可选的 line_offset（起始行号，支持负数从末尾倒数）、column_offset（正向读取时，起始行内从 0 开始的位置）、n_lines（请求读取的源文件行数）和 max_chars（结果的字符上限，包含行号和状态信息）。省略 n_lines 时向文件末尾读取。默认上限为 100,000 字符，调用可申请到 500,000 字符；两个值都可通过 read 配置 修改。字符数和列偏移按显示文本的 JavaScript 字符串长度计算，列偏移不包含行号前缀：常见字母和汉字各计 1，许多 emoji 计 2。

Read 优先返回完整行，结果不会再被通用工具输出限制缩短。如果单独一行也无法在一页中容纳，工具会返回片段，并在状态中说明列范围及 Next Read 参数，无需提高额度即可继续读取。拼接同一行的片段时不要额外插入换行。一行只返回部分内容时，仍会计入剩余的 n_lines 范围，直到行尾返回为止。非法列偏移会明确报错，不会跳过内容。

尾读优先返回请求范围中较新的完整行。如果连一条完整行都无法容纳，结果会给出未读范围的正向 Next Read 参数；column_offset 不能与负数 line_offset 同时使用。续读位置针对文件的当前内容，文件变化后应重新读取。如果尾读提示读取期间文件发生变化，请基于更新后的文件重试。10 MiB 以内的 UTF-16 LE/BE 文件会先尝试严格解码；失败后，Read 会将损坏序列替换为 � 并返回可读文本，同时在每一页提示发生了有损解码、文本可能与原文不同。告警也计入字符额度；有效文件中原本就有的 � 不会触发告警。图片和视频请使用 ReadMediaFile。

Write 接受 path、content 和可选的 mode（overwrite 或 append，默认覆盖）。缺失的父目录会自动创建；append 模式将内容追加到文件末尾，不自动添加换行。写入已存在的文件（无论 overwrite 还是 append 模式）要求本会话中先用 Read 读过该文件——若文件自上次读取后在磁盘上发生变化，写入会被拒绝；新建文件不受此限。

Edit 接受 path、old_string（要替换的精确文本）和 new_string（替换后的文本）。默认只替换唯一一处匹配，若文件中存在多处相同内容会报错并提示使用 replace_all: true。old_string 与 new_string 不能相同。目标文件必须在本会话中先用 Read 读过；若文件自读取后在磁盘上发生变化，编辑会被拒绝。

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，默认工作目录）中匹配文件，结果按修改时间倒序排列，默认返回 100 条。默认尊重 .gitignore、.ignore 和 .rgignore；设置 include_ignored=true 可包含构建产物等被忽略的文件，但敏感文件仍会被过滤。支持 *.{ts,tsx} 这类花括号模式，也允许宽泛通配符模式。

使用 offset（默认 0）和 head_limit（默认 100）对匹配路径分页；有更多结果时，工具会给出下一页的 offset。设置 head_limit: 0 可取消条数限制，但字符上限仍然有效：达到上限时，页面会在完整路径处结束，并给出下一页的 offset。较大的页面会保存到文件，Agent 可用 Read 读取。每次调用都会重新搜索当前文件系统，因此文件变化可能导致跨页结果移动。超时、目录无法读取或输出采集上限仍可能造成搜索不完整；结果会提示这些情况，增加 offset 无法恢复尚未收集的路径。

ReadMediaFile 将图片或视频以多模态内容发送给模型。它接受 path，以及 region、full_resolution 等可选的图片细节参数；文件大小上限为 100 MB。默认读图会按配置的模型限制压缩；如果自动压缩无法安全满足限制，工具会返回错误且不发送原图，并提示模型先创建更小的副本再读取。是否可用取决于当前模型的视觉能力（image_in / video_in）。

Shell

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

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

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

前台模式会阻塞当前轮次，直到命令结束或超时；命令运行期间，TUI 会把 stdout 和 stderr 流式显示在正在运行的 Bash 工具卡片中。前台命令超时后默认不会被终止，而是转为后台任务继续运行（受 600 秒默认后台超时约束）；如需恢复超时即终止的行为，将 [background] 的 bash_auto_background_on_timeout 设为 false。600 秒的默认后台超时可通过 bash_task_timeout_s 配置（0 = 无超时），且在 print 模式（kimi -p）下默认无超时。后台模式立即返回任务 ID，任务结束时自动通知 Agent。stdin 始终被关闭，交互式命令会立即收到 EOF。任务被停止或后台超时时采用两阶段终止策略（SIGTERM → 5 秒宽限期 → SIGKILL），确保进程可靠结束。Windows 平台默认使用 Git Bash。

网络类

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

WebSearch 接受 query（搜索词）。需要宿主提供搜索实现，未注入时不会出现在工具列表中。

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	自动放行	派生 subagent 执行子任务
AgentSwarm	swarm mode 中自动放行，否则需审批	启动基于 item 的 subagent，或恢复已有 subagent
AskUserQuestion	自动放行	向用户提问以获取结构化输入
NotifyUser	自动放行	在轮次进行中向用户展示一条简短的进展更新
Skill	自动放行	调用已注册的 inline Skill

Agent 将子任务委托给 subagent 执行。必填参数：prompt（完整任务描述）和 description（3–5 个词的简短说明）。可选参数：subagent_type（默认 coder）、resume（恢复已有 Agent 的 ID，与 subagent_type 互斥）、run_in_background（默认 false）和 model（在配置 subagent 模型池 后可用——[secondary_model.models] 表或仅一行 default_model：池中别名，或 "primary" 表示调用方自己运行的模型；resume 时无效）。未传入时 subagent 绑定池的 default_model；未配置模型池时，subagent 一律继承调用方模型。Agent 任务默认 2 小时超时，可通过 config.toml 的 [subagent] timeout_ms（0 = 无超时，或 KIMI_SUBAGENT_TIMEOUT_MS 环境变量）配置，且在 print 模式（kimi -p）下默认无超时。前台模式下父 Agent 等待 subagent 完成再继续；后台模式立即返回任务 ID，完成时通过合成 User 消息自动回到 main agent。多个前台 Agent 调用在同一步运行时，TUI 会合并展示，并为每个 subagent 显示运行、等待、完成或失败状态以及已耗时长。subagent 体系细节见 Agent 与 subagent。

AgentSwarm 可以从共享的 prompt_template 和 items 数组启动 subagent，也可以通过 resume_agent_ids 恢复已有 subagent，或在一次调用中同时使用两者。模板必须包含 占位符；每个 item 会替换该占位符，并启动一个新的 subagent。传入 subagent_type 可以指定整个 swarm 中所有新启动的 subagent 使用的 profile；省略时默认使用 coder。传入 model（在配置 subagent 模型池 后可用——[secondary_model.models] 表或仅一行 default_model）可以让新启动的 subagent 运行在池中别名指定的模型或调用方自己的模型（"primary"）上。未传入时新启动的 subagent 绑定池的 default_model；未配置模型池时则继承调用方模型。恢复的 subagent 保持其原有模型。不传 resume_agent_ids 时，本工具要求至少 2 个 item；传入 resume_agent_ids 时，可以恢复 1 个或多个已有 subagent。本工具最多支持 128 个 subagent，会等待全部 subagent 完成，并返回聚合报告。每个 subagent 默认 2 小时超时，可通过 config.toml 的 [swarm] timeout_ms（0 = 无超时，或 KIMI_CODE_SWARM_TIMEOUT_MS 环境变量）配置，且在 print 模式（kimi -p）下默认无超时；超时的 subagent 会被中止，并在聚合报告中标记为失败。在 TUI 中，前台 swarm 会在输入框上方显示实时 Agent swarm 进度面板。若一�模型响应调用 AgentSwarm，该调用必须是该响应中的唯一工具调用；如需运行多个 swarm，应先调用一个 AgentSwarm 并等待结果，再调用下一个，若单个模板可以覆盖这些工作，也可以合并为一个 swarm。在 manual 权限模式下，未处于 swarm mode 时调用 AgentSwarm 会触发审批，除非已有权限规则允许；swarm mode 已开启时，AgentSwarm 本身会自动放行。权限规则只能按工具名 AgentSwarm 匹配，不支持 AgentSwarm(swarm) 这类参数模式。默认情况下，本工具会逐步提升并发且不设上限（立即启动 5 个 subagent，之后每 700 毫秒再启动 1 个）；将 KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY 设为正整数可限制该阶段同时运行的 subagent 数量，不设置则表示不限制。若设置为非正整数的值，本次 AgentSwarm 调用会立即失败。

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

NotifyUser 让 main agent 和 subagent 发送简短进展更新，唯一参数 message 接受轻量 Markdown。TUI 的 Updates 面板会按顺序保留每条更新，同一来源的多条消息也不会互相覆盖。subagent 的消息使用已有的 agent ID（如 [agent-7]）作为同一行的来源标签；main agent 的消息不加前缀。完整消息通过分页阅读，不会被替换为一行摘要。

面板默认显示最新页，从末尾向前将渲染后的正文分组，每页最多八行。例如，十条单行更新会分为第一页两条、最后一页八条；不足八行的页面按实际内容占用空间。按 Ctrl-P 查看上一页，按 Ctrl-N 查看下一页。翻页直接在原面板中进行，不切换输入焦点、不改变草稿；到达第一页或最后一页时停止，不循环跳转。阅读旧页时，新追加的更新保持已有分页边界，并提示新增数量；回到最新页后，重新从末尾填满页面，并恢复跟随新更新。只有一页时，这两个按键保持原有编辑器行为。

轮次结束后，消息和当前页继续保留显示；下一次 main agent 轮次开始时才清空，subagent 自己的轮次不会清空面板。新会话、/clear 和重新打开会话时，面板从空白开始。只有工具成功返回并确认展示后，消息才会进入面板；等待审批时不会展示参数片段。失败、中断或被关闭开关抑制的通知不会进入面板，对话中的工具调用记录会保留实际展示结果。重要发现仍须写入最终回复或 subagent 的最终汇报。

整个功能都是默认关闭的实验特性。请在创建 TUI 会话前，通过 KIMI_CODE_EXPERIMENTAL_NOTIFY_USER=1、config.toml 中的 [experimental] notify_user = true 或 /experiments 启用。关闭状态下创建的会话不会提供该工具，也不会包含相关提示词指导。

已有会话的通知工具可用性和提示词保持不变，重新打开会话后也一样。关闭功能会隐藏面板并停用翻页快捷键；已有的 NotifyUser 调用仍正常结束�并返回更新未展示的说明。重新开启后，已具有该工具的会话恢复展示；如果会话是在关闭状态下创建的，需要新建会话才能使用 Updates。在 /experiments 中仅修改这个开关不会重载会话。

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

后台任务

后台任务工具用于管理通过 Bash、Agent 或 AskUserQuestion 启动的后台任务。任务进入终止状态时会自动把状态和已保存的输出路径（问题任务则直接送回答案）送回 Agent；如需提前检查进度，使用 TaskOutput；如果下一步必须等待某个任务的结果，使用 WaitFor 在当前轮次内等待。

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

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

TaskOutput 根据 task_id 返回任务状态与输出。内联预览最多包含最近 32 KB 的内容；完整日志保存在磁盘上，工具会一并返回 output_path 并提示通过 Read 分页读取。该调用始终是非阻塞的——立即返回当前快照，任务完成会通过自动通知送达。

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

WaitFor 把当前轮次挂起，直到后台任务结束、超时或收到 steer 消息。参数：timeout（必填，单位秒，上限 600）和可选的 task_id。不传 task_id 时，调用时刻运行中的任意一个后台任务结束即返回；当前没有运行中的后台任务时立即返回。超时不是错误——结果会列出仍在运行的任务，Agent 可以再次等待，也可以先处理其他工作。Steer（终端中按 Ctrl-S）会提前结束本次等待，后台任务继续运行，完成后仍会自动通知。已通过 WaitFor 汇报结果的任务不会再推送自动完成通知。

定时任务

定时任务工具允许 Agent 把一段 prompt 在未来某个时间重新注入到当前会话——既可以是一次性提醒，也可以是按 cron 周期触发的任务（定期巡检、每日报表、部署监控等）。计划绑定到会话，用 kimi --session 恢复会话后仍然有效，但不会带入全新的会话。单个会话最多保留 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 模式下同样会被拦截。

下一步

• Agent 与 subagent — Agent 工具的调度机制与上下文隔离
• Hooks — 在工具调用前后触发本地脚本
• 斜杠命令 — TUI 内置控制命令速查