Kimi Code CLI 自定义子代理使用指南本笔记讲解kimi code子代理机制：内置子代理特性、副模型配置、自定

版本：2026-08-01 依据：Kimi Code 官方文档（Agents and Sub-Agents / Configuration files）+ 本机实际配置官方文档入口：www.kimi.com/code/docs/e…

1. 什么是子代理（Sub-Agent）
2. 内置子代理
 3. 子代理模型（secondary model）
4. 自定义子代理：Agent 文件
 5. Agent 文件存放位置与优先级
 6. frontmatter 字段详解
 7. 正文模板变量
 8. 把自定义 Agent 用作主代理
 9. SYSTEM.md：永久覆盖主代理系统提示词
 10. 权限继承与工具控制
 11. 运行时行为与调试
 12. 完整实战示例
 13. 常见问题（FAQ）

1. 什么是子代理（Sub-Agent）

每个 Kimi Code 会话由一个主代理（main Agent） 驱动。主代理理解你的意图、规划步骤、调用工具；当任务可以拆分时，它会派出子代理处理更聚焦的子任务，例如：

探索不熟悉的代码库（避免把大量搜索日志灌进主上下文）
并行评审多个实现方案
在不污染主对话的前提下做大型重构的规划

子代理的特点：

上下文完全隔离：子代理只能看到主代理显式传给它的任务描述，看不到主对话历史；它的中间推理和工具调用记录也不会回流，只有最终结果进入主代理上下文。
独立消耗 token：每个子代理单独计费，简单任务没必要派子代理。
不直接与用户交互：它的输出是给主代理的"交接报告"。
可后台运行：完成后结果自动回传主代理，无需轮询；也可以被主代理"召回"（resume）继续同一任务。
派生需审批：每次派生在终端显示为一次审批请求（除非命中 allow 规则或处于 yolo/auto 模式），你可以审查任务描述。

2. 内置子代理

Kimi Code 自带三个内置子代理，开箱即用：

名称	用途	特点
`coder`	通用软件工程子代理（默认）	可读文件、改文件、执行命令、搜索代码；拥有主代理大部分工具集，可跑后台任务、维护 todo、进入 Plan 模式、调用 Skill、甚至再派生嵌套子代理
`explore`	代码库探索	只读，不修改任何文件。适合快速搜索、阅读、总结仓库
`plan`	实现规划与架构设计	连 shell 命令都没有，专注"搞清楚怎么做"而非"实际动手"

使用方式有两种：

自动派生：主代理根据任务复杂度、上下文消耗、子任务独立性自行决定时机，无需你指定。
对话中显式要求：例如直接说 "Use explore to map out the relevant files before making any changes."（用 explore 先梳理相关文件再动手）。

注意：coder 子代理如果在后台任务仍在运行时结束本轮，会等后台任务收尾后才汇报完成，保证父代理拿到的是"真正做完"的结果。

3. 子代理模型（secondary model）

3.1 功能说明

默认情况下，子代理继承主代理的模型。Kimi Code 提供了一个实验性功能：配置一个 secondary model（副模型），让新派生的子代理默认绑定到这个模型上——典型场景是给子代理配一个更便宜的模型，主代理继续用强模型。

配置后，主代理在派生子代理时可以在两种选择间切换：

"secondary"：使用 [secondary_model] 配置的模型（默认）
"primary"：使用主代理自己的模型

3.2 启用实验开关（必须）

该功能默认关闭，需要以下任一方式启用：

# 方式一：单独开关
export KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=1

# 方式二：实验功能总开关
export KIMI_CODE_EXPERIMENTAL_FLAG=1

或者在 config.toml 中启用（与 env 等效的配置文件形式）：

[experimental]
secondary-model = true

启用后在所有启动模式（含交互式 TUI）生效。

3.3 配置 secondary model

在 ~/.kimi-code/config.toml 中添加：

