OpenClaude Hook Chains 自愈 Agent 网格实战指南声明式规则、安全护栏与配置全解【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaudeHook Chains 是 OpenClaude 提供的一层基于事件的故障恢复层Self-Healing Agent Mesh MVP当工作流中的关键环节失败时运行时根据声明式规则评估事件并自动派发补救动作例如启动兜底 Agentspawn_fallback_agent、通知团队notify_team、预热远程容量warm_remote_capacity。读完本文你将掌握 Hook Chains 的启用流程、配置 Schema、三类动作的完整参数与模板变量、安全护栏的实现原理以及常见的故障排查方法。本文以仓库文档 docs/hook-chains.md 为核心骨架并结合实现源码 src/utils/hookChains.ts 与其触发链路 src/utils/hooks.ts 展开讲解所有结论均可回到仓库源码验证。一、Hook Chains 是什么事件驱动的自愈恢复层Hook Chains 解决的问题很具体OpenClaude 在执行任务、调用工具的过程中难免遇到工具调用失败、任务完成异常、超时或权限拒绝等故障。传统做法是人工介入重试Hook Chains 则提供了一条自动化的恢复路径——当匹配的hook 事件如PostToolUseFailure、TaskCompleted被派发时运行时加载一份确定性的 JSON 配置文件即hook-chains.json逐条评估配置中的声明式规则触发事件、结果匹配、条件约束对命中的规则按顺序执行一个或多个恢复动作。MVP 阶段的运行时触发接线trigger wiring在源码中体现为dispatchHookChainFromHookRuntime函数src/utils/hooks.ts它支持两种事件来源事件派发的 outcomePostToolUseFailure固定为failedTaskCompleted当完成类 hooks 未阻塞时派发success当完成类 hooks 返回阻塞错误或阻止继续时派发failed两种事件共享同一个入口dispatchHookChainFromHookRuntime内部再调用核心的dispatchHookChainsForEventsrc/utils/hookChains.ts完成加载配置 → 评估规则 → 派发动作的完整流程。二、默认关闭的灰度策略先验证、再启用Hook Chains 采用Disabled-By-Default的保守发布策略官方推荐在真实环境验证规则之前保持关闭顶层配置先设置为enabled: false在合适的环境中逐步启用动作派发受功能开关feature(HOOK_CHAINS)门控环境变量门控默认关闭除非显式设置CLAUDE_CODE_ENABLE_HOOK_CHAINS1。从源码看这个双重门控非常严格dispatchHookChainFromHookRuntime的第一步就是if (!feature(HOOK_CHAINS)) returnsrc/utils/hooks.ts即构建本身必须启用该特性而配置加载函数loadHookChainsConfig在开头就会检查isHookChainsEnabled()——当CLAUDE_CODE_ENABLE_HOOK_CHAINS未设置时直接返回禁用配置src/utils/hookChains.ts。小技巧即使不设环境变量enabled: false或空 ruleset 的配置也能让链路保持已配置但停用状态等规则就绪后再一键开启。这样既保证了既有工作流完全不受影响又能让你有充足时间调校防护窗口guard window与动作行为。三、配置文件路径与环境变量Hook Chains 的配置从一条确定性路径加载默认路径.openclaude/hook-chains.json相对原始工作目录解析覆盖路径通过环境变量指定# 用环境变量指定绝对或相对路径 CLAUDE_CODE_HOOK_CHAINS_CONFIG_PATH/abs/or/relative/path/to/hook-chains.json源码中getConfigPath会优先读取CLAUDE_CODE_HOOK_CHAINS_CONFIG_PATH否则拼接原始工作目录getOriginalCwd()与默认相对路径src/utils/hookChains.ts、src/utils/hookChains.ts。配置加载的关键实现事实对应文档Config changes not reflected一节按 mtime/size 记忆化缓存加载器使用ConfigCacheState记录path、mtimeMs、size、loadedAtMs做缓存判断只有当路径、修改时间、文件大小完全一致且缓存未超过 5 分钟CONFIG_CACHE_MAX_AGE_MS时才命中缓存src/utils/hookChains.ts强制重载从调用方传入forceReloadConfig: true对应dispatchHookChainsForEvent的forceReloadConfig参数可绕过缓存校验失败降级JSON 非法或 Schema 校验不通过时不会崩溃而是返回makeDisabledConfig()禁用配置并在结果中携带error信息src/utils/hookChains.ts。因此如果你的编辑器写入文件不完整或 mtime 未更新改动可能不生效——确保编辑器完整写盘。四、全局开关与运行时刻度Hook Chains 还有一层总开关与内存守卫状态# 全局启用默认未设置时关闭 CLAUDE_CODE_ENABLE_HOOK_CHAINS1 # 全局禁用 CLAUDE_CODE_ENABLE_HOOK_CHAINS0运行时刻度guard state全部保存在进程内内存中ruleCooldownUntil、dedupKeyUntil两个 Map并设置了上限防止内存无限增长规则冷却条目上限 5000MAX_RULE_COOLDOWN_ENTRIES去重条目上限 20000MAX_DEDUP_ENTRIES超过后按过期时间优先清理pruneGuardState/enforceGuardMapLimitsrc/utils/hookChains.ts。五、安全护栏Safety Guarantees实现原理Hook Chains 的运行时刻意保持保守文档列出 8 条安全保证这里结合源码逐条给出实现依据安全保证实现位置与说明深度守卫chainDepth maxChainDepth时阻止链式派发dispatchHookChainsForEvent中在评估规则前先比较runtime.chainDepth与config.maxChainDepth单条规则还支持rule.maxDepth逐规则上限src/utils/hookChains.ts。链深度实际取自queryTracking.depthsrc/utils/hooks.ts规则冷却每条规则只能在冷却期结束后重新触发命中规则后设置ruleCooldownUntil.set(rule.id, now cooldownMs)冷却期内所有动作以rule cooldown active for ...ms跳过src/utils/hookChains.ts去重窗口相同的事件/动作组合在窗口内被抑制去重键由ruleId actionId 事件指纹 dedupScope经 SHA-1 稳定指纹生成且先标记再去重——派发前就写入dedupKeyUntil避免并发故障引发惊群式重复补救src/utils/hookChains.tsAbort 安全当前信号被中止时动作安全跳过三条动作执行函数executeSpawnFallbackAgentAction/executeNotifyTeamAction/executeWarmRemoteCapacityAction开头均检查runtime.signal?.aborted返回skipped/aborted策略感知的远程预热远程会话被策略拒绝时跳过executeWarmRemoteCapacityAction先检查isPolicyAllowed(allow_remote_sessions)不通过则跳过并注明Remote sessions are blocked by policysrc/utils/hookChains.tsBridge 未激活时安全空操作无活跃 bridge 句柄时warm_remote_capacity安全跳过无回调时动态导入getReplBridgeHandle无句柄则跳过并注明Bridge is not active; warm_remote_capacity is a safe no-opsrc/utils/hookChains.ts团队上下文缺失安全无团队上下文/团队文件时notify_team带结构化原因跳过resolveTeamName依次取action.teamName→runtime.teamName→ payload 中的team_name/teamName→getTeamName()仍无则No team context is available...随后readTeamFileAsync(teamName)失败则Team file not found for team ...src/utils/hookChains.ts兜底启动器安全启动权限/上下文不可用时spawn_fallback_agent带结构化原因失败无runtime.onSpawnFallbackAgent回调时返回No fallback agent launcher is registered in runtime contextsrc/utils/hookChains.ts此外warm_remote_capacity在 MVP 中还有一层保守设计即使 bridge 激活也只在满足远程会话前置条件、存在可选环境时才执行一次轻量的环境列表调用作为受控预暖路径createDefaultEnvironmentIfMissing: true时才允许创建默认云环境src/utils/hookChains.ts。六、配置 Schema 完整参考顶层对象{ version: 1, enabled: true, maxChainDepth: 2, defaultCooldownMs: 30000, defaultDedupWindowMs: 30000, rules: [] }字段类型必填说明version1否默认1当前仅支持字面量1zodz.literal(1)enabledboolean否本配置文件的总开关默认truemaxChainDepthinteger否全局深度守卫默认2最大10defaultCooldownMsinteger否规则默认冷却时间毫秒默认30000defaultDedupWindowMsinteger否动作默认去重窗口毫秒默认30000rulesHookChainRule[]否默认为[]可省略或置空。无规则时派发为空操作返回enabled: false注意空 ruleset 是合法的。它可以把 Hook Chains 保持为已配置但实质禁用的状态直到添加规则。源码中dispatchHookChainsForEvent对!config.enabled || config.rules.length 0直接短路返回src/utils/hookChains.ts。值得补充的源码约束zod Schema 定义于 src/utils/hookChains.tsmaxChainDepth合法范围1..10默认2所有毫秒类字段defaultCooldownMs、defaultDedupWindowMs、规则cooldownMs、dedupWindowMs、动作dedupWindowMs都必须是0..MAX_GUARD_WINDOW_MS的整数其中MAX_GUARD_WINDOW_MS 24 * 60 * 60 * 1000一天防止误配超长窗口配置文件支持两种形态直接是配置对象或包一层{ hookChains: { ... } }HookChainsConfigFileSchema为二者的联合加载时自动解包见 src/utils/hookChains.ts。规则对象HookChainRule{ id: task-failure-recovery, enabled: true, trigger: { event: TaskCompleted, outcome: failed }, condition: { toolNames: [Edit], taskStatuses: [failed], errorIncludes: [timeout, permission denied], eventFieldEquals: { meta.source: scheduler } }, cooldownMs: 60000, dedupWindowMs: 30000, maxDepth: 2, actions: [] }字段类型必填说明idstring是稳定标识用于遥测与守卫必须非空enabledboolean否单规则开关默认truetrigger.eventHookEvent是要匹配的事件名必须是HOOK_EVENTS枚举成员trigger.outcomesuccess\|failed\|timeout\|unknown否单结果匹配器trigger.outcomesOutcome[]否多结果匹配器outcome与outcomes只能二选一zodsuperRefine强制约束见 src/utils/hookChains.tsconditionobject否可选附加匹配约束cooldownMsinteger否覆盖该规则的全局冷却dedupWindowMsinteger否覆盖该规则的全局去重窗口maxDepthinteger否该规则专属深度上限0..10actionsHookChainAction[]是一个或多个按顺序执行的动作至少 1 个trigger.event合法值来自HOOK_EVENTS定义于 src/entrypoints/sdk/coreSchemas.ts包括PostToolUseFailure、TaskCompleted、PostToolUse、PreToolUse、SessionStart、SessionEnd、SubagentStart、PermissionDenied等但 MVP 运行时的真实接线只派发PostToolUseFailure与TaskCompleted两类事件见 src/utils/hooks.ts 的类型签名配置其他事件目前不会在运行时触发这一点需要留意。条件字段Condition字段类型说明toolNamesstring[]匹配事件载荷中的tool_name/toolNametaskStatusesstring[]匹配task_status/taskStatus/statuserrorIncludesstring[]对error/reason/message做大小写不敏感的子串匹配eventFieldEqualsRecordstring, string\|number\|boolean对载荷做点路径dot-path等值匹配例如meta.source: scheduler条件求值实现于evaluateConditionsrc/utils/hookChains.ts字段读取遵循多键别名顺序如tool_name→toolNameeventFieldEquals通过getValueByPath逐段拆分点路径取值支持嵌套结构如meta.source而无需引入第二种自定义表达式语言。七、三类动作详解所有动作共享基础字段type判别字段、id可选、enabled默认 true、dedupWindowMs可选覆盖全局/规则级去重窗口。zod 用discriminatedUnion(type, ...)严格校验动作类型src/utils/hookChains.ts。1)spawn_fallback_agent兜底 Agent 重试{ type: spawn_fallback_agent, id: fallback-1, enabled: true, dedupWindowMs: 30000, description: Fallback recovery for failed task, promptTemplate: Recover task ${TASK_SUBJECT}. Event${EVENT_NAME}, outcome${OUTCOME}, error${ERROR}. Payload${PAYLOAD_JSON}, agentType: general-purpose, model: sonnet }字段类型说明descriptionstring兜底 Agent 的任务描述缺省时自动生成Fallback recovery: event (outcome)promptTemplatestring兜底提示词模板缺省时使用内置默认提示见下agentTypestring子代理类型如general-purposemodelstring模型名如sonnet底层实现executeSpawnFallbackAgentAction构造SpawnFallbackAgentRequest含runInBackground: true即后台运行调用运行时注入的onSpawnFallbackAgent回调在 hooks 运行时中该回调最终通过AgentTool.call以run_in_background: true启动子代理src/utils/hooks.ts。promptTemplate缺省时代码会组装一段内置提示词包含事件、结果、规则 ID、任务主题/描述、失败详情并以进行最小化、安全恢复尝试并汇报变更、失败项与下一步建议作为目标src/utils/hookChains.ts。2)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} }字段类型说明teamNamestring目标团队缺省时按 动作 → 运行时 → payload → 全局团队名 的顺序解析recipientsstring[]收件人列表包含*表示除发送者外的全部团队成员未命中团队成员的名字会被过滤summarystring通知摘要模板缺省为Hook chain rule.id triggered (event/outcome)messageTemplatestring通知正文模板缺省时自动生成结构化正文底层实现executeNotifyTeamAction先解析团队名并读取团队文件readTeamFileAsync再计算收件人排除发送者自己优先调用runtime.onNotifyTeam回调无回调时退化为直接向每个收件人写入邮箱消息writeToMailboxsrc/utils/hookChains.ts。无团队上下文/团队文件/合格收件人时都会带结构化原因跳过。3)warm_remote_capacity远程容量预热{ type: warm_remote_capacity, id: warm-bridge, enabled: true, dedupWindowMs: 60000, createDefaultEnvironmentIfMissing: false }字段类型说明createDefaultEnvironmentIfMissingboolean缺省环境时是否允许创建默认云环境默认false底层实现src/utils/hookChains.ts遵循一套保守的检查链Abort 检查策略检查isPolicyAllowed(allow_remote_sessions)有onWarmRemoteCapacity回调则交给回调否则检查 REPL bridge 是否激活getReplBridgeHandle未激活则安全跳过校验远程会话前置条件checkBackgroundRemoteSessionEligibility获取环境选择信息getEnvironmentSelectionInfo缺失且允许时才创建默认云环境最后执行一次轻量的环境列表调用fetchEnvironments作为受控预暖路径。八、完整示例配置示例 1失败任务通过兜底 Agent 重试{ version: 1, enabled: true, maxChainDepth: 2, defaultCooldownMs: 30000, defaultDedupWindowMs: 30000, rules: [ { id: retry-task-via-fallback, trigger: { event: TaskCompleted, outcome: failed }, cooldownMs: 60000, actions: [ { type: spawn_fallback_agent, id: spawn-retry-agent, description: Retry failed task with fallback agent, promptTemplate: A task failed. Recover it safely.\nTask${TASK_SUBJECT}\nDescription${TASK_DESCRIPTION}\nError${ERROR}\nPayload${PAYLOAD_JSON}, agentType: general-purpose, model: sonnet } ] } ] }适用场景任务完成但结果为失败时在后台启动一个通用兜底 Agent携带失败任务的主题、描述、错误与完整载荷 JSON 去安全恢复。规则级cooldownMs: 60000会覆盖全局默认的 30 秒冷却避免短时间内反复触发。示例 2仅通知工具失败告警{ version: 1, enabled: true, maxChainDepth: 2, defaultCooldownMs: 30000, defaultDedupWindowMs: 30000, rules: [ { id: notify-on-tool-failure, trigger: { event: PostToolUseFailure, outcome: failed }, condition: { toolNames: [Edit, Write, Bash] }, actions: [ { type: notify_team, id: notify-team-failure, recipients: [*], summary: Tool failure detected, messageTemplate: Tool failure detected.\nEvent${EVENT_NAME} outcome${OUTCOME}\nError${ERROR}\nPayload${PAYLOAD_JSON} } ] } ] }适用场景Edit、Write、Bash任一工具调用失败时向团队全员发送告警。注意condition.toolNames匹配的是事件载荷中的tool_name/toolName字段需要与真实派发载荷中的工具名保持一致工具执行上下文中通过hookChainsCanUseTool注入的能力见 src/services/tools/toolExecution.ts 附近。示例 3兜底 通知 远程预热组合{ version: 1, enabled: true, maxChainDepth: 2, defaultCooldownMs: 45000, defaultDedupWindowMs: 30000, rules: [ { id: full-recovery-chain, trigger: { event: TaskCompleted, outcomes: [failed, timeout] }, condition: { errorIncludes: [timeout, capacity, connection] }, cooldownMs: 90000, actions: [ { type: spawn_fallback_agent, id: fallback-agent, description: Recover failed task execution, promptTemplate: Recover failed task and produce a concise fix summary.\nTask${TASK_SUBJECT}\nError${ERROR}\nPayload${PAYLOAD_JSON} }, { type: notify_team, id: notify-team, recipients: [*], summary: Recovery chain triggered, messageTemplate: Recovery chain ${RULE_ID} fired.\nOutcome${OUTCOME}\nTask${TASK_SUBJECT}\nError${ERROR} }, { type: warm_remote_capacity, id: warm-capacity, createDefaultEnvironmentIfMissing: false } ] } ] }适用场景任务以failed或timeout结束且错误信息命中timeout/capacity/connection时依次执行启动兜底 Agent → 通知团队 → 预热远程容量。三个动作在同一规则内按数组顺序执行全局defaultCooldownMs: 45000配合规则级cooldownMs: 90000将整条恢复链的触发频率压到 90 秒一次。这是三种动作组合使用的完整范例也是文档Combined Fallback Notify Bridge Warm的完整继承。九、模板变量Template VariablespromptTemplate、summary、messageTemplate均支持以下占位符模板解析实现于resolveTemplate支持${NAME}与$NAME两种写法见 src/utils/hookChains.ts占位符含义数据来源payload 字段别名${EVENT_NAME}触发事件名event.eventName${OUTCOME}事件结果event.outcome${RULE_ID}命中规则 IDrule.id${TASK_SUBJECT}任务主题task_subject/taskSubject${TASK_DESCRIPTION}任务描述task_description/taskDescription${TASK_ID}任务 IDtask_id/taskId${ERROR}错误信息error/reason${PAYLOAD_JSON}完整事件载荷的稳定 JSON 序列化stableFingerprint(payload)关于${PAYLOAD_JSON}的实现细节它使用stableFingerprint对对象键排序后的稳定序列化含循环引用保护见 src/utils/hookChains.ts生成保证同一载荷序列化结果稳定、可复现也便于日志比对。未识别的占位符会被替换为空字符串因此模板中不要拼写错误。十、遥测与诊断每次派发都会产生结构化遥测便于观测自愈链路的运转情况chain_rule_matched规则命中记录rule_id、hook_event_name、outcome、chain_depthchain_action_executed/chain_action_skipped/chain_action_failed动作的执行、跳过、失败结果skip/fail 事件还会附上原因分类categorizeReasonaborted/cooldown/dedup/policy/context_missing/precondition/disabled/other见 src/utils/hookChains.ts。这些事件同时写入 analytics 与 OTelOpenTelemetry通道emitHookChainRuleMatched等四个函数见 src/utils/hookChains.ts并输出一条无 PII 的诊断日志hook_chains_dispatch含事件名、结果、命中规则数与动作结果数。十一、故障排查Troubleshooting规则从不触发Rule never triggers核对trigger.event与trigger.outcome/trigger.outcomes是否与真实派发的事件数据完全一致。注意 MVP 运行时只接线PostToolUseFailure与TaskCompleted两个事件检查condition过滤器尤其是toolNames与eventFieldEquals的点路径键eventFieldEquals是严格等值比较字段路径或值不一致即不匹配确认配置文件是合法 JSON 且通过 Schema 校验可用任意 JSON 校验器验证运行时校验失败会返回禁用配置并在结果中携带error。动作显示为跳过Actions show as skipped常见跳过原因均可从源码找到对应分支action disabled—— 动作enabled: falsesrc/utils/hookChains.tsrule cooldown active ...—— 规则处于冷却期dedup window active ...—— 动作处于去重窗口max chain depth reached ...—— 达到全局maxChainDepth或规则maxDepthNo team context is available .../Team file not found ...——notify_team缺少团队上下文或团队文件Remote sessions are blocked by policy——warm_remote_capacity被allow_remote_sessions策略拦截Bridge is not active; warm_remote_capacity is a safe no-op—— bridge 未激活时的安全空操作No fallback agent launcher is registered in runtime context—— 运行时未注册兜底 Agent 启动器。配置修改不生效Config changes not reflected加载器按文件 mtime/size 做记忆化缓存并附加 5 分钟最大缓存时间确保编辑器完整写盘并更新 mtime必要时从调用方强制重载forceReloadConfig: true。既有工作流意外改变Existing workflows changed unexpectedly顶层设置enabled: false或全局禁用CLAUDE_CODE_ENABLE_HOOK_CHAINS0一条规则一条规则地验证通过后再逐步重新启用。十二、从源码到测试验证链路可靠性的证据Hook Chains 的规则求值、守卫逻辑与跳过场景都有对应的单元测试与集成测试可作为验证行为的权威参考src/utils/hookChains.test.ts覆盖 Schema 校验hookChains schema validation、规则求值evaluateHookChainRules、派发守卫逻辑dispatchHookChainsForEvent guard logic含深度、冷却、去重、动作跳过场景action dispatch skip scenarios四大测试组src/utils/hookChains.integration.test.ts集成级验证同时印证了CLAUDE_CODE_ENABLE_HOOK_CHAINS与CLAUDE_CODE_HOOK_CHAINS_CONFIG_PATH两个环境变量在真实加载流程中的作用。这两个测试文件与实现 src/utils/hookChains.ts、触发接线 src/utils/hooks.ts、事件枚举 src/entrypoints/sdk/coreSchemas.ts 共同构成了 Hook Chains 从声明式配置到运行时自愈的完整闭环。建议在启用前先在测试环境跑一遍上述测试确认你对规则语义的理解与实现一致。【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考