Claude Code settings.json 详解（四）：env、模型、认证与其他实用字段

2026年4月9日

Claude

前言

前三篇分别介绍了配置文件体系（一）、permissions 权限系统（二）和 hooks 钩子（三）。这一篇把剩余的实用字段统一过一遍——它们不如前三篇那样”戏份重”，但实际上覆盖了日常使用中你最可能调整的那些旋钮。

内容按功能分组，方便按需查阅。

env — 注入环境变量

{
  "env": {
    "NODE_ENV": "development",
    "MY_API_URL": "https://api.example.com",
    "DEBUG": "true"
  }
}

env 是一个 Record<string, string>，Claude Code 启动时会将这些键值对注入到当前会话的环境变量里。所有通过 Bash 工具执行的命令、以及 hooks 脚本，都能读到这些变量。

常见用途：

为所有 Bash 命令设置固定的环境变量，避免每次手动 export
在项目设置里写入项目专属变量，让团队共享同一套环境配置
CI 场景下通过 --settings 临时注入敏感配置（配合管理员策略使用）

注意：env 字段的值必须是字符串，不支持动态求值。如果需要动态获取，可以使用下文介绍的 apiKeyHelper。

模型配置

model — 覆盖默认模型

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

覆盖 Claude Code 默认使用的模型。可以在用户设置里全局指定，也可以在项目设置里为特定项目指定不同的模型。

有效值示例：claude-opus-4-6、claude-sonnet-4-6、claude-haiku-4-5-20251001。

availableModels — 模型白名单

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

限制用户可以通过 /model 命令切换的模型范围。不在列表里的模型不会出现在选择界面里。适合团队统一管控允许使用的模型，防止成员随意切换到高成本模型。

modelOverrides — 模型 ID 映射

{
  "modelOverrides": {
    "claude-sonnet-4-6": "anthropic/claude-sonnet-4-6-custom"
  }
}

将 Anthropic 标准模型 ID 映射到提供商特定的模型 ID，适合通过第三方 API 代理使用 Claude 的场景。

身份认证辅助

apiKeyHelper — 动态获取 API 密钥

{
  "apiKeyHelper": "/path/to/get-api-key.sh"
}

指定一个可执行脚本的路径，Claude Code 在需要 API 密钥时会运行这个脚本，并读取其 stdout 作为认证值。适合以下场景：

密钥存储在密钥管理系统（如 1Password、Vault）里，需要动态获取
密钥会定期轮换，不方便硬编码在环境变量里

脚本只需在 stdout 输出密钥字符串即可，无需任何格式。

awsCredentialExport / awsAuthRefresh

{
  "awsCredentialExport": "/path/to/export-aws-creds.sh",
  "awsAuthRefresh": "/path/to/refresh-aws.sh"
}

用于 AWS Bedrock 集成场景：

awsCredentialExport：输出 AWS 凭证的脚本路径（export AWS_ACCESS_KEY_ID=... 格式）
awsAuthRefresh：凭证过期后用于刷新的脚本路径

gcpAuthRefresh

{
  "gcpAuthRefresh": "gcloud auth application-default login"
}

Google Cloud 认证刷新命令。当使用 Vertex AI 作为后端时，凭证过期后 Claude Code 会自动调用这条命令重新认证。

Git 与提交署名

attribution — 自定义提交署名

{
  "attribution": {
    "coAuthoredBy": true,
    "coAuthorName": "My Claude",
    "coAuthorEmail": "claude@example.com"
  }
}

自定义 Claude Code 在提交和 PR 里加入的署名信息。子字段：

字段	类型	说明
`coAuthoredBy`	boolean	是否在提交 message 里加入 `Co-authored-by`
`coAuthorName`	string	Co-author 的显示名称
`coAuthorEmail`	string	Co-author 的邮箱

includeCoAuthoredBy（已弃用）

{
  "includeCoAuthoredBy": false
}

控制是否在提交里加入 Claude 的 Co-authored-by 署名，默认为 true。这个字段已被 attribution 取代，建议迁移到新字段。设置为 false 可以彻底去掉 AI 署名。

