Claude Code settings.json 配置指南

Claude Code 的常用配置主要写在 ~/.claude/settings.json、项目 .claude/settings.json 和项目 .claude/settings.local.json。用户级配置影响所有项目，项目级配置适合团队共享，本地配置只影响当前仓库且通常不提交。本文先回答配置文件放哪里、settings.json 和 settings.local.json 有什么区别，再按权限、默认模型、statusline、环境变量、桌面版和 IDE 集成整理下一步阅读入口。

如果你是从搜索结果进来的，先看这三个结论：

个人默认配置放在 ~/.claude/settings.json。
团队共享配置放在项目根目录的 .claude/settings.json，可以提交到 Git。
个人对某个项目的临时覆盖放在 .claude/settings.local.json，通常不要提交。

在 Claude Code 内运行 /config 可以用图形界面查看和修改部分配置；需要精确控制权限、环境变量、statusline、MCP、Hooks 时，再直接编辑 settings 文件。

按需求查配置

你想解决的问题	主要配置项	建议放置位置	下一步阅读
配置自动权限、减少确认弹窗	`permissions.allow`、`permissions.ask`、`permissions.defaultMode`	团队规则放 `.claude/settings.json`，个人规则放 `settings.local.json`	权限配置
把默认权限模式改成自动接受编辑	`permissions.defaultMode`	个人常用放用户级，项目约定放项目级	权限模式
设置默认模型或限制可选模型	`model`、`availableModels`、`modelOverrides`	`~/.claude/settings.json` 或团队托管配置	模型设置
配置 statusline.sh 状态栏	`statusLine`	`~/.claude/settings.json`	状态栏设置
注入 API Key、代理等环境变量	`env`、`apiKeyHelper`	个人配置或密钥管理脚本，不要提交明文密钥	环境变量
配置 Bedrock、Vertex 或第三方网关	`modelOverrides`、`env`、云服务商环境变量	企业托管配置或个人环境变量	环境变量
添加插件市场或管理插件	`enabledPlugins`、`extraKnownMarketplaces`	团队共享市场放项目级，个人实验放本地级	插件设置
桌面版和 CLI 是否共用配置	CLAUDE.md、MCP、Hooks、Skills、settings	同一项目下共用大部分项目配置	桌面应用快速入门
JetBrains / VS Code 插件读哪些配置	diff 工具、CLI 路径、登录状态、项目 settings	IDE 插件设置 + Claude Code settings	JetBrains IDE 集成 / VS Code 扩展
登录失败、API Key 和订阅冲突	OAuth、`ANTHROPIC_API_KEY`、`apiKeyHelper`	认证凭证不应直接写进共享 settings	认证配置

Claude Code 提供丰富的配置项，可以通过 settings.json 文件或交互式 /config 命令调整。本文后半部分是完整字段参考。

配置作用域

选择配置文件时，可以先用一句话判断：会影响所有项目的放用户级，会影响整个团队的放项目级，只影响你自己的放本地级。

Claude Code 使用分层配置系统，不同位置的配置影响不同范围：

作用域	位置	影响范围	是否共享
托管	MDM/注册表/`managed-settings.json`	机器上所有用户	是（IT 部署）
用户	`~/.claude/settings.json`	你的所有项目	否
项目	`.claude/settings.json`	仓库所有协作者	是（提交到 git）
本地	`.claude/settings.local.json`	仅你在此仓库	否（gitignore）

使用场景

托管：全组织强制执行的安全策略、合规要求
用户：个人偏好（主题、编辑器）、跨项目工具
项目：团队共享的权限、Hooks、MCP 服务器
本地：个人对特定项目的覆盖、测试配置

优先级（从高到低）

托管设置（不可覆盖）
命令行参数（临时覆盖）
本地项目设置（.claude/settings.local.json）
共享项目设置（.claude/settings.json）
用户设置（~/.claude/settings.json）

数组合并：数组类型的设置（如 permissions.allow、sandbox.filesystem.allowWrite）跨作用域会合并（拼接去重），不是覆盖。低优先级可以追加，高优先级也可以追加。

如果你在排查“配置为什么不生效”，优先检查两件事：当前工作目录是不是你以为的项目根目录，以及同一配置是否被更高优先级的本地配置、命令行参数或托管配置覆盖。

配置不生效排查顺序

运行 /status，先看 Claude Code 实际加载了哪些配置来源。
确认当前终端或 IDE 打开的目录就是项目根目录，否则项目级 .claude/settings.json 不会按预期生效。
检查 .claude/settings.local.json 是否覆盖了项目共享配置。
检查启动命令里是否带了 --permission-mode、--model 这类临时参数。
检查企业托管设置是否强制了权限、模型、MCP 或登录方式。
改完 settings 后重启当前会话；IDE 和桌面版场景下，必要时也重启插件或应用。

