Claude Code settings.json 配置大全

settings.json 配置大全：shanraisshan/claude-code-best-practice: claude-set，适用于工程实践、代码质量与开发流程优化。

Skill Documentation

Claude Code settings.json 配置大全

摘要

settings.json 配置大全：shanraisshan/claude-code-best-practice: claude-set，适用于工程实践、代码质量与开发流程优化。

> 来源: shanraisshan/claude-code-best-practice (64k stars) — Claude Code 完整实践指南

> 原文件: best-practice/claude-settings.md

> 模型推荐: 看 skill 类型挑

这个 skill 是干嘛的

shanraisshan 在 64k stars 的仓库里整理的"Claude Code 完整实践指南" — 涵盖启动参数、commands、MCP、memory、settings、skills、subagents 等所有方面。

michael 强调"skill 要有相应的指导功能,指导用户使用",所以加了下面两节让 Agent 和用户对接。

---

🤖 Agent 使用说明

1. 用户问"Claude Code 怎么用 X"时,触发对应 skill

2. skill 严格按原文指南跑

3. 涉及配置改动前 ask user 确认(避免破坏现有配置)

4. 完工后让 Agent 跑自检

👤 用户需要做什么?

1. 问 Agent "Claude Code 怎么 X"(X = 子主题)

2. 如果 Agent 改配置,确认后再继续

3. 全程 Agent 自动化,你只需回答授权类问题

---

原 skill 内容(shanraisshan/claude-code-best-practice/best-practice/claude-settings.md,截断到 12k chars)

Settings Best Practice

 <br>

[](../.claude/settings.json)

A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.224, Claude Code exposes **127+ settings** and **311 environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts).

<table width="100%">

<tr>

<td><a href="../">← Back to Claude Code Best Practice</a></td>

<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>

</tr>

</table>

Table of Contents

