第 13 章：配置体系深度解析

在使用 Claude Code 的前几周，你可能只需要改几个基本设置——切个模型、调个主题、配个 API Key。但随着使用深入，你会发现 Claude Code 的配置体系远比"一个 settings.json 文件"要丰富：它有四层优先级、三个配置文件、数十个环境变量、VSCode 专属选项，还有一套允许你精确控制 Claude 行为的权限语法。

理解这套体系不是为了"记住所有选项"——而是为了在需要的时候，知道去哪里改、怎么改、改了之后会影响什么。

本章目标：全面掌握 Claude Code 的配置体系架构，理解四层优先级的合并规则，熟悉每一个配置项的用途和适用场景，能够根据个人、项目、团队的不同需求编写准确的配置。

13.1 四层配置优先级

Claude Code 的配置分为四个层级，优先级从高到低。这是整个配置体系的核心架构——理解了它，你就理解了"某个设置到底从哪里生效"这个最常见的问题。

优先级图

项目本地配置 (.claude/settings.local.json)     ← 最高优先级，不提交 Git
    ↓ 覆盖
项目配置 (.claude/settings.json)               ← 团队共享，提交 Git
    ↓ 覆盖
用户全局配置 (~/.claude/settings.json)          ← 个人偏好，所有项目生效
    ↓ 覆盖
内置默认值                                      ← 最低优先级

各层职责

层级	文件	Git	作用域	典型内容
第 1 层	`.claude/settings.local.json`	不提交	当前项目	API 密钥、本地数据库 URL、个人模型偏好
第 2 层	`.claude/settings.json`	提交	当前项目	团队共享的权限规则、MCP 服务器、Hooks
第 3 层	`~/.claude/settings.json`	—	所有项目	个人默认模型、主题、全局权限基线
第 4 层	内置默认值	—	所有项目	出厂设置（模型、权限模式等）

合并规则

四层配置不是简单的"高优先级替换低优先级"，而是逐层合并：

从最底层（内置默认值）开始构建完整配置
用户全局配置覆盖内置默认值中的同名字段
项目配置覆盖用户全局配置中的同名字段
本地配置覆盖项目配置中的同名字段

关键细节：对于对象类型的字段（如 permissions、hooks），合并是浅合并——高层级的对象会完全替换低层级的同名对象，而不是深度合并对象内部的子字段。

举个例子：

json

// ~/.claude/settings.json（全局）
{
  "permissions": {
    "allow": ["Bash(git:*)"],
    "deny": ["Bash(rm:-rf:*)"]
  }
}

// .claude/settings.json（项目）
{
  "permissions": {
    "allow": ["Bash(pnpm:*)"]
  }
}

// 生效结果（项目配置完全替换了全局的 permissions 对象）：
{
  "permissions": {
    "allow": ["Bash(pnpm:*)"]
    // deny 不见了！因为项目配置的 permissions 对象整个替换了全局的
  }
}

⚠️ 注意：如果你在项目配置中重新定义了 permissions，全局的 permissions.deny 规则不会自动保留。需要在项目配置中显式重新声明所有需要的 deny 规则。这个行为是设计如此——团队配置应该是完整的、自包含的，不应该依赖全局配置中不可见的规则。

当各层生效

启动时：Claude Code 按优先级顺序加载所有配置文件，构建最终生效的配置
运行时修改：如果你在 Claude Code 会话中通过 / 命令修改了设置（如切换模型、调整 Effort），这些修改只对当前会话有效，不会写入配置文件
修改配置文件后：需要重启 Claude Code 会话才能让新配置生效（/clear 或新开对话）
settings.local.json 的即时性：此文件的修改在某些版本中可以即时生效（因为它是最高优先级且不提交 Git），但安全做法仍是修改后重启

验证当前配置

要知道某个设置当前的实际值，在对话中直接问 Claude：

当前用的是哪个模型？配置文件是哪个？

Claude Code 可以读取自己的配置并告诉你最终生效的值。你也可以直接检查文件内容——但对于复杂配置（如权限规则），让 Claude 帮你分析合并结果更高效。

13.2 ~/.claude/settings.json 完整参考

~/.claude/settings.json 是用户全局配置文件，存放在你的用户目录下。它定义的设置对所有项目生效，除非被项目级配置覆盖。

完整配置结构

json

{
  "model": "claude-sonnet-4-6",
  "theme": "dark",
  "autoCompact": true,
  "autoCompactTokenLimit": 300000,
  "permissions": {
    "allow": [],
    "deny": []
  },
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [],
    "SessionStart": []
  },
  "env": {},
  "plugins": [],
  "mcpServers": {},
  "enableAllProjectMcpServers": false,
  "keybindings": {},
  "sandbox": {}
}

逐项详解

model

属性	说明
类型	`string`
默认值	`"claude-sonnet-4-6"`
可选值	`"claude-opus-4-7"` / `"claude-sonnet-4-6"` / `"claude-haiku-4-5"` / `"haiku"` / `"sonnet"` / `"opus"` / 自定义模型名

指定 Claude Code 默认使用的模型。这是最常修改的设置之一。

使用 Anthropic 官方模型：填写完整的模型 ID（如 "claude-sonnet-4-6"）
使用 DeepSeek：配合 env 中的模型映射环境变量，这里填写简写（如 "haiku"），由环境变量映射到实际模型
使用别名："haiku"、"sonnet"、"opus" 会映射到对应的默认模型

何时修改：

日常开发想省钱：设为 "haiku" 并用环境变量映射到 DeepSeek V4 Flash
复杂任务：临时切换为 "opus" 或用 / 菜单手动切换
使用第三方模型服务商：配合环境变量使用

theme

属性	说明
类型	`string`
默认值	`"dark"`
可选值	`"dark"` / `"light"` / `"system"`

