如何配置 OpenClaude 的 Hook Chains 在工具调用失败时自动触发补救动作【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude当 OpenClaude 会话中的工具调用失败时运行时会触发PostToolUseFailure钩子事件Hook Chains 就是为这类事件提供声明式恢复层的功能。你在一个 JSON 配置文件中声明规则触发事件、结果、匹配条件运行时在事件发生时评估规则并按顺序执行补救动作spawn_fallback_agent、notify_team、warm_remote_capacity。本文完成一条具体路径启用开关、写入配置、为工具调用失败配置一条自动补救规则并给出判断规则是否生效的方法。适用前提当前构建中feature(HOOK_CHAINS)已启用且设置了CLAUDE_CODE_ENABLE_HOOK_CHAINS1环境变量默认关闭。准备条件两层开关与灰度建议Hook Chains 受两道门禁控制缺一不可构建门禁feature(HOOK_CHAINS)必须在该构建中启用环境变量CLAUDE_CODE_ENABLE_HOOK_CHAINS0|1未设置时默认禁用。官方灰度建议来自 docs/hook-chains.md先把配置文件顶层写成enabled: false在环境中验证规则后再按环境启用。这样在调参期间不会影响现有工作流。创建配置文件并写入失败补救规则配置文件默认路径为.openclaude/hook-chains.json如需自定义位置用环境变量覆盖CLAUDE_CODE_HOOK_CHAINS_CONFIG_PATH/abs/or/relative/path/to/hook-chains.json顶层结构如下其中version固定为1省略时默认1maxChainDepth默认2、上限10defaultCooldownMs与defaultDedupWindowMs默认均为30000毫秒{ version: 1, enabled: true, maxChainDepth: 2, defaultCooldownMs: 30000, defaultDedupWindowMs: 30000, rules: [] }注意空rules是合法的相当于已配置但实际不触发dispatch 为 no-op。规则对象HookChainRule的关键字段字段必填说明id是规则的稳定标识用于遥测与守卫trigger.event是事件名工具调用失败场景为PostToolUseFailuretrigger.outcome/trigger.outcomes否结果匹配取success、failed、timeout、unknown之一两者只能用一个condition否附加匹配条件见下表cooldownMs/dedupWindowMs/maxDepth否覆盖全局冷却、去重窗口与深度上限actions是至少一个动作按声明顺序执行condition支持四种过滤字段匹配对象toolNames事件载荷中的tool_name/toolNametaskStatusestask_status/taskStatus/statuserrorIncludes对error/reason/message做大小写不敏感的子串匹配eventFieldEquals按点路径对载荷字段做相等匹配如meta.source: scheduler主路径配置工具调用失败后自动拉起一个补救 Agent。下面的配置按文档的 Schema 与示例组合而成toolNames与cooldownMs取值来自文档示例可按实际工具集替换toolNames数组{ version: 1, enabled: true, maxChainDepth: 2, defaultCooldownMs: 30000, defaultDedupWindowMs: 30000, rules: [ { id: tool-failure-remediation, trigger: { event: PostToolUseFailure, outcome: failed }, condition: { toolNames: [Edit, Write, Bash] }, cooldownMs: 60000, actions: [ { type: spawn_fallback_agent, id: spawn-retry-agent, description: Remediate failed tool call, promptTemplate: A tool call failed. Recover it safely.\nEvent${EVENT_NAME} outcome${OUTCOME}\nError${ERROR}\nPayload${PAYLOAD_JSON}, agentType: general-purpose, model: sonnet } ] } ] }promptTemplate、summary、messageTemplate中的${...}是运行时填充的模板变量不是需要读者手工替换的占位符。运行时支持的变量共 8 个${EVENT_NAME}、${OUTCOME}、${RULE_ID}、${TASK_SUBJECT}、${TASK_DESCRIPTION}、${TASK_ID}、${ERROR}、${PAYLOAD_JSON}。按灰度建议的实际操作顺序是先把顶层enabled写为false并验证 JSON 与 Schema再改为true启用。可选分支通知与容量预热动作文档给出的三种动作都可以作为actions数组的元素一条规则可声明多个动作并按顺序执行。notify_team仅通知文档示例{ type: notify_team, id: notify-ops, enabled: true, dedupWindowMs: 30000, teamName: mesh-team, recipients: [*], summary: Hook chain ${RULE_ID} fired, messageTemplate: Event${EVENT_NAME} outcome${OUTCOME}\nTask${TASK_ID}\nError${ERROR}\nPayload${PAYLOAD_JSON} }warm_remote_capacity预热远端容量文档示例{ type: warm_remote_capacity, id: warm-bridge, enabled: true, dedupWindowMs: 60000, createDefaultEnvironmentIfMissing: false }两种动作都有明确的安全跳过行为notify_team在无团队上下文或团队文件时以结构化原因跳过warm_remote_capacity在远端会话被策略拒绝、或没有活跃的 bridge 句柄时安全跳过no-op。spawn_fallback_agent在缺少启动权限或上下文时会以结构化原因失败而不是静默。文档的完整示例 3 展示了三个动作组合成一条规则但它触发的目标是TaskCompleted事件且outcomes为[failed, timeout]属于另一个事件入口与本文的工具调用失败场景不在同一条链路上仅作参考。验证规则是否生效触发条件来自文档的运行时接线说明PostToolUseFailure钩子会以 outcomefailed向 Hook Chains 分派事件代码路径见 toolExecution.ts 中工具出错分支里的runPostToolUseFailureHooks调用。规则是否命中、动作是否执行按文档的 Troubleshooting 一节对照判断规则从不触发时检查trigger.event与trigger.outcome/trigger.outcomes是否和实际分派的事件数据完全一致condition过滤是否过严尤其是toolNames和eventFieldEquals的点路径键配置文件是否为合法 JSON 且通过 Schema 校验。动作显示为跳过时对照文档列出的常见跳过原因action disabledrule cooldown active ...dedup window active ...max chain depth reached ...No team context is available ...Team file not found ...Remote sessions are blocked by policyBridge is not active; warm_remote_capacity is a safe no-opNo fallback agent launcher is registered in runtime context配置改动不生效时加载器按文件 mtime/size 做记忆化确认编辑器完整写入文件并更新了 mtime必要时在调用侧用forceReloadConfig: true强制重载。另从源码 src/utils/hookChains.ts 可见Schema 校验失败时运行时会输出[hook-chains] Config validation error at path: error调试日志每次分派还会记录一条hook_chains_dispatch诊断事件包含event_name、outcome、matched_rules、action_results可用于核对匹配到的规则数与动作结果。限制与回滚守卫窗口是内置的保守行为chainDepth maxChainDepth时分派被拦截每条规则冷却期内不会再次触发相同事件/动作组合在去重窗口内被抑制当前 signal 已中止时动作安全跳过。如果启用后现有工作流出现意外变化回滚方式有二把顶层改为enabled: false或全局设置CLAUDE_CODE_ENABLE_HOOK_CHAINS0。文档给出的下一步是逐条验证规则一次只启用一条确认行为符合预期后再逐步扩大启用范围。【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何配置 OpenClaude 的 Hook Chains 在工具调用失败时自动触发补救动作？
如何配置 OpenClaude 的 Hook Chains 在工具调用失败时自动触发补救动作【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude当 OpenClaude 会话中的工具调用失败时运行时会触发PostToolUseFailure钩子事件Hook Chains 就是为这类事件提供声明式恢复层的功能。你在一个 JSON 配置文件中声明规则触发事件、结果、匹配条件运行时在事件发生时评估规则并按顺序执行补救动作spawn_fallback_agent、notify_team、warm_remote_capacity。本文完成一条具体路径启用开关、写入配置、为工具调用失败配置一条自动补救规则并给出判断规则是否生效的方法。适用前提当前构建中feature(HOOK_CHAINS)已启用且设置了CLAUDE_CODE_ENABLE_HOOK_CHAINS1环境变量默认关闭。准备条件两层开关与灰度建议Hook Chains 受两道门禁控制缺一不可构建门禁feature(HOOK_CHAINS)必须在该构建中启用环境变量CLAUDE_CODE_ENABLE_HOOK_CHAINS0|1未设置时默认禁用。官方灰度建议来自 docs/hook-chains.md先把配置文件顶层写成enabled: false在环境中验证规则后再按环境启用。这样在调参期间不会影响现有工作流。创建配置文件并写入失败补救规则配置文件默认路径为.openclaude/hook-chains.json如需自定义位置用环境变量覆盖CLAUDE_CODE_HOOK_CHAINS_CONFIG_PATH/abs/or/relative/path/to/hook-chains.json顶层结构如下其中version固定为1省略时默认1maxChainDepth默认2、上限10defaultCooldownMs与defaultDedupWindowMs默认均为30000毫秒{ version: 1, enabled: true, maxChainDepth: 2, defaultCooldownMs: 30000, defaultDedupWindowMs: 30000, rules: [] }注意空rules是合法的相当于已配置但实际不触发dispatch 为 no-op。规则对象HookChainRule的关键字段字段必填说明id是规则的稳定标识用于遥测与守卫trigger.event是事件名工具调用失败场景为PostToolUseFailuretrigger.outcome/trigger.outcomes否结果匹配取success、failed、timeout、unknown之一两者只能用一个condition否附加匹配条件见下表cooldownMs/dedupWindowMs/maxDepth否覆盖全局冷却、去重窗口与深度上限actions是至少一个动作按声明顺序执行condition支持四种过滤字段匹配对象toolNames事件载荷中的tool_name/toolNametaskStatusestask_status/taskStatus/statuserrorIncludes对error/reason/message做大小写不敏感的子串匹配eventFieldEquals按点路径对载荷字段做相等匹配如meta.source: scheduler主路径配置工具调用失败后自动拉起一个补救 Agent。下面的配置按文档的 Schema 与示例组合而成toolNames与cooldownMs取值来自文档示例可按实际工具集替换toolNames数组{ version: 1, enabled: true, maxChainDepth: 2, defaultCooldownMs: 30000, defaultDedupWindowMs: 30000, rules: [ { id: tool-failure-remediation, trigger: { event: PostToolUseFailure, outcome: failed }, condition: { toolNames: [Edit, Write, Bash] }, cooldownMs: 60000, actions: [ { type: spawn_fallback_agent, id: spawn-retry-agent, description: Remediate failed tool call, promptTemplate: A tool call failed. Recover it safely.\nEvent${EVENT_NAME} outcome${OUTCOME}\nError${ERROR}\nPayload${PAYLOAD_JSON}, agentType: general-purpose, model: sonnet } ] } ] }promptTemplate、summary、messageTemplate中的${...}是运行时填充的模板变量不是需要读者手工替换的占位符。运行时支持的变量共 8 个${EVENT_NAME}、${OUTCOME}、${RULE_ID}、${TASK_SUBJECT}、${TASK_DESCRIPTION}、${TASK_ID}、${ERROR}、${PAYLOAD_JSON}。按灰度建议的实际操作顺序是先把顶层enabled写为false并验证 JSON 与 Schema再改为true启用。可选分支通知与容量预热动作文档给出的三种动作都可以作为actions数组的元素一条规则可声明多个动作并按顺序执行。notify_team仅通知文档示例{ type: notify_team, id: notify-ops, enabled: true, dedupWindowMs: 30000, teamName: mesh-team, recipients: [*], summary: Hook chain ${RULE_ID} fired, messageTemplate: Event${EVENT_NAME} outcome${OUTCOME}\nTask${TASK_ID}\nError${ERROR}\nPayload${PAYLOAD_JSON} }warm_remote_capacity预热远端容量文档示例{ type: warm_remote_capacity, id: warm-bridge, enabled: true, dedupWindowMs: 60000, createDefaultEnvironmentIfMissing: false }两种动作都有明确的安全跳过行为notify_team在无团队上下文或团队文件时以结构化原因跳过warm_remote_capacity在远端会话被策略拒绝、或没有活跃的 bridge 句柄时安全跳过no-op。spawn_fallback_agent在缺少启动权限或上下文时会以结构化原因失败而不是静默。文档的完整示例 3 展示了三个动作组合成一条规则但它触发的目标是TaskCompleted事件且outcomes为[failed, timeout]属于另一个事件入口与本文的工具调用失败场景不在同一条链路上仅作参考。验证规则是否生效触发条件来自文档的运行时接线说明PostToolUseFailure钩子会以 outcomefailed向 Hook Chains 分派事件代码路径见 toolExecution.ts 中工具出错分支里的runPostToolUseFailureHooks调用。规则是否命中、动作是否执行按文档的 Troubleshooting 一节对照判断规则从不触发时检查trigger.event与trigger.outcome/trigger.outcomes是否和实际分派的事件数据完全一致condition过滤是否过严尤其是toolNames和eventFieldEquals的点路径键配置文件是否为合法 JSON 且通过 Schema 校验。动作显示为跳过时对照文档列出的常见跳过原因action disabledrule cooldown active ...dedup window active ...max chain depth reached ...No team context is available ...Team file not found ...Remote sessions are blocked by policyBridge is not active; warm_remote_capacity is a safe no-opNo fallback agent launcher is registered in runtime context配置改动不生效时加载器按文件 mtime/size 做记忆化确认编辑器完整写入文件并更新了 mtime必要时在调用侧用forceReloadConfig: true强制重载。另从源码 src/utils/hookChains.ts 可见Schema 校验失败时运行时会输出[hook-chains] Config validation error at path: error调试日志每次分派还会记录一条hook_chains_dispatch诊断事件包含event_name、outcome、matched_rules、action_results可用于核对匹配到的规则数与动作结果。限制与回滚守卫窗口是内置的保守行为chainDepth maxChainDepth时分派被拦截每条规则冷却期内不会再次触发相同事件/动作组合在去重窗口内被抑制当前 signal 已中止时动作安全跳过。如果启用后现有工作流出现意外变化回滚方式有二把顶层改为enabled: false或全局设置CLAUDE_CODE_ENABLE_HOOK_CHAINS0。文档给出的下一步是逐条验证规则一次只启用一条确认行为符合预期后再逐步扩大启用范围。【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
