---
title: "Hooks"
description: "Gemini CLI hooks 的事件、配置、JSON I/O、退出码、安全边界和管理命令。"
verifiedAt: "2026-05-09"
---

Hooks 是 Gemini CLI agent loop 里的同步拦截点。它允许你在不改 CLI 源码的情况下，注入上下文、校验工具调用、记录审计日志或阻断危险动作。

> [!WARNING]
> Hooks 会以当前用户权限执行命令。陌生项目的项目级 hooks 必须先审查，不要直接信任。

## 典型用途

- 会话开始时加载项目状态。
- 模型请求前补充或过滤上下文。
- 工具执行前检查参数。
- 工具执行后解析结果。
- 对输出做脱敏或审计。
- 按策略禁用部分工具。

## 常见事件

常见事件包括 `SessionStart`、`SessionEnd`、`BeforeAgent`、`AfterAgent`、`BeforeModel`、`AfterModel`、`BeforeToolSelection`、`BeforeTool`、`AfterTool`、`PreCompress`、`Notification`。其中 `BeforeTool` 和 `AfterTool` 最常用于工具参数校验、结果过滤和审计记录。

## 配置位置

优先级从高到低：

1. 项目配置：`.gemini/settings.json`
2. 用户配置：`~/.gemini/settings.json`
3. 系统配置：`/etc/gemini-cli/settings.json`
4. extensions 内置 hooks

配置通常写在 `hooks.BeforeTool`、`hooks.AfterTool` 等事件下，用 `matcher` 匹配工具，再指定 hook 的 `name`、`type`、`command`、`timeout`。安全检查脚本可以放在 `$GEMINI_PROJECT_DIR/.gemini/hooks/`。

## JSON 规则

Hook 通过 `stdin` 接收 JSON，通过 `stdout` 返回 JSON。

> [!IMPORTANT]
> `stdout` 只能输出最终 JSON，不能夹杂 `echo`、日志或调试文本。调试信息写到 `stderr`。

## 退出码

`0` 表示成功且 `stdout` JSON 会被解析；`2` 表示系统级阻断，目标动作中止；其他退出码会作为非致命警告处理，原流程通常继续。

## 管理命令

常用命令包括 `/hooks panel`、`/hooks enable-all`、`/hooks disable-all`、`/hooks enable <name>`、`/hooks disable <name>`。

## 安全边界

Hooks 会以当前用户权限执行任意命令。陌生项目里的项目级 hooks 不能直接信任，尤其不要让 hooks 读取密钥、上传文件或静默执行部署。

| Hook 类型 | 适合做什么 | 不适合做什么 |
| --- | --- | --- |
| `BeforeTool` | 校验命令、路径、MCP 参数 | 大型网络请求 |
| `AfterTool` | 记录审计、解析失败原因 | 修改真实产物 |
| `BeforeModel` | 注入少量上下文 | 拼接大文件 |
| `AfterAgent` | 最终 QA、总结检查 | 高频重活 |

## 性能和调试

Hooks 是同步执行的，慢 hook 会拖慢 agent loop。高频事件不要做网络请求或大文件扫描；确实需要时，缓存结果并用 matcher 缩小触发范围。只想做最终质量检查时，用 `AfterAgent`，不要在 `AfterModel` 的每个输出片段上做重活。

调试 hook 时，先用样例 JSON 手动运行脚本，确认 stdout 是合法 JSON、退出码符合预期。复杂 hook 单独写日志文件，不要把调试文本写到 stdout。

## 验收方式

至少测试三条路径：允许、阻断、脚本异常。允许路径返回 `{"decision":"allow"}` 或空 JSON；阻断路径要给出可读原因；脚本异常不能静默放过高风险工具。项目级 hook 被 git pull 改动后，也要确认 CLI 会重新提示信任。

## 接下来去哪

<Cards>
  <Card title="Headless mode" description="hooks 稳定后，继续看脚本和 CI 的非交互式运行。" href="/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
  <Card title="Policy engine" description="权限边界优先写 policy，hooks 用于补充校验和审计。" href="/docs/gemini-cli/official/06-security-enterprise/61-policy-engine" />
  <Card title="Automation" description="准备把 hooks 放入流水线时，继续看自动化脚本设计。" href="/docs/gemini-cli/official/07-integrations-automation/73-automation" />
</Cards>

## 官方来源

- [Gemini CLI hooks](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/index.md)
- [Gemini CLI hooks best practices](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/best-practices.md)
- [Gemini CLI hooks reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/reference.md)
