企业官网建设流程全解析

• 人工智能
• AI 应用
• AI Agent
• 代码智能体
• 开发工具
• CLI
• MCP Clients

本篇指南围绕 Grok 的 Hooks 机制展开：它允许你在 Grok 会话的关键时刻（工具调用前后、会话启停、Agent 通知等）自动运行自定义脚本或发送 HTTP 请求，从而将自动化、安全防护、审计日志、通知和自有工具链深度集成到编码代理工作流中。读完本文，你将掌握 Hook 文件的 JSON 格式、事件与匹配器语义、脚本的 stdin/stdout 契约与退出码约定、环境变量与变量替换规则、信任模型，以及如何在 TUI 中管理、调试和分发 Hooks。

为什么使用 Hooks

Hooks 是挂在 Grok 会话生命周期上的"钩子"，典型用途包括：

• 安全守卫（Safety guards）：在rm -rf /这类危险命令执行前将其拦截。
• 审计日志（Audit logging）：把每一次工具调用或会话记录到文件或外部服务。
• 通知（Notifications）：长任务结束时向 Slack/Discord 发送消息。
• 自动格式化（Auto-formatting）：编辑完成后自动运行cargo fmt或prettier。
• 环境准备（Environment setup）：会话启动时导出密钥或设置变量。
• 自定义工作流（Custom workflows）：在特定事件上触发构建、测试或部署。

从实现上看，这套机制由仓库中的xai-grok-hookscrate 提供：它负责"基于文件的发现（discovery）、命令执行（runner）与策略执行（policy enforcement）"，文档与实现都明确其核心设计取向是fail-open（失败放行）——Hook 出错不会阻塞正常操作，只有显式的deny决策才会拦截工具调用（见 lib.rs）。

快速开始

1. 创建 hooks 目录：

   mkdir -p ~/.grok/hooks

2. 创建一个简单的 Hook 文件，例如~/.grok/hooks/session-start.json：

   { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "echo \"🚀 Grok session started in $(pwd)\"" } ] } ] } }

3. 启动（或重启）一个 Grok 会话，该 Hook 会在SessionStart事件时自动运行。

4. 验证加载：在非 VS Code 家族的终端按Ctrl+L（在 VS Code / Cursor / Windsurf / Zed 上推荐直接运行/hooks），打开 Hooks 标签页确认 Hook 已加载。

Hook 发现位置与信任模型

Hooks 从多个位置被发现，所有来源会合并加载：

配置文件的 Hook 使用相同的 TOML 形式 schema，详见 Hooks 用户指南的配置文件章节。

信任一个项目（Trusting a project）：首次打开带 Hook 的项目时，需要先信任它，项目 Hook 才会运行；在此之前会被静默跳过。授予信任的方式是打开 hooks 弹窗（非 VS Code 家族按Ctrl+L，或任何终端运行/hooks），或运行/hooks-trust（与--trust走同一个文件夹信任门禁，记录在~/.grok/trusted_folders.toml）。这一设计防止不受信任的仓库运行任意代码。

在 xai-grok-hooks 的 discovery.rs 中可以看到，加载后的 Hook 被组织成HookRegistry——一个按事件类型索引的HashMap<HookEventName, Vec<HookSpec>>快照，全局与项目两个目录分别作为参数传入load_hooks，最终按事件合并。SubagentEnd会被折叠为SubagentStop的别名（canonical()），保证以任一拼写注册的 Hook 都能被正确派发。

Hook JSON 格式详解

每个.json文件可以定义多个事件、多个匹配组的 Hook：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "bin/safety-check.sh", "timeout": 10 } ] } ], "PostToolUse": [ { "hooks": [ { "type": "command", "command": "bin/log-activity.sh" } ] } ] } }

关键字段：

• 事件名（顶层 key）：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、Notification、SessionEnd等。未知的事件名会被跳过，因此共享的 Claude 或 Cursor 配置文件也能照常加载。
• matcher（可选）：正则表达式，用于筛选触发条件——工具事件匹配工具名，其他事件匹配各自的事件值（详见 Hooks 用户指南 的 Hooks 章节）。留空 = 匹配所有。
• type："command"（运行脚本或 shell 单行命令）或"http"（把事件 POST 到 URL）。
• command：可执行文件路径（相对于 JSON 文件）或内联 shell 命令。
• timeout：杀掉 Hook 前的等待秒数（默认 5 秒；Stop/SubagentStop门控默认 600 秒）。超时的 Hook失败放行（fail open）。

