Claude Code 深度学习手册

主题

Settings（设置） ​

Claude Code 通过分层的 settings.json 文件统一管理权限、模型、环境变量、hooks、MCP、UI 等几乎所有可配置行为，并按 Managed → 命令行 → Local → Project → User 的优先级合并。

你的真实配置 ​

你现在生效的设置（两层）：

全局 ~/.claude/settings.json：

json
{
  "permissions": { "defaultMode": "bypassPermissions" },
  "enabledPlugins": { "...15 个插件...": true, "semgrep@claude-plugins-official": false },
  "skipDangerousModePermissionPrompt": true,
  "skipAutoPermissionPrompt": true,
  "theme": "..."
}

项目 .claude/settings.local.json（被 gitignore，只你本机）：

json
{
  "permissions": { "allow": ["WebFetch(domain:gitee.com)", "Bash(pip list *)", "Bash(xargs cat)"] },
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["linear"]
}

两个值得注意的点 ​

  1. enabledMcpjsonServers: ["linear"] 是悬空配置：它的作用是"自动批准项目 .mcp.json 里名为 linear 的 server"，但你项目根没有 .mcp.json，也没找到 linear server——所以这条目前是空转的。要么你删掉它，要么补一个 .mcp.json 定义 linear（比如连你们的 issue 系统）。
  2. enableAllProjectMcpServers: true：会自动批准项目 .mcp.json 里所有 server。和上面那条 enabledMcpjsonServers 有点重复（前者全开，后者只点名 linear）。当前没 .mcp.json 两者都没实际效果，但以后加 .mcp.json 时 enableAllProjectMcpServers 会让全部 server 免审批——团队共享时要留意安全。

去真实体验 ​

想验证什么这样做
交互式看/改设置输入 /config（主题、模型、effort、memory 开关等）
看权限规则及来源文件/permissions
看哪些设置文件在生效/doctor（含一堆健康检查）
加编辑器自动补全在 settings.json 顶部加 "$schema": "https://json.schemastore.org/claude-code-settings.json"

该把什么放哪一层（贴你的情况） ​

内容放哪你的现状
团队共享、要进 git 的规则项目 .claude/settings.json你没有这个文件——团队级规则目前没沉淀
个人本机偏好/放行项目 .claude/settings.local.json（gitignore）你的 gitee/pip 放行在这
跨所有项目的个人默认~/.claude/settings.jsonbypassPermissions、插件开关在这
组织强制策略Managed（最高优先级，不可覆盖）无

优先级（高→低）：Managed > 命令行参数 > Local > Project > User。所以你全局的 bypassPermissions（User 层）会被项目层覆盖——如果哪天想在本项目更严，在 .claude/settings.json 写 "defaultMode": "default" 即可压过全局。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

Settings 是 Claude Code 的核心配置系统，主体是 JSON 格式的 settings.json 文件，分布在四个 scope：Managed（IT 部署、不可覆盖）、User（~/.claude/settings.json）、Project（.claude/settings.json，提交到 git）、Local（.claude/settings.local.json，被 gitignore）。同一个 key 出现在多个 scope 时按固定优先级合并。文档原话：「settings.json supports a number of options」。除 settings.json 外，还有一批存放在 ~/.claude.json 的全局/UI 类配置，以及对应的环境变量、/config 命令交互界面。

怎么工作 ​

  • 四个 scope 的文件被读取后按优先级「合并」（merge），不是整体替换：同名 key 高优先级覆盖低优先级，未指定的 key 沿用低优先级值。
  • 优先级从高到低：1. Managed（最高，不可被任何东西覆盖）2. 命令行参数（临时 session 覆盖）3. Local（.claude/settings.local.json）4. Project（.claude/settings.json）5. User（~/.claude/settings.json，最低）。
  • permissions 的规则求值顺序固定为 deny → ask → allow，first match wins（第一个命中的规则生效），所以 deny 永远压过 allow。
  • 权限规则语法分两种：Tool 匹配该工具全部调用；Tool(specifier) 匹配特定模式，如 Bash(npm run *)、Read(./.env)、WebFetch(domain:example.com)。
  • 大多数设置支持 live reload：文件一改就生效无需重启（permissions、hooks、apiKeyHelper、credential helpers 等），并对每个检测到的变化触发 ConfigChange hook。
  • 少数设置需要重启或特定动作才生效：model 需用 /model 中途切换；outputStyle 在 /clear 或重启时重建 system prompt。
  • Managed 设置可由 MDM/OS 策略下发（macOS managed preferences、Windows 注册表、Linux/etc 等），并支持 managed-settings.d/ 目录下多个 *.json 按字母序合并。
  • env 里的环境变量会注入到每个 session 及其子进程；部分行为有版本差异（如 v2.1.143 起 NO_COLOR/FORCE_COLOR 传给子进程但不改 CLI 颜色）。

