职责概述

解决的问题:Claude Code 作为一个可编程的 AI 编程助手,需要一种灵活的配置机制,让不同角色(个人开发者、团队、企业管理员)能精确控制模型选择、权限边界、安全策略、UI 行为等 60+ 个维度。配置必须支持层级覆盖(用户级→项目级→企业级),同时保证向后兼容和安全隔离。

应用场景:① 个人开发者想默认用 opus 模型,同时开启自动记忆 ② 团队项目需要统一 MCP 服务器配置和权限规则,提交到 git ③ 企业管理员通过 managed-settings.json 限制可用模型、禁用危险模式、强制沙盒 ④ CI/CD 管道通过 --settings 注入一次性配置。

一句话理解:就像 VS Code 的 settings.json——五层优先级(用户→项目→本地→命令行→企业策略),支持深度合并、数组去重拼接、"先到先得"策略,用 Zod Schema 保证类型安全。

配置层级体系

源码位置:utils/settings/settings.ts:645utils/settings/constants.ts

1. pluginSettings
插件注入的基础配置(最低优先级)
2. userSettings
~/.claude/settings.json
用户全局配置
3. projectSettings
.claude/settings.json
可提交 git 的项目配置
4. localSettings
.claude/settings.local.json
本机独有(gitignore)
5. flagSettings
--settings <path>
CLI/SDK 一次性注入
policySettings(企业策略层)

独立于上述 5 层,采用 "first source wins" 策略,4 个子源竞争,第一个有内容的胜出:

远程 API
/api/claude_code/settings
>
MDM
macOS plist / Win HKLM
>
文件
managed-settings.json + .d/
>
HKCU
Windows 用户注册表
层级文件路径谁来写合并策略
userSettings~/.claude/settings.json用户自己深度合并
projectSettings.claude/settings.json项目团队深度合并
localSettings.claude/settings.local.json用户本机深度合并
flagSettingsCLI 参数 / SDK inline自动化管道深度合并
policySettingsmanaged-settings.json / MDM企业管理员first source wins

合并规则

源码位置:utils/settings/settings.ts:529-547

function settingsMergeCustomizer(objValue, srcValue) {
  if (Array.isArray(objValue) && Array.isArray(srcValue)) {
    return uniq([...objValue, ...srcValue])  // 数组:拼接 + 去重
  }
  return undefined  // 其他:lodash 默认深度合并
}
数据类型合并行为示例
数组底层 + 高层拼接,然后去重用户 allow=["A"] + 项目 allow=["B"] → ["A","B"]
对象深度合并,高层覆盖低层用户 env={X:"1"} + 项目 env={Y:"2"} → {X:"1",Y:"2"}
标量高层直接覆盖低层用户 model="opus" + 项目 model="sonnet" → "sonnet"
policySettingsfirst source wins,不合并远程有内容 → 直接用,不再看 MDM

模型与推理

参数类型默认值含义与使用场景
model string 平台默认 sonnet 覆盖使用的模型。可选 "opus" "sonnet" "haiku" 或完整模型 ID。
场景:个人用户切 opus 获得更强推理能力。
availableModels string[] 无(全部可用) 企业模型白名单。支持 family alias("opus")、version prefix("opus-4-5")、完整 ID。空数组=仅默认模型。
场景:企业限制员工只用 sonnet 控制成本。
modelOverrides Record<string,string> 模型 ID 映射。如 {"claude-opus-4-6": "arn:aws:bedrock:..."}
场景:Bedrock/Vertex 用户将 Anthropic ID 映射为云厂商 ARN。
advisorModel string 服务端 advisor 工具使用的模型。
alwaysThinkingEnabled boolean true 启用扩展思考。设 false 关闭。
场景:简单任务关掉思考加速响应。
effortLevel "low"|"medium"|"high"|"max" 推理努力级别。max 仅内部可用。
场景:日常设 medium,复杂 bug 设 high。
fastMode boolean false 快速模式(Opus 4.6 加速输出)。
fastModePerSessionOptIn boolean false 快速模式仅当次会话有效,下次启动不持久化。

权限系统

源码位置:utils/settings/types.ts:42-85utils/settings/permissionValidation.ts