配置文件示例

json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

加上 $schema 行后，VS Code 和 Cursor 会提供自动补全和验证。

核心设置项

键	说明	示例值
`model`	覆盖默认模型	`"claude-sonnet-4-6"`
`effortLevel`	思考深度：`low`/`medium`/`high`	`"medium"`
`alwaysThinkingEnabled`	默认开启扩展思考	`true`
`language`	Claude 的响应语言	`"japanese"`
`env`	每次会话都注入的环境变量	`{"FOO": "bar"}`
`autoUpdatesChannel`	更新频道：`latest` 或 `stable`	`"stable"`
`cleanupPeriodDays`	会话历史保留天数（0=不保留）	`30`
`plansDirectory`	计划文件存储目录	`"./plans"`
`statusLine`	自定义状态栏显示	见下方
`outputStyle`	调整系统提示的输出风格	`"Explanatory"`
`agent`	以指定子代理的身份运行主线程	`"code-reviewer"`
`includeGitInstructions`	是否注入内置 git 工作流指令（默认 `true`）	`false`
`companyAnnouncements`	启动时循环显示的公告	`["Welcome to Acme!"]`

权限设置

权限是 settings 页面最常见的搜索意图：用户通常不是想看字段名，而是想知道“哪些命令可以自动放行，哪些危险操作必须继续确认”。详细语法见权限配置文档。

键	说明	示例值
`permissions.allow`	允许的工具规则数组	`["Bash(git diff *)"]`
`permissions.ask`	需要确认的工具规则数组	`["Bash(git push *)"]`
`permissions.deny`	拒绝的工具规则数组	`["WebFetch", "Read(./.env)"]`
`permissions.additionalDirectories`	额外可访问的目录	`["../docs/"]`
`permissions.defaultMode`	默认权限模式	`"acceptEdits"`
`permissions.disableBypassPermissionsMode`	禁止 bypassPermissions 模式	`"disable"`

沙箱设置

沙箱隔离 Bash 命令的文件系统和网络访问，与权限系统互补。

json

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  }
}

沙箱选项详解

键	说明	默认值
`sandbox.enabled`	启用沙箱（macOS、Linux、WSL2）	`false`
`sandbox.autoAllowBashIfSandboxed`	沙箱内自动批准 Bash 命令	`true`
`sandbox.excludedCommands`	在沙箱外运行的命令	`[]`
`sandbox.allowUnsandboxedCommands`	允许通过 `dangerouslyDisableSandbox` 参数逃出沙箱	`true`

文件系统沙箱

键	说明
`sandbox.filesystem.allowWrite`	沙箱内可写的额外路径（数组跨作用域合并）
`sandbox.filesystem.denyWrite`	沙箱内禁止写入的路径
`sandbox.filesystem.denyRead`	沙箱内禁止读取的路径
`sandbox.filesystem.allowRead`	在 `denyRead` 区域内重新允许读取（优先级更高）

网络沙箱

键	说明	默认值
`sandbox.network.allowedDomains`	允许的出站域名（支持 `*.example.com` 通配符）
`sandbox.network.allowUnixSockets`	允许访问的 Unix Socket 路径
`sandbox.network.allowAllUnixSockets`	允许所有 Unix Socket 连接	`false`
`sandbox.network.allowLocalBinding`	允许绑定 localhost 端口（仅 macOS）	`false`
`sandbox.network.httpProxyPort`	自定义 HTTP 代理端口
`sandbox.network.socksProxyPort`	自定义 SOCKS5 代理端口

沙箱路径前缀

前缀	含义
`/`	从文件系统根的绝对路径
`~/`	相对于家目录
`./` 或无前缀	相对于项目根（项目设置）或 `~/.claude`（用户设置）

模型设置

如果你想把某个模型设为默认值，最直接的方式是在用户级 ~/.claude/settings.json 里写 model。团队如果要统一可用模型，应优先使用托管配置或项目共享配置，而不是让每个人手动改。

json

{
  "model": "claude-sonnet-4-6",
  "availableModels": ["sonnet", "haiku"],
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789:inference-profile/..."
  }
}

键	说明
`model`	覆盖默认模型
`availableModels`	限制用户可以通过 `/model` 选择的模型列表
`modelOverrides`	将 Anthropic 模型 ID 映射到 Bedrock ARN 等提供商 ID

归因设置

Claude Code 默认在 git commit 和 PR 中添加归因信息：

json