怎么配置 / 用法 ​

主配置文件路径（按 scope）：User=~/.claude/settings.json；Project=.claude/settings.json（提交 git）；Local=.claude/settings.local.json（gitignore）；Managed=系统级 managed-settings.json。Windows 上 ~/.claude 解析为 %USERPROFILE%.claude。

典型 permissions 配置：

json
"permissions": {
  "allow": ["Bash(npm run lint)", "Bash(npm run test *)", "Read(~/.zshrc)"],
  "deny": ["Bash(curl *)", "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"],
  "ask": ["Bash(git push *)"],
  "additionalDirectories": ["../docs/"],
  "defaultMode": "acceptEdits",
  "disableBypassPermissionsMode": "disable"
}

建议加 $schema 获得编辑器自动补全与校验：

json
{ "$schema": "https://json.schemastore.org/claude-code-settings.json" }

另一批 UI/全局配置存在 ~/.claude.json（当前为 autoConnectIde、autoInstallIdeExtension、externalEditorContext、teammateDefaultModel；editorMode、autoScrollEnabled、showTurnDuration、teammateMode、terminalProgressBarEnabled 这 5 项自 v2.1.119 起已改存 settings.json）。交互式修改用 /config 命令（含状态查看、模型/主题/effort/memory 等切换）。

什么时候用 ​

  • 团队共享、需进 git 的规则（统一 lint/test 白名单、deny 敏感文件读取）→ 放 Project 的 .claude/settings.json。
  • 个人偏好、不想提交（本地 API key helper、个人 allow 规则）→ 放 Local 的 .claude/settings.local.json（已被 gitignore）。
  • 跨所有项目的个人默认（model、editorMode、env）→ 放 User 的 ~/.claude/settings.json。
  • 组织强制策略（禁用 bypass、限制登录方式、MCP 白名单）→ 用 Managed，普通用户无法覆盖。
  • 纯 UI/会话偏好（主题、自动滚动、通知方式）→ 优先用 /config 命令交互修改，落到 ~/.claude.json。
  • 别把需要团队一致的安全规则放 User scope——它优先级最低，会被项目/本地覆盖。

限制 / 坑 ​

  • Managed 优先级最高且不可被任何 scope 覆盖；命令行参数仅做临时 session 覆盖。
  • permissions 求值 deny → ask → allow 且 first match wins：写了 allow 但又被 deny 命中，仍被拒绝。
  • model 改了不会热生效，需用 /model 切换；outputStyle 改了需 /clear 或重启才重建 system prompt。
  • includeCoAuthoredBy 已 Deprecated，应改用 attribution。
  • permission mode 中的 auto 在 project/local settings 里设置会被忽略（as of v2.1.142）。
  • cleanupPeriodDays 最小值为 1，默认 30；过期 session 文件在启动时删除。
  • 部分设置有最低版本要求：skillOverrides 需 v2.1.129；maxSkillDescriptionChars / skillListingBudgetFraction 需 v2.1.105；disableRemoteControl 需 v2.1.128；policyHelper 需 v2.1.136+；parentSettingsBehavior 需 v2.1.133+。
  • Windows 下 managed 文件路径 C:\ProgramData\ClaudeCode\ 自 v2.1.75 起不再支持，改为 C:\Program Files\ClaudeCode\。
  • 该官方页面不含「所有可用工具 + 是否需要权限」的完整工具表，工具名仅在权限示例里出现。