[secondary_model]
model = "alibaba-token-plan-cn/qwen3.8-max-preview"   # 必填：[models] 表中已定义的模型别名（不限于 Kimi 模型）
default_effort = "medium"                              # 可选：子代理绑定该模型时的思考力度
max_output_size = 8192                                 # 可选：模型参数补丁

字段说明：

字段	说明
`model`	指向 `[models]` 表中任意已配置的模型别名
`default_effort`	子代理的思考力度。不设置时按"全局 `[thinking]` → 模型自身默认"的规则解析；对 effort 校验严格的模型（如 Kimi 模型），不支持的值会回退到模型默认值
其他字段	接受 `[models."<alias>".overrides]` 的所有字段（`max_context_size`、`max_output_size`、`support_efforts` 等），作为仅作用于子代理的模型补丁

补丁机制：只要设置了至少一个补丁字段，运行时会在内存中合成一个派生模型条目（原条目 + 补丁，补丁优先），子代理绑定这个派生条目；它只存在于内存中，不会写回 config.toml，也不会出现在模型选择列表里。

3.4 TUI 命令与环境变量

/secondary_model：交互式 TUI 中打开模型选择器，写入配置并立即对当前会话生效，新派生的子代理马上绑定新模型。
环境变量覆盖（优先级高于 config.toml）：

export KIMI_SECONDARY_MODEL="alibaba-token-plan-cn/qwen3.8-max-preview"
export KIMI_SECONDARY_EFFORT="medium"

3.5 生效验证与优先级

启用实验功能后，会话启动时会校验配置：model 无法解析、或 default_effort 不在模型支持列表中，会产生启动警告。校验是提示性的——配置错误时子代理会在派生时报错，并附带来源提示。

模型选择优先级（从高到低）：

派生时工具调用显式传入的 model 参数（"primary" / "secondary"）
自定义 agent 文件 frontmatter 里的 model_preference
[secondary_model] 配置（配了就用 secondary）
以上都没有 → 继承主代理模型

本机当前配置（示例）：

# C:/Users/admin/.kimi-code/config.toml
default_model = "kimi-code/k3-256k"          # 主代理模型

[experimental]
secondary-model = true

[secondary_model]
default_effort = "medium"
model = "alibaba-token-plan-cn/qwen3.8-max-preview"

即：主代理跑 K3-256k，子代理默认跑 Qwen3.8 Max Preview（思考力度 medium）。

4. 自定义子代理：Agent 文件

除了三个内置子代理，你可以用 Markdown 文件定义自己的 agent。每个文件描述一个 agent：

frontmatter（文件顶部的 YAML 元数据）：声明名称、描述、工具权限、模型偏好等
正文：该 agent 的系统提示词（system prompt）

自定义 agent 有两种用途：

作为子代理被派生：主代理会像发现内置子代理一样自动发现它们
作为主代理启动：通过 --agent / --agent-file 在启动时选定（见第 8 节）

最小示例（reviewer.md）：

---
name: reviewer
description: 严格的代码评审员，按严重程度分级报告问题
whenToUse: 代码评审与 PR 检查
tools:
  - Read
  - Grep
  - Glob
---

你是一名严格的代码评审员。先阅读 diff，然后按严重程度分组报告发现的问题……

你的最后一条消息就是给调用方的完整交接结果，请确保它自包含、可直接使用。

重要提示：自定义 agent 作为子代理运行时，没有内置子代理的"最后一条消息即交接"框架。如果你写的 agent 是用于被派生的，请在正文中明确写明"你的最后一条消息应当是给调用方的完整、自包含的结果"。

5. Agent 文件存放位置与优先级

CLI 按"作用域"发现 agent 文件，更具体的作用域优先级更高：

显式（--agent-file） > 项目级 > Extra 目录 > 用户级 > 插件级 > 内置

两个文件定义了相同的 name 时，高优先级作用域胜出。每个目录都会递归扫描 .md 文件。

5.1 用户级（对所有项目生效）

