CClaude Code GuideEnglish

Claude Code 设置

Settings 决定 Claude Code 如何加载记忆、权限、hooks、MCP servers、模型和 UI 偏好。合理的 settings 能减少每个会话和每个同事重复手动配置。

最近核验
适用版本
Claude Code 2.1.x。本机使用 2.1.198 核对 CLI 拼写；官方文档可能描述更新的 2.1.x 行为。
核验方式
依据官方文档和本地 help 核对 settings scopes、local-file location、source selection、merge behavior 与 permission precedence；未修改真实 settings。
官方来源
SettingsPermissionsChangelog

可复现实践

共享 Setting 前隔离测试 Project Setting

区分 project、local、user 和 command-line settings，避免覆盖已有配置。

准备

  • 唯一临时 git 仓库。
  • 使用 jq 校验语法。
  • 一个可回退、有官方 key 和预期 scope 的 setting。

执行步骤

  1. 创建隔离 project/local layers

    Fixture 不能覆盖已有 `.claude` 目录。

    步骤 1
    SETTINGS_LAB=$(mktemp -d "${TMPDIR:-/tmp}/claude-settings.XXXXXX")
printf '%s\n' "$SETTINGS_LAB"
cd "$SETTINGS_LAB" && git init -q
mkdir .claude
printf '%s\n' '{"permissions":{"allow":["Read"]}}' > .claude/settings.json
printf '%s\n' '{"permissions":{"deny":["Read(.env)"]}}' > .claude/settings.local.json

  2. 验证两个文件

    Syntax 通过是必要条件，但不能证明有效 merge。

    步骤 2
    jq -e . .claude/settings.json >/dev/null
jq -e . .claude/settings.local.json >/dev/null

  3. 显式选择 source

    可选 session 只加载 project/local，排除无关 user settings。

    步骤 3
    claude --setting-sources project,local

  4. 覆盖 denial

    请求普通文件和 `.env`，检查真实 permission result，fixture 不放秘密。

预期结果

Project allow 和 local deny 均可归因，`.env` 保持拒绝，测试不依赖 user settings。

验证

  • 只用 `/status` 或 `/config` 检查 effective state，不推断未记录 merge rule。
  • 分别检查两个 JSON 和 git status。
  • 在真实 repo 采用前确认 local settings 仍 untracked。

失败处理

Setting 像是被忽略

检查 scope、repository root、支持的 key，以及 print mode 是否静默忽略 invalid settings。

Layer 冲突

缩减到一个 key 和一对 source；deny rule 始终保留 precedence。

清理或回退

  • 退出并返回原目录，确认 SETTINGS_LAB 是打印出的 mktemp 路径，只删除它。
  • 真实项目通过 reviewed commit 回退 shared settings，并保留无关 local settings。

边界与不适用场景

  • 较新 2.1.x 中 local settings 可能跨 worktree 解析到 repository root。
  • Managed settings 和安全控制可覆盖或补充 project choice，本地测试不能证明组织 policy。

Settings 层级

Claude Code 会合并多个作用域的 settings。组织 managed policy 可覆盖用户默认值；项目 settings 则细化某个仓库的行为。

常见配置项

大多数团队早期会配置 permissions、additional directories、默认模型、diff 工具行为，以及主题或输出偏好。

CommandDescription
/config打开 settings UI，或直接设置 key=value。
/permissions配置当前会话的 allow、ask、deny 工具规则。
--settings为脚本化或 CI 会话加载 JSON settings 文件。
--add-dir为当前运行授予额外工作目录访问。
在会话中直接设置
/config theme=dark
/config model=sonnet

环境变量

环境变量可覆盖认证、debug 日志、功能开关和集成行为，适合 CI、容器和团队标准 shell。

排查 settings 未生效

当某个 setting 看起来被忽略时，应检查当前会话实际加载了什么，而不是假设磁盘上的文件已经应用。

CommandDescription
/doctor验证 settings 文件并报告解析或优先级问题。
/context查看启动上下文占用，包括已加载配置。
/mcp修改 MCP 相关 settings 后，确认 servers 是否可见。

日常工作中的 settings

Settings 与 permissions、memory、MCP 和故障排查交叉。应调整真正控制当前行为的那一层。

Settings 检查

相关主题

权限项目记忆MCP故障排查