SuperAPI AI 工具集

update-config

编程与开发

查看项目

更新于 10-24 16:20

技能介绍

用途

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 等

使用方式

技能强调两条关键原则:

  1. 写入前先读取:始终先读取现有 settings 文件,将新设置与现有设置合并,绝不整体替换文件。
  2. 歧义时使用 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。

钩子类型:

  1. Command 钩子:运行 shell 命令,如 { "type": "command", "command": "prettier --write $FILE", "timeout": 30 }
  2. Prompt 钩子:用 LLM 评估条件,如 { "type": "prompt", "prompt": "Is this safe? $ARGUMENTS" },仅适用于工具事件(PreToolUse、PostToolUse、PermissionRequest)
  3. 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 查看钩子执行日志。