$KIMI_CODE_HOME/agents/（默认 ~/.kimi-code/agents/；Windows 上即 C:/Users/<用户名>/.kimi-code/agents/）
~/.agents/agents/（通用目录，不随 KIMI_CODE_HOME 移动，可跨工具共享）

5.2 项目级（项目根 = 从工作目录向上找最近的含 `.git` 的目录）

.kimi-code/agents/
.agents/agents/

5.3 Extra 目录

在 config.toml 顶层声明：

extra_agent_dirs = ["~/team-agents", ".agents/team-agents"]

5.4 插件级

已启用插件的 manifest agents 字段声明的目录（缺省取插件根下的 agents/）。插件 agent 仅高于内置 agent。

5.5 同名覆盖规则

目录中发现的文件要覆盖同名内置 agent，frontmatter 必须声明 override: true。
通过 --agent-file 加载的文件本身就是显式启动意图：可以覆盖同名内置 agent、高于一切目录作用域、仅本次启动生效（不需要 override 字段）。

⚠️ 信任模型警告：项目级 agent 文件来自仓库本身——包括你刚 clone 下来、还不信任的仓库。一个项目作用域的文件可以完全接管内置 agent：命名为 agent.md 且 override: true 会替换默认主代理的整个系统提示词；coder.md 且 override: true 会替换默认子代理类型。与 AGENTS.md（只是注入提示词的参考数据）不同，覆盖文件就是系统提示词本体，且不带 tools 列表的文件保留全部工具。在不熟悉的仓库中运行 Kimi Code 之前，请像审查脚本一样审查 .kimi-code/agents/ 和 .agents/agents/。

6. frontmatter 字段详解

---
name: reviewer                    # 可选，kebab-case；缺省用文件名去扩展名
description: 严格的代码评审员      # 必填，主代理据此决定何时派生
whenToUse: 代码评审与 PR 检查      # 可选，补充"何时使用"的提示
override: false                   # 可选，是否可覆盖同名内置 agent，默认 false
model_preference: secondary       # 可选，模型偏好：primary / secondary
tools:                            # 可选，工具白名单
  - Read
  - Grep
  - mcp__github__*
disallowedTools:                  # 可选，工具黑名单（在 tools 之后应用）
  - Bash
subagents:                        # 可选，允许再派生的子代理类型白名单
  - explore
---

字段	必填	说明
`name`	否	kebab-case 唯一标识。缺省取文件名（`review.md` → `review`）；解析不出或不合法的文件会被跳过并警告
`description`	是	agent 是干什么的。会展示给主代理用于派生决策，要写成能引导派生判断的描述
`whenToUse`	否	何时使用该 agent 的补充提示
`override`	否	是否允许覆盖同名内置 agent，默认 `false`；`--agent-file` 不需要此字段
`model_preference`	否	派生此 profile 时的符号化默认模型：`primary` = 调用方主模型，`secondary` = `[secondary_model]` 配置的模型。工具调用显式传 `model` 会覆盖它；两者都没有时用已配置的 secondary model。仅在 secondary-model 实验开启时对新派生的子代理生效；不能写具体模型别名；被 resume 的子代理保持原模型
`tools`	否	工具白名单。支持 YAML 列表或逗号分隔字符串（`tools: Read, Grep`）。MCP 工具用 glob 匹配（`mcp__github__`）。省略=允许全部；单独一个 `` 也允许全部；空列表 `tools: []` = 禁用全部工具
`disallowedTools`	否	黑名单，语法同 `tools`，在 `tools` 之后应用
`subagents`	否	该 agent 可以再派生哪些子代理（白名单），语法同 `tools`。省略=允许全部；`*` 也允许全部

工具名匹配规则与注意事项：

