---
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="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
  <Card title="Policy engine" description="許可權邊界優先寫 policy，hooks 用於補充校驗和審計。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/61-policy-engine" />
  <Card title="Automation" description="準備把 hooks 放入流水線時，繼續看自動化指令碼設計。" href="/zh-Hant/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)