控制 Claude Code 终端界面的颜色主题。仅影响 CLI 版本；VSCode 扩展版跟随 VSCode 的主题设置。

"dark"：深色背景，适合暗色终端
"light"：浅色背景，适合亮色终端
"system"：跟随操作系统的主题设置

autoCompact

属性	说明
类型	`boolean`
默认值	`true`

当对话上下文接近模型的上限时，是否自动触发上下文压缩（/compact）。

true：Claude 自动在必要时压缩上下文，保留关键信息，丢弃冗余对话
false：上下文达到上限时 Claude 会提示你手动执行 /compact

何时修改：

保持 true（推荐）：大多数场景下自动压缩不会丢失重要信息，且避免了手动操作的打断
设为 false：当你对上下文的精确控制有极高要求时（如法律、金融领域的精确引用），需要你自己决定哪些内容可以丢弃

autoCompactTokenLimit

属性	说明
类型	`number`
默认值	`300000`

触发自动压缩的 token 阈值。当已使用的上下文 token 数超过此值时，autoCompact 会触发。

如果你的模型有更大的上下文窗口（如 DeepSeek V4 系列支持 1M tokens），可以调高此值以充分利用上下文。但注意：更大的上下文也意味着更高的延迟和成本。

permissions

属性	说明
类型	`object`
默认值	`{ "allow": [], "deny": [] }`

权限规则配置，控制 Claude Code 可以执行哪些操作。这是安全体系的核心。

json

{
  "permissions": {
    "allow": [
      "Bash(git:status)",
      "Bash(git:diff)",
      "Bash(git:log)",
      "Bash(npm:*)",
      "Bash(pnpm:*)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm:-rf:*)",
      "Bash(sudo:*)",
      "Bash(git:push:--force:*)",
      "Bash(git:reset:--hard:*)"
    ]
  }
}

allow：白名单规则，匹配的操作无需确认直接执行
deny：黑名单规则，匹配的操作完全禁止执行（即使在 allow 列表中）

规则匹配遵循：deny 优先于 allow，详细规则语法见第 14 章：权限与安全。

hooks

属性	说明
类型	`object`
默认值	`{}`

事件钩子配置，在特定事件发生时自动执行自定义脚本或命令。

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git:commit:*)",
        "command": "echo 'About to commit...'"
      }
    ],
    "PostToolUse": [],
    "SessionStart": [
      {
        "command": "echo 'Claude Code session started at $(date)'"
      }
    ]
  }
}

PreToolUse：工具调用前触发。可以做前置检查、备份、自定义确认等
PostToolUse：工具调用后触发。可以做自动格式化、日志记录、通知等
SessionStart：会话启动时触发。可以加载项目环境、检查依赖等
Stop：会话停止时触发。可以做清理、保存状态等

详细用法见第 18 章：Hooks 钩子系统。

env

属性	说明
类型	`object`
默认值	`{}`

为 Claude Code 会话设置环境变量。这些变量仅在 Claude Code 运行期间生效，不影响你的全局 shell 环境。

json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash[1M]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_MODEL": "deepseek-v4-flash",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

⚠️ 安全提醒：不要在 env 中直接写 API 密钥（尤其是 ~/.claude/settings.json 可能会被同步或备份）。更安全的做法是将密钥放在 ~/.claude/.env 文件中，或使用操作系统的环境变量。

完整的环境变量列表见 13.5 节。

plugins

属性	说明
类型	`array`
默认值	`[]`

全局启用的插件列表。插件扩展了 Claude Code 的能力（如 WebSearch、WebFetch 等）。插件安装后会自动添加到此列表。

json

{
  "plugins": [
    "web-search",
    "web-fetch",
    "code-review"
  ]
}

全局安装（~/.claude/settings.json）：所有项目可用
项目安装（.claude/settings.json）：仅当前项目可用

详细用法见第 16 章：插件系统。

mcpServers

属性	说明
类型	`object`
默认值	`{}`

MCP（Model Context Protocol）服务器配置。MCP 服务器为 Claude Code 提供额外的工具和数据源。

json

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

每个 MCP 服务器通过 command 和 args 启动一个子进程，Claude Code 通过标准输入/输出与之通信。

详细用法见第 15 章：MCP 协议与服务器。

enableAllProjectMcpServers

属性	说明
类型	`boolean`
默认值	`false`

是否自动启用项目中配置的所有 MCP 服务器。

true：进入项目时自动启动 .claude/settings.json 中定义的所有 MCP 服务器
false：需要手动启用项目中的 MCP 服务器

出于安全考虑，默认关闭。因为项目级 MCP 服务器可以执行任意命令——如果克隆了一个恶意项目，自动启动其 MCP 服务器可能带来风险。

keybindings

属性	说明
类型	`object`
默认值	`{}`

自定义键盘快捷键配置。CLI 版本支持自定义键位绑定。

json

{
  "keybindings": {
    "submit": "Ctrl+Enter",
    "newline": "Enter",
    "interrupt": "Ctrl+C"
  }
}

VSCode 扩展版的快捷键在 VSCode 的 keybindings.json 中配置（见 13.6 节）。

sandbox

属性	说明
类型	`object`
默认值	`{}`

沙箱配置，控制 Claude Code 的文件系统和网络访问边界。

json

{
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowedDomains": [],
      "deniedDomains": []
    }
  }
}

沙箱模式在安全敏感场景下使用，限制 Claude 只能访问指定的目录和网络。绝大多数日常开发场景不需要配置此项。

13.3 .claude/settings.json 项目配置

.claude/settings.json 放在项目根目录的 .claude/ 文件夹下，存放团队共享的配置。该文件应提交到 Git，让团队的每个成员在克隆项目后自动获得统一的 Claude Code 行为配置。

团队配置的职责

项目级配置主要定义以下内容：

