Claude Code settings.json 配置规则详解

基于 Claude Code v2.1.104+ 官方文档整理，参考来源：
官方文档：https://code.claude.com/docs/en/settings
JSON Schema：https://json.schemastore.org/claude-code-settings.json
社区完整参考：https://gist.github.com/mculp/c082bd1e5a439410158974de90c89db7

一、文件位置与作用域体系

Claude Code 采用分层配置机制，不同层级的 settings.json 有不同的作用范围和优先级。

1.1 四种作用域

作用域	文件路径	影响范围	是否共享
Managed（托管）	服务端 / plist / 注册表 / `/etc/claude-code/managed-settings.json`	机器上所有用户	由 IT 部署
User（用户）	`~/.claude/settings.json`	当前用户所有项目	否
Project（项目共享）	`.claude/settings.json`（在项目根目录）	该项目所有协作者	是（提交到 Git）
Local（项目本地）	`.claude/settings.local.json`	仅当前用户在该项目	否（自动 gitignore）

1.2 优先级（从高到低）

Managed（最高，不可覆盖）
  ↓
命令行参数（--permission-mode 等）
  ↓
Local 项目本地（.claude/settings.local.json）
  ↓
Project 项目共享（.claude/settings.json）
  ↓
User 用户全局（~/.claude/settings.json）（最低）

核心规则：高优先级的 deny 规则会覆盖低优先级的 allow 规则。数组类型的设置在各层之间会**合并（merge）**而非替换。

1.3 Managed Settings 部署路径

平台	路径
macOS	`/Library/Application Support/ClaudeCode/managed-settings.json`
Linux / WSL	`/etc/claude-code/managed-settings.json`
Windows	`C:\Program Files\ClaudeCode\managed-settings.json`
macOS (MDM)	`com.anthropic.claudecode` managed preferences domain
Windows (注册表)	`HKLM\SOFTWARE\Policies\ClaudeCode` → `Settings` (REG_SZ)

支持 managed-settings.d/ 目录放置分片配置，按字母排序合并（推荐用数字前缀如 10-telemetry.json、20-security.json）。

二、基本文件格式

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",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "model": "claude-sonnet-4-6"
}

$schema 行启用编辑器的自动补全和内联校验（VS Code / Cursor 等均支持）
自动创建配置文件的时间戳备份，保留最近 5 个

三、完整配置项分类详解

3.1 权限与安全 (Permissions & Security)

这是 settings.json 最核心、最常用的配置区域。

3.1.1 permissions 对象

键	类型	说明
`permissions.allow`	`string[]`	允许自动执行的工具规则列表
`permissions.deny`	`string[]`	拒绝执行的工具规则列表
`permissions.ask`	`string[]`	需要确认后才执行的工具规则列表
`permissions.defaultMode`	`string`	默认权限模式
`permissions.additionalDirectories`	`string[]`	额外工作目录
`permissions.disableBypassPermissionsMode`	`string`	设为 `"disable"` 可禁用绕过权限模式
`permissions.skipDangerousModePermissionPrompt`	`bool`	跳过危险模式确认提示

3.1.2 权限规则语法（Permission Rule Syntax）

规则格式为 Tool 或 Tool(specifier)，评估顺序：deny → ask → allow，第一个匹配的规则生效。

基本规则示例：

规则	效果
`Bash`	匹配所有 Bash 命令
`Bash(npm run *)`	匹配以 `npm run` 开头的命令
`Bash(git diff *)`	匹配 git diff 相关命令
`Read(./.env)`	匹配读取 .env 文件
`Read(./.env.*)`	匹配读取所有 .env.* 文件
`Read(./secrets/**)`	匹配读取 secrets 目录下所有文件
`Edit(*.ts)`	匹配编辑所有 .ts 文件
`WebFetch`	匹配所有网络请求
`WebFetch(domain:example.com)`	匹配指定域名的请求
`MCP(server-name)`	匹配指定 MCP 服务器
`Agent(agent-name)`	匹配指定子代理
`*`	匹配所有工具的所有操作

通配符：* 用于模糊匹配，支持 gitignore 风格的模式。

3.1.3 defaultMode 可选值

值	说明
`default`	最严格，非读操作都需要确认，受保护路径始终提示
`acceptEdits`	自动接受文件编辑，其他操作仍需确认
`plan`	规划模式
`auto`	自动模式，使用分类器自动判断安全性
`dontAsk`	不再询问（信任模式）
`bypassPermissions`	完全绕过权限检查（最危险）