{
  "attribution": {
    "commit": "🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>",
    "pr": ""
  }
}

设为空字符串可隐藏归因。

Worktree 设置

优化大型单仓库（monorepo）中 --worktree 的性能：

json

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}

键	说明
`worktree.symlinkDirectories`	从主仓库软链接到 worktree 的目录，避免磁盘重复占用
`worktree.sparsePaths`	使用 git sparse-checkout 只检出指定路径，加速大型仓库

文件建议设置

自定义 @ 文件路径补全命令：

json

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

命令通过 stdin 接收 JSON：

json

{"query": "src/comp"}

在 stdout 输出换行分隔的文件路径（最多 15 条）。

状态栏设置

statusLine 适合显示当前模型、权限模式、Git 分支或自定义项目状态。它通过命令输出内容，所以排错时先单独运行脚本，确认脚本本身能正常输出。

json

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

插件设置

json

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": "github",
      "repo": "acme-corp/claude-plugins"
    }
  }
}

用 /plugin 命令交互式管理插件（浏览、安装、启用/禁用）。

MCP 相关设置

键	说明
`enableAllProjectMcpServers`	自动批准项目 `.mcp.json` 中的所有 MCP 服务器
`enabledMcpjsonServers`	只批准列出的 MCP 服务器
`disabledMcpjsonServers`	拒绝列出的 MCP 服务器

全局配置项（~/.claude.json）

这些项存储在 ~/.claude.json，不在 settings.json 中（否则会报 schema 错误）：

键	说明	默认值
`autoConnectIde`	从外部终端启动时自动连接 IDE	`false`
`autoInstallIdeExtension`	从 VS Code 终端启动时自动安装扩展	`true`
`editorMode`	输入框键绑定模式：`normal` 或 `vim`	`"normal"`
`showTurnDuration`	响应后显示用时信息	`true`
`terminalProgressBarEnabled`	显示终端进度条	`true`

企业托管设置（仅 managed-settings.json）

键	说明
`disableBypassPermissionsMode`	设为 `"disable"` 全局禁止跳过权限模式
`allowManagedPermissionRulesOnly`	仅允许托管权限规则，用户/项目规则无效
`allowManagedHooksOnly`	仅允许托管 Hooks
`allowManagedMcpServersOnly`	仅允许托管 MCP 服务器白名单
`channelsEnabled`	Team/Enterprise 用户启用 Channels 功能
`allowedMcpServers`	MCP 服务器白名单
`deniedMcpServers`	MCP 服务器黑名单
`strictKnownMarketplaces`	允许的插件市场
`blockedMarketplaces`	屏蔽的插件市场
`pluginTrustMessage`	自定义插件信任警告附加信息
`forceLoginMethod`	限定登录方式：`claudeai` 或 `console`
`forceLoginOrgUUID`	自动选择指定组织（需配合 `forceLoginMethod`）

托管设置文件位置

系统	路径
macOS	`/Library/Application Support/ClaudeCode/managed-settings.json`
Linux/WSL	`/etc/claude-code/managed-settings.json`
Windows	`C:\Program Files\ClaudeCode\managed-settings.json`

验证当前设置

在 Claude Code 中运行 /status 可以查看所有激活的配置来源，包括托管设置来自哪里（远程、plist、注册表还是文件）。如果 settings.json 有语法错误，/status 会报告具体问题。

排除敏感文件

推荐在 .claude/settings.json 中添加：

json

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

下一步阅读

权限配置：配置 allow、ask、deny，减少重复确认但保留危险操作审批。
权限模式：理解 acceptEdits、Plan mode、bypass permissions 等模式差异。
模型配置：设置默认模型、可选模型和提供商映射。
Status Line：配置 statusLine，显示模型、上下文、费用和 git 信息。
环境变量：区分哪些值放 settings，哪些值放 Shell 环境变量。
认证配置：排查 API Key、OAuth、订阅登录和环境变量冲突。
桌面应用快速入门：了解桌面版和 CLI 共用哪些项目配置。
JetBrains IDE 集成：配置 IDE 插件、Diff 查看器和 Claude 命令路径。
VS Code 扩展：理解扩展设置和 CLI 共用配置的边界。
Skills：理解插件 Skills 与 settings、Hooks、MCP 的关系。
服务器托管设置：团队或企业统一下发 Claude Code policy。
设置最佳实践：把个人偏好、团队规则和敏感配置分层管理。
Hooks：生命周期自动化。
MCP：外部工具集成。
子代理：自定义子代理配置。

常见搜索问题

Q: Claude Code 的配置文件 settings.json 应该放在哪里？