配置项	团队级（项目）	个人级（全局）
API 密钥、本地路径	✗	✓
项目特定的权限规则	✓	✗
项目 MCP 服务器	✓	✗
团队约定的 Hooks	✓	✗
模型选择偏好	✗	✓
主题、界面偏好	✗	✓
通用安全基线（deny 规则）	可选	✓

原则：与项目逻辑相关的配置放项目级，与个人偏好和密钥相关的配置放全局或 local。

完整示例

json

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(pnpm:*)",
      "Bash(node:*)",
      "Bash(npm:run:*)",
      "Bash(eslint:*)",
      "Bash(prettier:*)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm:-rf:*)",
      "Bash(sudo:*)",
      "Bash(git:push:--force:*)",
      "Bash(git:reset:--hard:*)",
      "Bash(git:branch:-D:*)",
      "Bash(gh:*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git:commit:*)",
        "command": "echo '记得写中文 commit message'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "pnpm lint --fix ${CLAUDE_TOOL_FILE_PATH}"
      }
    ]
  },
  "enableAllProjectMcpServers": true,
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-playwright"]
    }
  }
}

团队配置的设计考量

1. allow 规则要足够宽但不危险

团队配置的 allow 规则应该覆盖团队成员日常开发中 Claude Code 确实需要的操作。太窄——每个人都要频繁点 Allow，效率低；太宽——安全风险。

json

// ✅ 好的团队 allow 规则：精确到具体工具
"allow": [
  "Bash(git:status)",
  "Bash(git:diff)",
  "Bash(git:log)",
  "Bash(git:add:*)",
  "Bash(git:commit:*)",
  "Bash(pnpm:*)",
  "Bash(npm:run:*)",
  "Bash(node:*)",
  "Bash(ls:*)",
  "WebSearch",
  "WebFetch"
]

// ❌ 太宽的 allow 规则
"allow": [
  "Bash(*:*)"     // 允许所有 bash 命令——太危险
]

2. deny 规则应该覆盖不可逆操作

json

"deny": [
  "Bash(rm:-rf:*)",            // 强制递归删除
  "Bash(sudo:*)",              // 超级用户权限
  "Bash(git:push:--force:*)",  // 强制推送
  "Bash(git:reset:--hard:*)",  // 硬重置
  "Bash(git:clean:-fd:*)",     // 强制清理
  "Bash(chmod:777:*)",         // 危险权限修改
  "Bash(curl:*|sh)",           // 管道直接执行远程脚本
  "Bash(wget:*-O-*|sh)"        // 同上
]

3. 为团队留有定制空间

团队配置不应过度约束个人偏好。比如：

不要在项目配置中锁定模型——让团队成员通过 settings.local.json 选择自己偏好的模型
不要在项目配置中设置 "initialPermissionMode": "bypassPermissions"——权限模式是个人选择
要在项目配置中定义项目需要的 MCP 服务器和 hooks

版本控制

.claude/settings.json 应提交到 Git：

bash

git add .claude/settings.json
git commit -m "chore: 添加 Claude Code 团队配置"

.claude/settings.local.json 应加入 .gitignore：

bash

echo ".claude/settings.local.json" >> .gitignore

.claude/ 目录下的其他文件（如对话历史缓存）通常也不需要提交。建议的 .gitignore 条目：

.claude/settings.local.json
.claude/plans/
.claude/worktrees/

13.4 .claude/settings.local.json 本地覆盖

.claude/settings.local.json 是项目配置的本地覆盖文件，具有最高优先级。它解决了一个核心矛盾：团队配置需要版本控制，但个人密钥和本地路径不能提交到 Git。

应该放在 local.json 中的内容

类型	示例
API 密钥	`ANTHROPIC_AUTH_TOKEN`、第三方服务密钥
本地数据库 URL	`DATABASE_URL: "postgresql://localhost:5432/mydevdb"`
个人模型偏好	覆盖团队指定的模型，使用自己偏好的模型
调试开关	`DEBUG: "true"`、`VERBOSE: "1"`
本地路径	本地特有的工具路径、项目路径
个人权限调整	比团队配置更宽松或更严格的个人权限
个人 hooks	个人的自动化脚本（如自动格式化、通知）

完整示例

json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash[1M]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_MODEL": "deepseek-v4-flash",
    "DATABASE_URL": "postgresql://localhost:5432/mydevdb",
    "REDIS_URL": "redis://localhost:6379",
    "DEBUG": "true",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "model": "haiku",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "prettier --write ${CLAUDE_TOOL_FILE_PATH}"
      }
    ]
  }
}

它如何与项目配置协作

假设团队配置（.claude/settings.json）定义了项目需要的模型和权限：

json

// .claude/settings.json（团队配置，已提交 Git）
{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Bash(git:*)", "Bash(pnpm:*)", "WebSearch"],
    "deny": ["Bash(rm:-rf:*)", "Bash(sudo:*)"]
  }
}

你个人更喜欢用 DeepSeek V4 Flash（省钱），并且需要本地数据库连接：

json

// .claude/settings.local.json（你的本地覆盖，不提交 Git）
{
  "model": "haiku",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
    "DATABASE_URL": "postgresql://localhost:5432/mydevdb"
  }
}

生效结果：

模型："haiku"（你的 local 覆盖了团队配置的 "claude-sonnet-4-6"）
权限：团队定义的 allow/deny 规则保留（因为你的 local 中没有定义 permissions 字段）
环境变量：合并了你的本地密钥和数据库 URL

这正是配置分层设计的精妙之处——团队约束共享行为，个人覆盖本地偏好，互不干扰。

13.5 环境变量完整参考

Claude Code 的行为可以通过大量环境变量进行精细控制。环境变量可以在以下位置设置：

~/.claude/settings.json 的 env 字段（推荐，仅对 Claude Code 生效）
.claude/settings.local.json 的 env 字段（最高优先级，不提交 Git）
Shell 配置文件（~/.zshrc、~/.bashrc 等，对所有程序生效）
VSCode 的 .vscode/settings.json（仅对 VSCode 中的 Claude Code 生效）