3.1.4 实用配置示例

保守型配置（推荐生产项目使用）：

json

{
  "permissions": {
    "allow": [
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git status)",
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(ls *)",
      "Read(*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

开发者快速模式（个人项目）：

json

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(python3 *)",
      "Bash(pip *)",
      "Bash(docker *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(mkdir *)",
      "Bash(cp *)",
      "Bash(mv *)"
    ],
    "deny": [
      "Bash(rm -rf /)"
    ]
  }
}

完全绕过模式（仅限受信任环境）：

json

{
  "permissions": {
    "allow": ["*"],
    "deny": [],
    "defaultMode": "bypassPermissions"
  },
  "skipDangerousModePermissionPrompt": true
}

3.2 模型与推理 (Model & LLM)

键	类型	说明	示例
`model`	`string`	覆盖默认模型	`"claude-sonnet-4-6"`
`availableModels`	`string[]`	限制可选模型列表（企业用）	`["sonnet", "haiku"]`
`modelOverrides`	`object`	将 Anthropic 模型 ID 映射到供应商特定 ID（如 Bedrock ARN）	`{"claude-opus-4-6": "arn:aws:bedrock:..."}`
`alwaysThinkingEnabled`	`bool`	默认启用扩展思考模式	`true`
`effortLevel`	`string`	持久化推理深度	`"low"` / `"medium"` / `"high"` / `"xhigh"`
`fastModePerSessionOptIn`	`bool`	快速模式是否需要每次会话单独启用	`true`
`disableAutoMode`	`string`	设为 `"disable"` 可禁用自动模式	`"disable"`
`autoMode`	`object`	自动模式分类器配置	`{"environment": [...], "allow": [...]}`
`showThinkingSummaries`	`bool`	显示扩展思考摘要	`true`

3.3 环境与 Shell (Environment & Shell)

键	类型	说明	示例
`env`	`object`	注入到所有会话的环境变量	`{"FOO": "bar"}`
`defaultShell`	`string`	默认 Shell	`"bash"` / `"powershell"`
`language`	`string`	响应语言	`"chinese"` / `"japanese"`

3.4 归因设置 (Attribution)

键	类型	说明	示例
`attribution.commit`	`string`	Git commit 归因文本，空字符串禁用	`"🤖 Generated with Claude Code"`
`attribution.pr`	`string`	PR 描述归因文本，空字符串禁用	`""`
`includeCoAuthoredBy`	`bool`	已弃用，请用 `attribution.commit`	`false`

3.5 沙箱配置 (Sandbox)

json

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "allowUnsandboxedCommands": true,
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyWrite": ["/etc", "/usr/local/bin"],
      "denyRead": ["~/.aws/credentials"],
      "allowRead": ["."],
      "allowManagedReadPathsOnly": false
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "deniedDomains": ["uploads.github.com"],
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowAllUnixSockets": false,
      "allowLocalBinding": true,
      "allowMachLookup": ["com.apple.coresimulator.*"],
      "allowManagedDomainsOnly": false,
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  },
  "enableWeakerNestedSandbox": false,
  "enableWeakerNetworkIsolation": false
}

路径前缀规则：

前缀	含义	示例
`/`	文件系统绝对路径	`/tmp/build`
`~/`	相对于 HOME 目录	`~/.kube`
`./` 或无前缀	项目设置中相对项目根，用户设置中相对 `~/.claude`	`./output`

3.6 MCP 服务器 (MCP Servers)

键	类型	说明
`mcpServers`	`object`	MCP 服务器配置定义
`allowedMcpServers`	`array`	MCP 服务器允许列表（托管设置中使用）
`deniedMcpServers`	`array`	MCP 服务器阻止列表
`enableAllProjectMcpServers`	`bool`	自动批准项目 `.mcp.json` 中的所有 MCP 服务器
`enabledMcpjsonServers`	`array`	从 `.mcp.json` 启用的特定服务器列表
`disabledMcpjsonServers`	`array`	从 `.mcp.json` 禁用的特定服务器列表
`allowManagedMcpServersOnly`	`bool`	仅允许托管设置中的 MCP 服务器（托管专用）

3.7 Hooks 自动化