内置/用户工具按大小写敏感的精确名匹配；mcp__ 开头的条目按 glob 匹配 MCP 工具。
三种写法永远匹配不到任何东西，profile 生效时会告警：
- 在非 mcp__ 模式里用裸 *（disallowedTools 里的裸 * 什么也禁用不了）
- 不是完整 mcp__<server>__<tool> 形式的 mcp__ 字面量（mcp__github 匹配不到——整服务器要用 mcp__github__*）
- 不存在的工具名（通常是拼写错误，如 read 应为 Read）
tools / disallowedTools 决定模型能看到哪些工具，并在执行前再强制校验一次；subagents 同理（Agent 工具只列出可派生的类型，派生前再校验；resume 已有子代理不受限）。权限规则（permission）是另一层独立的审批控制。
未知字段会被忽略，因此新版文件在旧版 CLI 上仍可读；其他工具的字段（Claude Code 的 model、OpenCode 的 mode）同样被忽略——带 description + 正文的最小文件可跨工具加载。

7. 正文模板变量

agent 文件正文在每次构建提示词时按模板渲染，${var} 占位符会替换为实时上下文值：

变量	内容
`${skills}`	合并后的 Agent Skills 注入；无 Skill 工具时为空
`${agents_md}`	工作区指令文件（如 `AGENTS.md`）的内容
`${cwd}`	当前工作目录
`${cwd_listing}`	工作目录列表
`${os}`	操作系统类型
`${shell}`	Shell 名称与路径，如 bash (`/bin/bash`)
`${now}`	当前时间（ISO 格式）
`${additional_dirs_info}`	额外加入工作区的目录；没有则为空
`${base_prompt}`	默认系统提示词。在 agent 文件中是"生效中的默认提示词"（内置默认，或你的 `SYSTEM.md` 覆盖）
`${plugin_sections}`	已启用插件贡献的完整 Plugin Instructions 块；无插件贡献时为空

渲染规则：

未知变量原样保留；裸 $ 永远不是特殊字符；没有上下文值的变量渲染为空字符串。
另有四个预组装的块：${windows_notes}、${additional_dirs_section}、${skills_section}、${plugin_sections}，渲染对应内置提示词小节（不适用则为空）。
内置默认提示词已包含 ${plugin_sections}，当 ${base_prompt} 已展开为该提示词时不要重复添加。

典型用法——"包裹"默认行为而非替换它：

---
name: strict-coder
description: 在默认编码能力上叠加额外纪律的子代理
---

${base_prompt}

## 额外纪律
- 每次修改文件前先说明改动意图
- 禁止引入新依赖，除非用户明确批准

你的最后一条消息是给调用方的完整交接结果。

8. 把自定义 Agent 用作主代理

两个 CLI 旗标用于在新会话启动时选定主代理（print 模式 kimi -p 和交互式 TUI 均适用）：

旗标	作用
`--agent <name>`	用指定名字的 agent 作为主代理启动。名字可以是内置 agent 或任何已发现的文件；名字不存在会报错并列出可用 agent
`--agent-file <path>`	以最高优先级加载一个 agent 文件并用它启动。只能传一个文件，不能与 `--agent` 组合

示例：

kimi --agent reviewer
kimi -p --agent reviewer "Review the changes on this branch"

约束与行为：

两个旗标只适用于新会话——不能与 --session / --continue 组合。agent 在会话创建时绑定，resume 时自动恢复，无需（也不允许）再传旗标。
绑定的 agent 是会话的身份标识：首次绑定后不能切换。TUI 中旗标只绑定启动会话；之后在同进程内新建的会话（如 /new）回到默认 agent。
主代理定制的建议：正文中引用 ${base_prompt}，让环境、工作区指令、Skill、插件注入保持生效；只想保留插件指令用 ${plugin_sections}；两者都不写则正文独占整个提示词并排除插件指令（适合自包含的子代理）。

9. SYSTEM.md：永久覆盖主代理系统提示词

不想每次启动都传 --agent / --agent-file？写一个 $KIMI_CODE_HOME/SYSTEM.md（默认 ~/.kimi-code/SYSTEM.md，随 KIMI_CODE_HOME 移动）：