工具名别名（Tool name aliases）：Claude 风格的工具名（如Bash、Edit、Read）会自动匹配 Grok 的内部工具名（如run_terminal_cmd、search_replace、read_file）。这是基于 xai-grok-tools 的名称注册表 实现的别名展开。

matcher 的底层语义

matcher 的解析逻辑可以在 matcher.rs 中看到，它并非一律当正则处理，而是分三种模式：

• 空模式或"*"：匹配所有事件。
• "简单"模式（仅由[A-Za-z0-9_]和|组成）：按精确匹配处理，|分隔的每一项逐一展开为名字集合，并附加每个名字的 Grok 别名（因此"Bash"同时匹配Bash与run_terminal_command）。这种设计刻意避免了对a|b|c做朴素正则锚定导致的"只锚定首尾项、悄悄过度匹配"的经典 bug。
• 其余情况：按非锚定正则处理，且会同时测试工具的外部别名（例如^Bash$也能命中 Grok 工具run_terminal_command）。

注意 matcher 中空白是有效字符（不做 trim）：" "是一个匹配不到任何东西的正则，而不是匹配全部——这一细节避免了一个错误的 deny 门控变成"全拒"。另外，缺失 matcher 或缺失匹配值时采用 fail-open 默认（matcher_allows返回 true）。

从源码结构看，matcher 的"简单 vs 正则"拆分是刻意为之：is_simple_form判定 +exact_names展开，配合claude_names_for/grok_names_for双向别名注册表，让从其他 Agent CLI 迁移过来的 matcher 无需修改即可保持原有触发行为。

Hook 事件全景

事件按三种节奏触发：每次会话（SessionStart、SessionEnd）、每个回合（UserPromptSubmit、Stop、StopFailure）、回合内每次工具调用（PreToolUse、PostToolUse、PostToolUseFailure）。完整事件表见 Hooks 用户指南：

其中SubagentEnd被接受为SubagentStop的别名；PreToolUse可以拦截工具调用，Stop/SubagentStop可以阻止 Agent 结束回合（见下文"Stop 决策控制"），其余事件均为被动观察型。

Cursor Hook 兼容

Grok 接受 Cursor 的 camelCase 事件名，因此~/.cursor/hooks.json可以原样加载：sessionStart→SessionStart、preToolUse→PreToolUse、beforeShellExecution/beforeMCPExecution/beforeReadFile→PreToolUse、afterShellExecution/afterMCPExecution/afterFileEdit→PostToolUse、beforeSubmitPrompt→UserPromptSubmit等。Cursor 的按操作拆分的 Hook 会映射到通用的PreToolUse/PostToolUse，脚本通过 JSON 输入里的工具名配合 matcher 自行过滤。

从 event.rs 的源码看，事件名解析由一张宏表生成：每个事件维护display（规范蛇形名）、aliases（所有可接受的拼写，如 PascalCase、snake_case、camelCase 乃至beforeShellExecution这类按操作别名）以及(gate, matcher, hub)三个特征。GateKind区分 Observe / Tool / Stop 三种语义，MatcherPolicy区分 Ignored（如Stop、UserPromptSubmit上的 matcher 会被忽略并告警）与 Tested（如SessionStart的source、SessionEnd的reason、Notification的notificationType）。解析失败会给出清晰的错误提示，列出全部可用事件名。

编写 Hook 脚本

输入：stdin 上的 JSON 事件

完整事件以 JSON 形式通过stdin发送。以PreToolUse为例：

{ "hookEventName": "pre_tool_use", "sessionId": "abc-123", "cwd": "/Users/you/project", "workspaceRoot": "/Users/you/project", "toolName": "run_terminal_cmd", "toolInput": { "command": "npm test" }, "timestamp": "2026-04-14T12:00:00Z" }