核心环境变量

环境变量	说明	示例值	设置层级
`ANTHROPIC_AUTH_TOKEN`	API 认证令牌（替代 `ANTHROPIC_API_KEY`）	`sk-xxxxxxxx`	全局/项目/local
`ANTHROPIC_API_KEY`	API 密钥（旧称，与 AUTH_TOKEN 等效）	`sk-xxxxxxxx`	全局/项目/local
`ANTHROPIC_BASE_URL`	自定义 API 端点地址	`https://api.deepseek.com/anthropic`	全局
`ANTHROPIC_MODEL`	覆盖默认模型选择	`deepseek-v4-flash`	全局

模型映射变量

这些变量将 Claude Code 的三个模型档位（Haiku / Sonnet / Opus）映射到实际模型 ID。它们是使用第三方模型服务商（如 DeepSeek）的核心配置。

环境变量	说明	示例值
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Haiku 档位映射的实际模型	`deepseek-v4-flash`
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Sonnet 档位映射的实际模型	`deepseek-v4-flash[1M]`
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Opus 档位映射的实际模型	`deepseek-v4-pro[1m]`
`ANTHROPIC_DEFAULT_SONNET_MODEL_NAME`	Sonnet 档位的显示名称	`deepseek-v4-flash`

为什么有 DEFAULT_SONNET_MODEL_NAME：ANTHROPIC_DEFAULT_SONNET_MODEL 用于实际 API 调用（包含 [1M] 等后缀来指定上下文大小），而 DEFAULT_SONNET_MODEL_NAME 用于 UI 显示和日志中——更简洁，不带后缀。

超时与性能

环境变量	说明	默认值	示例值
`API_TIMEOUT_MS`	API 请求超时时间（毫秒）	取决于 SDK	`3000000`（50 分钟）
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	单次响应的最大输出 token 数	—	`32768`
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	禁用非必要的网络流量	`0`	`1`

API_TIMEOUT_MS：DeepSeek 等第三方服务响应可能较慢（尤其是高 Effort + 长上下文时），设置一个足够大的超时值避免误中断。3000000（50 分钟）是 DeepSeek 用户的常见设置。
CLAUDE_CODE_MAX_OUTPUT_TOKENS：限制 Claude 单次响应的最大长度。对于需要长输出的场景（如批量代码生成），可适当调高。
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC：设为 1 可禁用遥测、更新检查等非必要网络请求。在使用第三方 API 端点时建议开启，避免不必要的流量。

隐私与遥测

环境变量	说明	默认值
`CLAUDE_CODE_DISABLE_TELEMETRY`	禁用遥测数据上报	`0`
`NO_COLOR`	禁用 CLI 彩色输出	`0`

CLAUDE_CODE_DISABLE_TELEMETRY：设为 1 后 Claude Code 不会向 Anthropic 发送使用数据。如果你关心隐私或使用第三方 API 端点，建议开启。
NO_COLOR：设为 1 后终端输出为纯文本。在日志记录、CI/CD 环境或终端不支持颜色时使用。

其他环境变量

环境变量	说明
`CLAUDE_CODE_WORKING_DIRECTORY`	强制指定工作目录（覆盖当前目录）
`CLAUDE_CODE_PROJECT_DIR`	项目根目录路径
`DISABLE_AUTOUPDATER`	禁用自动更新检查
`HTTP_PROXY` / `HTTPS_PROXY`	HTTP/HTTPS 代理设置
`NODE_EXTRA_CA_CERTS`	额外的 CA 证书文件路径（企业代理环境）

环境变量优先级

当同一个环境变量在多个地方定义时，优先级如下：

1. Shell 环境变量（export 方式）或 .claude/.env 文件   ← 最高
2. .claude/settings.local.json 的 env 字段
3. .claude/settings.json 的 env 字段
4. ~/.claude/settings.json 的 env 字段                  ← 最低

⚠️ 特别注意：如果你在 shell 中 export ANTHROPIC_BASE_URL=...，它会覆盖所有配置文件中的同名设置。这是很多"配置明明改了但就是不生效"问题的根源。排查时先检查 env | grep ANTHROPIC。

13.6 VSCode 专属配置

以下配置项位于 VSCode 的 settings.json（Cmd+, 打开），控制 Claude Code 扩展在 VSCode 中的行为。它们与 Claude Code 自身的配置体系完全独立。

完整配置

json

{
  "claudeCode.preferredLocation": "sidebar",
  "claudeCode.enableNewConversationShortcut": true,
  "claudeCode.useCtrlEnterToSend": true,
  "claudeCode.allowDangerouslySkipPermissions": true,
  "claudeCode.disableLoginPrompt": true,
  "claudeCode.initialPermissionMode": "bypassPermissions",
  "claudeCode.environment": {}
}

逐项详解

claudeCode.preferredLocation

属性	说明
类型	`string`
默认值	`"sidebar"`
可选值	`"sidebar"` / `"editor"` / `"terminal"`

控制 Claude Code 面板在 VSCode 中的显示位置。

"sidebar"（推荐）：固定在侧边栏，与文件树并列。优势：有足够的竖向空间，与源代码在同一视图中，切换文件不中断对话
"editor"：以编辑器标签页形式打开。优势：可以和其他代码文件并排查看
"terminal"：在终端面板中显示。优势：适合 CLI 习惯的用户

推荐："sidebar"——这是大多数用户的共同偏好，也是 Claude Code 扩展的设计重心。

claudeCode.enableNewConversationShortcut

属性	说明
类型	`boolean`
默认值	`false`

是否启用 Cmd+N（macOS）/ Ctrl+N（Windows）快捷键来快速创建新会话。