Hooks 允许在生命周期事件时执行自定义命令。

键	类型	说明
`hooks`	`object`	生命周期钩子配置（PreToolUse / PostToolUse / SessionStart / Stop / CwdChanged / Notification）
`allowedHttpHookUrls`	`array`	HTTP Hook 可访问的 URL 白名单（支持通配符）
`httpHookAllowedEnvVars`	`array`	HTTP Hook 可使用的环境变量白名单
`disableAllHooks`	`bool`	禁用所有 Hooks（托管专用）
`allowManagedHooksOnly`	`bool`	仅允许托管 Hooks（托管专用）
`disableSkillShellExecution`	`bool`	禁用 Skills 中的 Shell 执行

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'About to run Bash'"
          }
        ]
      }
    ]
  },
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

3.8 UI 与显示 (UI & Display)

键	类型	说明	示例
`theme`	`string`	UI 主题	-
`tui`	`string`	终端渲染器	`"fullscreen"` / `"default"`
`viewMode`	`string`	转录视图模式	`"default"` / `"verbose"` / `"focus"`
`outputStyle`	`string`	输出风格	`"Explanatory"`
`prefersReducedMotion`	`bool`	减少动画	`true`
`statusLine`	`object`	自定义状态栏	`{"type": "command", "command": "..."}`
`spinnerTipsEnabled`	`bool`	加载时显示提示	`true`
`spinnerTipsOverride`	`object`	自定义加载提示	`{"excludeDefault": true, "tips": [...]}`
`spinnerVerbs`	`object`	自定义加载动词	`{"mode": "append", "verbs": [...]}`
`showTurnDuration`	`bool`	显示每轮耗时	`true`
`terminalProgressBarEnabled`	`bool`	终端进度条	`true`
`autoScrollEnabled`	`bool`	全屏模式自动滚动	`true`
`showClearContextOnPlanAccept`	`bool`	计划接受后显示清除上下文选项	`true`
`awaySummaryEnabled`	`bool`	离开后返回时显示会话摘要	`true`

3.9 认证与 API (Authentication & API)

键	类型	说明	示例
`apiKeyHelper`	`string`	自定义 API Key 生成脚本	`"/bin/generate_temp_api_key.sh"`
`awsAuthRefresh`	`string`	AWS 凭证刷新脚本	`"aws sso login --profile myprofile"`
`awsCredentialExport`	`string`	AWS 凭证导出脚本	`"/bin/generate_aws_grant.sh"`
`forceLoginMethod`	`string`	强制登录方式	`"claudeai"` / `"console"`
`forceLoginOrgUUID`	`string/array`	强制登录到指定组织	`"xxxxxxxx-xxxx-..."`
`forceRemoteSettingsRefresh`	`bool`	启动时强制刷新远端托管设置（托管专用）	`true`
`otelHeadersHelper`	`string`	OpenTelemetry 头部生成脚本	`"/bin/generate_otel_headers.sh"`

3.10 文件与目录 (File & Directory)

键	类型	说明	示例
`autoMemoryDirectory`	`string`	自动记忆存储目录（不允许在项目共享设置中使用）	`"~/my-memory-dir"`
`plansDirectory`	`string`	计划文件存储路径	`"./plans"`
`fileSuggestion`	`object`	`@` 文件补全的自定义命令	`{"type": "command", "command": "..."}`
`respectGitignore`	`bool`	文件选择器是否尊重 .gitignore	`true`

3.11 Worktree 配置

键	类型	说明	示例
`worktree.symlinkDirectories`	`array`	在 worktree 中通过符号链接共享的目录	`["node_modules", ".cache"]`
`worktree.sparsePaths`	`array`	通过 git sparse-checkout 检出的路径	`["packages/my-app"]`

3.12 插件系统 (Plugins)

键	类型	说明
`enabledPlugins`	`object`	启用/禁用插件，格式 `"plugin@marketplace": true/false`
`extraKnownMarketplaces`	`object`	额外的插件市场源
`strictKnownMarketplaces`	`array`	插件市场白名单（托管专用）
`blockedMarketplaces`	`array`	插件市场黑名单（托管专用）
`pluginTrustMessage`	`string`	自定义插件信任提示消息

json

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

3.13 子代理 (Subagents)

键	类型	说明	示例
`agent`	`string`	将主线程作为命名子代理运行	`"code-reviewer"`

