本页目录8
要点速览
- 优先级(高→低):Managed > 命令行参数 > .claude/settings.local.json > .claude/settings.json > ~/.claude/settings.json。
- 权限规则跨层【合并】而非覆盖:allow/deny/ask/additionalDirectories 从所有层累积。
- permissions.defaultMode 设默认权限模式;deny 优先于 ask 优先于 allow,首条匹配生效。
- env 对象注入所有会话与子进程;model 设默认模型(被 --model / ANTHROPIC_MODEL 覆盖)。
- 多数字段改完实时重载(无需重启);model/outputStyle 等读取一次,需 /model 或重启。
本文是对官方 Claude Code settings 的中文整理,字段与默认值以原文为准。
配置文件位置与优先级
按优先级从高到低应用(高优先级覆盖低优先级;权限规则例外:跨层合并):
| 优先级 | 范围 | 位置 |
|---|---|---|
| 1(最高) | Managed | macOS /Library/Application Support/ClaudeCode/managed-settings.json · Linux /etc/claude-code/managed-settings.json · Windows C:\Program Files\ClaudeCode\managed-settings.json · 或服务器下发 |
| 2 | 命令行参数 | CLI flags(仅当前会话) |
| 3 | Local | .claude/settings.local.json(gitignore,仅你+本仓库) |
| 4 | Project | .claude/settings.json(入 git,团队共享) |
| 5(最低) | User | ~/.claude/settings.json(你的所有项目) |
其他:~/.claude.json(OAuth/MCP/缓存)、项目 MCP 在 .mcp.json。
核心字段
模型与推理
| 键 | 说明 | 示例 |
|---|---|---|
model | 默认模型(被 --model/ANTHROPIC_MODEL 覆盖) | "claude-sonnet-4-6" |
availableModels | 限制可选模型 | ["sonnet","haiku"] |
fallbackModel | 主模型超载时的备用链(≤3) | ["claude-sonnet-4-6","claude-haiku-4-5"] |
effortLevel | 持久化 effort | "low"/"medium"/"high"/"xhigh" |
alwaysThinkingEnabled | 默认开启 extended thinking | true |
outputStyle | 输出风格 | "Explanatory" |
权限与安全
| 键 | 说明 |
|---|---|
permissions | 含 allow/deny/ask/additionalDirectories/defaultMode(见下) |
forceLoginMethod | "claudeai" 或 "console" |
minimumVersion | 防止自动更新到低于此版本 |
{
"permissions": {
"allow": ["Bash(npm run lint)", "Bash(npm run test *)", "Read(~/.zshrc)"],
"deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"],
"ask": ["Write(*.ts)"],
"additionalDirectories": ["/opt/project"],
"defaultMode": "ask"
}
}
规则求值顺序 deny → ask → allow,首条匹配生效;权限规则跨配置层累积合并,不互相覆盖。
环境与认证
| 键 | 说明 |
|---|---|
env | 注入所有会话与子进程的环境变量 |
apiKeyHelper | 生成 auth 值的脚本(作 X-Api-Key 与 Authorization: Bearer) |
awsCredentialExport / gcpAuthRefresh | AWS/GCP 凭证刷新脚本 |
文件与会话
| 键 | 说明 | 默认 |
|---|---|---|
cleanupPeriodDays | 删除超过 N 天的会话文件 | 30 |
autoMemoryEnabled | 启用 auto memory | true |
fileCheckpointingEnabled | 每次编辑前快照以支持 /rewind | true |
autoCompactEnabled | 接近上限自动 compact | true |
respectGitignore | 文件选择器遵守 .gitignore | true |
plansDirectory | 计划文件目录 | ~/.claude/plans |
Hooks / MCP / 插件 / 功能开关
| 键 | 说明 |
|---|---|
hooks | 生命周期事件的自定义命令 |
disableAllHooks | 禁用所有 hooks 与自定义状态栏 |
enableAllProjectMcpServers | 自动批准项目 .mcp.json 的全部 MCP |
enabledMcpjsonServers / disabledMcpjsonServers | 批准/拒绝特定 MCP |
statusLine | 自定义状态栏(type/command/padding) |
autoUpdatesChannel | "latest"(默认)或 "stable" |
disableWorkflows / disableBundledSkills / disableAgentView | 关闭相应功能 |
attribution | 自定义 commit/PR 署名(替代已废弃的 includeCoAuthoredBy) |
查看有效配置与生效时机
- 查看/编辑:
/config;诊断:claude doctor。 - 实时重载(无需重启):
permissions/hooks/env/apiKeyHelper等多数键。 - 读取一次:
model(用/model切换)、outputStyle(/clear或重启)。
字段众多,本表为高频项;完整字段(含 Managed 专用、通知、显示等)见官方原文。