硬事实速查（24 条） ​

  • 四个 scope 文件路径：User=~/.claude/settings.json；Project=.claude/settings.json（committed to git）；Local=.claude/settings.local.json（gitignored）；Managed=system managed-settings.json。
  • 优先级（高→低）：1 Managed 2 Command line arguments 3 Local 4 Project 5 User。
  • Windows：~/.claude 解析为 %USERPROFILE%.claude。
  • 其他配置文件位置：Subagents 在 ~/.claude/agents/ 或 .claude/agents/；MCP servers 在 ~/.claude.json 与 .mcp.json；CLAUDE.md 在 ~/.claude/CLAUDE.md、CLAUDE.md 或 .claude/CLAUDE.md、CLAUDE.local.md。
  • API/认证 key：apiKeyHelper（/bin/sh 脚本，生成 X-Api-Key 与 Authorization: Bearer 头）、forceLoginMethod（"claudeai" 或 "console"）、forceLoginOrgUUID（UUID 字符串或数组）。
  • 模型类 key：model、availableModels（如 ["sonnet","haiku"]）、modelOverrides（映射到 Bedrock ARN 等）、alwaysThinkingEnabled、effortLevel（"low"/"medium"/"high"/"xhigh"）。
  • env：注入每个 session 及子进程的环境变量；v2.1.143 起 NO_COLOR/FORCE_COLOR 传子进程但不改 CLI 颜色。
  • permissions 子字段：allow、deny、ask、additionalDirectories、defaultMode、disableBypassPermissionsMode、skipDangerousModePermissionPrompt。
  • 权限规则语法：Tool 匹配全部；Tool(specifier) 如 Bash(npm run *)、Read(./.env)、WebFetch(domain:example.com)。求值顺序 deny → ask → allow，first match wins。
  • permission modes：default（每次询问）、acceptEdits（自动批准编辑）、plan（先展示计划）、auto（AI 分类器，project/local 设置时被忽略，as of v2.1.142）、dontAsk、bypassPermissions（跳过全部权限检查）。
  • memory 类：autoMemoryEnabled（默认 true，可用 /memory 或 env CLAUDE_CODE_DISABLE_AUTO_MEMORY 切换）、autoMemoryDirectory、claudeMd（Managed only）、claudeMdExcludes、cleanupPeriodDays（默认 30，最小 1）。
  • MCP 类：enableAllProjectMcpServers、enabledMcpjsonServers（如 ["memory","github"]）、disabledMcpjsonServers、allowedMcpServers/deniedMcpServers/allowManagedMcpServersOnly（Managed）。
  • hooks 类：hooks、disableAllHooks、allowManagedHooksOnly（Managed）、allowedHttpHookUrls（支持 * 通配）、httpHookAllowedEnvVars、statusLine（如 {"type":"command","command":"~/.claude/statusline.sh"}）。
  • 凭据集成：awsAuthRefresh、awsCredentialExport（输出 JSON）、gcpAuthRefresh、otelHeadersHelper。
  • Git/署名：attribution（{"commit":...,"pr":...}）、includeCoAuthoredBy（已 Deprecated，默认 true）、includeGitInstructions、prUrlTemplate（占位符 {host}{owner}{repo}{number}{url}）。
  • UI/UX：spinnerTipsEnabled（默认 true）、outputStyle（如 "Explanatory"，/clear 或重启重建）、language、viewMode、showThinkingSummaries（默认 false）、autoUpdatesChannel（"stable"/"latest"）、minimumVersion。
  • 存于 ~/.claude.json 的全局/UI 配置（当前）：autoConnectIde、autoInstallIdeExtension、externalEditorContext、teammateDefaultModel（放进 settings.json 会触发 schema 校验错误）。editorMode（"normal"/"vim"）、autoScrollEnabled、showTurnDuration、teammateMode、terminalProgressBarEnabled 在 v2.1.119 之前存这里，自 v2.1.119 起改存 settings.json。
  • Skills 类：skillOverrides（"on"/"name-only"/"user-invocable-only"/"off"，v2.1.129）、maxSkillDescriptionChars（默认 1536，v2.1.105）、skillListingBudgetFraction（默认 0.01=1%，v2.1.105）、disableWorkflows、disableSkillShellExecution。
  • 关键环境变量：ANTHROPIC_MODEL、CLAUDE_CODE_EFFORT_LEVEL、CLAUDE_CODE_DISABLE_THINKING=1、CLAUDE_CODE_ENABLE_TELEMETRY（设为 1 开启遥测，默认关闭/需 opt-in）、CLAUDE_CODE_DISABLE_AUTO_MEMORY、CLAUDE_CODE_USE_POWERSHELL_TOOL=1、CLAUDE_CODE_API_KEY_HELPER_TTL_MS、DISABLE_AUTOUPDATER、OTEL_METRICS_EXPORTER、CLAUDE_CODE_NO_FLICKER。
  • Managed 下发路径：macOS managed preferences domain com.anthropic.claudecode；Windows 注册表 HKLM\SOFTWARE\Policies\ClaudeCode（user 级 HKCU 最低优先级）；macOS /Library/Application Support/ClaudeCode/；Linux/WSL /etc/claude-code/；Windows C:\Program Files\ClaudeCode\（C:\ProgramData\ClaudeCode\ 自 v2.1.75 不再支持）；drop-in 目录 managed-settings.d/ 下 *.json 按字母序合并。
  • live reload 生效项：permissions、hooks、apiKeyHelper、credential helpers，并对每个变化触发 ConfigChange hook；需重启/特定动作项：model（用 /model）、outputStyle（/clear 或重启）。
  • $schema 校验地址：https://json.schemastore.org/claude-code-settings.json
  • worktree 配置：baseRef（"fresh"/"head"）、symlinkDirectories、sparsePaths、bgIsolation（"worktree"/"none"，v2.1.143+）。
  • sandbox 配置含 enabled、failIfUnavailable、excludedCommands，及 filesystem（allowWrite/denyWrite/denyRead/allowRead）与 network（allowedDomains/deniedDomains/allowLocalBinding 等）子块。

官方出处：https://code.claude.com/docs/en/settings