子代理文件以 Markdown + YAML frontmatter 的形式存储在：

用户级：~/.claude/agents/
项目级：.claude/agents/

3.14 企业/组织专用 (Enterprise)

键	类型	说明
`companyAnnouncements`	`array`	启动时显示的公司公告
`allowManagedHooksOnly`	`bool`	仅允许托管 Hooks
`allowManagedMcpServersOnly`	`bool`	仅允许托管 MCP 服务器
`allowManagedPermissionRulesOnly`	`bool`	仅允许托管权限规则
`channelsEnabled`	`bool`	启用频道通信功能
`allowedChannelPlugins`	`array`	频道插件白名单

3.15 其他杂项

键	类型	说明	示例
`cleanupPeriodDays`	`number`	会话文件保留天数（默认 30，最小 1）	`20`
`minimumVersion`	`string`	最低版本要求	`"2.1.100"`
`autoUpdatesChannel`	`string`	更新通道	`"stable"` / `"latest"`
`feedbackSurveyRate`	`number`	调查出现概率（0-1）	`0.05`
`voiceEnabled`	`bool`	启用语音输入	`true`
`teammateMode`	`string`	团队协作显示模式	`"auto"` / `"in-process"` / `"tmux"`
`disableDeepLinkRegistration`	`string`	禁用 `claude-cli://` 协议注册	`"disable"`
`includeGitInstructions`	`bool`	系统提示中包含 Git 操作指导	`true`
`sshConfigs`	`array`	SSH 连接预配置（Desktop 环境用）	`[{"id":"dev","name":"Dev VM","sshHost":"user@dev.example.com"}]`

四、全局配置文件（~/.claude.json）

以下设置存储在 ~/.claude.json 中，不是 settings.json 的一部分（放到 settings.json 会触发 schema 校验错误）：

键	说明	示例
`autoConnectIde`	自动连接到运行中的 IDE	`true`
`autoInstallIdeExtension`	自动安装 IDE 扩展	`false`
`autoScrollEnabled`	全屏模式自动滚动	`true`
`editorMode`	编辑器键绑定模式（`"normal"` / `"vim"`）	`"vim"`
`externalEditorContext`	Ctrl+G 打开外部编辑器时附加上下文	`true`
`showTurnDuration`	显示每轮耗时	`false`
`terminalProgressBarEnabled`	终端进度条	`true`
`teammateMode`	Agent Team 显示模式	`"in-process"`

五、配置管理命令

命令	说明
`/config`	打开分页设置界面，可视化修改配置
`/status`	查看当前生效的所有配置来源和层级
`/model`	切换模型
`/effort`	设置推理深度
`/tui`	切换终端渲染器
`/plugin`	管理插件
`/voice`	启用/关闭语音输入

六、最佳实践

6.1 安全建议

始终拒绝敏感文件读取：将 .env、secrets/、凭证文件加入 deny 列表
使用项目级配置：不同项目有不同的风险等级，避免在全局设置中过度放开权限
从严格开始：先只允许你频繁确认的命令，再逐步扩展
审查 diff 而非只看命令：即使命令被允许，也要关注实际执行效果

6.2 团队协作

将 .claude/settings.json 提交到 Git，统一团队配置
个人偏好放 .claude/settings.local.json（自动 gitignore）
企业用户使用 managed-settings.json 强制执行安全策略

6.3 推荐项目模板

json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(npm run build)",
      "Bash(ls *)",
      "Bash(cat *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.*)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "attribution": {
    "commit": "🤖 Generated with Claude Code\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
    "pr": "🤖 Generated with [Claude Code](https://claude.com/claude-code)"
  }
}

七、与其他配置文件的关系

文件	用途	位置
`settings.json`	权限、环境变量、工具行为配置	`.claude/` 或 `~/.claude/`
`CLAUDE.md`	启动时加载的指令和上下文（记忆文件）	项目根目录或 `.claude/` 或 `~/.claude/`
`.mcp.json`	项目级 MCP 服务器配置	项目根目录
`~/.claude.json`	偏好设置、OAuth 会话、信任配置、缓存	用户 HOME 目录
`.claude/agents/*.md`	子代理定义	`.claude/agents/` 或 `~/.claude/agents/`

八、排查与调试

