Hooks

Qwen Code hooks：四种执行器类型（command/http/function/prompt）、事件列表与匹配器、HTTP hook 的安全特性、/hooks 浏览器、禁用开关与作用域。

Qwen Code hooks 提供一种强大的机制，用来扩展和定制 Qwen Code 应用的行为。Hooks 让用户在应用生命周期的特定点执行自定义脚本或程序，例如工具执行之前、工具执行之后、会话开始/结束，以及其他关键事件。Hooks 默认启用；你可以在设置文件里（顶层，与 hooks 并列）把 disableAllHooks 设为 true 暂时禁用所有 hooks，这会禁用所有 hooks 而不删除它们的配置。官方文档很长（含每个事件的输入输出细节），这里整理核心内容，细节以官方文档为准。

Hooks 是用户定义的脚本或程序，由 Qwen Code 在应用流程的预定义节点自动执行。它们让用户：监控和审计工具使用；强制执行安全策略；向对话注入额外上下文；基于事件定制应用行为；与外部系统和服务集成；以编程方式修改工具输入或响应。

浏览你的 hooks：运行 /hooks 打开本会话所运行 hooks 的只读浏览器，它从事件到匹配器再到匹配器下的各个 hook 逐级深入（不支持匹配器的事件直接进入它们的 hooks）；hook 的详情显示它的类型、来源、是否启用，以及它的命令、URL 或提示。浏览器从不编辑你的配置：要添加、更改或删除 hook，编辑 settings.json；但它会重新读取：打开交互式菜单会从本会话使用的用户、工作区和系统设置文件重新加载 hook 定义（保存文件、拉取更改或切换分支不会自动让新的 hook 命令生效）。这个重新加载覆盖 hook 定义，不覆盖 hook 控制或 HTTP 安全设置：disableAllHooks、stopHookBlockingCap、security.allowedHttpHookUrls 和 security.allowPrivateNetworkHooks 的更改仍需重启；项目 hooks 只在受信任的工作区里加载。智能体 frontmatter 作用域：在智能体 frontmatter 里声明的 hooks 只适用于那次调用（包括它的 SubagentStart 和 SubagentStop 事件），不会继承进嵌套的智能体，也不为父级和同级运行；用 SubagentStop 表示智能体完成（Stop 不会自动重映射）；如果智能体 hook 应该观察整个会话，把它移到设置里。

Hook 类型

Qwen Code 支持四种 hook 执行器类型：

类型	说明
`command`	执行 shell 命令，通过 `stdin` 接收 JSON，通过 `stdout` 返回结果
`http`	把 JSON 作为 `POST` 请求体发送到指定 URL，通过 HTTP 响应体返回结果
`function`	直接调用已注册的 JavaScript 函数（仅会话级 hooks）
`prompt`	用 LLM 评估 hook 输入并返回决定

Command hooks