true：一键创建新对话，适合同时处理多个独立任务的场景
false：需要通过命令面板 Claude Code: New Session 手动创建

推荐：true。当你同时在做一个功能开发和一个 Bug 修复时，快速新建会话能避免上下文污染。

claudeCode.useCtrlEnterToSend

属性	说明
类型	`boolean`
默认值	`false`

改变消息发送的按键行为。

true：Enter 换行，Ctrl+Enter（macOS: Cmd+Enter）发送消息
false（默认）：Enter 发送，Shift+Enter 换行

强烈推荐设为 true。默认行为下，当你贴一段多行代码并要求 Claude 修改时，很容易忘记按住 Shift 而不小心发送不完整的消息。改为 Ctrl+Enter 发送后，换行就是自然的 Enter，和所有文本编辑器一致。适应时间大约需要一小时，但之后能防止无数次误发送。

claudeCode.allowDangerouslySkipPermissions

属性	说明
类型	`boolean`
默认值	`false`

是否允许在 VSCode 扩展中使用 Bypass 权限模式。

true：扩展中的 Bypass 模式可用
false：即使配置了 Bypass，扩展中仍会限制

⚠️ 仅推荐资深用户开启。使用前提：你对 Claude Code 的行为有充分信任、项目使用 Git 管理、你熟练使用 git diff / git reset 回滚、工作项目不涉及生产环境直接操作。

claudeCode.disableLoginPrompt

属性	说明
类型	`boolean`
默认值	`false`

是否跳过 VSCode 扩展启动时的登录提示界面。

true：直接跳过登录提示，适合已通过环境变量或配置文件设置好认证信息的用户
false：每次冷启动显示登录界面

推荐：如果你通过环境变量（ANTHROPIC_AUTH_TOKEN）或 cc-switch 配置好了认证，设为 true 能减少不必要的界面跳转。

claudeCode.initialPermissionMode

属性	说明
类型	`string`
默认值	`"askBeforeEdit"`
可选值	`"askBeforeEdit"` / `"editAutomatically"` / `"planMode"` / `"autoMode"` / `"bypassPermissions"`

Claude Code 启动时的默认权限模式。

"askBeforeEdit"（默认）：每次修改前确认，最安全的起点
"editAutomatically"：直接编辑，危险操作仍需确认
"planMode"：先计划后执行
"autoMode"：自动判断是否需要确认
"bypassPermissions"：直接执行一切操作

初学者：保持默认 "askBeforeEdit"有经验用户："autoMode"资深用户："bypassPermissions"（需配合 allowDangerouslySkipPermissions）

关于各模式的详细对比和选择策略，见第 9 章：模式切换。

claudeCode.environment

属性	说明
类型	`object`
默认值	`{}`

在 VSCode 中为 Claude Code 扩展设置环境变量。这些变量仅对 VSCode 中的 Claude Code 扩展生效。

json

{
  "claudeCode.environment": {
    "ANTHROPIC_BASE_URL": "https://your-proxy.example.com",
    "CLAUDE_CODE_DISABLE_TELEMETRY": "1"
  }
}

与 settings.json 的 env 字段相比：

claudeCode.environment：仅 VSCode 扩展，不影响 CLI
settings.json 的 env：CLI 和 VSCode 扩展都生效

初学者 vs 资深用户推荐配置

配置项	初学者推荐	资深用户推荐
`preferredLocation`	`"sidebar"`	`"sidebar"`
`enableNewConversationShortcut`	`true`	`true`
`useCtrlEnterToSend`	`true`（强烈推荐）	`true`
`allowDangerouslySkipPermissions`	`false`	`true`
`disableLoginPrompt`	`false`	`true`
`initialPermissionMode`	`"askBeforeEdit"`	`"bypassPermissions"`

核心差异只在权限相关配置上——这恰好印证了"信任只能通过时间积累"的原则。

VSCode 快捷键参考

快捷键（macOS）	快捷键（Windows）	操作
`Cmd+Shift+L`	`Ctrl+Shift+L`	打开侧边栏对话面板
`Cmd+Shift+I`	`Ctrl+Shift+I`	打开内联编辑输入框
`Cmd+Esc`	`Ctrl+Esc`	快速打开 Claude Code
`Enter`	`Enter`	发送消息（默认）
`Shift+Enter`	`Shift+Enter`	消息内换行（默认）
`Ctrl+C`	`Ctrl+C`	中断 Claude 当前操作
`Cmd+K`	`Ctrl+K`	选中代码后打开上下文菜单
`Tab`	`Tab`	接受内联编辑建议
`Escape`	`Escape`	拒绝内联编辑建议 / 关闭面板

在 VSCode 中按 Cmd+K Cmd+S 打开快捷键设置，搜索 Claude Code 即可自定义所有绑定。

13.7 配置调试与排错

配置文件出问题时，Claude Code 可能行为异常、无法启动，或者不按你的预期执行。本节覆盖最常见的配置问题和排查方法。

验证当前生效的配置

方法 1：直接问 Claude

当前用的是哪个模型？配置文件在哪里？我的权限规则是什么？

Claude Code 可以读取自己的配置文件并告诉你合并后的最终结果。

方法 2：检查配置文件内容

bash

# 检查全局配置
cat ~/.claude/settings.json | python3 -m json.tool

# 检查项目配置
cat .claude/settings.json | python3 -m json.tool

# 检查本地覆盖
cat .claude/settings.local.json | python3 -m json.tool

使用 python3 -m json.tool 格式化输出，同时会做 JSON 语法检查——如果命令报错，说明 JSON 格式有问题。

方法 3：检查环境变量

bash

# 检查当前 shell 中与 Claude Code 相关的环境变量
env | grep -i anthropic
env | grep -i claude

常见配置错误

错误 1：JSON 语法错误

症状：Claude Code 启动时报错或配置不生效

常见原因：

