Gemini CLI Hooks 最佳实践性能、调试、安全与隐私的源码级实战指南【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文基于 gemini-cli 仓库的 Hooks Best Practices 文档展开系统讲解在 Gemini CLI 中编写、调试、部署 hooks钩子的工程化实践如何保持 hook 快速响应、如何排查“Strict JSON”污染与退出码问题、如何理解项目级 hook 的信任指纹与信任模型以及如何通过环境变量脱敏与隐私设置防止敏感数据泄露。读完后你将能够编写一个性能可控、可调试、安全合规的 hook 体系并对照 源码实现 验证其底层行为。1. 背景Hooks 在 Gemini CLI 中的执行模型Hooks 是 Gemini CLI 在 agent 循环特定节点执行的脚本或程序允许在不修改 CLI 源码的前提下拦截并定制其行为注入上下文、校验工具参数、实施安全策略、记录审计日志。完整的事件表与配置 schema 见 hooks 总览文档 与 I/O 规范参考。理解最佳实践之前必须先理解执行模型这决定了后文所有优化与调试手段同步执行hook 事件触发时CLI 等待所有匹配的 hook 完成才继续。慢 hook 直接拖慢 agent 循环——这是性能章节的第一驱动力。stdin 进、stdout 出CLI 将事件输入序列化为 JSON 写入子进程 stdin脚本将决策 JSON 写到 stdout。源码证据见 hookRunner.tschild.stdin.write(JSON.stringify(input))。超时强制终止默认超时 60000mshookRunner.ts 中DEFAULT_HOOK_TIMEOUT 60000。超时后先发送SIGTERM5 秒后仍存活则升级为SIGKILLWindows 平台改用taskkill /f /thookRunner.ts。另外值得注意的是同一事件下的多个 hook 由 CLI 并行执行executeHooksParallel 使用Promise.all而顺序执行模式下前一个 hook 的hookSpecificOutput会合并进下一个 hook 的输入如BeforeAgent追加上下文、BeforeTool合并tool_input这对应 applyHookOutputToInput。2. 性能优化2.1 保持 hook 快速Hooks 同步运行慢 hook 会延迟 agent 循环。优化手段是并行化 I/O 操作// Sequential operations are slower const data1 await fetch(url1).then((r) r.json()); const data2 await fetch(url2).then((r) r.json()); // Prefer parallel operations for better performance // Start requests concurrently const p1 fetch(url1).then((r) r.json()); const p2 fetch(url2).then((r) r.json()); // Wait for all results const [data1, data2] await Promise.all([p1, p2]);2.2 缓存昂贵操作对于高频触发的事件如BeforeTool、AfterModel在多次调用之间持久化结果可以避免重复计算。示例为按小时过期的文件缓存const fs require(fs); const path require(path); const CACHE_FILE .gemini/hook-cache.json; function readCache() { try { return JSON.parse(fs.readFileSync(CACHE_FILE, utf8)); } catch { return {}; } } function writeCache(data) { fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2)); } async function main() { const cache readCache(); const cacheKey tool-list-${(Date.now() / 3600000) | 0}; // Hourly cache if (cache[cacheKey]) { // Write JSON to stdout console.log(JSON.stringify(cache[cacheKey])); return; } // Expensive operation const result await computeExpensiveResult(); cache[cacheKey] result; writeCache(cache); console.log(JSON.stringify(result)); }配合后文的.gitignore建议缓存文件应纳入忽略清单.gemini/hook-cache.json避免污染版本库。2.3 选用合适的事件事件选择直接决定执行频次错用事件是最常见的性能浪费AfterAgent每轮仅一次在模型给出最终响应后触发。适合质量校验触发重试或最终日志。AfterModelLLM 输出的每个 chunk后都会触发。适合实时脱敏、PII 过滤、流式输出监控。若只需要校验最终结果用AfterAgent即可显著节省开销。事件触发时机与影响的权威对照表见 hooks 总览文档。2.4 用 matcher 过滤不要对所有工具匹配*只指定真正关心的工具可省去无关事件下 spawn 子进程的开销{ matcher: write_file|replace, hooks: [ { name: validate-writes, type: command, command: ./validate.sh } ] }从源码结构看matcher 在 hook 规划阶段完成正则匹配见 hookPlanner.ts不匹配的事件根本不会走到 hookRunner.ts 的spawn路径——这就是“具体 matcher 更省”的底层原因。2.5 优化 JSON 解析对于大输入例如AfterModel收到大上下文标准 JSON 解析可能成为瓶颈。若只需提取一个字段可考虑流式解析器或轻量抽取逻辑不过对大多数 shell 脚本来说jq已足够见 5.3 节。3. 调试技巧3.1 “Strict JSON”规则hook 失败的头号原因是污染了 stdoutstdout只能输出JSONstderr用于日志和文本。正确示范#!/bin/bash echo Starting check... 2 # --- Redirect to stderr echo {decision: allow}为什么污染会“失败”而非“报错”源码给出了明确答案hookRunner.ts 中CLI 优先尝试JSON.parse(stdout)解析失败时走convertPlainTextToHookOutput按退出码降级处理见 3.5 节。因此一行提前echo的调试文本会让整段输出变成纯文本decision语义被丢弃只剩systemMessage——这正是 hooks 总览文档 称之为 “Pollution Failure” 的机制。3.2 写日志文件hook 在后台运行写专用日志文件是排查复杂逻辑的最直接方式#!/usr/bin/env bash LOG_FILE.gemini/hooks/debug.log # Log with timestamp log() { echo [$(date %Y-%m-%d %H:%M:%S)] $* $LOG_FILE } input$(cat) log Received input: ${input:0:100}... # Hook logic here log Hook completed successfully # Always output valid JSON to stdout at the end, even if just empty echo {}3.3 用 stderr 报告错误stderr 中的错误信息会按退出码被恰当呈现给用户/agenttry { const result dangerousOperation(); console.log(JSON.stringify({ result })); } catch (error) { // Write the error description to stderr so the user/agent sees it console.error(Hook error: ${error.message}); process.exit(2); // Blocking error }3.4 独立测试 hook接入 CLI 之前先用样例 JSON 手动喂给脚本验证行为。macOS/Linux# Create test input cat test-input.json EOF { session_id: test-123, cwd: /tmp/test, hook_event_name: BeforeTool, tool_name: write_file, tool_input: { file_path: test.txt, content: Test content } } EOF # Test the hook cat test-input.json | .gemini/hooks/my-hook.sh # Check exit code echo Exit code: $?Windows (PowerShell)# Create test input { session_id: test-123, cwd: C:\\temp\\test, hook_event_name: BeforeTool, tool_name: write_file, tool_input: { file_path: test.txt, content: Test content } } | Out-File -FilePath test-input.json -Encoding utf8 # Test the hook Get-Content test-input.json | .\.gemini\hooks\my-hook.ps1 # Check exit code Write-Host Exit code: $LASTEXITCODEWindows 细节补充hookRunner.ts 在执行 PowerShell 命令时会追加if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }确保脚本的退出码正确传播为进程退出码——所以.ps1内部正确设置$LASTEXITCODE或exit很重要。3.5 退出码决定控制流Gemini CLI 用退出码做高层流程控制Exit 0Successhook 成功运行CLI 解析 stdout 中的 JSON 决策。Exit 2System Block关键阻断。stderr内容作为拒绝理由。对Agent/Model事件中止当前 turn对Tool事件阻断该次工具调用但 agent 可继续对AfterAgent触发自动重试 turn。其他非 0 退出码Warning非致命失败显示警告后按原参数继续。退出码与行为的测试级证据见 hookRunner.test.ts退出码 2 且 stdout 为非法 JSON 时CLI 将其转换为{ decision: deny, reason: stderr文本 }退出码 1 则转换为{ decision: allow, systemMessage: Warning: ... }。完整的纯文本降级逻辑在 convertPlainTextToHookOutput。TIP — 阻断与终止的区别用decision: deny或 Exit Code 2阻断某个具体动作若要在 JSON 输出中返回{continue: false}则立即终止整个 agent 循环。#!/usr/bin/env bash set -e # Hook logic if process_input; then echo {decision: allow} exit 0 else echo Critical validation failure 2 exit 2 fi3.6 开启遥测日志当telemetry.logPrompts启用时hook 执行会被记录可用于调试执行流{ telemetry: { logPrompts: true } }注意这是调试开关生产/敏感环境下应按第 7 节建议关闭。3.7 使用 /hooks panelCLI 内置命令/hooks panel可查看执行状态与近期输出重点检查hook 执行计数、近期成功/失败、错误消息、执行耗时。完整的 hook 管理命令enable/disable/enable-all/disable-all见 hooks 总览文档。4. 开发规范4.1 从简单开始先写一个“记录输入结构”的极简 hook摸清输入形态再实现复杂逻辑#!/usr/bin/env bash # Simple logging hook to understand input structure input$(cat) echo $input .gemini/hook-inputs.log # Always return valid JSON echo {}4.2 为 hook 写好文档description字段会显示在/hooks panelUI 中是排障时的重要线索{ hooks: { BeforeTool: [ { matcher: write_file|replace, hooks: [ { name: secret-scanner, type: command, command: $GEMINI_PROJECT_DIR/.gemini/hooks/block-secrets.sh, description: Scans code changes for API keys and secrets before writing } ] } ] } }脚本内部也应注明性能预期与依赖#!/usr/bin/env node /** * RAG Tool Filter Hook * * Reduces the tool space by extracting keywords from the users request. * * Performance: ~500ms average * Dependencies: google/generative-ai */4.3 使用 JSON 库解析不要用脆弱的文本处理代替 JSON 解析Bad# Fragile text parsing tool_name$(echo $input | grep -oP tool_name:\s*\K[^])Good# Robust JSON parsing tool_name$(echo $input | jq -r .tool_name)4.4 确保脚本可执行macOS/Linux 下始终赋予执行权限chmod x .gemini/hooks/*.sh chmod x .gemini/hooks/*.jsWindows 注意PowerShell 脚本.ps1不涉及chmod但可能需要执行策略允许其运行例如Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。4.5 纳入版本控制将 hooks 提交以便团队共享git add .gemini/hooks/ git add .gemini/settings.json.gitignore建议# Ignore hook cache and logs .gemini/hook-cache.json .gemini/hook-debug.log .gemini/memory/session-*.jsonl # Keep hook scripts !.gemini/hooks/*.sh !.gemini/hooks/*.js5. Hook 安全5.1 威胁模型hook 从哪里来理解 hook 的来源及其能力边界是安全使用的前提Hook 来源说明System由系统管理员配置例如/etc/gemini-cli/settings.json、/Library/...。默认视为最安全。User~/.gemini/...由你自己配置安全性由你负责。Extensions由你显式批准并安装。安全性取决于扩展来源的完整性。Project./.gemini/...默认不可信。在受信任的内部仓库中风险最低在第三方/公开仓库中风险最高。5.2 项目级 hook 的信任机制源码印证当你打开一个在.gemini/settings.json中定义了 hooks 的项目时流程如下DetectionCLI 检测到这些 hooksIdentification为每个 hook 基于其name与command生成唯一身份指纹Warning若该 hook 身份此前未见显示警告Execution执行 hook除非特定安全设置将其阻断Trust该 hook 被标记为“已信任”。这套机制的源码实现在 trustedHooks.tsgetHookKey生成指纹信任记录持久化到全局目录下的trusted_hooks.jsongetUntrustedHooks返回本项目下未信任的 hook 列表用户确认后trustHooks落盘。另外hookRunner.ts 中还有第二道保险ConfigSource.Project来源的 hook 在非信任文件夹中会被直接拒绝执行Security: Blocked execution of project hook in untrusted folder。修改检测如果项目 hook 的command字符串发生变化例如一次git pull其指纹随之改变CLI 会将其视为新的不可信 hook并再次警告。这防止了恶意者将已验证的命令悄悄替换为恶意命令。5.3 主要风险风险说明任意代码执行Hook 以你的用户身份运行能做任何你能做的事删文件、装软件。数据外泄Hook 可以读取你的输入prompts、输出代码或环境变量如GEMINI_API_KEY并发送到远程服务器。提示注入文件或网页中的恶意内容可能诱导 LLM 以非预期方式触发工具进而触发 hook。5.4 缓解策略验证来源启用任何项目 hook 或扩展前先验证来源。开源项目建议快速审查 hook 脚本扩展应确认作者/发布者可信对来源不明的混淆脚本或编译二进制保持警惕。清理环境Sanitize environmentHook 继承 Gemini CLI 进程的环境变量其中可能包含敏感 API 密钥。CLI 提供了环境变量脱敏系统自动过滤匹配敏感模式如KEY、TOKEN的变量。默认关闭环境脱敏当前默认 OFF。如果你运行第三方 hook 或在敏感环境中工作强烈建议启用。对 hooks 的影响安全防止 hook 脚本意外泄露密钥排障如果你的 hook 依赖某个被拦截的环境变量必须在settings.json中显式放行。{ security: { environmentVariableRedaction: { enabled: true, allowed: [MY_REQUIRED_TOOL_KEY] } } }系统管理员可在系统级配置中为所有用户强制开启脱敏。源码级印证脱敏逻辑位于 environmentSanitization.ts由 hookRunner.ts 在spawn前对 hook 进程环境调用sanitizeEnvironment。关键行为变量名匹配NEVER_ALLOWED_NAME_PATTERNS/TOKEN/i、/SECRET/i、/PASSWORD/i、/KEY/i、/AUTH/i、/CREDENTIAL/i、/PRIVATE/i、/CERT/i等L111-L122即被过滤变量值匹配NEVER_ALLOWED_VALUE_PATTERNSPEM 私钥头、URL 内嵌凭据、ghp_系列 GitHub token、AIzaSyGoogle API key、AKIAAWS 访问密钥、JWT、Stripesk_/rk_、Slackxox*L124-L141即被过滤GEMINI_CLI_*前缀与ALWAYS_ALLOWED_ENVIRONMENT_VARIABLESPATH、HOME、TERM等L52-L92始终放行注意 getSecureSanitizationConfig 中enableEnvironmentVariableRedaction的默认值为false与文档“默认关闭”一致另外源码中存在严格模式检测到GITHUB_SHA或SURFACEGithubCI 环境时强制启用脱敏L17-L22从源码结构看这是针对 CI 场景的额外保护建议在 CI 中运行 hook 时以实际行为为准进行验证。hook 自身可用的环境变量的注入点也在 hookRunner.tsGEMINI_PROJECT_DIR、GEMINI_PLANS_DIR、GEMINI_CWD、GEMINI_SESSION_ID以及兼容别名CLAUDE_PROJECT_DIR命令字符串中的同名占位符由 expandCommand 在执行前展开因此脚本内可直接使用$GEMINI_PROJECT_DIR等路径。6. 故障排查6.1 Hook 没有执行在/hooks panel中检查 hook 名称确认 hook 出现在列表中且已启用。验证 matcher 模式# Test regex pattern echo write_file|replace | grep -E write_.*|replace检查禁用列表确认 hook 未被列入settings.json的 disabled 数组{ hooks: { disabled: [my-hook-name] } }确保脚本可执行macOS/Linuxls -la .gemini/hooks/my-hook.sh chmod x .gemini/hooks/my-hook.shWindows 注意确认执行策略允许运行脚本例如Get-ExecutionPolicy。验证脚本路径确认settings.json中的路径能正确解析# Check path expansion echo $GEMINI_PROJECT_DIR/.gemini/hooks/my-hook.sh # Verify file exists test -f $GEMINI_PROJECT_DIR/.gemini/hooks/my-hook.sh echo File exists6.2 Hook 超时检查配置的超时默认 60000ms1 分钟可在settings.json中调大{ name: slow-hook, timeout: 120000 }源码印证超时值取自hookConfig.timeout ?? DEFAULT_HOOK_TIMEOUThookRunner.ts触发后先SIGTERM、5 秒后SIGKILL最终结果为Hook timed out after ${timeout}mshookRunner.ts。优化慢操作把重处理移到后台任务或使用第 2.2 节的缓存。6.3 输出非法 JSON输出前先校验 JSON 合法性#!/usr/bin/env bash output{decision: allow} # Validate JSON if echo $output | jq empty 2/dev/null; then echo $output else echo Invalid JSON generated 2 exit 1 fi6.4 环境变量不可用检查变量是否被设置#!/usr/bin/env bash if [ -z $GEMINI_PROJECT_DIR ]; then echo GEMINI_PROJECT_DIR not set 2 exit 1 fi调试可用变量env .gemini/hook-env.log若怀疑是脱敏导致变量“消失”可对照第 5.4 节的过滤规则必要时在allowed列表中显式放行。7. 编写安全 Hook 的实践编写自己的 hook 时遵循以下实践保证其健壮与安全。7.1 校验所有输入永远不要无条件信任 hook 输入——它们常来自 LLM 或用户 prompt可能被操纵#!/usr/bin/env bash input$(cat) # Validate JSON structure if ! echo $input | jq empty 2/dev/null; then echo Invalid JSON input 2 exit 1 fi # Validate tool_name explicitly tool_name$(echo $input | jq -r .tool_name // empty) if [[ $tool_name ! write_file $tool_name ! read_file ]]; then echo Unexpected tool: $tool_name 2 exit 1 fi7.2 使用超时通过强制超时防止“拒绝服务”agent 挂起。Gemini CLI 默认 60 秒但对快 hook 应设置更严格的限制{ hooks: { BeforeTool: [ { matcher: *, hooks: [ { name: fast-validator, type: command, command: ./hooks/validate.sh, timeout: 5000 // 5 seconds } ] } ] } }7.3 限制权限以最小必要权限运行 hook#!/usr/bin/env bash # Dont run as root if [ $EUID -eq 0 ]; then echo Hook should not run as root 2 exit 1 fi # Check file permissions before writing if [ -w $file_path ]; then # Safe to write else echo Insufficient permissions 2 exit 1 fi7.4 示例密钥扫描器Secret Scanner用BeforeToolhook 阻止敏感数据被写入/提交这是增强工作流安全的强力模式const SECRET_PATTERNS [ /api[_-]?key\s*[:]\s*[]?[a-zA-Z0-9_-]{20,}[]?/i, /password\s*[:]\s*[]?[^\s]{8,}[]?/i, /secret\s*[:]\s*[]?[a-zA-Z0-9_-]{20,}[]?/i, /AKIA[0-9A-Z]{16}/, // AWS access key /ghp_[a-zA-Z0-9]{36}/, // GitHub personal access token /sk-[a-zA-Z0-9]{48}/, // OpenAI API key ]; function containsSecret(content) { return SECRET_PATTERNS.some((pattern) pattern.test(content)); }配合 4.2 节的description字段如Scans code changes for API keys and secrets before writing与matcher: write_file|replace可组成完整的“写前拦截”链路。8. 隐私考量Hook 的输入与输出可能包含敏感信息需要专门管理。8.1 收集了哪些数据Hook 遥测可能包含输入prompts、代码与输出decisions、reasons除非被禁用。8.2 隐私设置禁用 PII 日志处理敏感数据时在设置中关闭 prompt 日志{ telemetry: { logPrompts: false } }Suppress Output单个 hook 可在 JSON 响应中返回suppressOutput: true请求将其元数据从日志和遥测中隐藏。NotesuppressOutput只影响后台日志JSON 中的systemMessage或reason仍会在终端显示给用户。8.3 Hook 中的敏感数据处理如果你的 hook 处理敏感数据最小化日志不要把敏感数据写入日志文件净化输出输出 JSON 或写 stderr 之前先移除敏感数据。9. 要点速查主题关键做法源码/文档依据性能并行 I/O、文件缓存、AfterAgent替代AfterModel、具体 matcher、jqhookRunner.ts 并行/顺序执行调试stdout 只出 JSON、stderr 打日志、/hooks panel、手动喂样例 JSONhooks 总览 全局机制退出码0成功解析 JSON2系统阻断stderr 为理由其他警告继续convertPlainTextToHookOutput信任项目 hook 按 namecommand 指纹变更后重新警告trustedHooks.ts环境脱敏默认关闭建议启用allowed显式放行environmentSanitization.ts隐私logPrompts: false、suppressOutput: true、最小化日志Best Practices掌握以上实践后建议按 Writing hooks 教程 动手建立第一个 hook再对照 I/O 规范参考 核对输入输出 schema最后用本文第 6 节排查清单与/hooks panel完成上线验证。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gemini CLI Hooks 最佳实践：性能、调试、安全与隐私的源码级实战指南
Gemini CLI Hooks 最佳实践性能、调试、安全与隐私的源码级实战指南【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文基于 gemini-cli 仓库的 Hooks Best Practices 文档展开系统讲解在 Gemini CLI 中编写、调试、部署 hooks钩子的工程化实践如何保持 hook 快速响应、如何排查“Strict JSON”污染与退出码问题、如何理解项目级 hook 的信任指纹与信任模型以及如何通过环境变量脱敏与隐私设置防止敏感数据泄露。读完后你将能够编写一个性能可控、可调试、安全合规的 hook 体系并对照 源码实现 验证其底层行为。1. 背景Hooks 在 Gemini CLI 中的执行模型Hooks 是 Gemini CLI 在 agent 循环特定节点执行的脚本或程序允许在不修改 CLI 源码的前提下拦截并定制其行为注入上下文、校验工具参数、实施安全策略、记录审计日志。完整的事件表与配置 schema 见 hooks 总览文档 与 I/O 规范参考。理解最佳实践之前必须先理解执行模型这决定了后文所有优化与调试手段同步执行hook 事件触发时CLI 等待所有匹配的 hook 完成才继续。慢 hook 直接拖慢 agent 循环——这是性能章节的第一驱动力。stdin 进、stdout 出CLI 将事件输入序列化为 JSON 写入子进程 stdin脚本将决策 JSON 写到 stdout。源码证据见 hookRunner.tschild.stdin.write(JSON.stringify(input))。超时强制终止默认超时 60000mshookRunner.ts 中DEFAULT_HOOK_TIMEOUT 60000。超时后先发送SIGTERM5 秒后仍存活则升级为SIGKILLWindows 平台改用taskkill /f /thookRunner.ts。另外值得注意的是同一事件下的多个 hook 由 CLI 并行执行executeHooksParallel 使用Promise.all而顺序执行模式下前一个 hook 的hookSpecificOutput会合并进下一个 hook 的输入如BeforeAgent追加上下文、BeforeTool合并tool_input这对应 applyHookOutputToInput。2. 性能优化2.1 保持 hook 快速Hooks 同步运行慢 hook 会延迟 agent 循环。优化手段是并行化 I/O 操作// Sequential operations are slower const data1 await fetch(url1).then((r) r.json()); const data2 await fetch(url2).then((r) r.json()); // Prefer parallel operations for better performance // Start requests concurrently const p1 fetch(url1).then((r) r.json()); const p2 fetch(url2).then((r) r.json()); // Wait for all results const [data1, data2] await Promise.all([p1, p2]);2.2 缓存昂贵操作对于高频触发的事件如BeforeTool、AfterModel在多次调用之间持久化结果可以避免重复计算。示例为按小时过期的文件缓存const fs require(fs); const path require(path); const CACHE_FILE .gemini/hook-cache.json; function readCache() { try { return JSON.parse(fs.readFileSync(CACHE_FILE, utf8)); } catch { return {}; } } function writeCache(data) { fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2)); } async function main() { const cache readCache(); const cacheKey tool-list-${(Date.now() / 3600000) | 0}; // Hourly cache if (cache[cacheKey]) { // Write JSON to stdout console.log(JSON.stringify(cache[cacheKey])); return; } // Expensive operation const result await computeExpensiveResult(); cache[cacheKey] result; writeCache(cache); console.log(JSON.stringify(result)); }配合后文的.gitignore建议缓存文件应纳入忽略清单.gemini/hook-cache.json避免污染版本库。2.3 选用合适的事件事件选择直接决定执行频次错用事件是最常见的性能浪费AfterAgent每轮仅一次在模型给出最终响应后触发。适合质量校验触发重试或最终日志。AfterModelLLM 输出的每个 chunk后都会触发。适合实时脱敏、PII 过滤、流式输出监控。若只需要校验最终结果用AfterAgent即可显著节省开销。事件触发时机与影响的权威对照表见 hooks 总览文档。2.4 用 matcher 过滤不要对所有工具匹配*只指定真正关心的工具可省去无关事件下 spawn 子进程的开销{ matcher: write_file|replace, hooks: [ { name: validate-writes, type: command, command: ./validate.sh } ] }从源码结构看matcher 在 hook 规划阶段完成正则匹配见 hookPlanner.ts不匹配的事件根本不会走到 hookRunner.ts 的spawn路径——这就是“具体 matcher 更省”的底层原因。2.5 优化 JSON 解析对于大输入例如AfterModel收到大上下文标准 JSON 解析可能成为瓶颈。若只需提取一个字段可考虑流式解析器或轻量抽取逻辑不过对大多数 shell 脚本来说jq已足够见 5.3 节。3. 调试技巧3.1 “Strict JSON”规则hook 失败的头号原因是污染了 stdoutstdout只能输出JSONstderr用于日志和文本。正确示范#!/bin/bash echo Starting check... 2 # --- Redirect to stderr echo {decision: allow}为什么污染会“失败”而非“报错”源码给出了明确答案hookRunner.ts 中CLI 优先尝试JSON.parse(stdout)解析失败时走convertPlainTextToHookOutput按退出码降级处理见 3.5 节。因此一行提前echo的调试文本会让整段输出变成纯文本decision语义被丢弃只剩systemMessage——这正是 hooks 总览文档 称之为 “Pollution Failure” 的机制。3.2 写日志文件hook 在后台运行写专用日志文件是排查复杂逻辑的最直接方式#!/usr/bin/env bash LOG_FILE.gemini/hooks/debug.log # Log with timestamp log() { echo [$(date %Y-%m-%d %H:%M:%S)] $* $LOG_FILE } input$(cat) log Received input: ${input:0:100}... # Hook logic here log Hook completed successfully # Always output valid JSON to stdout at the end, even if just empty echo {}3.3 用 stderr 报告错误stderr 中的错误信息会按退出码被恰当呈现给用户/agenttry { const result dangerousOperation(); console.log(JSON.stringify({ result })); } catch (error) { // Write the error description to stderr so the user/agent sees it console.error(Hook error: ${error.message}); process.exit(2); // Blocking error }3.4 独立测试 hook接入 CLI 之前先用样例 JSON 手动喂给脚本验证行为。macOS/Linux# Create test input cat test-input.json EOF { session_id: test-123, cwd: /tmp/test, hook_event_name: BeforeTool, tool_name: write_file, tool_input: { file_path: test.txt, content: Test content } } EOF # Test the hook cat test-input.json | .gemini/hooks/my-hook.sh # Check exit code echo Exit code: $?Windows (PowerShell)# Create test input { session_id: test-123, cwd: C:\\temp\\test, hook_event_name: BeforeTool, tool_name: write_file, tool_input: { file_path: test.txt, content: Test content } } | Out-File -FilePath test-input.json -Encoding utf8 # Test the hook Get-Content test-input.json | .\.gemini\hooks\my-hook.ps1 # Check exit code Write-Host Exit code: $LASTEXITCODEWindows 细节补充hookRunner.ts 在执行 PowerShell 命令时会追加if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }确保脚本的退出码正确传播为进程退出码——所以.ps1内部正确设置$LASTEXITCODE或exit很重要。3.5 退出码决定控制流Gemini CLI 用退出码做高层流程控制Exit 0Successhook 成功运行CLI 解析 stdout 中的 JSON 决策。Exit 2System Block关键阻断。stderr内容作为拒绝理由。对Agent/Model事件中止当前 turn对Tool事件阻断该次工具调用但 agent 可继续对AfterAgent触发自动重试 turn。其他非 0 退出码Warning非致命失败显示警告后按原参数继续。退出码与行为的测试级证据见 hookRunner.test.ts退出码 2 且 stdout 为非法 JSON 时CLI 将其转换为{ decision: deny, reason: stderr文本 }退出码 1 则转换为{ decision: allow, systemMessage: Warning: ... }。完整的纯文本降级逻辑在 convertPlainTextToHookOutput。TIP — 阻断与终止的区别用decision: deny或 Exit Code 2阻断某个具体动作若要在 JSON 输出中返回{continue: false}则立即终止整个 agent 循环。#!/usr/bin/env bash set -e # Hook logic if process_input; then echo {decision: allow} exit 0 else echo Critical validation failure 2 exit 2 fi3.6 开启遥测日志当telemetry.logPrompts启用时hook 执行会被记录可用于调试执行流{ telemetry: { logPrompts: true } }注意这是调试开关生产/敏感环境下应按第 7 节建议关闭。3.7 使用 /hooks panelCLI 内置命令/hooks panel可查看执行状态与近期输出重点检查hook 执行计数、近期成功/失败、错误消息、执行耗时。完整的 hook 管理命令enable/disable/enable-all/disable-all见 hooks 总览文档。4. 开发规范4.1 从简单开始先写一个“记录输入结构”的极简 hook摸清输入形态再实现复杂逻辑#!/usr/bin/env bash # Simple logging hook to understand input structure input$(cat) echo $input .gemini/hook-inputs.log # Always return valid JSON echo {}4.2 为 hook 写好文档description字段会显示在/hooks panelUI 中是排障时的重要线索{ hooks: { BeforeTool: [ { matcher: write_file|replace, hooks: [ { name: secret-scanner, type: command, command: $GEMINI_PROJECT_DIR/.gemini/hooks/block-secrets.sh, description: Scans code changes for API keys and secrets before writing } ] } ] } }脚本内部也应注明性能预期与依赖#!/usr/bin/env node /** * RAG Tool Filter Hook * * Reduces the tool space by extracting keywords from the users request. * * Performance: ~500ms average * Dependencies: google/generative-ai */4.3 使用 JSON 库解析不要用脆弱的文本处理代替 JSON 解析Bad# Fragile text parsing tool_name$(echo $input | grep -oP tool_name:\s*\K[^])Good# Robust JSON parsing tool_name$(echo $input | jq -r .tool_name)4.4 确保脚本可执行macOS/Linux 下始终赋予执行权限chmod x .gemini/hooks/*.sh chmod x .gemini/hooks/*.jsWindows 注意PowerShell 脚本.ps1不涉及chmod但可能需要执行策略允许其运行例如Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。4.5 纳入版本控制将 hooks 提交以便团队共享git add .gemini/hooks/ git add .gemini/settings.json.gitignore建议# Ignore hook cache and logs .gemini/hook-cache.json .gemini/hook-debug.log .gemini/memory/session-*.jsonl # Keep hook scripts !.gemini/hooks/*.sh !.gemini/hooks/*.js5. Hook 安全5.1 威胁模型hook 从哪里来理解 hook 的来源及其能力边界是安全使用的前提Hook 来源说明System由系统管理员配置例如/etc/gemini-cli/settings.json、/Library/...。默认视为最安全。User~/.gemini/...由你自己配置安全性由你负责。Extensions由你显式批准并安装。安全性取决于扩展来源的完整性。Project./.gemini/...默认不可信。在受信任的内部仓库中风险最低在第三方/公开仓库中风险最高。5.2 项目级 hook 的信任机制源码印证当你打开一个在.gemini/settings.json中定义了 hooks 的项目时流程如下DetectionCLI 检测到这些 hooksIdentification为每个 hook 基于其name与command生成唯一身份指纹Warning若该 hook 身份此前未见显示警告Execution执行 hook除非特定安全设置将其阻断Trust该 hook 被标记为“已信任”。这套机制的源码实现在 trustedHooks.tsgetHookKey生成指纹信任记录持久化到全局目录下的trusted_hooks.jsongetUntrustedHooks返回本项目下未信任的 hook 列表用户确认后trustHooks落盘。另外hookRunner.ts 中还有第二道保险ConfigSource.Project来源的 hook 在非信任文件夹中会被直接拒绝执行Security: Blocked execution of project hook in untrusted folder。修改检测如果项目 hook 的command字符串发生变化例如一次git pull其指纹随之改变CLI 会将其视为新的不可信 hook并再次警告。这防止了恶意者将已验证的命令悄悄替换为恶意命令。5.3 主要风险风险说明任意代码执行Hook 以你的用户身份运行能做任何你能做的事删文件、装软件。数据外泄Hook 可以读取你的输入prompts、输出代码或环境变量如GEMINI_API_KEY并发送到远程服务器。提示注入文件或网页中的恶意内容可能诱导 LLM 以非预期方式触发工具进而触发 hook。5.4 缓解策略验证来源启用任何项目 hook 或扩展前先验证来源。开源项目建议快速审查 hook 脚本扩展应确认作者/发布者可信对来源不明的混淆脚本或编译二进制保持警惕。清理环境Sanitize environmentHook 继承 Gemini CLI 进程的环境变量其中可能包含敏感 API 密钥。CLI 提供了环境变量脱敏系统自动过滤匹配敏感模式如KEY、TOKEN的变量。默认关闭环境脱敏当前默认 OFF。如果你运行第三方 hook 或在敏感环境中工作强烈建议启用。对 hooks 的影响安全防止 hook 脚本意外泄露密钥排障如果你的 hook 依赖某个被拦截的环境变量必须在settings.json中显式放行。{ security: { environmentVariableRedaction: { enabled: true, allowed: [MY_REQUIRED_TOOL_KEY] } } }系统管理员可在系统级配置中为所有用户强制开启脱敏。源码级印证脱敏逻辑位于 environmentSanitization.ts由 hookRunner.ts 在spawn前对 hook 进程环境调用sanitizeEnvironment。关键行为变量名匹配NEVER_ALLOWED_NAME_PATTERNS/TOKEN/i、/SECRET/i、/PASSWORD/i、/KEY/i、/AUTH/i、/CREDENTIAL/i、/PRIVATE/i、/CERT/i等L111-L122即被过滤变量值匹配NEVER_ALLOWED_VALUE_PATTERNSPEM 私钥头、URL 内嵌凭据、ghp_系列 GitHub token、AIzaSyGoogle API key、AKIAAWS 访问密钥、JWT、Stripesk_/rk_、Slackxox*L124-L141即被过滤GEMINI_CLI_*前缀与ALWAYS_ALLOWED_ENVIRONMENT_VARIABLESPATH、HOME、TERM等L52-L92始终放行注意 getSecureSanitizationConfig 中enableEnvironmentVariableRedaction的默认值为false与文档“默认关闭”一致另外源码中存在严格模式检测到GITHUB_SHA或SURFACEGithubCI 环境时强制启用脱敏L17-L22从源码结构看这是针对 CI 场景的额外保护建议在 CI 中运行 hook 时以实际行为为准进行验证。hook 自身可用的环境变量的注入点也在 hookRunner.tsGEMINI_PROJECT_DIR、GEMINI_PLANS_DIR、GEMINI_CWD、GEMINI_SESSION_ID以及兼容别名CLAUDE_PROJECT_DIR命令字符串中的同名占位符由 expandCommand 在执行前展开因此脚本内可直接使用$GEMINI_PROJECT_DIR等路径。6. 故障排查6.1 Hook 没有执行在/hooks panel中检查 hook 名称确认 hook 出现在列表中且已启用。验证 matcher 模式# Test regex pattern echo write_file|replace | grep -E write_.*|replace检查禁用列表确认 hook 未被列入settings.json的 disabled 数组{ hooks: { disabled: [my-hook-name] } }确保脚本可执行macOS/Linuxls -la .gemini/hooks/my-hook.sh chmod x .gemini/hooks/my-hook.shWindows 注意确认执行策略允许运行脚本例如Get-ExecutionPolicy。验证脚本路径确认settings.json中的路径能正确解析# Check path expansion echo $GEMINI_PROJECT_DIR/.gemini/hooks/my-hook.sh # Verify file exists test -f $GEMINI_PROJECT_DIR/.gemini/hooks/my-hook.sh echo File exists6.2 Hook 超时检查配置的超时默认 60000ms1 分钟可在settings.json中调大{ name: slow-hook, timeout: 120000 }源码印证超时值取自hookConfig.timeout ?? DEFAULT_HOOK_TIMEOUThookRunner.ts触发后先SIGTERM、5 秒后SIGKILL最终结果为Hook timed out after ${timeout}mshookRunner.ts。优化慢操作把重处理移到后台任务或使用第 2.2 节的缓存。6.3 输出非法 JSON输出前先校验 JSON 合法性#!/usr/bin/env bash output{decision: allow} # Validate JSON if echo $output | jq empty 2/dev/null; then echo $output else echo Invalid JSON generated 2 exit 1 fi6.4 环境变量不可用检查变量是否被设置#!/usr/bin/env bash if [ -z $GEMINI_PROJECT_DIR ]; then echo GEMINI_PROJECT_DIR not set 2 exit 1 fi调试可用变量env .gemini/hook-env.log若怀疑是脱敏导致变量“消失”可对照第 5.4 节的过滤规则必要时在allowed列表中显式放行。7. 编写安全 Hook 的实践编写自己的 hook 时遵循以下实践保证其健壮与安全。7.1 校验所有输入永远不要无条件信任 hook 输入——它们常来自 LLM 或用户 prompt可能被操纵#!/usr/bin/env bash input$(cat) # Validate JSON structure if ! echo $input | jq empty 2/dev/null; then echo Invalid JSON input 2 exit 1 fi # Validate tool_name explicitly tool_name$(echo $input | jq -r .tool_name // empty) if [[ $tool_name ! write_file $tool_name ! read_file ]]; then echo Unexpected tool: $tool_name 2 exit 1 fi7.2 使用超时通过强制超时防止“拒绝服务”agent 挂起。Gemini CLI 默认 60 秒但对快 hook 应设置更严格的限制{ hooks: { BeforeTool: [ { matcher: *, hooks: [ { name: fast-validator, type: command, command: ./hooks/validate.sh, timeout: 5000 // 5 seconds } ] } ] } }7.3 限制权限以最小必要权限运行 hook#!/usr/bin/env bash # Dont run as root if [ $EUID -eq 0 ]; then echo Hook should not run as root 2 exit 1 fi # Check file permissions before writing if [ -w $file_path ]; then # Safe to write else echo Insufficient permissions 2 exit 1 fi7.4 示例密钥扫描器Secret Scanner用BeforeToolhook 阻止敏感数据被写入/提交这是增强工作流安全的强力模式const SECRET_PATTERNS [ /api[_-]?key\s*[:]\s*[]?[a-zA-Z0-9_-]{20,}[]?/i, /password\s*[:]\s*[]?[^\s]{8,}[]?/i, /secret\s*[:]\s*[]?[a-zA-Z0-9_-]{20,}[]?/i, /AKIA[0-9A-Z]{16}/, // AWS access key /ghp_[a-zA-Z0-9]{36}/, // GitHub personal access token /sk-[a-zA-Z0-9]{48}/, // OpenAI API key ]; function containsSecret(content) { return SECRET_PATTERNS.some((pattern) pattern.test(content)); }配合 4.2 节的description字段如Scans code changes for API keys and secrets before writing与matcher: write_file|replace可组成完整的“写前拦截”链路。8. 隐私考量Hook 的输入与输出可能包含敏感信息需要专门管理。8.1 收集了哪些数据Hook 遥测可能包含输入prompts、代码与输出decisions、reasons除非被禁用。8.2 隐私设置禁用 PII 日志处理敏感数据时在设置中关闭 prompt 日志{ telemetry: { logPrompts: false } }Suppress Output单个 hook 可在 JSON 响应中返回suppressOutput: true请求将其元数据从日志和遥测中隐藏。NotesuppressOutput只影响后台日志JSON 中的systemMessage或reason仍会在终端显示给用户。8.3 Hook 中的敏感数据处理如果你的 hook 处理敏感数据最小化日志不要把敏感数据写入日志文件净化输出输出 JSON 或写 stderr 之前先移除敏感数据。9. 要点速查主题关键做法源码/文档依据性能并行 I/O、文件缓存、AfterAgent替代AfterModel、具体 matcher、jqhookRunner.ts 并行/顺序执行调试stdout 只出 JSON、stderr 打日志、/hooks panel、手动喂样例 JSONhooks 总览 全局机制退出码0成功解析 JSON2系统阻断stderr 为理由其他警告继续convertPlainTextToHookOutput信任项目 hook 按 namecommand 指纹变更后重新警告trustedHooks.ts环境脱敏默认关闭建议启用allowed显式放行environmentSanitization.ts隐私logPrompts: false、suppressOutput: true、最小化日志Best Practices掌握以上实践后建议按 Writing hooks 教程 动手建立第一个 hook再对照 I/O 规范参考 核对输入输出 schema最后用本文第 6 节排查清单与/hooks panel完成上线验证。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考