千问办公的 Hooks：在哪几个时机能插进自己的动作

一、你想解决的其实不是”让模型听话”

用 Agent 干活久了，多数人都撞过同一堵墙：你在提示词里反复交代”删文件之前先问我”，它十次里有九次照做，第十次还是把东西删了。你再加一句”必须、务必、绝对不要”，效果也就那样。

问题出在机制上：写进提示词的约束要经过模型理解这一层，理解偏差多少总会有。千问办公帮助中心《Hooks》一页对这件事有一句文档自述：与 Prompt 指令不同，Hooks 是确定性的，只要事件触发，脚本就一定执行，不受模型理解偏差的影响。

所以 Hooks 处理的是另一类需求：不是”让模型更听话”，而是”在模型行为之外，另起一条一定会跑的路”。文档举的三个用途也都是这个味道——在工具执行前拦截危险操作、写文件后自动跑 lint 保持代码风格一致、Agent 完成任务时弹出桌面通知不用一直盯着屏幕。共同点是它们都不指望模型主动想起来做。

需要先说清楚位置：帮助中心把 Hooks 放在”桌面端核心功能”这一组下面，页面本身也标着”桌面端”。在”网页端核心功能”那一组里，我们没有找到 Hooks 条目。

二、官方文档写明它怎么用

配置入口只有一处。文档给的”配置文件位置”表只有一行：~/.qwenwork/settings.json，作用域是用户级（全局），说明是”用户个人配置，对所有 QwenWork 会话生效”。

配置结构是三层嵌套：最外层的 hooks 下按事件名分组，每个事件名对应一个数组，数组的每一项是一个 matcher 分组，分组内部再放一个 hooks 数组装具体命令。文档写明一个事件下可以配置多个 matcher 分组，每个分组可以包含多个 Hook 命令。

具体命令这一层，文档给了四个字段：

字段	必填	说明
type	是	固定为 "command"
command	是	要执行的 shell 命令
timeout	否	超时时间（秒），默认 60
matcher	否	匹配条件，不填则匹配所有

matcher 的四种写法文档也列了：不填或 "*" 匹配所有；精确值如 "Bash" 只在 Bash 工具时触发；用 | 分隔匹配多个值，例如 "Write | Edit"；也支持正则，文档给的例子是 "mcp__.*" 匹配所有 MCP 工具。要注意同一个 matcher 字段在不同事件下匹配的东西不一样——在 PreToolUse 里匹配的是工具名，在 SessionStart 里匹配的是会话来源，在 PreCompact 里匹配的是触发方式。

脚本那一侧的约定只有两条通道：输入走 stdin 的 JSON，输出走 exit code 和 stdout。文档写明所有事件的输入都包含三个通用字段：session_id（当前会话 ID）、cwd（当前工作目录）、hook_event_name（触发的事件名称），不同事件在此基础上附加各自的额外字段。exit code 的语义是：0 成功，2 阻塞（stderr 内容注入对话，仅对支持阻塞的事件生效），其他值为非阻塞错误。stdout 的 JSON 只在 exit 0 时解析，exit 非 0 时 stdout 被忽略。

可挂载的时机，文档一共列了 12 个：SessionStart（会话开始，matcher 取 startup/resume/compact）、SessionEnd（结束，matcher 取 prompt_input_exit/other）、UserPromptSubmit（用户提交 Prompt 后、Agent 处理前）、PreToolUse（工具执行前）、PostToolUse（工具执行成功后）、PostToolUseFailure（工具执行失败后，额外带 error 与 is_interrupt）、Stop（主 Agent 完成响应、且无待执行工具调用时）、SubagentStart 与 SubagentStop（子 Agent 启动与完成，额外带 agent_id、agent_type）、PreCompact（上下文压缩前，matcher 取 manual/auto）、Notification（matcher 取 permission/result）、PermissionRequest（工具执行需要用户授权时）。

三、边界在哪：文档写了什么，更要看它没写什么

这一节是真正值钱的部分，因为上面那些字段照抄谁都会，坑都在下面。

改完配置要重启。 文档在”配置文件位置”下面挂了一条说明，逐字是：当前版本暂不支持热加载，修改配置文件后需要重启 QwenWork 才能生效。这条很容易吃亏——改了 JSON 发现 Hook 没触发时，除了怀疑配置写错，也要先按这句说明确认是不是没重启。

不要指望环境变量。 文档另有一条说明写明：QwenWork 目前不会向 Hook 脚本注入环境变量，所有数据通过 stdin JSON 传递；如需会话 ID、工作目录或工具信息，请从 stdin JSON 输入中解析。这意味着从别的工具那里抄来的、靠读环境变量拿上下文的脚本，直接搬过来是拿不到值的。