参数类型含义与使用场景
permissions.allowstring[]自动放行的操作规则。场景:信任的 git 操作不需要每次确认。
permissions.denystring[]明确拒绝的操作规则。优先于 allow。
permissions.askstring[]总是弹确认的操作规则。
permissions.defaultMode enum 默认权限模式:
"default" — 标准模式,每次询问
"plan" — 计划模式,先规划再执行
"acceptEdits" — 自动接受文件编辑
"dontAsk" — 不弹确认(危险)
"auto" — AI 自动判断(功能门控)
permissions.disableBypassPermissionsMode"disable"禁用危险模式(bypass),企业安全策略。
permissions.disableAutoMode"disable"禁用 auto 模式。
permissions.additionalDirectoriesstring[]扩展权限作用域到额外目录。
allowManagedPermissionRulesOnlyboolean仅托管设置的权限规则生效(企业策略)。
skipDangerousModePermissionPromptboolean已接受 bypass 模式对话框。注意:projectSettings 中此值被忽略(防 RCE)。
skipAutoPermissionPromptboolean已接受 auto 模式对话框。
// 权限规则格式示例
{
  "permissions": {
    "allow": [
      "Bash(git *)",      // Bash 命令前缀匹配
      "Bash(npm test *)", // npm test 自动放行
      "Read",             // 所有读取操作
      "Edit",             // 所有编辑操作
      "Glob"              // 文件搜索
    ],
    "deny": ["Bash(rm -rf /*)"],
    "ask": ["Bash(curl *)"],
    "defaultMode": "plan"
  }
}

MCP 服务器管理

参数类型含义与使用场景
enableAllProjectMcpServersboolean自动批准项目所有 MCP 服务器。场景:个人项目不想逐个确认。
enabledMcpjsonServersstring[]已批准的 .mcp.json 中的服务器名列表。
disabledMcpjsonServersstring[]已拒绝的 .mcp.json 中的服务器名列表。
allowedMcpServersobject[]企业 MCP 白名单。每项三选一:serverNameserverCommandserverUrl。空数组=全部禁止。
deniedMcpServersobject[]企业 MCP 黑名单。优先于白名单——同时在两个列表中的服务器会被拒绝。
allowManagedMcpServersOnlyboolean仅托管设置的 MCP 白名单生效。
// 企业 MCP 白名单示例
{
  "allowedMcpServers": [
    { "serverName": "internal-tools" },
    { "serverCommand": ["npx", "my-mcp-server"] },
    { "serverUrl": "https://*.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

Hook 系统

源码位置:schemas/hooks.tsutils/settings/types.ts:435

参数类型含义
hooksobject生命周期钩子,按事件名分组。详见 Hook 机制
disableAllHooksboolean禁用所有 hooks 和 statusLine 执行。
allowManagedHooksOnlyboolean仅执行托管设置的 hooks(企业策略)。
allowedHttpHookUrlsstring[]HTTP hook 的 URL 白名单。支持 * 通配符。空数组=禁止所有。
httpHookAllowedEnvVarsstring[]HTTP hook 可注入到 headers 的环境变量名白名单。

支持的 Hook 事件:

PreToolUse PostToolUse Notification UserPromptSubmit SessionStart SessionEnd Stop SubagentStop PreCompact PostCompact TeammateIdle TaskCreated TaskCompleted
// Hook 配置示例
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "audit-log.sh"}]
    }],
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{"type": "command", "command": "echo 'file modified' >> log.txt"}]
    }]
  }
}

记忆与自动学习

源码位置:utils/settings/types.ts:938-955memdir/paths.ts

参数类型默认值含义与使用场景
autoMemoryEnabled boolean false 启用自动记忆(读写 ~/.claude/projects/<cwd>/memory/)。
场景:跨会话保留项目知识。
autoMemoryDirectory string ~/.claude/projects/<cwd>/memory/ 自定义记忆存储目录,支持 ~/ 前缀。
安全限制:projectSettings(.claude/settings.json)中设置此值会被忽略,防止恶意项目重定向记忆路径。
autoDreamEnabled boolean 服务端默认 启用后台记忆整理(auto-dream),自动从对话中提取结构化记忆。
场景:长期项目自动积累知识库。

环境变量

源码位置:utils/settings/types.ts:35-37

参数类型含义
env Record<string,string> 为 Claude Code 会话注入环境变量。所有值会被 z.coerce.string() 强制转为字符串。
重要:很多高级配置通过环境变量实现,如 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 控制压缩阈值。
{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",  // 上下文达 50% 时触发压缩
    "MY_API_KEY": "sk-xxx",
    "DISABLE_AUTOUPDATER": "1"
  }
}

沙盒配置

源码位置:entrypoints/sandboxTypes.ts

