Claude Code Manual

配置与自检

大多数“配置不生效”的问题，都是改错了文件，或者被更高优先级的设置覆盖了。弄清楚配置放在哪里，排查就容易了。

配置文件在哪里

安装 Claude Code 不会自动创建配置文件，需要时自己创建，或者在 /config 菜单里改一项设置，它会帮你创建。

文件	作用范围	适合放什么
`~/.claude/settings.json`	你电脑上的所有项目	个人偏好、接入 XAI Router 的 `env`、默认权限模式
`项目/.claude/settings.json`	这个项目，可以提交到 Git 与团队共享	团队统一的权限规则、Hooks
`项目/.claude/settings.local.json`	这个项目，只属于你，不提交	个人对这个项目的特殊设置
托管设置（managed）	公司统一下发	由 IT 管理，个人不能修改

Windows 上的 ~/.claude 指 %USERPROFILE%\.claude。

另外还有一个 ~/.claude.json，是 Claude Code 自己维护的状态文件，保存登录会话、MCP 服务器配置等，一般不需要手动编辑。

优先级

同一个设置出现在多个文件里时，按这个顺序取值，越靠前越优先：

托管设置
启动命令里的参数，例如 claude --permission-mode plan
.claude/settings.local.json
.claude/settings.json
~/.claude/settings.json

permissions.allow 这类列表不会互相覆盖，而是合并：每个文件都可以往里加规则。

少数和安全有关的设置有特殊规则。例如 useAutoModeDuringPlan：个人或项目本地配置里的 false，即使托管设置是 true 也照样生效；而写在项目共享 .claude/settings.json 里的 false 会被忽略。

一个推荐的个人配置

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.xairouter.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
  },
  "permissions": {
    "defaultMode": "default",
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  },
  "useAutoModeDuringPlan": false
}

env：接入 XAI Router，见凭证与接入 XAI Router。如果你已经用系统环境变量设置过，这一段可以省略。
defaultMode: "default"：每次会话从手动审批开始。
useAutoModeDuringPlan: false：计划模式里调查用的命令不再由分类模型代你批准，内置只读命令之外的都会先问你（启用了跳过权限的交互式终端会话除外）。它要写在个人或项目本地的配置里，写在项目共享的 .claude/settings.json 中会被忽略。
deny：禁止读取项目里的 .env 文件，这类文件通常存放密钥。它挡住的是 Claude 自带的读文件工具和 cat 这类它认得的命令；如果它运行一个脚本，脚本里照样能读到这个文件。需要严格隔离时，再配合沙箱限制文件访问。

JSON 格式很严格：键名要用双引号，最后一项后面不能有逗号。改完可以用 claude doctor 检查。

改了什么时候生效

Claude Code 会监视配置文件，大部分修改（包括权限规则和 Hooks）保存后立即对正在运行的会话生效。默认模型等少数设置只在会话启动时读取。修改了 env（比如换了 Key）或默认模型后如果没有生效，退出并重新启动 Claude Code。

自检

/status：在会话里运行，查看当前的登录方式、模型，以及 Setting sources（这次会话读取了哪些配置文件）。

claude doctor：在终端里运行（不用进入会话），检查安装是否健康、配置文件有没有写错、哪些设置被拒绝了。会话里也可以用 /doctor。

/config：会话里的设置菜单，可以直接修改主题、更新渠道等常用选项。

排查顺序

配置不生效时，按这个顺序检查：

当前在哪个环境运行：Windows 原生、WSL、macOS 还是 Linux？Windows 原生和 WSL 的配置互不影响。
改的文件对不对：用 /status 看 Setting sources。
有没有被更高优先级覆盖：项目里的 .claude/settings.json、启动参数都可能覆盖个人设置。
JSON 格式对不对：运行 claude doctor。
改的是不是 env 或只在启动时读取的设置：重启 Claude Code 再试。

上一章凭证与接入 XAI Router 下一章权限与安全