settings.json 常用配置项逐个讲清

网上分享的“Claude Code 推荐配置”往往很长：默认模型、输出风格、一串放行规则、自动批准项目里所有 MCP 服务器的开关，再加一个 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80。

整份复制进 settings.json，用了一阵，模型回答变了，某个 MCP 工具连不上，你却说不清是哪一项在起作用。

照抄配置的麻烦在于，每个字段都在改变 Claude Code 的运行方式，而你不知道它改了什么。有的字段只是界面偏好，有的会自动批准外部服务器，有的环境变量在你的模型和环境里根本不起作用。几项一起改，出了问题就没有判断依据。

更稳的做法是反过来：

• 先分清哪些内容属于项目说明，哪些属于运行配置；
• 从一份每项都能解释的最小配置开始；
• 每次只加一个解决当前问题的字段，加完核对结果。

下面按这个顺序，把常用字段逐个过一遍：它解决什么问题，用的时候要注意什么。

01 项目说明和运行配置分开放

CLAUDE.md 说明团队要求，Settings 则改变模型、权限、环境变量等运行行为。把“默认用某个模型”写进自然语言指令，并不会直接修改运行配置。

可以用下面的对照快速判断内容应该放在哪里：

两者配合使用：项目指令提供行动依据，Settings 决定对应的运行方式，各自都要验证。

02 从一份能解释的最小配置开始

从简单、能解释清楚的配置开始。先理清来源和合并方式，再检查 JSON 是否合法。下面几项分别设置模型、输出与读取限制，每一项都要知道用来解决什么问题：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "outputStyle": "Explanatory",
  "respectGitignore": true,
  "permissions": {
    "allow": [
      "Bash(pnpm lint)",
      "Bash(pnpm typecheck)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

$schema 让编辑器提示字段、类型并做基础校验。它可能更新得较慢。新字段被标成警告时，还要查当前官方字段表。另外，设置文档提醒，设置文件是严格的 JSON，// 注释和多余逗号都算语法错误。

每次只调整解决当前问题的字段。例如需要更详细的解释，就先试输出风格，再核对结果。同时更换模型、权限和插件，会让变化难以追溯。这份配置会和用户、本地等其他来源合并，最后生效的值怎样推算，见Claude Code 多份配置冲突时，哪个生效。

03 模型与输出风格

model 设置新会话默认模型。上例使用稳定别名 sonnet，通常比写死具体版本更容易维护。

想在当前会话换模型，用 /model。官方文档说明，/model 会把选择保存为新会话的默认值；只想临时试用，就在 /model 打开的选择器里按 s，只切换当前会话。直接改文件里的 model 后，最好新建或重启会话，再用 /model 核对当前模型。

outputStyle 改的是系统提示里的表达方式，作用不限于回答长短，项目要求仍放在项目指令里。切换后的生效方式要看版本：

这张表来自 输出风格文档。先确认版本，保留当前任务仍需要的历史。

04 权限、环境变量与文件建议

permissions 决定工具调用被允许、询问还是拒绝。采用外部配置前，逐条核对工具、参数和影响范围，避免无意中放开整个 Bash。规则怎样写窄，见Claude Code 权限白名单的五个常见漏洞。

env 可以向 Claude Code 会话及它启动的子进程注入环境变量：

{
  "env": {
    "MY_PROJECT_MODE": "development"
  }
}

共享配置只放不含秘密的团队开关。API Key、令牌用密钥管理、Claude Code 认证或受控启动环境提供。本地的 settings.local.json 也是明文，不能当密钥库。

MCP 服务器还要看自己的连接配置。需要哪些变量，就在对应 MCP 配置中设置并检查；官方文档在添加本地 MCP 服务器时，用 --env 把变量传给服务器进程。

比如终端已经能读到 JIRA_TOKEN，Jira MCP 仍报未授权。这时要查清变量传到了哪个进程：终端能读取，MCP 进程未必读得到。核对 MCP 的变量配置，再做一次最小工具调用，看鉴权结果是否改变。

respectGitignore 主要影响 @ 的文件建议，按官方字段说明，它控制 @ 文件选择器是否排除被 .gitignore 匹配的文件。保护秘密要分开做：内置读取工具用 permissions.deny，任意子进程的访问再用沙箱限制。

界面提示只影响使用体验，通常留在用户或本地配置。具体开关可以在需要时再设置。

05 插件、项目 MCP 与提交署名

enabledPlugins 按完整的“插件名@市场名”控制插件的启用和停用。

插件开关很容易改，来源和权限更值得先查。确认它做什么、能访问哪里，再启用；这个开关本身不会替你判断外部代码是否可信。

enableAllProjectMcpServers 会自动批准项目 .mcp.json 中定义的所有 MCP 服务器。这在服务器来源完全受控的团队仓库中可以减少确认，但不应作为所有项目的默认设置。MCP 服务器能连接外部系统，也可能获得敏感能力；不清楚仓库配置来源时，应逐个检查和批准。

设置字段参考里还有一个细节：在还没接受信任对话框的文件夹里，共享项目配置中的这个开关会被忽略，只有用户配置、托管配置和 --settings 里的值才算数。

attribution 设置 Git 提交或 Pull Request 的署名。有团队披露规范，就在项目配置中统一维护。是否保留署名应服从团队和组织要求，团队规定了 AI 使用披露，就别因为个人偏好把它关掉。

06 照抄阈值之前，先观察问题

看到 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80，可能想直接照着设置，让上下文到 80% 就压缩。但问题真出在压缩时机上吗？还要看模型和环境是否支持。

环境变量参考对它的说明是：它设置自动压缩在窗口的百分之多少时触发，只能调低、让压缩提前，高于默认值的设置会被忽略；而且只在那些会在模型上下文上限之前压缩的会话里生效。照抄可能无效，也可能过早压缩仍在使用的信息。

先观察问题，再按这个顺序处理：

1. 先用 /context 观察上下文主要被什么占用。
2. 在无关任务之间使用 /clear。
3. 需要保留当前任务时，使用 /compact 主动压缩，并说明希望保留的重点。
4. 只有明确了解当前模型和环境的压缩行为后，再设置阈值变量。

只针对已观察到的问题做最小调整，避免同时改动多个参数后失去判断依据。

日常维护时逐项引入插件、MCP 和 Hook，删除失效字段，升级后用 /doctor 检查。每项设置都记下用途与来源，下次哪里不对劲，你知道该先看哪一行。