适用场景Claude Code 升级后启动弹 Settings Errorhooks 配置校验失败环境Windows / macOS / LinuxClaude Code 2025–2026 新版 hooks 格式一、问题现象启动 Claude Code 时弹出如下错误Settings ErrorC:\Users\xxx\.claude\settings.json└ hooks├ Notification│ └ 0│ └ hooks: Expected array, but received undefined├ PermissionRequest│ └ 0│ └ hooks: Expected array, but received undefined├ PreToolUse│ └ 0│ └ hooks: Expected array, but received undefined├ Stop│ └ 0│ └ hooks: Expected array, but received undefined└ UserPromptSubmit└ 0└ hooks: Expected array, but received undefined弹窗通常提供三个选项Fix with Claude — 让 Claude 自动修复Exit and fix manually — 退出后手动改Continue without these settings — 跳过整个配置文件⚠️ 注意选第 3 项会跳过整个settings.json不只是 hooks还包括envAPI 配置、permissions等一般不建议。二、根因分析Claude Code 的 hooks 配置格式已升级从两层结构变为三层嵌套结构。❌ 旧格式已废弃会报错{hooks: {UserPromptSubmit: [{command: node /path/to/hook-relay.js --source claude-code}],PreToolUse: [{command: node /path/to/hook-relay.js --source claude-code}]}}问题事件数组里直接写{ command: ... }缺少中间的hooks数组校验器报Expected array, but received undefined。✅ 新格式官方要求{hooks: {PostToolUse: [{matcher: Edit|Write,hooks: [{type: command,command: echo Done}]}]}}三层结构事件名 (EventName)└── matcher 组 (数组)├── matcher: 匹配规则字符串└── hooks: 处理器数组└── { type, command, timeout, ... }层级字段说明第 1 层UserPromptSubmit/PreToolUse等生命周期事件名第 2 层matcherhooks匹配组决定何时触发第 3 层typecommand具体执行的 hook 处理器官方文档Claude Code Hooks Reference三、完整修复示例打开~/.claude/settings.jsonWindows 为C:\Users\你的用户名\.claude\settings.json将hooks段改为如下结构。3.1 通用 relay hook监控/转发类适用于 cursor-traffic-light、自定义状态 relay 等场景{env: {ANTHROPIC_BASE_URL: https://api.example.com/anthropic,ANTHROPIC_AUTH_TOKEN: your-token-here,ANTHROPIC_MODEL: your-model},permissions: {allow: [Bash(python -m pytest *)]},hooks: {UserPromptSubmit: [{matcher: ,hooks: [{type: command,command: node \D:/path/to/hook-relay.js\ --source claude-code}]}],PreToolUse: [{matcher: ,hooks: [{type: command,command: node \D:/path/to/hook-relay.js\ --source claude-code}]}],PermissionRequest: [{matcher: ,hooks: [{type: command,command: node \D:/path/to/hook-relay.js\ --source claude-code}]}],Notification: [{matcher: ,hooks: [{type: command,command: node \D:/path/to/hook-relay.js\ --source claude-code}]}],Stop: [{matcher: ,hooks: [{type: command,command: node \D:/path/to/hook-relay.js\ --source claude-code}]}]}}3.2 工具事件加 matcher 过滤若只想在特定工具调用时触发 hook{hooks: {PreToolUse: [{matcher: Bash|Edit|Write,hooks: [{type: command,command: node \D:/path/to/hook-relay.js\ --source claude-code,timeout: 30}]}],PostToolUse: [{matcher: Edit|Write,hooks: [{type: command,command: jq -r .tool_input.file_path | xargs npx prettier --write}]}]}}3.3 Windows 桌面通知 hook{hooks: {Notification: [{matcher: ,hooks: [{type: command,command: powershell -Command \[System.Reflection.Assembly]::LoadWithPartialName(System.Windows.Forms); [System.Windows.Forms.MessageBox]::Show(Claude Code 需要你的 attention)\}]}]}}macOS 可用osascript{type: command,command: osascript -e display notification \Claude Code needs your attention\ with title \Claude Code\}四、matcher 规则速查事件类型matcher 匹配对象示例值PreToolUse/PostToolUse/PermissionRequest工具名Bash、Edit|Write、mcp__.*UserPromptSubmit无需精确匹配或省略Notification通知类型、permission_prompt、idle_promptStop无需精确匹配SessionStart启动来源startup、resume、clearmatcher 语法或省略 → 匹配全部Bash→ 精确匹配 Bash 工具Edit|Write→ 管道符分隔的多工具匹配mcp__memory__.*→ JavaScript 正则五、Hook 处理器类型type说明典型用途command执行 shell 命令stdin 接收 JSON格式化、审计、relayprompt让 LLM 做 yes/no 判断轻量策略检查http调用 HTTP 端点远程日志/告警mcp_tool调用 MCP 工具与外部系统集成agent启动子 agent 验证实验性复杂校验command hook 约定从 stdin 读取事件 JSON通过 stdout 返回 JSON 决策如permission: allow/deny退出码0 成功2 阻断操作六、验证修复是否成功Step 1保存settings.json重启 Claude Code确认不再出现 Settings Error。Step 2在 Claude Code 内执行/hooks应能看到已加载的 hook 列表及来源User / Project / Plugin 等。Step 3触发一次用户输入或工具调用观察 hook 脚本是否正常执行如 relay 日志、通知弹窗等。七、常见踩坑1. 重装 hook 安装脚本写回旧格式部分第三方安装器如 cursor-traffic-light 的install-hooks.js对 Claude 仍生成旧格式// ❌ 旧写法const entry [{ command: cmd }];// ✅ 新写法const entry [{ hooks: [{ type: command, command: cmd }] }];重装 hooks 后若再次报错检查安装脚本是否已适配新 schema。2. JSON 语法错误最后一项后不要多余逗号Windows 路径建议用/或双反斜杠\\含空格的路径用双引号包裹3. 误选「Continue without these settings」会跳过整个配置文件API Key、权限白名单等一并失效。优先选手动修复或「Fix with Claude」。4. hook 脚本路径不存在Claude Code 会校验配置格式但不会检查command指向的文件是否存在。路径错误时 hook 静默失败需自行查看日志。八、配置文件层级Claude Code hooks 可写在多个位置优先级从高到低位置作用域是否可提交 Git~/.claude/settings.json用户全局否.claude/settings.json项目级是.claude/settings.local.json项目本地否通常 gitignorePluginhooks/hooks.json插件启用时是Managed policy settings企业策略管理员控制九、总结项目内容报错原因hooks 使用了旧的两层{ command }格式修复方法改为{ matcher, hooks: [{ type, command }] }三层结构最快修复弹窗选「Fix with Claude」或手动改~/.claude/settings.json验证方式重启后执行/hooks查看加载状态注意事项勿选「Continue without these settings」会丢失全部配置Hooks 是 Claude Code 实现确定性自动化格式化、审计、权限拦截、状态监控的核心机制。掌握新格式后可以稳定搭建自己的 Agent 工作流。参考资料Claude Code Hooks 官方文档Hooks 入门指南Claude Code Settings 配置说明标签Claude CodeHookssettings.jsonAI编程Agent自动化Windows开发配置修复