文件存在且非空时，完整替换默认主代理的系统提示词——仅替换提示词；description、工具集、子代理派生白名单仍继承内置默认。
所有启动模式（含 TUI）生效；无需 frontmatter（也不读取）。
文件缺失/为空无效果；读取失败回退到内置提示词并告警。

优先级关系：

显式意图高于它：项目作用域同名 agent 文件 + override: true、以及 --agent-file 传入的文件都优先于 SYSTEM.md；用 --agent 选择其他 agent 则完全绕过它。
用户作用域内部：SYSTEM.md 优先于 agents/ 目录中发现的同名文件。

SYSTEM.md 正文同样按模板渲染（变量见第 7 节）。用变量重建内置提示词骨架的示例：

You are Kimi, running at ${cwd} on ${os}.

${agents_md}

${skills}

${plugin_sections}

另外，全局 Kimi 专属指令可放 $KIMI_CODE_HOME/AGENTS.md（默认 ~/.kimi-code/AGENTS.md，随 KIMI_CODE_HOME 移动）；跨工具通用指令放 ~/.agents/AGENTS.md；项目级指令放项目树内（如 .kimi-code/AGENTS.md 或 AGENTS.md）。

10. 权限继承与工具控制

权限规则继承：主代理通过 /permission 或审批对话框接受的 "always allow" 规则，会自动传播给它派生的所有子代理——子代理无需对同类工具调用重复审批。
Agent 工具本身默认放行，主代理可以多次委派而不打断你。
要让某类工具在子代理内永久不可用，在主代理上收紧对应的权限规则。
三层控制的区别：
1. agent 文件的 tools / disallowedTools / subagents：决定该 agent 能用哪些工具/能派生哪些子代理
2. config.toml 的 [tools]（enabled / disabled）：全局开关，作用于所有会话的所有 agent，与各 agent 自身的策略取交集
3. [[permission.rules]]：审批控制（allow / deny / ask），与前两层独立

全局工具开关示例：

[tools]
disabled = ["EnterPlanMode", "ExitPlanMode", "mcp__github__*"]

11. 运行时行为与调试

11.1 超时

[subagent]
timeout_ms = 7200000    # 单个子代理最长运行时间，默认 2 小时；0 = 不限时

可被环境变量 KIMI_SUBAGENT_TIMEOUT_MS 覆盖。超过 2147483647（约 24.8 天）会被钳制到约 24.8 天。print 模式（kimi -p）下默认 0（不限时）。

11.2 派生时的模型选择（主代理视角）

secondary-model 实验开启后，主代理的 Agent / AgentSwarm 工具会收到 model 参数说明：

不传 model：使用配置的 secondary model（未配置则继承主模型）
model: "secondary"：显式使用 secondary model
model: "primary"：显式使用主模型（困难、质量敏感的任务建议用主模型）
agent 文件的 model_preference 会作为 profile 描述的一部分展示给主代理，主代理仍可为特定任务显式覆盖

11.3 会话目录中的持久化

子代理的运行时状态保存在当前会话目录的 agents/ 子目录下。每个子代理实例一个目录，其中：

wire.jsonl：按时间顺序记录提示词、消息历史、最终状态
后台子代理还通过 tasks/ 子目录暴露生命周期状态

⚠️ 会话目录、wire 文件、任务记录都是本地调试材料，可能包含你的提示词、命令输出、仓库路径、工具返回值甚至凭据痕迹。不要直接提交到公开仓库、issue 或聊天记录，分享前先脱敏。

12. 完整实战示例

12.1 场景：为 GEO 项目配一个"平台内容审核"子代理

需求：主代理生成营销内容后，派一个子代理按项目规范审核，审核用便宜的 secondary model 跑。

第一步：确认 secondary model 已配置（本机已配好，见 3.5 节）。