参数类型含义
sandbox.enabledboolean启用沙盒隔离。
sandbox.failIfUnavailableboolean沙盒不可用时是否失败(vs 静默降级)。
sandbox.autoAllowBashIfSandboxedboolean在沙盒内的 Bash 命令自动放行。
sandbox.allowUnsandboxedCommandsstring[]不需要沙盒的命令列表。
网络控制
sandbox.network.allowedDomainsstring[]允许的网络域名白名单。
sandbox.network.allowManagedDomainsOnlyboolean仅托管域名生效(企业)。
sandbox.network.allowUnixSocketsstring[]允许的 Unix socket 路径(仅 macOS)。
sandbox.network.allowAllUnixSocketsboolean允许所有 Unix socket。
sandbox.network.allowLocalBindingboolean允许本地端口绑定。
文件系统控制
sandbox.filesystem.allowWritestring[]额外允许写入的路径。
sandbox.filesystem.denyWritestring[]拒绝写入的路径。
sandbox.filesystem.denyReadstring[]拒绝读取的路径。
sandbox.filesystem.allowReadstring[]在 denyRead 中重新允许的路径。
sandbox.filesystem.allowManagedReadPathsOnlyboolean仅托管读取路径生效。
其他
sandbox.ignoreViolationsboolean忽略沙盒违规(仅记录日志)。
sandbox.excludedCommandsstring[]排除出沙盒的命令。
sandbox.enableWeakerNestedSandboxboolean允许弱化嵌套沙盒。
sandbox.enableWeakerNetworkIsolationboolean允许弱化网络隔离。

UI 与显示

参数类型含义
outputStylestring助手回复的输出风格。
languagestring偏好语言,如 "japanese" "chinese" "spanish"。影响回复语言和语音听写。
syntaxHighlightingDisabledboolean禁用 diff 语法高亮。
terminalTitleFromRenameboolean/rename 是否更新终端标题(默认 true)。
prefersReducedMotionboolean减少动画(无障碍辅助)。
spinnerTipsEnabledboolean显示 spinner 提示。
spinnerVerbs{mode, verbs[]}自定义 spinner 动词。mode:"append" 追加,"replace" 替换。
spinnerTipsOverride{excludeDefault?, tips[]}自定义 spinner 提示文本。excludeDefault:true 只显示自定义。
showThinkingSummariesbooleantranscript 视图显示思考摘要(默认 false)。
showClearContextOnPlanAcceptbooleanplan 审批对话框显示"清除上下文"选项。
promptSuggestionEnabledboolean启用提示建议。
defaultView"chat"|"transcript"默认 transcript 视图(功能门控)。
feedbackSurveyRatenumber (0~1)反馈问卷弹出概率。0.05 即 5% 概率弹出。
statusLine{type:"command", command:string, padding?:number}自定义状态栏显示。

认证与企业

参数类型含义
apiKeyHelperstring输出认证值的脚本路径。
awsCredentialExportstring导出 AWS 凭证的脚本路径。
awsAuthRefreshstring刷新 AWS 认证的脚本路径。
gcpAuthRefreshstring刷新 GCP 认证的命令,如 "gcloud auth application-default login"
forceLoginMethod"claudeai"|"console"强制登录方式。"claudeai" = Claude Pro/Max,"console" = Console 计费。
forceLoginOrgUUIDstringOAuth 登录的组织 UUID。
otelHeadersHelperstring输出 OpenTelemetry headers 的脚本路径。
companyAnnouncementsstring[]启动时随机显示的公司公告(企业内部使用)。

插件与市场

参数类型含义
enabledPluginsRecord<string, boolean|string[]>已启用的插件。Key 格式 "pluginName@marketplaceName"
pluginConfigsRecord<string, object>插件配置,含 mcpServersoptions 子字段。
extraKnownMarketplacesRecord<string, object>额外市场源(通常在项目 settings 中配置团队共享市场)。
strictKnownMarketplacesobject[]企业市场白名单(仅托管设置)。下载前拦截。
blockedMarketplacesobject[]企业市场黑名单。
strictPluginOnlyCustomizationboolean|("skills"|"agents"|"hooks"|"mcp")[]限制非插件自定义源。true=锁定全部,数组=锁定指定项。
pluginTrustMessagestring插件信任警告追加的自定义消息(仅托管设置)。
// 插件配置示例
{
  "enabledPlugins": {
    "formatter@anthropic-tools": true
  },
  "pluginConfigs": {
    "formatter@anthropic-tools": {
      "options": { "tabSize": 2 }
    }
  }
}

Git 与 Attribution

参数类型含义
attribution.commitstringGit 提交的署名文本。空字符串 ""=隐藏署名。
attribution.prstringPR 描述的署名文本。空字符串=隐藏。
includeCoAuthoredByboolean已废弃,请用 attribution 代替。
includeGitInstructionsboolean系统提示中包含 Git 操作指引(默认 true)。

自动更新

参数类型含义
autoUpdatesChannel"latest"|"stable"自动更新频道。"latest" = 最新版,"stable" = 稳定版。
minimumVersionstring最低版本号,防止切换到 stable 频道时被降级。

文件与工作区