exit 2 不是到处都灵。 文档在通用输出那一节给 exit 2 加了限定词”仅对支持阻塞的事件生效”，但没有给出一份”哪些事件支持阻塞”的清单。我们能在各事件说明里逐字找到阻塞语义的只有三处：PreToolUse 写了”可以阻止工具执行”，Stop 写了”可以阻止 Agent 停止，让其继续工作”，SubagentStop 写的是”与 Stop 类似，可以阻止子 Agent 停止”。其余事件在 exit 2 时会怎样，官方文档没有说明这一点。

stdout 的精细控制字段查不到。 文档写”stdout JSON（仅 exit 0 时解析）可为部分事件提供精细控制，具体支持的字段见各事件说明”，但翻遍下面十几个事件的小节，我们没有找到任何一处列出 stdout JSON 的字段名。这两处放在一起是不一致的，我们只陈述差异：想用 stdout 做精细控制的话，字段名在这一页里核不出来。

超时之后算什么，没写。 timeout 默认 60 秒是白纸黑字，但脚本超过 60 秒被中断之后，算成功、算非阻塞错误还是算阻塞，官方文档没有说明这一点。

Windows 侧这一页是空白。 页面里的示例脚本全是 shell：#!/bin/bash 开头，用 jq 解析 JSON，用 grep 判断，桌面通知那个示例文档自己标了”（macOS）“并调用 osascript。帮助中心的”桌面端安装指引”下面确实有 macOS、Windows、HarmonyOS 三份安装指南，但 Hooks 这一页没有写明 command 字段在 Windows 上如何解析、~ 如何展开、是否需要另装 jq。这些都属于官方文档没有说明的部分，别照抄示例就当 Windows 上一定能跑。

脚本放哪儿，两处口径要对着看。 配置加载那张表只列了用户级一行；而”写文件后自动 Lint”那个场景示例里，脚本路径写的是 ${project}/.qwenwork/hooks/auto-lint.sh，配置里的 command 写的是相对路径 .qwenwork/hooks/auto-lint.sh。也就是说：脚本文件本身可以放在项目目录下，但”配置从哪些文件加载”这张表里，我们没有找到项目级 settings.json 那一行。相对路径按什么基准解析，文档也没有说明。

这是在你本机跑命令，说清楚比说安全重要。 Hook 的 command 是 shell 命令，事件一触发就以你自己的身份在本机执行。文档没有说明 Hook 脚本本身是否受任何白名单、沙箱或确认环节的限制。所以两件事要摆正：一是别把来路不明的脚本往 settings.json 里贴；二是即便配了 PreToolUse 拦截，那也是你自己写的那几行 grep 的能力边界，不是产品给的保证——那个拦 rm -rf 的示例只匹配字面量 rm -rf，换个写法它就不认。安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。

还有一条得记着：千问办公官网的品牌标识旁挂着 Beta 角标，页头与页脚各一处。上面这些事件名、字段名和默认值都可能随版本变动，隔一段时间回帮助中心对一遍不吃亏。

四、什么时候值得配，什么时候别碰

值得配的场合有三类。第一类是硬拦截：某个动作一旦发生就没法回头，比如碰生产目录、碰某个配置文件，用 PreToolUse 加 matcher 精确匹配工具名，exit 2 把话说死，比在提示词里嘱咐十遍可靠。第二类是收尾动作固定不变：写完文件跑 lint、跑格式化，用 PostToolUse 配 "Write | Edit" 这种 matcher，省得每次提醒模型。第三类是你不想守着屏幕：Notification 的 matcher 分 permission 和 result，前者是权限请求、后者是产出结果，想只在需要授权时才响一声，就只挂 permission。

不必开的场合更多。只用一两次的动作，直接让 Agent 做就行，为它写脚本还要重启一次，划不来。规则本身还在变的时候也别急着配——不支持热加载意味着每调一次都要重启，试错成本压在你身上。Stop 事件尤其要慎重：它的作用是阻止 Agent 停下来继续干活，而文档没有说明连续阻塞多少次之后会怎样，把判断条件写得太宽是给自己找麻烦。至于跨端使用，前面说过，帮助中心把这一页归在桌面端，网页端那一组里我们没有找到对应条目，所以别指望网页那边有同一套配置。

最后一个判断标准很朴素：如果这件事”漏做一次就出事”，交给 Hooks；如果这件事”漏做一次也就重来一遍”，交给提示词。

---

本文依据千问办公官方帮助中心（qwenwork.cn/docs）于 2026-08-17 的公开内容整理。 我们没有开通付费账号，也没有实际操作过该产品，因此不涉及界面外观、操作手感与生成质量的任何描述。 该产品官网标注为 Beta 阶段，功能、权益与套餐随版本变动，文中涉及价格与权益的表述均为复述官方文档原文， 请以官网最新说明为准。 安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。