Claude Code Settings.json 完全配置指南

掌握 settings.json 的所有参数，让 Claude Code 完全按你的方式工作。

概述

Claude Code 的 settings.json 是整个应用的配置中枢。它存在于三个层级，优先级从低到高：

三者支持完全相同的配置结构，高优先级会覆盖低优先级的同名配置。

一、权限管理（permissions）

1.1 基本权限规则

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Bash(npm test)",
      "Bash(git *)",
      "Edit(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Edit(//.ssh/**)"
    ],
    "ask": [
      "Bash(npm publish:*)",
      "WebFetch(domain:*.internal.com)"
    ]
  }
}

规则语法：工具名(内容匹配模式)

• * — 匹配任意内容
• 前缀:* — 前缀匹配
• domain:example.com — 域名匹配（用于 WebFetch）

1.2 可用的工具名

1.3 默认权限模式

{
  "permissions": {
    "defaultMode": "normal"
  }
}

可选值："normal" | "bypassPermissions" | "plan" | "auto"

1.4 额外允许的目录

{
  "permissions": {
    "additionalDirectories": [
      "/path/to/another/project",
      "/shared/libraries"
    ]
  }
}

二、沙箱配置（sandbox）

2.1 基本开关

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": false,
    "autoAllowBashIfSandboxed": true,
    "allowUnsandboxedCommands": true
  }
}

2.2 网络限制

{
  "sandbox": {
    "network": {
      "allowedDomains": ["npmjs.org", "github.com", "*.amazonaws.com"],
      "allowLocalBinding": true,
      "httpProxyPort": 8080
    }
  }
}

2.3 文件系统限制

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["~/.cargo", "/tmp/build"],
      "denyWrite": ["/etc", "/usr"],
      "denyRead": ["~/.ssh", "~/.aws"],
      "allowRead": ["~/.aws/config"]
    }
  }
}

注意：permissions 中的 Edit(path) 和 Read(path) 规则会自动同步到沙箱的文件系统限制中。

2.4 排除命令

{
  "sandbox": {
    "excludedCommands": ["docker", "bazel", "podman"]
  }
}

这些命令不会在沙箱中运行（通常因为它们自身有隔离机制）。

三、模型配置

3.1 覆盖默认模型

{
  "model": "claude-opus-4-6"
}

3.2 企业模型白名单

{
  "availableModels": ["opus", "sonnet", "claude-sonnet-4-6"]
}

支持三种匹配方式：

• 家族别名："opus" 匹配所有 opus 版本
• 版本前缀："opus-4-5" 仅匹配该版本
• 完整 ID：精确匹配

3.3 模型路由映射

{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456:inference-profile/xxx"
  }
}

将 Anthropic 模型 ID 映射到 Bedrock ARN 或其他提供商 ID。

3.4 Thinking 和 Effort

{
  "alwaysThinkingEnabled": true,
  "effortLevel": "high",
  "fastMode": false
}

四、环境变量

{
  "env": {
    "NODE_ENV": "development",
    "CUSTOM_API_KEY": "sk-xxx",
    "PATH": "/usr/local/bin:$PATH"
  }
}

所有在 Claude Code session 中执行的命令都会继承这些环境变量。

4.1 自定义 Anthropic API 配置

如果需要为 Claude Code CLI 调整 Anthropic API 的连接方式，可以直接在 settings.json 的 env 中声明相关变量：

• ANTHROPIC_API_KEY：常规 API Key，适用于官方 API 或完全兼容的代理网关。
• ANTHROPIC_AUTH_TOKEN：用于需要 OAuth/控制台会话注入的场景，例如企业内部控制台登录态下发短期 Token。
• ANTHROPIC_BASE_URL：自定义接口地址。典型用途包括通过可代理的内网出口访问官方 API，或在一、二方/预发环境之间切换。

同时，settings.json 顶层的 model 字段可设定 CLI 的默认模型；若命令行未显式传入 --model，则会优先读取这里的值；再没有时才回退至 ANTHROPIC_MODEL 环境变量。也就是说，CLI 参数 > model 字段 > ANTHROPIC_MODEL，确保团队可以在配置层面固定默认模型，而仍允许个人临时覆盖。

示例：

{
  "model": "claude-sonnet-4.2",
  "env": {
    "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
    "ANTHROPIC_BASE_URL": "https://proxy.internal.example.com",
    "ANTHROPIC_AUTH_TOKEN": "${ANTHROPIC_AUTH_TOKEN}"
  }
}