多余的逗号（trailing comma）：JSON 不允许最后一个元素后面有逗号
缺少引号：所有 key 和 string value 必须用双引号
注释：标准 JSON 不支持 // 或 /* */ 注释（虽然 Claude Code 的 JSON 解析器可能容忍注释，但不建议依赖此行为）

json

// ❌ 错误——有注释和 trailing comma
{
  "model": "haiku",  // 注释会导致 JSON 解析失败
  "theme": "dark",
}

// ✅ 正确
{
  "model": "haiku",
  "theme": "dark"
}

解决：用 JSON linter 检查，或使用支持 JSON Schema 的编辑器（VSCode 自带 JSON 验证）。

错误 2：API 端点 URL 错误

症状：Claude Code 无法连接到模型，报连接超时或 404 错误

排查：

bash

# 测试 API 端点是否可达
curl -v https://api.deepseek.com/anthropic/v1/messages \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}]}'

常见问题：

URL 末尾多了或少了路径（如 /anthropic vs /anthropic/）
协议写错了（https:// vs http://）
API 密钥没有对应的访问权限

错误 3：模型设置冲突

症状：Claude Code 使用了预期之外的模型

常见场景：

ANTHROPIC_MODEL 环境变量和 model 字段同时设置了不同的值
Shell 中 export 了模型变量，覆盖了配置文件中的设置
cc-switch 修改了配置文件，但你手动编辑后又让它改回去了

排查：

先用 env | grep ANTHROPIC 检查 shell 环境
再检查各级配置文件的 model 和 env 字段
如果用了 cc-switch，确认它的配置是否覆盖了你的手动修改

错误 4：权限过严——Claude 无法工作

症状：Claude Code 每次操作都需要确认，即使是最简单的 git status

原因：permissions.allow 列表为空或太窄

json

// ❌ 太严——Claude 几乎什么都做不了
{
  "permissions": {
    "allow": [],
    "deny": ["Bash(*:*)"]
  }
}

解决：至少在 allow 中加入必要的安全操作：

json

{
  "permissions": {
    "allow": [
      "Bash(git:status)",
      "Bash(git:diff)",
      "Bash(git:log)",
      "Bash(git:add:*)",
      "Bash(git:commit:*)",
      "Bash(ls:*)",
      "Bash(pnpm:run:*)",
      "Bash(npm:run:*)",
      "WebSearch",
      "WebFetch"
    ]
  }
}

错误 5：权限过松——安全风险

症状：Claude Code 可以执行任意命令，包括危险操作

原因：permissions.deny 为空或 allow 中包含了过于宽泛的规则

json

// ❌ 太松——Claude 可以执行任何 bash 命令
{
  "permissions": {
    "allow": ["Bash(*:*)", "WebSearch", "WebFetch"]
  }
}

解决：至少加入基础的安全 deny 规则：

json

{
  "permissions": {
    "allow": ["Bash(git:*)"],
    "deny": [
      "Bash(rm:-rf:*)",
      "Bash(sudo:*)",
      "Bash(git:push:--force:*)",
      "Bash(git:reset:--hard:*)"
    ]
  }
}

错误 6：配置文件位置错误

症状：配置修改后不生效

常见问题：

把全局配置写到了项目目录下的 ~/.claude/settings.json（~ 应该在用户目录下）
项目配置放在了项目根目录而不是 .claude/ 子目录下
文件命名为 setting.json（少了个 s）或 Setting.json（大小写）

正确的文件位置：

~/.claude/settings.json                     ← 全局配置（用户目录下）
your-project/.claude/settings.json          ← 项目配置（项目 .claude/ 目录下）
your-project/.claude/settings.local.json    ← 本地覆盖（项目 .claude/ 目录下）

调试技巧

1. 启用详细日志

在对话中观察 Claude Code 的工具调用日志——每一次配置相关的判断（如权限检查、环境变量读取）都会在日志中体现。

2. 二分法定位问题

如果修改配置后出现异常，用二分法回退：

先移除 .claude/settings.local.json（最高优先级，最可能出问题）
再移除 .claude/settings.json 中的最近修改
最后检查 ~/.claude/settings.json

每移除一层，重启 Claude Code 测试行为是否恢复。这样能快速定位是哪一层、哪个字段出了问题。

3. 使用最小化配置测试

创建一个只包含最少字段的配置来验证基础功能是否正常：

json

{
  "model": "haiku",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxx"
  }
}

如果最小配置能正常工作，再逐步添加其他字段，每添加一个就测试一次——这样能精确找到出问题的配置项。

4. 重启和清除缓存

有些配置修改不会即时生效。如果怀疑缓存问题：

bash

# 清除 VSCode 扩展缓存
rm -rf ~/Library/Application\ Support/Code/User/globalStorage/anthropic.claude-code

# 重启 VSCode
# Cmd+Q 完全退出，再重新打开

13.8 配置模板集

以下是五套可以直接使用的配置模板，覆盖从初学者到高级用户的不同需求。

模板一：初学者安全模板

适合使用 Claude Code 第一周的用户。Ask 模式，严格权限，最大安全保障。

json

{
  "model": "claude-sonnet-4-6",
  "theme": "dark",
  "autoCompact": true,
  "permissions": {
    "allow": [
      "Bash(git:status)",
      "Bash(git:diff)",
      "Bash(git:log)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm:-rf:*)",
      "Bash(sudo:*)",
      "Bash(git:push:--force:*)",
      "Bash(git:reset:--hard:*)",
      "Bash(git:clean:-fd:*)",
      "Bash(git:branch:-D:*)",
      "Bash(chmod:*)",
      "Bash(curl:*|sh)",
      "Bash(wget:*|sh)"
    ]
  }
}

配套 VSCode 设置：

json