第二步：创建用户级 agent 文件 C:/Users/admin/.kimi-code/agents/geo-content-reviewer.md：

---
name: geo-content-reviewer
description: 按 GEO 项目规范审核营销内容的审核员，输出按严重程度分级的问题清单
whenToUse: 审核为各平台生成的营销文案、检查品牌语气与合规性
model_preference: secondary
tools:
  - Read
  - Grep
  - Glob
disallowedTools:
  - Bash
  - Write
  - Edit
---

你是一名中文营销内容审核员。审核流程：

1. 先阅读工作区中的品牌语气与规范文件（如 AGENTS.md、品牌语气.md，如存在）。
2. 再阅读调用方指定的待审核内容文件。
3. 按以下维度检查：品牌语气一致性、事实准确性、平台合规风险、错别字与语病。
4. 输出按严重程度（阻断/重要/建议）分级的问题清单，每条注明文件与位置。

纪律：
- 只读不写，绝不修改任何文件。
- 不确定的事实要标注"待人工确认"，不要臆断。

你的最后一条消息就是给调用方的完整审核报告，必须自包含（调用方看不到你的中间过程）。

第三步：对话中直接使用：

用 geo-content-reviewer 审核 test/旅游/ 下刚生成的三篇文案

主代理会自动发现这个 agent，派生时按 model_preference: secondary 绑定 Qwen3.8 Max Preview。

12.2 场景：项目级 agent（团队共享）

在仓库内创建 .kimi-code/agents/db-migrator.md，该 agent 仅在此项目中可用，并随仓库分发给团队（注意第 5.5 节的信任模型——团队成员应审查该文件）。

12.3 场景：批量并行评审（AgentSwarm）

主代理可以用 AgentSwarm 让一个 prompt 模板跑在多个输入上，例如对 10 个文件并行做同一类评审，每个文件一个子代理实例（最多 128 个，自动排队）。适合无共享状态、无先后依赖的独立任务。每个实例同样遵守 secondary model 绑定规则。

13. 常见问题（FAQ）

Q：配了 [secondary_model] 但子代理还是在用主模型？ A：检查实验开关是否启用（[experimental] secondary-model = true 或环境变量 KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=1 / KIMI_CODE_EXPERIMENTAL_FLAG=1）。其次检查 KIMI_SECONDARY_MODEL 环境变量是否覆盖成了别的值。最后确认 [secondary_model].model 指向的别名在 [models] 表中存在。

Q：model_preference 能直接写模型名吗？ A：不能。它只接受符号值 primary / secondary，具体模型由 default_model 和 [secondary_model] 决定。

Q：自定义 agent 文件改了之后不生效？ A：检查 name 是否 kebab-case、是否与更高优先级作用域的文件同名（项目级 > Extra > 用户级）。目录中发现的无效文件会被跳过并告警。另外 resume 已有子代理会保持它原有的模型和 profile。

Q：想让子代理彻底不能执行 shell 命令？ A：在 agent 文件中 disallowedTools: [Bash]（或 tools 白名单不含 Bash）。要对所有 agent 生效，用 config.toml 的 [tools] disabled。不要用裸 * 放进 disallowedTools——它匹配不到任何东西。

Q：MCP 工具怎么整体放行/禁用某个 server？ A：用 glob 形式 mcp__<server>__*（如 mcp__github__*）。mcp__github 这种不带工具段的写法匹配不到任何工具。

Q：子代理跑太久卡住了？ A：默认超时 2 小时（[subagent] timeout_ms）。可用 KIMI_SUBAGENT_TIMEOUT_MS 调整；主代理也可以用任务管理工具查看/停止后台子代理。

Q：如何确认当前生效的子代理模型？ A：TUI 中 /secondary_model 可查看/修改；或直接检查 config.toml 的 [secondary_model] 段及环境变量。会话中主代理的 Agent 工具描述里也会列出当前的 primary/secondary 模型。

Kimi Code CLI 自定义子代理使用指南

目录