使用 /status 查看哪些配置源生效，以及来源（如 Enterprise managed settings (remote) / (file) / (plist) 等）
如果配置文件有错误，/status 会报告具体问题
JSON Schema 可能不包含最新版本新增的字段，验证警告不一定表示配置无效
Claude Code 自动保留最近 5 个配置文件备份，防止数据丢失

code index

hooks

langfuse trace

docs

hook

watcher

Claude Code settings.json 配置规则详解

一、文件位置与作用域体系

1.1 四种作用域

1.2 优先级（从高到低）

1.3 Managed Settings 部署路径

二、基本文件格式

三、完整配置项分类详解

3.1 权限与安全 (Permissions & Security)

3.1.1 permissions 对象

3.1.2 权限规则语法（Permission Rule Syntax）

3.1.3 defaultMode 可选值

3.1.4 实用配置示例

3.2 模型与推理 (Model & LLM)

3.3 环境与 Shell (Environment & Shell)

3.4 归因设置 (Attribution)

3.5 沙箱配置 (Sandbox)

3.6 MCP 服务器 (MCP Servers)

3.7 Hooks 自动化

3.8 UI 与显示 (UI & Display)

3.9 认证与 API (Authentication & API)

3.10 文件与目录 (File & Directory)

3.11 Worktree 配置

3.12 插件系统 (Plugins)

3.13 子代理 (Subagents)

3.14 企业/组织专用 (Enterprise)

3.15 其他杂项

四、全局配置文件（~/.claude.json）

五、配置管理命令

六、最佳实践

6.1 安全建议

6.2 团队协作

6.3 推荐项目模板

七、与其他配置文件的关系

八、排查与调试

docs

hook

watcher

Claude Code settings.json 配置规则详解 ​

一、文件位置与作用域体系 ​

1.1 四种作用域 ​

1.2 优先级（从高到低） ​

1.3 Managed Settings 部署路径 ​

二、基本文件格式 ​

三、完整配置项分类详解 ​

3.1 权限与安全 (Permissions & Security) ​

3.1.1 permissions 对象 ​

3.1.2 权限规则语法（Permission Rule Syntax） ​

3.1.3 defaultMode 可选值 ​

3.1.4 实用配置示例 ​

3.2 模型与推理 (Model & LLM) ​

3.3 环境与 Shell (Environment & Shell) ​

3.4 归因设置 (Attribution) ​

3.5 沙箱配置 (Sandbox) ​

3.6 MCP 服务器 (MCP Servers) ​

3.7 Hooks 自动化 ​

3.8 UI 与显示 (UI & Display) ​

3.9 认证与 API (Authentication & API) ​

3.10 文件与目录 (File & Directory) ​

3.11 Worktree 配置 ​

3.12 插件系统 (Plugins) ​

3.13 子代理 (Subagents) ​

3.14 企业/组织专用 (Enterprise) ​

3.15 其他杂项 ​

四、全局配置文件（~/.claude.json） ​

五、配置管理命令 ​

六、最佳实践 ​

6.1 安全建议 ​

6.2 团队协作 ​

6.3 推荐项目模板 ​

七、与其他配置文件的关系 ​

八、排查与调试 ​

Claude Code settings.json 配置规则详解

一、文件位置与作用域体系

1.1 四种作用域

1.2 优先级（从高到低）

1.3 Managed Settings 部署路径

二、基本文件格式

三、完整配置项分类详解

3.1 权限与安全 (Permissions & Security)

3.1.1 permissions 对象

3.1.2 权限规则语法（Permission Rule Syntax）

3.1.3 defaultMode 可选值

3.1.4 实用配置示例

3.2 模型与推理 (Model & LLM)

3.3 环境与 Shell (Environment & Shell)

3.4 归因设置 (Attribution)

3.5 沙箱配置 (Sandbox)

3.6 MCP 服务器 (MCP Servers)

3.7 Hooks 自动化

3.8 UI 与显示 (UI & Display)

3.9 认证与 API (Authentication & API)

3.10 文件与目录 (File & Directory)

3.11 Worktree 配置

3.12 插件系统 (Plugins)

3.13 子代理 (Subagents)

3.14 企业/组织专用 (Enterprise)

3.15 其他杂项

四、全局配置文件（~/.claude.json）

五、配置管理命令

六、最佳实践

6.1 安全建议

6.2 团队协作

6.3 推荐项目模板

七、与其他配置文件的关系

八、排查与调试