includeGitInstructions

{
  "includeGitInstructions": false
}

控制是否在系统提示里包含内置的 Git 提交和 PR 工作流说明，默认为 true。如果你有自己的 CLAUDE.md 里已经写了完整的 Git 规范，可以设为 false 避免重复。

会话与清理

cleanupPeriodDays — 会话记录保留天数

{
  "cleanupPeriodDays": 60
}

控制聊天记录（transcript）的保留天数，默认为 30 天。超过这个天数的记录会被自动清理。

特殊值：设为 0 会完全禁用会话持久化，Claude Code 不会在磁盘上保存任何聊天记录。适合对隐私有严格要求的场景。

语言与界面

language — 响应语言

{
  "language": "chinese"
}

设置 Claude 的首选响应语言。支持自然语言名称，如 "chinese"、"japanese"、"spanish" 等。这个字段同时影响语音听写的识别语言。

未设置时，Claude 默认用用户输入的语言回复。

syntaxHighlightingDisabled

{
  "syntaxHighlightingDisabled": true
}

禁用 diff 视图里的语法高亮。在某些终端渲染有问题时可以用这个字段关掉高亮。

terminalTitleFromRename

{
  "terminalTitleFromRename": false
}

控制执行 /rename 命令时是否同步更新终端标签页的标题，默认为 true。不需要这个行为时可以关掉。

spinnerTipsEnabled

{
  "spinnerTipsEnabled": false
}

控制是否在 Claude 思考时的 spinner 里显示小提示，默认开启。喜欢干净界面的用户可以关掉。

prefersReducedMotion

{
  "prefersReducedMotion": true
}

减少或禁用界面动画，适合对动画敏感的用户或无障碍需求场景。

思考深度与效率

effortLevel — 思考深度

{
  "effortLevel": "high"
}

持久化保存思考深度设置，等效于每次手动执行 /effort。支持三个值：

值	效果
`low`	快速回复，减少思考时间
`medium`	默认平衡
`high`	深度思考，适合复杂任务

只对支持 Extended Thinking 的模型（Opus、Sonnet）有效。

alwaysThinkingEnabled

{
  "alwaysThinkingEnabled": false
}

设为 false 完全禁用思考（thinking）功能；缺省或设为 true 时由模型自动决定是否启用思考。

fastMode

{
  "fastMode": true
}

开启 Fast Mode（等效于执行 /fast），持久化保存该设置。

{
  "fastModePerSessionOptIn": true
}

当 fastModePerSessionOptIn 为 true 时，Fast Mode 的设置不会跨会话保留，每次启动 Claude Code 都会重置。

自动更新

autoUpdatesChannel — 更新渠道

{
  "autoUpdatesChannel": "stable"
}

控制 Claude Code 的自动更新渠道：

值	说明
`latest`	最新版本（可能包含预发布功能）
`stable`	稳定版本（默认，经过更多测试的版本）

minimumVersion — 最低版本约束

{
  "minimumVersion": "2.1.88"
}

防止降级到低于指定版本。在切换到 stable 渠道时，如果 stable 版本低于当前版本，这个字段可以阻止降级。

记忆系统

autoMemoryEnabled — 自动记忆

{
  "autoMemoryEnabled": true
}

为当前项目启用自动记忆功能。Claude Code 会自动将对话中学到的重要信息持久化，供后续会话使用。

autoMemoryDirectory — 记忆存储目录

{
  "autoMemoryDirectory": ".claude/memory"
}

自定义记忆文件的存储目录（相对于项目根目录）。默认存储在 Claude Code 内置的记忆目录里。

autoDreamEnabled — 后台记忆整合

{
  "autoDreamEnabled": true
}

启用后台记忆整合（Auto Dream）。Claude Code 会在后台对已有记忆进行汇总和去重，保持记忆库的整洁。

MCP 服务器管理

enableAllProjectMcpServers

{
  "enableAllProjectMcpServers": true
}

自动批准 .mcp.json 里的所有 MCP 服务器，不需要逐个确认。适合信任项目配置的场景。

enabledMcpjsonServers / disabledMcpjsonServers

