update-config — 配置管理技能

Claude Code 技能详解 · 配置管理

一、技能概述

update-config 是 Claude Code 中用于管理配置的核心技能，专门负责操作 settings.json 和 settings.local.json 文件。该技能覆盖所有与配置相关的操作，包括权限管理、环境变量设置、Hook 管理、MCP 服务器配置以及配置故障排除。用户可以通过自然语言指令直接修改 Claude Code 的行为和运行环境，无需手动编辑配置文件。

update-config 技能的设计目标是让配置管理变得更加直观和高效。用户无需记忆配置文件的 JSON 结构，也不必担心语法错误，只需用日常语言描述需求，技能便会自动解析指令并执行相应的配置变更。无论是添加新的权限规则、设置调试环境变量，还是配置自动运行的 Hook，update-config 都能通过一个简单的自然语言命令完成。

该技能是 Claude Code 日常使用中最高频调用的技能之一，尤其适合需要频繁调整工作环境的开发者和高级用户。它的存在大大降低了 Claude Code 的配置门槛，让用户能够专注于实际工作而非工具配置。

二、触发机制

update-config 技能通过特定的关键词和语义模式自动触发。当用户的指令涉及配置文件的修改、权限调整、环境变量设置、Hook 管理或 MCP 服务器配置时，系统会自动识别并调用该技能。以下是常见的触发模式和对应的触发词：

触发场景	触发关键词示例
权限管理	"allow npm commands"、"add bq permission"、"move permission to"
环境变量	"set DEBUG=true"、"set X=Y"、"configure env"
Hook 管理	"when claude starts show X"、"when claude stops show Y"、"each time I run npm test"
MCP 配置	"add MCP server"、"configure MCP"、"setup weather server"
故障排除	"hooks are not working"、"fix settings"、"config not loading"

该技能的触发是自动进行的，用户无需手动指定技能名称。系统会根据指令的语义内容判断是否匹配 update-config 的处理范围，并自动路由到对应的处理逻辑。这种设计使得用户的学习成本降到最低，只需描述想要的结果即可。

三、权限管理详解

3.1 权限模型概述

Claude Code 使用基于 settings.json 的权限管理系统来控制各种操作的执行权限。每次 Claude 执行工具调用时，系统都会检查相应的权限设置，确保操作在授权范围内进行。权限管理是 Claude Code 安全模型的核心组成部分，防止未经授权的操作影响系统安全。

3.2 添加权限

用户可以通过自然语言指令添加新的权限。系统支持三种权限作用域：全局设置（对所有项目生效）和用户设置（仅对当前项目生效）。例如："allow npm commands" 会在项目设置中添加 npm 相关命令的执行权限。"add bq permission to global settings" 则会在全局设置中添加 BigQuery 工具的权限，使所有项目都能使用该工具。

3.3 移动权限

技能支持在不同配置层级之间移动权限。例如，"move permission to user settings" 可以将当前在全局设置中的权限移动到用户设置，实现更细粒度的控制。权限移动功能为企业和团队用户提供了灵活的配置管理方式，便于在不同环境间同步设置。

3.4 权限优先级与合并规则

Claude Code 的权限系统遵循层级优先级规则：项目级设置（.claude/settings.json）优先级最高，用户级设置（~/.claude/settings.json）次之，全局设置优先级最低。当多个层级的配置中存在冲突时，高优先级的配置会覆盖低优先级的配置。update-config 技能在处理权限变更时会自动遵循这一优先级规则，确保配置变更的生效行为符合用户预期。

四、环境变量配置

4.1 配置方式

用户可以直接通过自然语言设置环境变量，技能会自动将这些配置写入 settings.json 的 env 字段。环境变量配置支持字符串、数字和布尔值等常见数据类型。配置完成后，Claude Code 在后续所有会话中都会自动加载这些环境变量。

用户指令：set DEBUG=true
用户指令：set NODE_ENV=production
用户指令：set API_KEY=your-api-key

4.2 使用场景