所有事件都携带公共字段：hookEventName、sessionId、cwd、workspaceRoot、timestamp、permissionMode（取值为default、auto、plan或bypassPermissions）、promptId（所属回合；会话级事件无此字段），再加上事件特有的字段（如上面的toolName）。PreToolUse还会附带toolUseId与toolInputTruncated标志。事件信封在 event.rs 中以HookEventEnvelope（camelCase 序列化）与HookPayload（untagged 枚举）建模；payload 超过 128 KB（MAX_PAYLOAD_SIZE）时会被截断并标注[truncated]，长文本字段按字符边界裁剪并追加… [+N chars]标记（如lastAssistantMessage上限 32,768 字符）。

输出：阻塞型 Hook 的决策文档

对于PreToolUse这类阻塞 Hook，向stdout写 JSON：

• 放行：{"decision": "allow"}
• 拒绝：{"decision": "deny", "reason": "Unsafe command detected"}
• 改写工具输入：{"hookSpecificOutput": {"hookEventName": "PreToolUse", "updatedInput": {"command": "npm test"}}}

updatedInput会在工具运行前替换其输入，且必须是一个 JSON 对象（非对象会被忽略）。改写后的输入会被 plan-mode 门控、权限提示和工具本身共同看到，因此一个 Hook 可以做"规范化/加固"而非仅仅允许或拒绝。多个 Hook 都返回updatedInput时最后一个生效；若改写结果不符合工具 schema，调用会被拦截并报告为 invalid-input 错误；deny决策会丢弃任何updatedInput。

从 runner/mod.rs 的实现看，输出解析很严谨：只有同时携带decision或hookSpecificOutput的 JSON 才被当作门控文档（is_gate_document），偶然打印的 JSON 日志行不会被误读为 allow；decision出现未知值（拼写错误）会报错而不是静默放行；deny缺少reason时，命令行 Hook 会用 stderr 的首行作为兜底原因，HTTP Hook 则使用"denied by hook '<name>'"。

退出码约定

关键结论：要拦截工具调用，必须让 Hook 完整运行并在 stdout 返回{"decision":"deny","reason":"..."}。另外，对PreToolUse而言，stdout 中的deny决策会无视退出码被采纳；对Stop/SubagentStop，stdout 上有效的决策 JSON 优先于退出码，只有 stdout 没有可用 JSON 时才以退出码裁决（退出码 2 用 stderr 作为反馈阻塞停止）。人类可读的诊断信息请写到stderr——它是 Hook 的反馈通道，失败时 stderr 首行会出现在滚动区与日志中。

Stop 决策控制

Stop和SubagentStopHook 在 Agent 即将结束回合时运行，可以"不让它停"（与 Claude Code 兼容）。向 stdout 写 JSON：

• 阻止停止：{"decision": "block", "reason": "The test suite hasn't been run yet"}——reason 会作为用户消息反馈给模型，Agent 在同一回合内再跑一轮。
• 非错误反馈：{"hookSpecificOutput": {"hookEventName": "Stop", "additionalContext": "Run the linter before finishing"}}——同样让 Agent 继续工作，但以 Hook 反馈而非 Hook 错误的形式呈现。
• 强制停止：{"continue": false, "stopReason": "Budget exhausted"}——结束回合，覆盖任何 block。
• 允许停止：退出码 0 且无输出（或任意非 JSON 输出）。

退出码2同样会阻止停止，此时以stderr作为反馈。每个回合最多8 次连续续跑（block 或非错误反馈），之后门控被强制覆盖、回合结束。输入中携带stopHookActive（本轮是否已因之前的 block 在续跑）和lastAssistantMessage（本回合 Agent 最终回复的文本），Hook 可以据此判断"阻止一个永远无法满足的条件"还是及时放弃。Stop/SubagentStop默认 600 秒超时（与 Claude Code 一致），因为门控常常要跑构建或测试套件；超时同样 fail-open——Agent 会正常停止。完整可运行的"keep-working"策略脚本示例见 Hooks 用户指南。

需要注意：Stop门控只在真实完成的回合运行；被中断、被拒绝或触达回合上限的回合会改走StopCancelled（API 错误则走StopFailure），因此在Stop上计数或门控的脚本应当先检查reason == "end_turn"，以免把会话结束时的观察型触发算进去。会话结束时还会额外触发一次仅观察的Stop（reason为"channel_closed"或"shutdown"），其决策会被解析但忽略。Stop输入还携带backgroundTasks与sessionCrons，帮助 Hook 区分"会话确实结束"与"会话暂停、等待后台任务唤醒"。