Command hooks 通过子进程执行命令。输入 JSON 通过 stdin 传入，输出通过 stdout 返回。配置字段：type（必需，"command"）、command（必需，要执行的命令）、name（可选，hook 名称，用于日志）、description（可选）、timeout（可选，秒，默认 60）、async（可选，是否在后台异步运行）、env（可选，环境变量）、shell（可选，"bash" 或 "powershell"）、statusMessage（可选，执行期间显示的状态消息）。timeout 对 command、HTTP 和 prompt hooks 以秒为单位（SDK 注册的 function hooks 保持毫秒）；command hooks 的超时过去以毫秒书写，所以对 command hooks，值 1000 及以上仍被读作毫秒，已有设置继续有效。示例：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "write_file",
        "hooks": [
          {
            "type": "command",
            "command": "\"$QWEN_PROJECT_DIR/.qwen/hooks/security-check.sh\"",
            "name": "security-check",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

QWEN_PROJECT_DIR、CLAUDE_PROJECT_DIR 和 GEMINI_PROJECT_DIR 在每个 command hook 的环境里都被设为项目目录。Bash hooks 从环境读取它们，所以像其他 shell 变量一样用双引号包住，如 "$QWEN_PROJECT_DIR/.qwen/hooks/security-check.sh"。迁移说明：bash hooks 过去会在 shell 运行之前把这些变量在命令文本里替换，该替换已被移除；在含空格的项目路径里不加引号地使用该变量，或写在单引号里（如 '$QWEN_PROJECT_DIR/hook.sh'）的 bash hook，现在必须加双引号。

HTTP hooks

HTTP hooks 把 hook 输入作为 POST 请求发送到指定 URL，支持 URL 白名单、DNS 级的 SSRF 保护、环境变量插值和其他安全特性。字段：type（"http"）、url（目标 URL）、headers（请求头，支持环境变量插值）、allowedEnvVars（允许出现在 URL/头里的环境变量白名单）、timeout（秒，默认 600）、name、statusMessage、once（每个会话每个事件只执行一次，仅 HTTP hooks）。安全特性：URL 白名单（通过 allowedUrls 配置允许的 URL 模式）；SSRF 保护（阻止私有 IP（10.x.x.x、172.16-31.x.x、192.168.x.x 等），但允许环回地址（127.0.0.1、::1））；DNS 验证（请求前验证域名解析，防止 DNS 重绑定攻击）；环境变量插值（${VAR} 语法，只允许 allowedEnvVars 白名单里的变量）。HTTP hooks 从不跟随重定向：3xx 响应与其他非 2xx 状态一样处理，是非阻塞的 hook 失败，重定向目标从不被联系。

允许私有网络 hooks（仅限受管环境）：默认 HTTP hooks 不能以私有或链路本地 IP 范围为目标。在平台受管的环境里，hook 接收端是第一方的、VPC 内部端点时（如解析到 172.16.0.0/12 的内部 API 网关），可以用 "security": { "allowPrivateNetworkHooks": true } 放宽 IP 范围检查：这个设置只在用户、系统和 SystemDefaults 设置作用域里被遵守，工作区（项目）设置里的值被忽略并记录警告，所以克隆的仓库永远不能给自己授予这个绕过；该标志只放宽一般的私有/CGNAT/链路本地范围检查，云元数据端点在任何配置下都保持被阻止；security.allowedHttpHookUrls 白名单仍独立适用（在受管环境里把该标志与白名单配对，让只有预期的内部端点可达）。警告：启用这个标志让 hooks 能触及你网络上的内部基础设施，只在受信任的受管设置里启用，永远不要在你无法控制的仓库里启用。

Hook 事件

Hooks 在 Qwen Code 会话期间的特定点触发，不同事件支持不同的匹配器来过滤触发条件：

事件	触发时机	匹配器目标
`PreToolUse`	工具执行之前	工具 id（`write_file`、`read_file`、`run_shell_command` 等）
`PostToolUse`	工具成功执行之后	工具 id
`PostToolUseFailure`	工具执行失败之后	工具 id
`PostToolBatch`	一批工具调用全部解决之后一次	无（总是触发）
`UserPromptSubmit`	受支持的模型调用之前	无
`UserPromptExpansion`	斜杠命令展开为提示之后、提示发送之前	命令名（不带前导 `/`）
`SessionStart`	会话开始或恢复时	来源（`startup`、`resume`、`clear`、`compact`）
`SessionEnd`	会话结束时	原因（`clear`、`logout`、`prompt_input_exit` 等）
`SessionDelete`	显式选择的会话被删除之后	无
`MessageDisplay`	回复流式输出时反复触发	无（总是触发）
`Stop`	这一轮结束之前	无（总是触发）
`StopFailure`	API 错误或循环检测结束这一轮时，代替 `Stop`	错误类型（`rate_limit`、`server_error`、`loop_detected` 等）
`SubagentStart`	子智能体启动时	智能体类型（`Bash`、`Explorer`、`Plan` 等）
`SubagentStop`	子智能体停止时	智能体类型
`PreCompact`	对话压缩之前	触发方式（`manual`、`auto`）
`PostCompact`	对话压缩成功之后	触发方式（`manual`、`auto`）
`Notification`	发送通知时	类型（`permission_prompt`、`idle_prompt`、`auth_success`）
`PermissionRequest`	权限对话框显示时	工具 id
`PermissionDenied`	AUTO 模式分类拒绝某个工具调用时	工具 id
`TodoCreated`	创建新的待办项时	无（总是触发）
`TodoCompleted`	待办项被标记为完成时	无（总是触发）
`InstructionsLoaded`	`QWEN.md` 这样的上下文文件，或它导入的文件被加载时	被加载文件的路径

每个事件的输入/输出结构、配置、并行与顺序执行、异步 hooks、安全模型、最佳实践示例（安全校验 hook、HTTP 审计 hook、提交提示校验 hook）和排障（hook 不触发等）见官方 hooks 文档。