环境变量配置功能适用于以下典型场景：设置调试模式以获取更详细的日志输出；配置 API 密钥和访问令牌；指定运行时环境的参数（如 NODE_ENV）；配置数据库连接字符串；设置第三方服务的认证信息。通过统一的环境变量管理，用户可以在不同项目和任务间保持配置的一致性和可移植性。

4.3 安全注意事项

值得注意的是，存储在 settings.json 中的环境变量是明文字段。对于敏感信息（如 API 密钥、数据库密码等），建议使用专门的安全存储方案或环境变量注入机制，避免将密钥硬编码到配置文件中。update-config 技能本身不提供加密存储功能，用户需要自行评估安全风险并采取适当的安全措施。

五、Hook 管理

5.1 Hook 机制概述

Hook 是 Claude Code 中实现自动化行为的关键机制。与基于记忆或偏好的自动化不同，Hook 由 Claude Code 的底层运行环境（harness）直接执行，不依赖 Claude 自身的判断。这意味着 Hook 的执行更加可靠和确定，不会被会话上下文或模型状态影响。

5.2 Hook 类型与生命周期

update-config 技能支持管理多种类型的 Hook，每种 Hook 对应不同的触发时机：

Hook 类型	触发时机	使用示例
onStart	Claude Code 启动时	"when claude starts show the current branch"
onStop	Claude Code 停止时	"when claude stops save workspace state"
beforeCommand	特定命令执行前	"before npm test run lint"
afterCommand	特定命令执行后	"after git commit notify me"
custom	自定义触发条件	"each time I run python script show memory usage"

5.3 自动化行为配置

用户可以使用以下模式配置自动化行为："from now on when X" 用于配置条件触发的 Hook；"each time X" 用于配置重复执行的 Hook；"whenever X" 和 "before/after X" 用于配置时间相关的 Hook。这些自然语言模式会被 update-config 技能自动解析并转换为 settings.json 中的 Hook 配置。

5.4 Hook 调试与故障排除

当 Hook 无法正常工作时，用户可以求助 update-config 技能进行诊断。技能会检查 Hook 的配置语法、执行环境依赖以及权限设置，帮助用户快速定位问题。常见的 Hook 问题包括：配置文件语法错误、Hook 脚本路径不正确、执行权限不足、环境变量缺失等。

六、MCP 服务器配置

6.1 MCP 协议概述

Model Context Protocol (MCP) 是 Claude Code 的扩展协议，允许用户通过配置 MCP 服务器来扩展 Claude 的功能。MCP 服务器可以提供自定义的工具、数据源和计算能力，极大地丰富了 Claude Code 的应用场景。update-config 技能负责管理 MCP 服务器的配置、更新和故障排除。

6.2 配置 MCP 服务器

用户可以通过自然语言命令添加、修改和删除 MCP 服务器配置。例如，"add weather MCP server" 会引导用户完成 MCP 服务器的配置过程。技能会自动验证配置的完整性和语法正确性，确保 MCP 服务器能够正常连接和通信。

用户指令：add a MCP server for weather data
用户指令：configure MCP server for database access
用户指令：update MCP server endpoint

6.3 多服务器管理

update-config 支持同时管理多个 MCP 服务器的配置，包括服务器的启用/禁用、优先级排序以及依赖关系管理。对于企业级应用，还可以配置 MCP 服务器的认证信息和访问控制策略，确保只有授权的操作才能调用特定的 MCP 工具。

七、settings.json 文件结构详解

settings.json 是 Claude Code 所有配置的核心文件，位于项目的 .claude 目录或用户主目录的 .claude 目录中。update-config 技能的所有操作最终都会反映到这个文件的结构中。以下是完整的配置结构说明：