参数类型含义
fileSuggestion{type:"command", command:string}@ 提及的自定义文件建议命令。
respectGitignoreboolean文件选择器是否尊重 .gitignore(默认 true)。.ignore 始终被尊重。
cleanupPeriodDaysnumber (≥0)聊天记录保留天数(默认 30)。设 0 完全禁用持久化。
defaultShell"bash"|"powershell"! 命令的默认 shell。所有平台默认 bash。
worktree.symlinkDirectoriesstring[]worktree 中符号链接的目录,如 ["node_modules"]
worktree.sparsePathsstring[]worktree 稀疏检出路径,大型 monorepo 加速。
plansDirectorystring计划文件目录,相对项目根。默认 ~/.claude/plans/
claudeMdExcludesstring[]排除加载的 CLAUDE.md glob 模式。

SSH 远程连接

源码位置:utils/settings/types.ts:1013-1052

参数类型含义
sshConfigs[].idstring唯一标识符。
sshConfigs[].namestring显示名称。
sshConfigs[].sshHoststringSSH 主机(user@hostname 或别名)。
sshConfigs[].sshPortnumberSSH 端口(默认 22)。
sshConfigs[].sshIdentityFilestring私钥文件路径。
sshConfigs[].startDirectorystring远程默认工作目录,支持 ~/ 展开。
// SSH 配置示例
{
  "sshConfigs": [
    {
      "id": "dev-server",
      "name": "开发服务器",
      "sshHost": "dev.example.com",
      "sshPort": 2222,
      "sshIdentityFile": "~/.ssh/id_rsa",
      "startDirectory": "~/projects/my-app"
    }
  ]
}

实战配置示例

个人开发者(~/.claude/settings.json)

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "opus",
  "alwaysThinkingEnabled": true,
  "effortLevel": "high",
  "autoMemoryEnabled": true,
  "language": "chinese",
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
  },
  "permissions": {
    "allow": ["Bash(git *)", "Bash(npm *)", "Read", "Edit", "Glob"],
    "deny": ["Bash(rm -rf /*)"],
    "defaultMode": "plan"
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{"type": "command", "command": "echo 'modified' >> /tmp/cc-log.txt"}]
    }]
  },
  "cleanupPeriodDays": 14,
  "terminalTitleFromRename": true,
  "spinnerTipsEnabled": true
}

团队项目(.claude/settings.json,提交 git)

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run lint *)",
      "Read",
      "Edit",
      "Glob"
    ],
    "defaultMode": "plan"
  },
  "enabledMcpjsonServers": ["database", "internal-api"],
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{"type": "command", "command": "npm run format"}]
    }]
  }
}

企业管理员(managed-settings.json,仅 admin 可写)

{
  "availableModels": ["sonnet"],
  "permissions": {
    "deny": ["Bash(curl *external*)"],
    "disableBypassPermissionsMode": "disable"
  },
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["api.internal.com"],
      "allowManagedDomainsOnly": true
    }
  },
  "strictKnownMarketplaces": [
    { "source": { "type": "url", "url": "https://plugins.internal.com/marketplace.json" } }
  ],
  "strictPluginOnlyCustomization": ["hooks", "mcp"],
  "forceLoginMethod": "console",
  "companyAnnouncements": ["请勿将敏感数据粘贴到对话中"],
  "cleanupPeriodDays": 7
}

源码索引

文件职责
utils/settings/types.tsZod Schema 定义,60+ 参数的单源真相(817 行)
utils/settings/settings.ts配置加载引擎:文件解析、5 层合并、缓存、文件监听
utils/settings/constants.tsSETTING_SOURCES 枚举、SettingSource 类型
utils/settings/validation.tsZod 错误格式化、JSON Schema 生成
utils/settings/permissionValidation.tsPermissionRuleSchema:Bash 前缀/文件模式/MCP 规则验证
utils/settings/settingsCache.ts会话级缓存:per-source cache + parsed-file cache
utils/settings/changeDetector.tschokidar 文件监听,配置变更自动重载
utils/settings/applySettingsChange.ts配置变更→AppState 同步(重载权限、hooks、effort level)
utils/settings/managedPath.ts平台托管路径:macOS=/Library/Application Support/ClaudeCode
utils/settings/mdm/settings.tsMDM 配置读取:macOS plist / Windows HKLM+HKCU
utils/settings/pluginOnlyPolicy.tsstrictPluginOnlyCustomization 策略执行
tools/ConfigTool/supportedSettings.tsUI 可设置的配置项元数据
entrypoints/sandboxTypes.ts沙盒配置 Zod Schema
schemas/hooks.tsHook 系统 Zod Schema(13 种事件 × 4 种类型)
services/remoteManagedSettings/index.ts远程托管配置拉取 + ETag 缓存
services/settingsSync/index.ts多设备配置同步(上传用户设置 + memory)