1. [Settings Hierarchy](#settings-hierarchy)

2. [Core Configuration](#core-configuration)

3. [Permissions](#permissions)

4. [Hooks](#hooks)

5. [MCP Servers](#mcp-servers)

6. [Sandbox](#sandbox)

7. [Plugins](#plugins)

8. [Model Configuration](#model-configuration)

9. [Display & UX](#display--ux)

10. [AWS & Cloud Credentials](#aws--cloud-credentials)

11. [Environment Variables](#environment-variables-via-env)

12. [Useful Commands](#useful-commands)

---

Settings Hierarchy

Settings apply in order of precedence (highest to lowest):

| Priority | Location | Scope | Shared? | Purpose |

|----------|----------|-------|---------|---------|

| 1 | Managed settings | Organization | Yes (deployed by IT) | Security policies that cannot be overridden |

| 2 | Command line arguments | Session | N/A | Temporary single-session overrides |

| 3 | `.claude/settings.local.json` | Project | No (git-ignored) | Personal project-specific |

| 4 | `.claude/settings.json` | Project | Yes (committed) | Team-shared settings |

| 5 | `~/.claude/settings.json` | User | N/A | Global personal defaults |

**Managed settings** are organization-enforced and cannot be overridden by any other level, including command line arguments. Delivery methods:

• **Server-managed** settings (remote delivery)
• **MDM profiles** — macOS plist at `com.anthropic.claudecode`
• **Registry policies** — Windows `HKLM\SOFTWARE\Policies\ClaudeCode` (admin) and `HKCU\SOFTWARE\Policies\ClaudeCode` (user-level, lowest policy priority)
• **File** — `managed-settings.json` and `managed-mcp.json` (macOS: `/Library/Application Support/ClaudeCode/`, Linux/WSL: `/etc/claude-code/`, Windows: `C:\Program Files\ClaudeCode\`)
• **Drop-in directory** — `managed-settings.d/` alongside `managed-settings.json` for independent policy fragments (v2.1.83). Following the systemd convention, `managed-settings.json` is merged first as the base, then all `*.json` files in the drop-in directory are sorted alphabetically and merged on top. Later files override earlier ones for scalar values; arrays are concatenated and de-duplicated; objects are deep-merged. Hidden files starting with `.` are ignored. Use numeric prefixes to control merge order (e.g., `10-telemetry.json`, `20-security.json`)

Within the managed tier, precedence is: server-managed > MDM/OS-level policies > file-based (`managed-settings.d/*.json` + `managed-settings.json`) > HKCU registry (Windows only). Only one managed source wins for most keys; sources do not merge across tiers. Within the file-based tier, drop-in files and the base file are merged together.

**Exception — admin-source union keys:** The following keys are honored when *any* admin-controlled managed source sets them, not just the winning source: `sandbox.network.allowManagedDomainsOnly`, `sandbox.network.allowedDomains` (when `allowManagedDomainsOnly` is set), `sandbox.filesystem.allowManagedReadPathsOnly`, `sandbox.filesystem.allowRead` (when `allowManagedReadPathsOnly` is set), `allowAllClaudeAiMcps`, `sandbox.bwrapPath`, `sandbox.socatPath`, `forceRemoteSettingsRefresh`, and `env` (which merges **per key** across all admin sources rather than taking the highest-precedence source's entire object).

> **Note:** As of v2.1.75, the deprecated Windows fallback path `C:\ProgramData\ClaudeCode\managed-settings.json` has been removed. Use `C:\Program Files\ClaudeCode\managed-settings.json` instead.

> **Note (v2.1.126):** `/config` now persists changes to `~/.claude/settings.json` instead of holding them in memory only. Edits made through the interactive Config UI survive restarts.

**Managed-only policy keys:**

| Key | Type | Default | Description |

|-----|------|---------|-------------|

| `parentSettingsBehavior` | string | `"first-wins"` | Controls whether managed settings supplied programmatically by an embedding host process (SDK parent) apply when an admin-deployed managed tier is also present. `"first-wins"`: parent-supplied settings are dropped and only the admin tier applies. `"merge"`: parent-supplied settings apply under the admin tier and are filtered so they can **tighten** policy but not loosen it. Requires v2.1.133+ |

| `policyHelper` | object | - | Admin-deployed executable that computes managed settings dynamically at startup. Object shape: `{path: string, timeoutMs?: number, refreshIntervalMs?: number}` — `path` points at the helper binary; `timeoutMs` caps the wait (omit or `0` for no timeout); `refreshIntervalMs` controls re-runs at session start (omit for startup-only, `0` disables, otherwise must be ≥ `60000`). Only honored from MDM or a system `managed-settings.json` file (never from user/project settings). **When configured, `policyHelper` output is the sole active managed source — other managed-tier sources (server-managed, MDM, file) are ignored for that run.** Requires v2.1.136+ |

| `requiredMinimumVersion` | string | - | **(Managed only)** Prevents Claude Code from starting if the installed version is below this floor. CLI exits with an error prompting the user to upgrade. Complements `minimumVersion` (which controls auto-update floor) — this one enforces at startup. Example: `"2.1.163"` |

| `requiredMaximumVersion` | string | - | **(Managed only)** Prevents Claude Code from starting if the installed version exceeds this ceiling. CLI exits with an error if the version is too new. Use alongside `requiredMinimumVersion` to pin a specific version range in managed environments. Example: `"2.1.165"` |

| `browserExternalPageTools` | string | - | **(Managed only)** Set to `"disabled"` to prevent Claude from using tools to read or act on external pages in the desktop app's Browser pane. Users can still navigate to external sites themselves, and local dev server previews are unaffected |

| `disableBrowserExternalNavigation` | boolean | - | **(Managed only)** Set to `true` (JSON boolean only — string `"true"` is silently ignored) to prevent Claude from navigating the desktop app's Browser pane to external URLs. Only JSON boolean `true` is honored |

| `disableMobileSimulatorTools` | boolean | - | **(Managed only)** Set to `true` (JSON boolean only — a malformed value logs a warning) to remove mobile simulator tools from Claude. Only JSON boolean `true` is honored |

**Important**:

• `deny` rules have highest safety precedence and cannot be overridden by lower-priority allow/ask rules.
• Managed settings may lock or override local behavior even if local files specify different values.
• Array settings (e.g., `permissions.allow`) are **concatenated and deduplicated** across scopes — entries from all levels are combined, not replaced. **Exceptions:** `fallbackModel` and `availableModels` do **not** merge — the highest-precedence settings file that defines them supplies the entire value. For `availableModels`, a managed-source value applies as-is and lower scopes cannot extend it.

---

Core Configuration

General Settings

| Key | Type | Default | Description |

|-----|------|---------|-------------|

| `$schema` | string | - | JSON Schema URL for IDE validation and autocompletion (e.g., `"https://json.schemastore.org/claude-code-settings.json"`) |

| `model` | string | `"default"` | Override default model. Accepts aliases (`sonnet`, `opus`, `haiku`) or full model IDs |

| `agent` | string | - | Set the default agent for the main conversation. Value is the agent name from `.claude/agents/`. Also available via `--agent` CLI flag |

| `language` | string | `"english"` | Claude's preferred response language. Also sets the voice dictation language and **auto-generated session titles** (v2.1.121; since v2.1.176, an unset language causes titles to match the conversation language) |

| `claudeMdExcludes` | array | - | Glob patterns or absolute paths of `CLAUDE.md` files to skip when loading [memory](https://code.claude.com/docs/en/memory). Patterns match against absolute file paths. Only applies to user, project, and local memory; managed policy files cannot be excluded. Example: `["**/vendor/**/CLAUDE.md"]` |

| `claudeMd` | string | - | **(Managed only)** CLAUDE.md-style instructions injected as organization-managed [memory](https://code.claude.com/docs/en/memory). Only honored when set in managed or policy settings; ignored in user, project, and local settings. Example: `"Always run make lint before committing."` |

| `cleanupPeriodDays` | number | `30` | Age cutoff for the startup cleanup sweep (minimum 1). Inactive session transcripts and orphaned subagent worktrees are deleted; as of v2.1.117 the sweep also covers `~/.claude/tasks/`, `~/.claude/shell-snapshots/`, and `~/.claude/backups/`. Setting to `0` is rejected with a validation error. To disable transcript writes in non-interactive mode (`-p`), use `--no-session-persistence` or `persistSession: false` SDK option |

| `autoUpdatesChannel` | string | `"latest"` | Release channel: `"stable"` or `"latest"` |

| `minimumVersion` | string | - | Prevent the auto-updater from downgrading below a specific version. Automatically set when switching to the stable channel and choosing to stay on the current version until stable catches up. Used with `autoUpdatesChannel` |

| `alwaysThinkingEnabled` | boolean | `false` | Enable extended thinking by default for all sessions |

| `thinkingBudgetTokens` | number | - | Set a fixed token budget for extended thinking per response. When set, limits the number of thinking tokens to the specified value. If unset, Claude Code uses a dynamic budget based on the model and effort level. Works alongside `alwaysThinkingEnabled` *(not in official settings page — unverified)* |

| `skipWebFetchPreflight` | boolean | `false` | Skip the WebFetch domain safety check that sends each requested hostname to `api.anthropic.com` before fetching. Set to `true` in environments that block outbound traffic to Anthropic, such as Bedrock, Vertex AI, or Foundry deployments with restrictive egress |

| `availableModels` | array | - | Restrict which models users can select via `/model`, `--model`, Config tool, or `ANTHROPIC_MODEL`. Does not affect the Default option. As of v2.1.172, also constrains the model picker for subagent dispatching and the `advisorModel` picker. Use `enforceAvailableModels: true` to additionally constrain the Default model option. Example: `["sonnet", "haiku"]` |

| `enforceAvailableModels` | boolean | `false` | **(Managed only)** When `true`, the `availableModels` allowlist also constrains the Default model option — users cannot select a model outside the allowlist even via the Default slot. Without this flag, `availableModels` leaves the Default option unrestricted. Pair with `availableModels` for full model lockdown (v2.1.175) |

| `fastModePerSessionOptIn` | boolean | `false` | Require users to opt in to fast mode each session |

| `fastMode` | boolean | `false` | Enable fast mode for all sessions. When `true`, Claude Code uses the faster model tier by default. Users can also toggle fast mode per session with `/fast`. Pairs with `fastModePerSessionOptIn` |

| `defaultShell` | string | `"bash"` | Default shell for input-box `!` commands. Accepts `"bash"` (default) or `"powershell"`. Setting `"powershell"` routes interactive

常见问题（FAQ）

使用「settings.json 」这个 skill 能解决什么问题?

本 skill 专注于settings.json ，shanraisshan/claude-code-best-practice: claude-settings。它将相关流程标准化，帮助用户更快拿到可靠结果，减少重复手工操作。

什么情况下适合使用「settings.json 」?

当你需要在settings.json 配置大全相关工作中获得稳定、可复用的产出时最适合——无论是单次任务还是纳入日常工作流，都能直接调用。

使用「settings.json 」前需要准备什么?

需要一个具体的项目或任务上下文，最好带有代码仓库或需求文档。