Claude Code 配置文件 settings.json 详解（附示例）

浏览：2次阅读

Claude Code 配置文件 主要是 settings.json：个人配置放 ~/.claude/settings.json，团队共享放项目里的 .claude/settings.json，个人项目覆盖放 .claude/settings.local.json。改完运行 /status 看是否加载，不生效优先查优先级和 JSON 语法。

图片来源：Claude Code Docs · Settings files and precedence

官方文档把配置分成四个作用域，安装 Claude Code 时 不会自动创建 任何配置文件，需要自己建，或者让 Claude Code 在你第一次改设置时自动写入。

作用域	文件位置	对谁生效	适合放什么
用户	`~/.claude/settings.json`	你本机的所有项目	主题、默认模型、个人权限规则
项目共享	`.claude/settings.json`	该项目所有成员（提交到 git）	团队权限、hooks、插件、项目环境变量
项目本地	`.claude/settings.local.json`	只有你，只在这个项目	个人覆盖、测试配置
托管	`managed-settings.json` 等	组织统一下发	安全策略、合规要求

Windows 下 ~/.claude 指的是 %USERPROFILE%\.claude，例如 C:\Users\ 你的用户名 \.claude\settings.json。如果想把配置目录放到别处，可以设置环境变量 CLAUDE_CONFIG_DIR。还没装好的话，先看 Claude Code Windows 安装教程（2026）。

另外还有一个 ~/.claude.json，它由 Claude Code 自己维护，存账号信息、MCP 服务器配置和项目信任状态，一般不需要手动改。MCP 的添加方法见 Claude Code 配置 MCP 教程。

在 Claude Code 里输入 /config，在 Config 标签页改主题、编辑模式、详细输出等常用选项，大多数会自动保存到 ~/.claude/settings.json。也可以直接写成 /config verbose=true 这种形式。注意 /config 只在终端界面可用，VS Code 面板和桌面版需要直接改文件。

用编辑器打开对应作用域的文件，按需写入键值。下面是官方示例：允许免确认运行 lint 和测试命令，同时禁止读取 .env：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": ["Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

第一行 $schema 指向官方发布的 JSON Schema，在 VS Code、Cursor 里能获得字段自动补全和校验。

不想改文件时，可以启动时用 --settings 传 JSON：

claude --settings '{"model":"claude-opus-5-5"}'

也可以用单项参数（如 --model）或对应环境变量（如 ANTHROPIC_MODEL）。这些都只影响当前会话。

图片来源：Claude Code Docs · All settings

{"model": "claude-sonnet-5"}

设置后每个新会话默认使用该模型，会话中仍可用 /model 切换。优先级：--model > ANTHROPIC_MODEL > 配置文件里的 model。

permissions.allow、ask、deny 分别是放行、询问、拒绝规则。permissions.defaultMode 决定新会话的权限模式，可选 default、acceptEdits、plan、auto、dontAsk、bypassPermissions。其中 auto 和 bypassPermissions 写在项目或本地配置里不生效，只能写在 ~/.claude/settings.json。

{
  "permissions": {"defaultMode": "acceptEdits"}
}

env 可以给每次会话注入环境变量。接 Anthropic 兼容网关时，常用 ANTHROPIC_BASE_URL（改 API 地址）和 ANTHROPIC_AUTH_TOKEN（会作为 Authorization: Bearer 发送）：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https:// 你的网关地址",
    "ANTHROPIC_AUTH_TOKEN": "你的密钥",
    "DISABLE_AUTO_COMPACT": "1"
  }
}

官方提醒：env 里的值以明文保存，并会传给 Claude Code 启动的所有子进程；需要轮换的凭据更推荐用 apiKeyHelper，让一条命令动态输出密钥。接 DeepSeek 的完整写法可参考 Claude Code 接入 DeepSeek V4 教程。

同一个键在多处设置时，从高到低依次是：

托管配置（组织下发，个人无法覆盖）
命令行 --settings（仅本次会话）
项目本地 .claude/settings.local.json
项目共享 .claude/settings.json
用户 ~/.claude/settings.json

注意两点：一是 permissions.allow 这类列表会合并而不是覆盖；二是环境变量不在这个层级里，比如在 shell 里 export 的 ANTHROPIC_MODEL 会压过任何文件里的 model。

图片来源：anthropics/claude-code GitHub

配置文件是严格 JSON，不能写 // 注释，也不能有结尾多余逗号。出现 Settings Error 时可以选择让 Claude 帮你修、退出或跳过坏配置继续。只是个别条目有问题时会显示 Settings Warning，坏条目被跳过，其余照常生效。之后运行 claude doctor 查看具体错误。