第三方钩子

Cherri Code 支持加载第三方工具的钩子，并兼容其他 AI 编程助手现有的钩子配置。

Claude Code 钩子

Cherri Code 可以加载并执行为 Claude Code 配置的钩子，让您可以在两个工具中使用相同的钩子脚本。

要求

只有在 Cherri Code 设置 → 代理 → 第三方导入 中启用 包含第三方插件、技能及其他配置 后，Claude Code 钩子 才会加载。该设置默认开启。

配置位置

Claude Code 钩子会从以下位置加载 (按优先级排序) ：

优先级顺序

当钩子配置在多个位置时，将按以下优先级顺序合并 (从高到低) ：

1. 企业版 钩子 (托管部署)
2. 团队 钩子 (在仪表盘中配置)
3. 项目 钩子 (.cursor/hooks.json)
4. 用户 钩子 (~/.cursor/hooks.json)
5. Claude 项目本地配置 (.claude/settings.local.json)
6. Claude 项目配置 (.claude/settings.json)
7. Claude 用户配置 (~/.claude/settings.json)

来自所有来源的匹配钩子都会运行。响应发生冲突时，合并时以优先级较高的来源为准。

企业版托管的 钩子 和仪表盘分发功能需要企业版方案。联系销售了解更多。

Claude Code 钩子格式

Claude Code 钩子使用相似但略有不同的格式。Cherri Code 会自动将 Claude 钩子名称映射为 Cherri Code 中对应的名称。

Claude Code settings.json 示例：

{  "hooks": {    "PreToolUse": [      {        "matcher": "Shell",        "hooks": [          {            "type": "command",            "command": "./hooks/validate-shell.sh"          }        ]      }    ],    "PostToolUse": [      {        "matcher": ".*",        "hooks": [          {            "type": "command",            "command": "./hooks/audit.sh"          }        ]      }    ]  }}

响应格式兼容性

Cherri Code 同时支持 Claude Code 的嵌套 hookSpecificOutput 响应格式和较早的扁平响应格式。为 Claude Code 编写的钩子脚本无论采用哪种格式，均可在 Cherri Code 中正常运行。

PreToolUse 响应格式

嵌套格式 (Claude Code 风格) ：

{  "hookSpecificOutput": {    "hookEventName": "PreToolUse",    "permissionDecision": "deny",    "permissionDecisionReason": "Blocked by policy",    "updatedInput": { "command": "npm ci" }  }}

扁平格式 (Cherri Code 原生风格) ：

{  "permission": "deny",  "user_message": "Blocked by policy",  "updated_input": { "command": "npm ci" }}

两种格式等效。嵌套的 permissionDecision 对应 permission，permissionDecisionReason 对应 user_message，updatedInput 对应 updated_input。

Stop / SubagentStop 响应格式

嵌套格式 (Claude Code 风格) ：

{  "hookSpecificOutput": {    "decision": "block",    "reason": "Tasks incomplete, continue working"  }}

扁平格式 (Claude Code 旧版风格) ：

{  "decision": "block",  "reason": "Tasks incomplete, continue working"}

Cherri Code 原生格式：

{  "followup_message": "Tasks incomplete, continue working"}

对于 Stop 和 SubagentStop 钩子，decision 为带有 reason 的 "block" 时，会被视为自动跟进，等同于在 Cherri Code 原生格式中提供 followup_message。

钩子步骤映射

Claude Code 钩子名称会自动映射为对应的 Cherri Code 钩子名称：

退出码行为

Cherri Code 和 Claude Code 钩子均支持通过退出码 2 阻止操作，从而确保在不同工具间共享钩子时行为一致：

#!/bin/bash# 阻止危险命令if [[ "$COMMAND" == *"rm -rf"* ]]; then  echo '{"permission": "deny", "user_message": "Destructive command blocked"}'  exit 2fiecho '{"permission": "allow"}'exit 0

• 退出码 0：钩子执行成功，使用 JSON 输出
• 退出码 2：阻止该操作 (等同于 permission: "deny")
• 其他退出码：钩子执行失败，操作仍会继续执行 (失败时放行)

从 Claude Code 迁移

如果您已有 Claude Code 钩子，可以：

1. 继续使用 Claude Code 配置文件：保持 包含第三方插件、技能及其他配置 处于启用状态，现有 .claude/settings.json 中的钩子会自动生效
2. 迁移到 Cherri Code 格式：按照 Cherri Code 格式将钩子复制到 .cursor/hooks.json，即可获得完整功能支持

对应的 Cherri Code 格式：

{  "version": 1,  "hooks": {    "preToolUse": [      {        "command": "./hooks/validate-shell.sh",        "matcher": "Shell"      }    ],    "postToolUse": [      {        "command": "./hooks/audit.sh"      }    ]  }}

支持的功能

在 Cherri Code 中使用 Claude Code 钩子时，支持以下功能：

其他支持的功能：

工具名称映射

Claude Code 工具名称与 Cherri Code 工具名称的映射如下：

限制

以下功能仅在使用 Cherri Code 原生格式时可用：

• subagentStart 钩子 (Claude Code 仅支持 SubagentStop)
• 循环限制配置 (loop_limit)
• 通过仪表盘分发团队/企业版钩子

疑难排查

Claude Code 钩子未加载

1. 确认已在 Cherri Code 设置 → 代理 → 第三方导入中启用“包含第三方插件、技能及其他配置”
2. 检查 .claude/settings.json 文件是否为有效的 JSON
3. Cherri Code 会监视配置文件并自动重新加载。如果钩子仍未加载，请重启 Cherri Code。

钩子正在运行但未阻止操作

1. 确保钩子脚本以退出码 2 退出，以阻止操作
2. 检查 JSON 输出格式是否符合预期的 schema
3. 在 Cherri Code 中查看 Hooks 输出通道，获取错误详情

Cherri Code 与 Claude Code 的行为差异

由于执行环境不同，二者的行为可能存在差异。请在两个工具中测试钩子，以确保兼容性。