{
  "enabledMcpjsonServers": ["github", "playwright"],
  "disabledMcpjsonServers": ["legacy-tool"]
}

精细控制 .mcp.json 里哪些 MCP 服务器被启用、哪些被禁用。两个数组都是 MCP 服务器名称的列表，遵循上一篇介绍的数组合并规则（多层配置的值会拼接）。

其他实用字段

defaultShell

{
  "defaultShell": "bash"
}

设置输入框 ! 命令的默认 Shell，可选 "bash" 或 "powershell"，默认为 "bash"。

respectGitignore

{
  "respectGitignore": false
}

控制文件选择器（@ 提及时）是否遵守 .gitignore 规则，默认为 true。.ignore 文件始终生效，不受此字段影响。

plansDirectory — 计划文件目录

{
  "plansDirectory": ".claude/plans"
}

自定义 /plan 命令生成的计划文件的存储目录（相对于项目根目录）。

disableAllHooks

{
  "disableAllHooks": true
}

一键禁用所有 hooks 和 statusLine 的执行。调试配置问题时非常有用——先用这个字段排除 hooks 的干扰，再逐步开启。

feedbackSurveyRate

{
  "feedbackSurveyRate": 0
}

控制会话质量问卷弹出的概率（0 到 1 之间）。设为 0 可以完全禁用反馈弹窗。

企业级管控字段

以下字段只在 managed-settings.json（管理员策略）中生效，用户设置里写了也不起作用：

字段	说明
`allowManagedHooksOnly`	只允许管理员策略里的 hooks 执行
`allowManagedPermissionRulesOnly`	只使用管理员策略里的权限规则
`allowManagedMcpServersOnly`	MCP 服务器白名单只从管理员策略读取
`allowedMcpServers`	企业级 MCP 服务器白名单
`deniedMcpServers`	企业级 MCP 服务器黑名单
`strictPluginOnlyCustomization`	限制只允许通过插件扩展（禁止本地 skills/agents/hooks）
`forceLoginMethod`	强制使用指定的登录方式（`claudeai` 或 `console`）
`forceLoginOrgUUID`	强制绑定到指定的组织 UUID

settings.json 字段速查表

把前四篇涉及的字段汇总成一张表，方便日常参考：

分类	字段	简述
基础	`$schema`	JSON Schema 引用（编辑器补全）
配置体系	见第一篇	文件路径、优先级、合并规则
权限	`permissions`	allow/deny/ask 规则，见第二篇
钩子	`hooks`、`disableAllHooks`	生命周期钩子，见第三篇
环境变量	`env`	注入环境变量到会话
模型	`model`、`availableModels`、`modelOverrides`	模型选择与限制
认证	`apiKeyHelper`、`awsCredentialExport`、`gcpAuthRefresh`	动态获取凭证
Git	`attribution`、`includeCoAuthoredBy`、`includeGitInstructions`	提交署名与 Git 说明
会话	`cleanupPeriodDays`	记录保留天数
语言界面	`language`、`syntaxHighlightingDisabled`、`prefersReducedMotion`	语言与 UI
思考	`effortLevel`、`alwaysThinkingEnabled`、`fastMode`	思考深度与快速模式
更新	`autoUpdatesChannel`、`minimumVersion`	更新渠道控制
记忆	`autoMemoryEnabled`、`autoMemoryDirectory`、`autoDreamEnabled`	自动记忆系统
MCP	`enableAllProjectMcpServers`、`enabledMcpjsonServers`	MCP 服务器管理

小结

这四篇把 settings.json 的核心配置项都过了一遍：

第一篇：五层配置体系，文件在哪里，谁覆盖谁
第二篇：permissions 权限规则，allow/deny/ask，通配符，defaultMode
第三篇：hooks 钩子，四种类型，四个核心事件，stdin/stdout 协议
第四篇：env、模型、认证、Git、会话、界面、思考、更新、记忆等杂项字段

绝大多数日常需求在这四篇里都能找到对应的配置项。遇到”怎么让 Claude Code 做 XXX”的问题，不妨先来这里翻一翻。

前言