提示：涉及密钥/Token 的值建议放在 .claude/settings.local.json 或使用系统环境变量占位，防止误提交。

安全注意事项：

1. 仅当代理或自建网关完整转发 Anthropic API 协议时才重写 ANTHROPIC_BASE_URL，避免出现不兼容行为。
2. ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 属于敏感凭证，务必存储在本地未提交的配置或凭证管理服务中。
3. 切换内外网端点时，确认网络策略允许访问对应地址，并在必要时与安全团队同步。

4.2 自定义默认模型

除了 ANTHROPIC_MODEL 以外，CLI 还支持通过 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 为「自动/计划模式」的家族默认值设定不同的模型。当且仅当用户没有在命令中显式选择模型时，这些变量才会生效：

claude --model > ANTHROPIC_MODEL > settings.json 顶层 model 字段 > ANTHROPIC_DEFAULT_* 环境变量。

因此，如果既未传 --model，也没有配置 ANTHROPIC_MODEL 与 model，CLI 会根据对应家族的 ANTHROPIC_DEFAULT_* 值在 src/utils/model/model.ts 中自动回退到你定义的默认模型。配合 ANTHROPIC_DEFAULT_*_MODEL_NAME 与 ANTHROPIC_DEFAULT_*_MODEL_DESCRIPTION，src/utils/model/modelOptions.ts 中的模型选择器和 Planner 视图也会展示你自定义的文案，方便团队成员区分官方模型与代理模型。

典型场景包括：

• 企业代理转发 GPT/Bedrock 等第三方模型，需要将默认的 claude-opus-* 映射到代理的模型 ID；
• 通过 Amazon Bedrock、Azure 等提供的 ARN/Endpoint ID 来替换默认模型，以满足合规或地域要求；
• 内部私有化部署仅提供部分 TOOL 能力，需要提示成员必要的能力覆盖。

注意：这些字符串必须与代理或提供商实际支持的模型 ID 完全一致；若代理不支持部分工具（代码执行、检索等），请配合 capabilityOverrides 或相关配置禁用对应功能，避免运行期异常。

推荐将此类覆盖放在 .claude/settings.local.json 或其他未提交的配置文件中，示例：

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "bedrock:arn:aws:bedrock:us-east-1:123:inference-profile/opus-proxy",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "企业 Opus 代理",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION": "通过内网代理访问，具备代码解释器",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-sonnet-lite",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "GPT Sonnet",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "local-haiku-fast"
  }
}

这样，未显式指定模型的自动模式（如 Planner、Auto QA）都会回退到新的默认值，同时 UI 也能展示符合团队语境的命名与说明。

五、认证配置

{
  "apiKeyHelper": "/path/to/auth-script.sh",
  "awsCredentialExport": "/path/to/aws-creds.sh",
  "gcpAuthRefresh": "gcloud auth application-default login",
  "forceLoginMethod": "console"
}

apiKeyHelper 脚本需要输出认证信息到 stdout。

六、Git 归属

{
  "attribution": {
    "commit": "Generated with Claude Code\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
    "pr": "This PR was created with assistance from Claude Code."
  },
  "includeGitInstructions": true
}

设为空字符串可完全隐藏归属信息。

七、UI 与体验

{
  "language": "chinese",
  "outputStyle": "concise",
  "syntaxHighlightingDisabled": false,
  "prefersReducedMotion": false,
  "showThinkingSummaries": true,
  "promptSuggestionEnabled": true,
  "spinnerTipsEnabled": true,
  "spinnerVerbs": {
    "mode": "append",
    "verbs": ["思考中", "分析中", "推理中"]
  }
}

八、其他实用配置

自动记忆

{
  "autoMemoryEnabled": true,
  "autoMemoryDirectory": "~/.claude/my-project-memory/"
}

会话保留

{
  "cleanupPeriodDays": 30
}

设为 0 将完全禁用 session 持久化。

自动更新

{
  "autoUpdatesChannel": "stable"
}

企业公告

{
  "companyAnnouncements": [
    "请使用内部模型端点，不要使用外部 API Key",
    "本周五进行系统维护，请及时保存进度"
  ]
}

启动时会随机显示其中一条。

最佳实践

1. 团队规范放 settings.json：权限规则、hooks、沙箱配置等
2. 个人偏好放 settings.local.json：模型选择、语言、UI 配置等
3. 全局默认放 ~/.claude/settings.json：适用于所有项目的通用配置
4. 敏感信息用 apiKeyHelper：不要直接在配置文件中存储密钥