Hooks

Hooks（钩子）是 Kimi Code CLI 提供的高度灵活的事件驱动扩展机制：你预先告诉 Kimi Code CLI"每当发生 X，运行这个脚本"，脚本在你的本机执行，你可以在里面写任何逻辑。作为AI开发工作流的"黏合剂"，Hooks可以帮你实现安全管控、自动化操作、状态同步等高度定制化的需求，配合DeepSeek的工具调用能力，可打造完全适配团队习惯的智能开发流程。 典型的使用场景：

• 安全拦截：Agent 要执行 Shell 命令前，检查是否包含危险操作（如 rm -rf），包含则阻断执行
• 桌面通知：后台任务完成时，弹出系统通知提醒你回来查看结果
• 自动检查：每次用户提交消息时，自动在上下文里附加一些背景信息（如当前 Git 分支、环境版本）
• 流程自动化：代码修改后自动执行ESLint检查、Git提交后自动触发CI流水线
• 多渠道同步：子Agent完成任务后自动将结果同步到企业微信、邮件等平台

通过阅读本文，你将全面掌握Hooks的工作原理、配置方法、事件体系与常见场景的实现方案，能够根据需求开发自定义Hook扩展CLI能力。

Hooks 是怎么工作的

配置一条 hook 规则，需要指定三件事：在什么事件上触发、匹配哪些目标、运行哪个脚本，三者共同构成Hook的核心三要素：

• 触发事件（Event）：Agent生命周期中的特定节点，如工具调用前、用户提交消息后、子Agent完成等
• 匹配规则（Matcher）：用于过滤事件的正则表达式，可精准匹配你需要处理的特定场景
• 执行脚本（Command）：触发时运行的自定义逻辑，支持Shell命令、Python/Node.js脚本等任意可执行程序

触发时，CLI 会把事件的详细信息（触发原因、工具名称、命令内容等）打包成 JSON（一种结构化文本格式），通过标准输入（stdin，程序运行时用来接收外部数据的通道）传给你的脚本，无需额外SDK或网络请求，脚本只需读取stdin即可获取完整上下文信息。脚本读取这些信息后，决定怎么响应。

脚本的响应结果由两样东西决定：

• 退出码（exit code，程序结束时向操作系统报告的状态数字）：0 表示放行，2 表示阻断，其他数字默认放行
• 标准输出（stdout，就是你用 console.log 或 print 打印出来的内容）：可以附带说明文字，内容会被自动附加到会话上下文，模型可直接读取

即使脚本报错、超时，CLI 也不会因此中断你的工作——这种"出错就放行"的设计叫 fail-open（失败开放），避免 hook 异常变成绊脚石，确保核心功能的可用性。

快速上手：一个最简单的 hook

下面这条 hook 会在每次后台任务完成时，在终端标题栏闪一下通知（macOS 需要安装 terminal-notifier），避免你长时间等待任务完成，提升多任务处理效率。

前置环境检查：

1. 运行brew install terminal-notifier安装通知工具（macOS），Windows用户可使用burnttoast、Linux用户可使用notify-send替代
2. 执行terminal-notifier -title "测试" -message "通知测试"，若弹出系统通知说明环境正常

配置步骤：

# 写在 ~/.kimi-code/config.toml 里
[[hooks]]
event = "Notification"           # 触发时机：后台任务状态变化时
matcher = "task\\.completed"     # 只关心"已完成"的通知（注意正则转义）
command = "terminal-notifier -title Kimi -message 'Task done'"
timeout = 5                      # 超时时间5秒，避免阻塞主流程

生效验证： 保存配置、运行/reload重载配置，无报错则说明配置生效。下次后台任务完成时就会弹出通知，你也可以执行/run sleep 10触发测试，10秒后将收到通知。

配置

所有 hook 规则写在 ~/.kimi-code/config.toml 的 [[hooks]] 数组里，每一项是一条规则：

[[hooks]] 只允许这四个字段，多写会导致配置文件加载失败，可运行/config validate命令检查配置语法是否正确。

同一事件匹配多条规则时，所有命中的 hook 并行运行，不会互相等待，若有依赖关系建议合并为一个脚本执行；command 完全相同的多条规则只运行一次，避免重复执行。 Hook 命令的工作目录是当前会话的项目目录，可直接使用相对路径访问项目内的文件。非 Windows 平台上，hook 进程放在独立进程组里，超时时先发SIGTERM信号让它有机会善后，之后才强制终止。

事件数据格式

每次触发时，CLI 都会把以下基础信息通过 stdin 传给脚本，所有字段名使用下划线命名（snake_case）：

{
  "hook_event_name": "PreToolUse",
  "session_id": "session_abc123",
  "cwd": "/path/to/project"
}

具体事件还会附带额外字段（如工具名称、命令内容），例如PreToolUse事件的完整payload：

{
  "hook_event_name": "PreToolUse",
  "session_id": "session_abc123",
  "cwd": "/Users/xxx/project/my-app",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "args": []
  }
}

你可在脚本中直接读取这些字段获取完整上下文信息。

返回值

脚本结束后，CLI 根据退出码判断 hook 的意图：

也可以通过标准输出返回一段 JSON 来实现更灵活的阻断逻辑：

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "请用 rg 代替 grep 提升搜索效率"
  }
}

事件一览

示例：阻断危险 Shell 命令

下面的 hook 在 Agent 调用 Bash 工具前检查命令内容，发现 rm -rf 就阻断，避免误删文件造成数据损失。

前置环境检查： 运行node -v确认已安装Node.js v16及以上版本，若未安装可通过官网或包管理器安装。

配置步骤：

1. 在~/.kimi-code/下新建hooks目录，创建block-dangerous-bash.mjs文件：

[[hooks]]
event = "PreToolUse"
matcher = "Bash"
command = "node ~/.kimi-code/hooks/block-dangerous-bash.mjs"
timeout = 5

// block-dangerous-bash.mjs
// 从 stdin 读取 CLI 传来的事件数据
let input = '';
process.stdin.on('data', (chunk) => { input += chunk; });
process.stdin.on('end', () => {
  const payload = JSON.parse(input);         // 解析事件数据
  const command = payload.tool_input?.command ?? '';

  // 可扩展白名单逻辑，例如允许删除当前项目下的node_modules目录
  if (command.includes('rm -rf') && !command.includes('node_modules')) {
    // 通过 stderr 说明阻断原因，退出码 2 表示阻断
    console.error('检测到危险命令，已阻断。如需删除文件请指定具体路径，避免使用rm -rf');
    process.exit(2);
  }
  // 正常退出（退出码 0）表示放行
});

生效验证： 保存文件后运行/reload重载配置，当Agent要执行包含rm -rf且不在白名单内的命令时，会弹出阻断提示，模型会收到该提示并调整为更安全的操作方式。

常见问题（FAQ）

1. Hook脚本没有生效怎么办？ 首先运行/config validate检查config.toml语法是否正确，然后检查脚本是否有可执行权限（可运行chmod +x <脚本路径>添加权限），最后可在脚本中添加日志输出将payload写入本地文件，或运行/logs hooks查看Hook执行日志排查问题。
2. Hook可以修改Agent的工具调用参数吗？ 目前不支持直接修改工具调用参数，只能选择放行或阻断。如果需要修改参数，可在阻断原因中说明需要调整的内容，模型会自动调整参数重新发起调用。
3. Hook的执行日志在哪里查看？ 运行/logs hooks命令可查看所有Hook的执行日志，包括stdout、stderr、退出码、执行时间等信息，方便排查问题。