被动 Hook

对于SessionStart、PostToolUse这类事件，stdout 会被忽略，成功退出 0 即可。

常用环境变量

Grok 会向每个 Hook 进程注入以下变量：

• GROK_HOOK_EVENT—— 事件名（如pre_tool_use、session_start、post_tool_use）
• GROK_HOOK_NAME—— 该 Hook 的完整配置名
• GROK_SESSION_ID—— 当前会话标识
• GROK_WORKSPACE_ROOT—— 工作区根目录的绝对路径

此外，兼容层还总是注入CLAUDE_PROJECT_DIR（工作区根目录的 Claude Code 兼容别名）。由插件提供的 Hook 还会获得：

• GROK_PLUGIN_ROOT—— 插件安装目录的绝对路径
• GROK_PLUGIN_DATA—— 插件可写数据目录的绝对路径

这些 runner/插件注入的变量优先级最高：任何试图通过env字段覆盖保留键（reserved keys）的尝试都会在加载时被剥离（并记录告警）；插件的GROK_PLUGIN_ROOT/GROK_PLUGIN_DATA同样覆盖用户声明的同名值——插件契约不可协商。

自定义环境变量（env字段）

每个 handler 可以声明额外的环境变量注入子进程：

{ "type": "command", "command": "bin/check.sh", "env": { "MY_API_TOKEN": "secret-here", "LOG_LEVEL": "debug" } }

注意：值必须是字符串——JSON 数字和布尔值目前会解析失败（需要时请用引号包裹）。

变量替换

command与url字符串在配置加载时支持$VAR和${VAR}替换：

{ "type": "command", "command": "${HOME}/.config/grok-hooks/check.sh" }

每个引用的查找顺序：

1. 该 handler 自身的env映射；
2. 当前进程环境（Grok 自己看到的环境）。

两处都未定义时，引用会原样保留（如${UNSET}保持为字面字符串）。runner 注入的保留名（CLAUDE_PROJECT_DIR、GROK_WORKSPACE_ROOT、GROK_HOOK_EVENT、GROK_HOOK_NAME、GROK_SESSION_ID）不会从 Grok 进程环境取值：Unix 下由sh -c从子进程环境展开，Windows PowerShell 会把$VAR改写为$env:VAR。HTTP 的url在请求时再做一次替换（紧接 SSRF 校验之前），因此${GROK_PLUGIN_ROOT}/check这类引用能解析到插件真实路径。剩余的未解析命令引用会以 "required env var(s) not set" 拒绝执行。

