用途
update-config 技能用于修改 Claude Code 的配置,主要通过更新 settings.json 文件来实现。当用户需要调整设置、环境变量或 CLI 工具权限时可以使用该技能。
该技能明确指出:如果用户希望某个动作在特定事件发生时自动执行,需要配置钩子(hook),因为记忆/偏好无法触发自动化操作。例如「压缩前询问保留内容」需要 PreCompact 钩子,「写文件后运行 prettier」需要带 Write|Edit 匹配器的 PostToolUse 钩子,「运行 bash 命令时记录日志」需要带 Bash 匹配器的 PreToolUse 钩子,「代码变更后总是运行测试」需要 PostToolUse 钩子。
主要能力
- 修改 settings.json 中的权限(allow/deny/ask 数组、defaultMode、additionalDirectories)
- 配置环境变量(env 对象)
- 设置模型与代理(model、agent、alwaysThinkingEnabled)
- 配置提交与 PR 归属信息(attribution)
- 管理 MCP 服务器(enableAllProjectMcpServers、enabledMcpjsonServers、disabledMcpjsonServers)
- 管理插件(enabledPlugins)
- 配置钩子(hooks),支持 command、prompt、agent 三种类型
- 其他设置:language、cleanupPeriodDays、respectGitignore、spinnerTipsEnabled、spinnerVerbs、spinnerTipsOverride、syntaxHighlightingDisabled 等
使用方式
技能强调两条关键原则:
- 写入前先读取:始终先读取现有 settings 文件,将新设置与现有设置合并,绝不整体替换文件。
- 歧义时使用 AskUserQuestion:当请求不明确时,澄清要修改哪个设置文件(user/project/local)、是追加到现有数组还是替换、以及多个选项时的具体取值。
对于简单设置(theme、editorMode、verbose、model、language、alwaysThinkingEnabled、permissions.defaultMode),建议使用 /config 斜杠命令;对于钩子、复杂权限规则、环境变量、MCP 服务器配置、插件配置,则直接编辑 settings.json。
设置文件位置与作用域:
| 文件 | 作用域 | Git | 用途 |
|---|---|---|---|
| ~/.claude/settings.json | 全局 | 不适用 | 所有项目的个人偏好 |
| .claude/settings.json | 项目 | 提交 | 团队级钩子、权限、插件 |
| .claude/settings.local.json | 项目 | Gitignore | 本项目的个人覆盖 |
设置加载顺序为:user → project → local(后者覆盖前者)。
工作流程:澄清意图 → 读取现有文件 → 小心合并(保留现有设置,尤其是数组)→ 编辑文件(若文件不存在,先请用户创建)→ 确认变更内容。
合并数组时需保留现有项并追加新项,例如在 permissions.allow 中同时保留已有的 Bash(git *)、Edit(.claude) 并新增 Bash(npm *)。
钩子配置
钩子在 Claude Code 生命周期的特定节点运行命令。钩子事件包括:PermissionRequest、PreToolUse、PostToolUse、PostToolUseFailure、Notification、Stop、PreCompact、PostCompact、UserPromptSubmit、SessionStart。常见工具匹配器有 Bash、Write、Edit、Read、Glob、Grep。
钩子类型:
- Command 钩子:运行 shell 命令,如 { "type": "command", "command": "prettier --write $FILE", "timeout": 30 }
- Prompt 钩子:用 LLM 评估条件,如 { "type": "prompt", "prompt": "Is this safe? $ARGUMENTS" },仅适用于工具事件(PreToolUse、PostToolUse、PermissionRequest)
- Agent 钩子:运行带工具的代理,如 { "type": "agent", "prompt": "Verify tests pass: $ARGUMENTS" },仅适用于工具事件
钩子通过 stdin 接收 JSON 输入,可返回 JSON 控制行为,字段包括 systemMessage、continue、stopReason、suppressOutput、decision、reason、hookSpecificOutput(含 additionalContext、permissionDecision、permissionDecisionReason、updatedInput)。
常见模式包括:写入后自动格式化、记录所有 bash 命令、Stop 钩子显示消息、代码变更后运行测试。
构造钩子(含验证)的流程:去重检查 → 针对本项目构造命令(安全提取载荷、按项目方式调用工具、跳过不处理的输入、暂不包裹 || true)→ 管道测试原始命令 → 写入 JSON 并合并 → 用 jq 校验语法与 schema → 证明钩子触发(仅限可在本轮触发的 Pre|PostToolUse)→ 清理 → 交接说明。若证明失败但管道测试与 jq 校验通过,可能是设置监视器未监视 .claude/,需用户打开 /hooks 一次或重启。
适用场景
- 需要为 Claude Code 添加或修改权限规则
- 需要配置环境变量
- 需要设置钩子实现自动化(格式化、日志、测试等)
- 需要管理 MCP 服务器或插件
- 需要调整模型、语言、清理周期等设置
限制
- 除非明确指示,否则不要更新 env
- 无效 JSON 会静默禁用该文件的所有设置
- 钩子静默成功在 UI 中不可见,仅当钩子出错或缓慢时才显示「Ran N hooks」
- 设置监视器只监视会话启动时已有设置文件的目录
- 若目标文件不存在,需先请用户创建
- 创建 .claude/settings.local.json 时需将其加入 .gitignore(Write 工具不会自动处理)
常见错误
- 替换而非合并
- 选错文件
- JSON 无效
- 忘记先读取
钩子故障排查
若钩子未运行:检查设置文件、验证 JSON 语法、检查匹配器是否匹配工具名、检查钩子类型、手动运行钩子命令测试、使用 claude --debug 查看钩子执行日志。