{
  "claudeCode.preferredLocation": "sidebar",
  "claudeCode.enableNewConversationShortcut": true,
  "claudeCode.useCtrlEnterToSend": true,
  "claudeCode.initialPermissionMode": "askBeforeEdit"
}

特点：Claude 只能读取 Git 状态和搜索网络，任何文件修改和命令执行都需要你确认。这是最安全的学习模式。

模板二：日常开发模板

适合使用 Claude Code 一个月以上的开发者。Auto 模式，平衡效率与安全。

json

{
  "model": "sonnet",
  "theme": "dark",
  "autoCompact": true,
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(pnpm:*)",
      "Bash(npm:*)",
      "Bash(node:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(which:*)",
      "Bash(mkdir:*)",
      "Bash(cp:*)",
      "Bash(mv:*)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm:-rf:*)",
      "Bash(sudo:*)",
      "Bash(git:push:--force:*)",
      "Bash(git:reset:--hard:*)",
      "Bash(git:clean:-fd:*)",
      "Bash(git:branch:-D:*)",
      "Bash(curl:*-o-*|sh)",
      "Bash(wget:*|sh)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "echo '文件已修改：${CLAUDE_TOOL_FILE_PATH}'"
      }
    ]
  }
}

配套 VSCode 设置：

json

{
  "claudeCode.preferredLocation": "sidebar",
  "claudeCode.enableNewConversationShortcut": true,
  "claudeCode.useCtrlEnterToSend": true,
  "claudeCode.initialPermissionMode": "autoMode"
}

特点：Claude 可以执行大部分日常开发命令（Git 操作、包管理、文件浏览），危险操作被禁止。

模板三：高级用户模板

适合使用 Claude Code 三个月以上的资深用户。Bypass 模式，最小摩擦。

json

{
  "model": "sonnet",
  "theme": "dark",
  "autoCompact": true,
  "permissions": {
    "allow": [
      "Bash(*:*)",
      "WebSearch",
      "WebFetch",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm:-rf:~:*)",
      "Bash(rm:-rf:/:*)",
      "Bash(sudo:rm:-rf:*)",
      "Bash(git:push:--force:main)",
      "Bash(git:push:--force:master)",
      "Bash(git:reset:--hard:HEAD~*:*)",
      "Bash(curl:*-o-*|sh)",
      "Bash(wget:*|sh)"
    ]
  }
}

配套 VSCode 设置：

json

{
  "claudeCode.preferredLocation": "sidebar",
  "claudeCode.enableNewConversationShortcut": true,
  "claudeCode.useCtrlEnterToSend": true,
  "claudeCode.allowDangerouslySkipPermissions": true,
  "claudeCode.disableLoginPrompt": true,
  "claudeCode.initialPermissionMode": "bypassPermissions"
}

特点：几乎无摩擦，Claude 可以自主执行绝大多数操作。但仍保留了对毁灭性操作（删除用户目录、sudo rm -rf、force push 到保护分支）的禁止。

⚠️ 使用前提：你已深度使用 Claude Code 超过三个月，对行为模式有精确预期；项目使用 Git 管理且你熟练使用 git diff / git reset 回滚；每次操作后会在 Diff 审查区过一遍修改。

模板四：DeepSeek 专用模板

使用 DeepSeek 模型，优化成本和性能。将 Haiku 映射到 Flash（日常），Sonnet 和 Opus 映射到 Pro（复杂任务）。

json

{
  "model": "haiku",
  "theme": "dark",
  "autoCompact": true,
  "autoCompactTokenLimit": 500000,
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash[1M]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "deepseek-v4-flash",
    "ANTHROPIC_MODEL": "deepseek-v4-flash",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_DISABLE_TELEMETRY": "1"
  },
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(pnpm:*)",
      "Bash(npm:*)",
      "Bash(node:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm:-rf:*)",
      "Bash(sudo:*)",
      "Bash(git:push:--force:*)",
      "Bash(git:reset:--hard:*)"
    ]
  }
}

⚠️ 注意：ANTHROPIC_AUTH_TOKEN 不应写在此模板中。将它放在 .claude/settings.local.json 的 env 字段中，避免密钥泄露。

配套 settings.local.json（放密钥）：

json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的-deepseek-api-key"
  }
}

特点：

autoCompactTokenLimit 调高到 500000，充分利用 DeepSeek V4 的 1M 上下文
API_TIMEOUT_MS 设为 3000000（50 分钟），适应 DeepSeek 高 Effort 下的长响应时间
禁用了遥测和非必要流量（使用第三方 API 时这些流量没有意义）
默认模型为 "haiku"（映射到 Flash），需要强推理时通过 / 菜单切换到 "opus"（映射到 Pro）

模板五：双模型模板

同时配置 Anthropic 官方和 DeepSeek，通过 cc-switch 或手动切换在两者之间选择。日常开发用 DeepSeek（省钱），复杂任务用 Claude Opus（保质量）。

json

{
  "model": "haiku",
  "theme": "dark",
  "autoCompact": true,
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(pnpm:*)",
      "Bash(npm:*)",
      "Bash(node:*)",
      "Bash(ls:*)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm:-rf:*)",
      "Bash(sudo:*)",
      "Bash(git:push:--force:*)",
      "Bash(git:reset:--hard:*)"
    ]
  }
}

配套 settings.local.json（双密钥 + DeepSeek 映射）：

json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的-deepseek-api-key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash[1M]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "deepseek-v4-flash",
    "ANTHROPIC_MODEL": "deepseek-v4-flash",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

切换方式：

日常使用：默认走 DeepSeek（ANTHROPIC_BASE_URL 指向 DeepSeek）
切换到 Anthropic 官方：使用 cc-switch 选择 Anthropic 官方模型，或手动注释掉 local.json 中的 DeepSeek 相关环境变量
按任务切换：简单任务用 / 菜单选 Haiku（映射到 Flash），复杂任务选 Opus（映射到 Pro）

模板选择建议