参数展开修饰符：POSIX 形式如${VAR:-default}、${VAR-default}、${VAR:=x}、${VAR:?msg}、${VAR:+x}、${VAR%pat}、${VAR#pat}、${VAR/pat/repl}、${VAR:N:M}绝不会在加载时展开，而是原样留给运行时的sh -c分支处理——这避免了加载期展开器与 POSIX shell 语义（尤其是:-的空字符串行为）之间的微妙偏差。

如果命令包含 shell 元字符（空格、管道、&&、重定向、$等），runner 会通过sh -c路由，获得完整的 shell 展开语义；如果是无元字符的裸路径，则直接 spawn——但路径中的$VAR/${VAR}仍在加载时解析，因此${HOME}/bin/check.sh这类直接执行的路径无需包一层sh -c。

哪些内容不会被展开：

• matcher是正则（$是行尾锚点），从不做环境变量展开——替换$VAR会悄悄改变正则语义甚至产生非法模式。需要动态 matcher 时，请在写文件阶段生成 JSON。
• timeout是数值，无可展开。
• env映射自身的值——按原样存储并透传给子进程，因此"BAR": "${HOME}/x"注入到子进程环境里就是字面字符串${HOME}/x。

从配置到执行的源码链路

Hook 的完整生命周期在 xai-grok-hooks crate 中有清晰的模块划分，可以作为排查问题时的地图：

1. 发现（discovery.rs）：从~/.grok/hooks/与<project>/.grok/hooks/扫描 JSON，解析为HookSpec列表并合并进HookRegistry；load_hooks返回(registry, errors)，加载告警（如保留环境变量被剥离、matcher 被忽略）会作为错误列表返回。
2. 匹配（matcher.rs）：按上文所述"简单精确 / 非锚定正则 / 全匹配"三态编译 matcher；无效正则解析失败时降级为Never（fail-closed，宁可不匹配也不扩大为全匹配）。
3. 执行（runner/）：command.rs与http.rs分别实现子进程与 HTTP 两类 handler；runner/mod.rs统一解释输出为HookRunnerResult（Allow/Deny/Stop/Success/Failed），Failed由调用方 fail-open。
4. 派发（dispatcher.rs）：按事件特征（EventTraits中的 gate/matcher/hub 三元组）决定某事件是门控还是观察、matcher 是否生效、是否转发给 hub。

从 lib.rs 的快速开始示例 可以看出 crate 的编程接口：load_hooks(Some(global), Some(project))加载后，用registry.hooks_for(HookEventName::PreToolUse)按事件取 Hook——这也意味着如果你在自己的工具中集成 Grok 的 Hook 系统，可以直接复用这套注册表与 runner。

在 TUI 中管理 Hooks

在非 VS Code 家族终端按Ctrl+L（或任何终端运行/hooks）打开 Hooks & Plugins 弹窗。在Hooks标签页中：

• l—— 重新加载所有 Hooks
• a—— 按路径添加自定义 Hook（便于测试）
• e—— 启用/禁用
• r—— 移除
• Space—— 展开分组

来自~/.grok/hooks/的 Hook 显示在Global分组下，项目 Hook 显示在Project分组下，依此类推。每个 Hook 展示其触发事件、运行的命令或 URL、超时时长与启停状态。

提示：Hooks 用户指南 记录了更新一版的键位布局：r重新加载、x移除所选 Hook（按小写y确认）、Space启用/禁用、f循环切换状态过滤（All / Enabled / Disabled）。以你所用版本的?帮助面板为准。用户指南还列出了/hooks-list、/hooks-trust、/hooks-add <path>、/hooks-remove <path>、/hooks-untrust等斜杠命令。

启用/禁用单条 Hook 立即生效（Space），无需重启会话；r重新加载后，会话期间对 Hook 文件所做的修改会被重新读取。Hook 执行结果会以注解（annotations）形式出现在 TUI 滚动区，可以直观看到哪些 Hook 运行了、是允许还是拒绝、输出了什么（需启用插件 UI，默认开启）。

HTTP Hooks

除了本地脚本，还可以调用远端端点：

{ "type": "http", "url": "https://hooks.example.com/grok-event", "timeout": 15 }

完整的事件信封会以 JSON 形式 POST 到该 URL，适用于 webhook、分析或 serverless 函数场景。如前所述，url会在请求时（SSRF 校验之前）再次做变量替换。

在配置文件中定义 Hooks（TOML）

Hook 也可以直接放在 Grok 配置中，让团队随配置分发 Hook 而无需单独维护 JSON 文件。同一个hooks对象可以从三个 TOML 文件读取：~/.grok/config.toml（用户层）、managed_config.toml（$GROK_HOME与/etc/grok，组织托管层）、requirements.toml（用户与系统，需求层）。TOML 结构与 JSON 的 hooks 对象完全一致，已有 JSON Hook 可以直接转写：

[[hooks.PreToolUse]] matcher = "Bash|Write|Edit" hooks = [ { type = "command", command = "/opt/guard/pretooluse.sh", timeout = 10 }, ]

每个 matcher 组是一个[[hooks.<Event>]]条目，带可选的matcher和内层hooks数组；handler 字段（type、command、url、timeout、env）与事件名和 JSON 格式完全一致。TOML 还接受嵌套的数组表写法（[[hooks.PreToolUse.hooks]]），但官方推荐上面的内联表形式，避免为每个 handler 重复写头。配置层 Hook 具有三个特性：跨层叠加（低优先级层只增不减，完全相同的定义去重并保留最高权威副本）、来源标注（/hooks中以managed:、requirements/user:、user:等前缀标记每个 Hook 来自哪一层）、不做读时展开（字面${VAR}原样到达 runner，由 runner 做唯一一次展开，与 JSON 文件语义一致）。

最佳实践

1. 保持 Hook 快速——长时间运行的 Hook 会阻塞 UI（尽量用后台&或异步）。
2. 用显式deny来拦截——Hook 在任何错误下都是 fail-open（超时、崩溃、缺环境变量都不会阻塞工具调用）。要强制策略，Hook 必须运行到结束并在 stdout 输出{"decision":"deny","reason":"..."}；在脚本内部自行处理错误，确保总能返回明确决策。
3. 使用绝对路径或相对 Hook 文件的路径——JSON 旁边的bin/目录放脚本最便于移植。
4. 测试优先——用Ctrl+L（非 VS Code 家族）//hooks验证加载与匹配，再依赖它。
5. 项目 Hook 纳入版本控制——提交.grok/hooks/（但绝不提交密钥）。

安全注意事项

• 全局 Hook（~/.grok/...）以你的用户权限运行——请像对待 shell 脚本一样对待它们。
• 项目 Hook 需要显式信任（/hooks-trust或弹窗），以防恶意仓库的供应链攻击。信任决策记录在~/.grok/trusted_folders.toml，与仓库级 MCP/LSP 服务器共用同一个文件夹信任门禁：一次--trust//hooks-trust会同时信任该文件夹的 MCP、LSP 与 Hooks，并向子目录级联；关闭文件夹信任（GROK_FOLDER_TRUST=0或[folder_trust] enabled = false）也会一并解锁项目 Hook。
• HTTP Hook 会发送会话数据——只使用可信端点。

故障排查

• Hook 没运行？→ 非 VS Code 家族按Ctrl+L（或任何终端运行/hooks），检查它是否已加载并被 matcher 命中。
• 项目 Hook 被忽略？→ 先信任该项目（/hooks-trust或用--trust重启）。
• 脚本找不到？→ 检查路径是否相对于.json文件，并确认可执行（chmod +x）。
• PowerShell 报The argument '/.claude/hooks/….ps1' to the -File parameter does not exist？→ PowerShell 把$CLAUDE_PROJECT_DIR当成了空值。Grok 会把它改写为$env:CLAUDE_PROJECT_DIR，除非设置了GROK_SHELL=cmd。
• 看到错误？→ 查看 pager 日志（通常在 tracing 面板或~/.grok/logs）。也可以带RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok启动以捕获详细日志。

更多示例

xai-grok-hooks/examples 目录提供了可直接复制的内置示例（安装说明）：

• safe-shell.json —— 安全 shell 守卫，拒绝rm -rf /、mkfs、dd等破坏性命令。
• no-recursive-grep.json —— 硬性拦截grep -r/grep -R/rgrep（OOM 防护）。递归 grep 会把整棵目录树读入内存，在大型仓库上可能 OOM 杀掉 Agent 进程；系统提示只是建议性的，这个 Hook 把它变成确定性的硬拦截。示例还精心避免误报：ls -R | grep foo、grep -e -r file、grep -- -r file都会被放行。
• session-log.json —— 会话审计日志（SessionStart+SessionEnd）。
• tool-logger.json —— 工具活动日志（PreToolUse+PostToolUse）。
• stop-verify.json —— 停止门控：cargo build通过前不允许 Agent 结束回合（Stop事件 + 300 秒超时，超时 fail-open 让 Agent 正常停止）。

把它们复制到~/.grok/hooks/并定制即可：

mkdir -p ~/.grok/hooks/bin cp crates/codegen/xai-grok-hooks/examples/hooks/safe-shell.json ~/.grok/hooks/ cp crates/codegen/xai-grok-hooks/examples/hooks/bin/safe-shell-guard.sh ~/.grok/hooks/bin/ chmod +x ~/.grok/hooks/bin/safe-shell-guard.sh

完整参考

关于完整事件列表、matcher 语义、信任模型与更深入的细节（含 Claude Code Hook 移植差异清单、StopCancelled/StopFailure的字段说明、忙碌/空闲状态机的五事件注册法），请阅读 Hooks 用户指南；Hook 系统的 Rust 实现可深入 xai-grok-hooks crate 的 event.rs、matcher.rs、runner/mod.rs 与 discovery.rs 继续探索。

• 人工智能
• AI 应用
• AI Agent
• 代码智能体
• 开发工具
• CLI
• MCP Clients