Claude Code 支持多层配置：用户级放在 ~/.claude/settings.json，项目级放在 .claude/settings.json，本地覆盖用 .claude/settings.local.json，企业托管则通过 managed-settings.json 文件部署。

Q: 如何进行 claude code 配置来设置权限规则？

在 settings.json 的 permissions 对象中，使用 allow、deny、ask 数组来定义允许、拒绝或需要确认的工具规则，例如 "deny": ["Read(./.env)"] 来保护环境变量文件。

Q: claudecode配置中如何启用和设置沙箱？

在 sandbox 对象中设置 "enabled": true 即可启用。您可以进一步配置 filesystem 和 network 规则，例如 allowedDomains 限制网络访问，allowWrite 控制可写路径。

Q: 如何通过 claude code 配置文件切换使用的模型？

在 settings.json 中直接设置 "model": "claude-sonnet-4-6" 即可覆盖默认模型。还可以通过 availableModels 限制可选列表，或用 modelOverrides 映射到自定义模型端点。

Q: settings.json 和 settings.local.json 有什么区别？

.claude/settings.json 适合项目共享规则，可以提交到 Git；.claude/settings.local.json 只适合你自己的本地覆盖，通常被 .gitignore 忽略。团队约定、常用 Hooks、MCP 白名单放前者；个人 API Key、临时权限放后者。

Q: Claude Code 配置 defaultMode 应该写在哪里？

defaultMode 位于 permissions.defaultMode。如果是团队希望统一的默认审批策略，放项目 .claude/settings.json；如果只是你个人希望少点确认弹窗，放 .claude/settings.local.json 或用户级 ~/.claude/settings.json。

Q: statusline.sh 没显示或没有更新怎么办？

先确认 statusLine.command 指向的脚本可以在终端单独运行，再检查脚本权限、输出内容和路径是否使用了当前系统能识别的格式。跨平台团队最好把共享脚本放进仓库，用相对路径引用。

Q: 桌面版和 CLI 会读取同一份 settings 吗？

桌面版 Code 标签页和 CLI 使用同一套 Claude Code 引擎，在同一个项目里会共享 CLAUDE.md、MCP、Hooks、Skills 和大部分项目设置。桌面版的登录与图形界面偏好仍以应用自身为准，迁移时建议继续阅读桌面应用快速入门。

Q: 项目成员之间的 claude code 配置如何共享？

将配置写入项目根目录的 .claude/settings.json 并提交到 Git，即可在所有协作者间共享。个人本地覆盖配置应放在 .claude/settings.local.json（通常被 .gitignore 忽略）。

Q: --permission-mode acceptEdits 能不能写进 settings.json？

可以用 permissions.defaultMode 设置默认权限模式。如果只是某一次会话想临时自动接受编辑，用命令行参数；如果你每个项目都这样用，放用户级 settings；如果团队希望统一模式，放项目级或托管配置。

Q: extraKnownMarketplaces 是做什么的？

它用于告诉 Claude Code 额外的插件市场来源。团队共享插件市场时可以写进项目 .claude/settings.json，个人实验市场则更适合放 .claude/settings.local.json。

Q: AWS Bedrock 的模型默认值应该写在哪里？

模型映射通常写在 modelOverrides，认证和区域更适合用环境变量或企业托管配置。具体变量见环境变量和Amazon Bedrock。

Claude Code settings.json 配置指南 ​

按需求查配置 ​

配置作用域 ​

使用场景 ​

优先级（从高到低） ​

配置不生效排查顺序 ​

配置文件示例 ​

核心设置项 ​

权限设置 ​

沙箱设置 ​

沙箱选项详解 ​

文件系统沙箱 ​

网络沙箱 ​

沙箱路径前缀 ​

模型设置 ​

归因设置 ​

Worktree 设置 ​

文件建议设置 ​

状态栏设置 ​

插件设置 ​

MCP 相关设置 ​

全局配置项（~/.claude.json） ​

企业托管设置（仅 managed-settings.json） ​

托管设置文件位置 ​

验证当前设置 ​

排除敏感文件 ​

下一步阅读 ​

常见搜索问题 ​

Claude Code settings.json 配置指南

按需求查配置

配置作用域

使用场景

优先级（从高到低）

配置不生效排查顺序

配置文件示例

核心设置项

权限设置

沙箱设置

沙箱选项详解

文件系统沙箱

网络沙箱

沙箱路径前缀

模型设置

归因设置

Worktree 设置

文件建议设置

状态栏设置

插件设置

MCP 相关设置

全局配置项（~/.claude.json）

企业托管设置（仅 managed-settings.json）

托管设置文件位置

验证当前设置

排除敏感文件

下一步阅读

常见搜索问题