settings.json 全局参数配置
60+ 参数的全量手册:从模型选择、权限控制、沙盒隔离到记忆系统的完整配置指南,附源码出处
职责概述
解决的问题:Claude Code 作为一个可编程的 AI 编程助手,需要一种灵活的配置机制,让不同角色(个人开发者、团队、企业管理员)能精确控制模型选择、权限边界、安全策略、UI 行为等 60+ 个维度。配置必须支持层级覆盖(用户级→项目级→企业级),同时保证向后兼容和安全隔离。
应用场景:① 个人开发者想默认用 opus 模型,同时开启自动记忆 ② 团队项目需要统一 MCP 服务器配置和权限规则,提交到 git ③ 企业管理员通过 managed-settings.json 限制可用模型、禁用危险模式、强制沙盒 ④ CI/CD 管道通过 --settings 注入一次性配置。
一句话理解:就像 VS Code 的 settings.json——五层优先级(用户→项目→本地→命令行→企业策略),支持深度合并、数组去重拼接、"先到先得"策略,用 Zod Schema 保证类型安全。
配置层级体系
源码位置:utils/settings/settings.ts:645,utils/settings/constants.ts
~/.claude/settings.json用户全局配置
.claude/settings.json可提交 git 的项目配置
.claude/settings.local.json本机独有(gitignore)
--settings <path>CLI/SDK 一次性注入
独立于上述 5 层,采用 "first source wins" 策略,4 个子源竞争,第一个有内容的胜出:
| 层级 | 文件路径 | 谁来写 | 合并策略 |
|---|---|---|---|
| userSettings | ~/.claude/settings.json | 用户自己 | 深度合并 |
| projectSettings | .claude/settings.json | 项目团队 | 深度合并 |
| localSettings | .claude/settings.local.json | 用户本机 | 深度合并 |
| flagSettings | CLI 参数 / SDK inline | 自动化管道 | 深度合并 |
| policySettings | managed-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" |
| policySettings | first 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-85,utils/settings/permissionValidation.ts
| 参数 | 类型 | 含义与使用场景 |
|---|---|---|
permissions.allow | string[] | 自动放行的操作规则。场景:信任的 git 操作不需要每次确认。 |
permissions.deny | string[] | 明确拒绝的操作规则。优先于 allow。 |
permissions.ask | string[] | 总是弹确认的操作规则。 |
permissions.defaultMode |
enum | 默认权限模式: • "default" — 标准模式,每次询问• "plan" — 计划模式,先规划再执行• "acceptEdits" — 自动接受文件编辑• "dontAsk" — 不弹确认(危险)• "auto" — AI 自动判断(功能门控)
|
permissions.disableBypassPermissionsMode | "disable" | 禁用危险模式(bypass),企业安全策略。 |
permissions.disableAutoMode | "disable" | 禁用 auto 模式。 |
permissions.additionalDirectories | string[] | 扩展权限作用域到额外目录。 |
allowManagedPermissionRulesOnly | boolean | 仅托管设置的权限规则生效(企业策略)。 |
skipDangerousModePermissionPrompt | boolean | 已接受 bypass 模式对话框。注意:projectSettings 中此值被忽略(防 RCE)。 |
skipAutoPermissionPrompt | boolean | 已接受 auto 模式对话框。 |
// 权限规则格式示例
{
"permissions": {
"allow": [
"Bash(git *)", // Bash 命令前缀匹配
"Bash(npm test *)", // npm test 自动放行
"Read", // 所有读取操作
"Edit", // 所有编辑操作
"Glob" // 文件搜索
],
"deny": ["Bash(rm -rf /*)"],
"ask": ["Bash(curl *)"],
"defaultMode": "plan"
}
}MCP 服务器管理
| 参数 | 类型 | 含义与使用场景 |
|---|---|---|
enableAllProjectMcpServers | boolean | 自动批准项目所有 MCP 服务器。场景:个人项目不想逐个确认。 |
enabledMcpjsonServers | string[] | 已批准的 .mcp.json 中的服务器名列表。 |
disabledMcpjsonServers | string[] | 已拒绝的 .mcp.json 中的服务器名列表。 |
allowedMcpServers | object[] | 企业 MCP 白名单。每项三选一:serverName、serverCommand、serverUrl。空数组=全部禁止。 |
deniedMcpServers | object[] | 企业 MCP 黑名单。优先于白名单——同时在两个列表中的服务器会被拒绝。 |
allowManagedMcpServersOnly | boolean | 仅托管设置的 MCP 白名单生效。 |
// 企业 MCP 白名单示例
{
"allowedMcpServers": [
{ "serverName": "internal-tools" },
{ "serverCommand": ["npx", "my-mcp-server"] },
{ "serverUrl": "https://*.example.com/*" }
],
"deniedMcpServers": [
{ "serverName": "dangerous-server" }
]
}Hook 系统
源码位置:schemas/hooks.ts,utils/settings/types.ts:435
| 参数 | 类型 | 含义 |
|---|---|---|
hooks | object | 生命周期钩子,按事件名分组。详见 Hook 机制 |
disableAllHooks | boolean | 禁用所有 hooks 和 statusLine 执行。 |
allowManagedHooksOnly | boolean | 仅执行托管设置的 hooks(企业策略)。 |
allowedHttpHookUrls | string[] | HTTP hook 的 URL 白名单。支持 * 通配符。空数组=禁止所有。 |
httpHookAllowedEnvVars | string[] | HTTP hook 可注入到 headers 的环境变量名白名单。 |
支持的 Hook 事件:
// 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-955,memdir/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.enabled | boolean | 启用沙盒隔离。 |
sandbox.failIfUnavailable | boolean | 沙盒不可用时是否失败(vs 静默降级)。 |
sandbox.autoAllowBashIfSandboxed | boolean | 在沙盒内的 Bash 命令自动放行。 |
sandbox.allowUnsandboxedCommands | string[] | 不需要沙盒的命令列表。 |
| 网络控制 | ||
sandbox.network.allowedDomains | string[] | 允许的网络域名白名单。 |
sandbox.network.allowManagedDomainsOnly | boolean | 仅托管域名生效(企业)。 |
sandbox.network.allowUnixSockets | string[] | 允许的 Unix socket 路径(仅 macOS)。 |
sandbox.network.allowAllUnixSockets | boolean | 允许所有 Unix socket。 |
sandbox.network.allowLocalBinding | boolean | 允许本地端口绑定。 |
| 文件系统控制 | ||
sandbox.filesystem.allowWrite | string[] | 额外允许写入的路径。 |
sandbox.filesystem.denyWrite | string[] | 拒绝写入的路径。 |
sandbox.filesystem.denyRead | string[] | 拒绝读取的路径。 |
sandbox.filesystem.allowRead | string[] | 在 denyRead 中重新允许的路径。 |
sandbox.filesystem.allowManagedReadPathsOnly | boolean | 仅托管读取路径生效。 |
| 其他 | ||
sandbox.ignoreViolations | boolean | 忽略沙盒违规(仅记录日志)。 |
sandbox.excludedCommands | string[] | 排除出沙盒的命令。 |
sandbox.enableWeakerNestedSandbox | boolean | 允许弱化嵌套沙盒。 |
sandbox.enableWeakerNetworkIsolation | boolean | 允许弱化网络隔离。 |
UI 与显示
| 参数 | 类型 | 含义 |
|---|---|---|
outputStyle | string | 助手回复的输出风格。 |
language | string | 偏好语言,如 "japanese" "chinese" "spanish"。影响回复语言和语音听写。 |
syntaxHighlightingDisabled | boolean | 禁用 diff 语法高亮。 |
terminalTitleFromRename | boolean | /rename 是否更新终端标题(默认 true)。 |
prefersReducedMotion | boolean | 减少动画(无障碍辅助)。 |
spinnerTipsEnabled | boolean | 显示 spinner 提示。 |
spinnerVerbs | {mode, verbs[]} | 自定义 spinner 动词。mode:"append" 追加,"replace" 替换。 |
spinnerTipsOverride | {excludeDefault?, tips[]} | 自定义 spinner 提示文本。excludeDefault:true 只显示自定义。 |
showThinkingSummaries | boolean | transcript 视图显示思考摘要(默认 false)。 |
showClearContextOnPlanAccept | boolean | plan 审批对话框显示"清除上下文"选项。 |
promptSuggestionEnabled | boolean | 启用提示建议。 |
defaultView | "chat"|"transcript" | 默认 transcript 视图(功能门控)。 |
feedbackSurveyRate | number (0~1) | 反馈问卷弹出概率。0.05 即 5% 概率弹出。 |
statusLine | {type:"command", command:string, padding?:number} | 自定义状态栏显示。 |
认证与企业
| 参数 | 类型 | 含义 |
|---|---|---|
apiKeyHelper | string | 输出认证值的脚本路径。 |
awsCredentialExport | string | 导出 AWS 凭证的脚本路径。 |
awsAuthRefresh | string | 刷新 AWS 认证的脚本路径。 |
gcpAuthRefresh | string | 刷新 GCP 认证的命令,如 "gcloud auth application-default login"。 |
forceLoginMethod | "claudeai"|"console" | 强制登录方式。"claudeai" = Claude Pro/Max,"console" = Console 计费。 |
forceLoginOrgUUID | string | OAuth 登录的组织 UUID。 |
otelHeadersHelper | string | 输出 OpenTelemetry headers 的脚本路径。 |
companyAnnouncements | string[] | 启动时随机显示的公司公告(企业内部使用)。 |
插件与市场
| 参数 | 类型 | 含义 |
|---|---|---|
enabledPlugins | Record<string, boolean|string[]> | 已启用的插件。Key 格式 "pluginName@marketplaceName"。 |
pluginConfigs | Record<string, object> | 插件配置,含 mcpServers 和 options 子字段。 |
extraKnownMarketplaces | Record<string, object> | 额外市场源(通常在项目 settings 中配置团队共享市场)。 |
strictKnownMarketplaces | object[] | 企业市场白名单(仅托管设置)。下载前拦截。 |
blockedMarketplaces | object[] | 企业市场黑名单。 |
strictPluginOnlyCustomization | boolean|("skills"|"agents"|"hooks"|"mcp")[] | 限制非插件自定义源。true=锁定全部,数组=锁定指定项。 |
pluginTrustMessage | string | 插件信任警告追加的自定义消息(仅托管设置)。 |
// 插件配置示例
{
"enabledPlugins": {
"formatter@anthropic-tools": true
},
"pluginConfigs": {
"formatter@anthropic-tools": {
"options": { "tabSize": 2 }
}
}
}Git 与 Attribution
| 参数 | 类型 | 含义 |
|---|---|---|
attribution.commit | string | Git 提交的署名文本。空字符串 ""=隐藏署名。 |
attribution.pr | string | PR 描述的署名文本。空字符串=隐藏。 |
includeCoAuthoredBy | boolean | 已废弃,请用 attribution 代替。 |
includeGitInstructions | boolean | 系统提示中包含 Git 操作指引(默认 true)。 |
自动更新
| 参数 | 类型 | 含义 |
|---|---|---|
autoUpdatesChannel | "latest"|"stable" | 自动更新频道。"latest" = 最新版,"stable" = 稳定版。 |
minimumVersion | string | 最低版本号,防止切换到 stable 频道时被降级。 |
文件与工作区
| 参数 | 类型 | 含义 |
|---|---|---|
fileSuggestion | {type:"command", command:string} | @ 提及的自定义文件建议命令。 |
respectGitignore | boolean | 文件选择器是否尊重 .gitignore(默认 true)。.ignore 始终被尊重。 |
cleanupPeriodDays | number (≥0) | 聊天记录保留天数(默认 30)。设 0 完全禁用持久化。 |
defaultShell | "bash"|"powershell" | ! 命令的默认 shell。所有平台默认 bash。 |
worktree.symlinkDirectories | string[] | worktree 中符号链接的目录,如 ["node_modules"]。 |
worktree.sparsePaths | string[] | worktree 稀疏检出路径,大型 monorepo 加速。 |
plansDirectory | string | 计划文件目录,相对项目根。默认 ~/.claude/plans/。 |
claudeMdExcludes | string[] | 排除加载的 CLAUDE.md glob 模式。 |
SSH 远程连接
源码位置:utils/settings/types.ts:1013-1052
| 参数 | 类型 | 含义 |
|---|---|---|
sshConfigs[].id | string | 唯一标识符。 |
sshConfigs[].name | string | 显示名称。 |
sshConfigs[].sshHost | string | SSH 主机(user@hostname 或别名)。 |
sshConfigs[].sshPort | number | SSH 端口(默认 22)。 |
sshConfigs[].sshIdentityFile | string | 私钥文件路径。 |
sshConfigs[].startDirectory | string | 远程默认工作目录,支持 ~/ 展开。 |
// 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.ts | Zod Schema 定义,60+ 参数的单源真相(817 行) |
utils/settings/settings.ts | 配置加载引擎:文件解析、5 层合并、缓存、文件监听 |
utils/settings/constants.ts | SETTING_SOURCES 枚举、SettingSource 类型 |
utils/settings/validation.ts | Zod 错误格式化、JSON Schema 生成 |
utils/settings/permissionValidation.ts | PermissionRuleSchema:Bash 前缀/文件模式/MCP 规则验证 |
utils/settings/settingsCache.ts | 会话级缓存:per-source cache + parsed-file cache |
utils/settings/changeDetector.ts | chokidar 文件监听,配置变更自动重载 |
utils/settings/applySettingsChange.ts | 配置变更→AppState 同步(重载权限、hooks、effort level) |
utils/settings/managedPath.ts | 平台托管路径:macOS=/Library/Application Support/ClaudeCode |
utils/settings/mdm/settings.ts | MDM 配置读取:macOS plist / Windows HKLM+HKCU |
utils/settings/pluginOnlyPolicy.ts | strictPluginOnlyCustomization 策略执行 |
tools/ConfigTool/supportedSettings.ts | UI 可设置的配置项元数据 |
entrypoints/sandboxTypes.ts | 沙盒配置 Zod Schema |
schemas/hooks.ts | Hook 系统 Zod Schema(13 种事件 × 4 种类型) |
services/remoteManagedSettings/index.ts | 远程托管配置拉取 + ETag 缓存 |
services/settingsSync/index.ts | 多设备配置同步(上传用户设置 + memory) |