使用阶段	推荐模板	核心理由
第 1-2 周	模板一（初学者）	每一步确认是学习过程，安全第一
第 3-8 周	模板二（日常开发）	Auto 模式在效率和安全间取得平衡
3 个月以上	模板三（高级用户）	最小摩擦，思维不被打断
使用 DeepSeek	模板四（DeepSeek）	针对 DeepSeek 优化的超时和上下文配置
多模型策略	模板五（双模型）	根据任务在省钱和质量之间灵活切换

记住：这些模板是起点而非终点。随着你对 Claude Code 行为的理解加深，你应该不断调整配置以匹配自己的使用习惯。

13.9 本章小结

本章覆盖了 Claude Code 配置体系的完整图景。让我们回顾核心要点：

四层配置架构

settings.local.json  →  个人密钥、本地路径、模型偏好     ← 最高优先级，不提交
settings.json        →  团队共享的权限、hooks、MCP       ← 提交 Git
~/.claude/settings   →  个人默认设置，所有项目生效        ← 全局基线
内置默认值            →  出厂设置                          ← 兜底

理解了这个架构，你就理解了整个配置体系。所有后续的配置操作——无论是修改一个环境变量、添加一条权限规则、还是为团队编写项目配置——都可以在这个框架下找到正确的位置。

核心原则

密钥不进 Git：API 密钥、Token 等敏感信息始终放在 settings.local.json 或 ~/.claude/.env 中
团队共享的放项目配置：权限规则、MCP 服务器、Hooks——提交到 Git，团队成员自动获得
个人偏好的放全局配置：默认模型、主题、界面设置——不强制团队成员
修改后要测试：改完配置后，用一个简单任务验证 Claude Code 行为是否符合预期
JSON 语法要正确：养成用 linter 检查 JSON 的习惯，避免因一个多余的逗号导致配置全部失效

配置体系的"设计哲学"

Claude Code 的配置体系体现了一个清晰的理念：给团队足够的控制力，给个人足够的自由度。

团队通过项目配置确保安全基线（deny 规则）和必要的自动化（hooks、MCP）
个人通过 local 覆盖满足本地需求，而不影响团队其他成员
全局配置作为"你的默认工作方式"，在所有项目中保持一致

当你理解了这一点，配置就不再是一个"要记的东西"，而是你使用 Claude Code 的方式——你可以根据自己的信任程度、项目风险、成本偏好来设计一套最适合自己的配置方案。

与其他章节的关系

权限规则的语法和策略：见第 14 章：权限与安全
MCP 服务器的配置和使用：见第 15 章：MCP 协议与服务器
Plugins 的安装和管理：见第 16 章：插件系统
Hooks 的编写和调试：见第 18 章：Hooks 钩子系统
模式选择的详细对比：见第 9 章：模式切换
CLAUDE.md 的编写规范：见第 12 章：CLAUDE.md

下一步：第 14 章将深入权限与安全体系——allow/deny 规则的完整语法、通配符匹配机制、常见安全场景的配置模板、以及沙箱与安全边界的最佳实践。配置体系定义了你让 Claude Code 能走多远，而权限体系定义了你让 Claude Code 能走多深。

第 13 章：配置体系深度解析 ​

13.1 四层配置优先级 ​

优先级图 ​

各层职责 ​

合并规则 ​

当各层生效 ​

验证当前配置 ​

13.2 ~/.claude/settings.json 完整参考 ​

完整配置结构 ​

逐项详解 ​

13.3 .claude/settings.json 项目配置 ​

团队配置的职责 ​

完整示例 ​

团队配置的设计考量 ​

版本控制 ​

13.4 .claude/settings.local.json 本地覆盖 ​

应该放在 local.json 中的内容 ​

完整示例 ​

它如何与项目配置协作 ​

13.5 环境变量完整参考 ​

核心环境变量 ​

模型映射变量 ​

超时与性能 ​

隐私与遥测 ​

其他环境变量 ​

环境变量优先级 ​

推荐的环境变量配置方式 ​

13.6 VSCode 专属配置 ​

完整配置 ​

逐项详解 ​

初学者 vs 资深用户推荐配置 ​

VSCode 快捷键参考 ​

13.7 配置调试与排错 ​

验证当前生效的配置 ​

常见配置错误 ​

调试技巧 ​

13.8 配置模板集 ​

模板一：初学者安全模板 ​

模板二：日常开发模板 ​

模板三：高级用户模板 ​

模板四：DeepSeek 专用模板 ​

模板五：双模型模板 ​

模板选择建议 ​

13.9 本章小结 ​

四层配置架构 ​

核心原则 ​

配置体系的"设计哲学" ​

与其他章节的关系 ​

第 13 章：配置体系深度解析

13.1 四层配置优先级

优先级图

各层职责

合并规则

当各层生效

验证当前配置

13.2 ~/.claude/settings.json 完整参考

完整配置结构

逐项详解

13.3 .claude/settings.json 项目配置

团队配置的职责

完整示例

团队配置的设计考量

版本控制

13.4 .claude/settings.local.json 本地覆盖

应该放在 local.json 中的内容

完整示例

它如何与项目配置协作

13.5 环境变量完整参考

核心环境变量

模型映射变量

超时与性能

隐私与遥测

其他环境变量

环境变量优先级

推荐的环境变量配置方式

13.6 VSCode 专属配置

完整配置

逐项详解

初学者 vs 资深用户推荐配置

VSCode 快捷键参考

13.7 配置调试与排错

验证当前生效的配置

常见配置错误

调试技巧

13.8 配置模板集

模板一：初学者安全模板

模板二：日常开发模板

模板三：高级用户模板

模板四：DeepSeek 专用模板

模板五：双模型模板

模板选择建议

13.9 本章小结

四层配置架构

核心原则

配置体系的"设计哲学"

与其他章节的关系