{
  "permissions": {
    "allow": ["npm", "bq", "git"],
    "deny": ["rm -rf"]
  },
  "env": {
    "DEBUG": "true",
    "NODE_ENV": "development"
  },
  "hooks": {
    "onStart": ["echo 'Claude is ready'"],
    "onStop": ["echo 'Session ended'"]
  },
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["weather-server.js"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}

配置文件支持 JSON 和 JSONC 格式，后者允许在配置文件中添加注释，便于团队协作和配置文档化。update-config 技能会自动处理注释的保留和维护，不会因为配置更新而丢失已有的注释信息。

八、使用场景与代码示例

8.1 场景一：新项目初始化

在开始新项目时，用户可以通过 update-config 快速配置项目环境。以下是一个典型的项目初始化流程：

// 允许 Node.js 相关命令
allow npm commands
// 设置项目环境变量
set NODE_ENV=development
// 配置启动 Hook
when claude starts show the current project info

8.2 场景二：调试模式配置

当需要调试应用时，可以通过 update-config 快速启用调试模式：

// 启用调试输出
set DEBUG=app:*
// 允许所有调试相关工具
allow debug commands
// 配置调试后自动清理
after claude stops unset DEBUG

8.3 场景三：权限审计与优化

对于安全敏感的项目，定期审计和优化权限配置是必要的维护工作。使用 fewer-permission-prompts 技能扫描会话记录后，可以将识别出的常用操作通过 update-config 添加到权限列表中，减少重复的权限确认提示。这种组合使用方式能够大幅提升工作效率和安全性。

8.4 场景四：多项目管理

对于同时管理多个项目的用户，update-config 支持在不同项目间切换配置。用户可以为每个项目创建独立的 settings.json，并通过环境变量和权限设置隔离不同项目的运行环境。这种配置隔离机制是 Claude Code 在多项目环境中的核心能力。

九、常见模式与最佳实践

9.1 权限管理最佳实践

9.2 Hook 使用模式

常用 Hook 模式

1. 使用 "from now on when" 配置一次性条件 Hook。

2. 使用 "each time" 配置重复执行的周期性 Hook。

3. 将常用的自动化流程封装为完整的 Hook 链。

4. 在 Hook 中加入日志输出，便于调试和追踪。

9.3 配置管理策略

在实际使用中，建议遵循以下配置管理策略：全局配置用于设置通用规则和默认行为；用户配置用于个性化设置和偏好；项目配置用于特定项目的环境和权限需求。这种分层配置策略能够最大限度地提高配置的可维护性和可移植性。

十、与其他技能的协作

update-config 技能并非孤立存在，它与多个其他 Claude Code 技能存在协作关系：

技能名称	协作方式
fewer-permission-prompts	扫描会话记录后，通过 update-config 添加权限白名单
keybindings-help	键盘快捷键配置与 settings.json 中的权限配置互补
claude-md-management	CLAUDE.md 中的流程文档可引用配置规范
init	项目初始化时调用 update-config 进行环境配置

这种协作模式使得 Claude Code 的技能生态系统更加完善，用户可以通过组合使用多个技能实现复杂的工作流程。例如，先用 init 技能初始化项目，再用 update-config 配置项目环境，最后用 keybindings-help 设置快捷键，形成完整的项目搭建流程。

十一、故障排除指南

11.1 配置文件问题

当 settings.json 配置无法正常加载时，常见的原因包括：JSON 语法错误（遗漏逗号、括号不匹配等）；文件编码不正确（必须使用 UTF-8 编码）；文件权限不足（无法读取或写入）；配置路径错误（文件位置不正确）。update-config 技能可以自动检测这些常见问题并提供修复建议。

11.2 Hook 执行失败

Hook 执行失败通常由以下原因导致：Hook 命令或脚本不存在；执行环境变量缺失；命令执行超时；权限配置不匹配。建议在配置 Hook 时加入异常处理和日志记录，以便快速定位执行失败的原因。

11.3 MCP 连接问题

MCP 服务器连接失败时，需要检查：服务器地址和端口配置是否正确；网络连接是否正常；认证信息是否有效；服务器端是否正常运行。update-config 技能支持 MCP 连接测试功能，可以验证配置的有效性。

十二、/update-config 命令使用方法

12.1 调用方式

/update-config 是 Claude Code 中的内置斜杠命令（Slash Command），可以在对话中直接输入触发。该技能由底层 Harness 直接处理，不经过模型调用，因此响应速度极快，适合快速配置场景。

/update-config                      # 触发技能，后续描述需求
/update-config allow npm commands   # 直接附加指令
/update-config 设置 DEBUG=true

12.2 技能工作流程

步骤一：澄清意图 — 如果请求有歧义，技能会通过 AskUserQuestion 确认：修改哪个配置文件（用户/项目/本地）？是追加到已有数组还是替换？具体值是什么？

步骤二：读取现有文件 — 使用 Read 工具读取目标 settings.json，绝不跳过此步骤。合并新配置与现有配置，绝不替换整个文件。

步骤三：判断使用 /config 命令还是直接编辑

方式	适用场景
`/config` 命令	theme、editorMode、verbose、model、language、alwaysThinkingEnabled、permissions.defaultMode 等简单设置
直接编辑 settings.json	Hook 配置（PreToolUse/PostToolUse 等）、复杂权限规则（allow/deny 数组）、环境变量、MCP 服务器、插件配置

步骤四：合并配置（重要！） — 操作权限数组或 Hook 数组时，必须合并而非替换：

// 错误（会覆盖已有权限）：
{ "permissions": { "allow": ["Bash(npm *)"] } }

// 正确（保留已有+新增）：
{
  "permissions": {
    "allow": [
      "Bash(git *)",      // 已有
      "Edit(.claude)",    // 已有
      "Bash(npm *)"       // 新增
    ]
  }
}

12.3 配置文件层级

文件	作用域	Git	用途
`~/.claude/settings.json`	全局	不提交	个人偏好，所有项目生效
`.claude/settings.json`	项目	可提交	团队共享的 Hook、权限、插件
`.claude/settings.local.json`	项目	Gitignore	个人对当前项目的覆盖

加载顺序：用户级 → 项目级 → 本地级（后加载覆盖先加载）。

12.4 Hook 构造与验证流程

当需要配置 Hook 时，update-config 遵循以下严谨流程：

去重检查：读取目标文件，如果同一事件+匹配器上已有 Hook，展示现有命令并询问：保留、替换还是并排添加。
构造命令：使用 jq -r 提取负载并用 { read -r f; ... "$f"; } 管道处理，禁止不带引号的 xargs。
管道测试：模拟 stdin 负载直接测试命令，验证退出码和副作用。
写入 JSON：合并到目标文件，首次创建 .claude/settings.local.json 时自动加入 .gitignore。
验证语法：使用 jq -e 验证 JSON 语法和结构。
证明 Hook 触发：通过制造可检测的变更验证 Hook 确实生效。
交接：告知用户 Hook 已生效（或需重启），指引使用 /hooks 菜单查看。

# 添加格式化 Hook 示例
用户：每次写入文件后自动运行 prettier

→ 读取 .claude/settings.json
→ 构造命令：jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write "$f"; } 2>/dev/null || true
→ 写入 PostToolUse 匹配 Write|Edit 的 Hook

12.5 常见配置示例

添加权限：

用户：允许 npm 命令
→ 读取 settings.json → 在 permissions.allow 中追加 "Bash(npm *)"

设置环境变量：

用户：设置 DEBUG=true
→ 在 env 字段中添加 "DEBUG": "true"

切换模型：

用户：改用 Sonnet 模型
→ 设置 "model": "sonnet"（可用 /config 命令更快完成）

十三、核心总结

update-config 技能是 Claude Code 配置管理的核心入口，覆盖权限、环境变量、Hook、MCP 四大配置领域。设计哲学是"自然语言驱动，零手动编辑"，用户只需描述需求即可完成配置。掌握 update-config 能够显著提升 Claude Code 的使用效率，是进阶用户的必备技能。关键要点：权限管理遵循最小权限原则，Hook 由运行时直接执行比记忆更可靠，环境变量支持灵活的跨项目配置，MCP 服务器扩展了 Claude 的功能边界。建议用户将 update-config 与 fewer-permission-prompts、keybindings-help 等技能配合使用，构建高效的 Claude Code 工作环境。