2.5 settings.json：权限与行为配置

两层配置，各司其职

读完上一节，你已经知道 CLAUDE.md 是什么了——用自然语言告诉 Claude Code "这个项目怎么运作"。

但 Claude Code 还有另一层配置，它不是写给 Claude 看的，而是直接控制工具本身的行为：它能做什么、不能做什么、用哪个模型、环境变量是什么……

这一层配置写在 settings.json 里。

两者的分工很清楚：

配置文件	写给谁看	控制什么
CLAUDE.md	Claude（AI）	项目指令、代码规范、工作方式
settings.json	Claude Code（工具）	权限、模型、环境变量、沙盒

一个是"你希望它怎么工作"，另一个是"它被允许做什么"。两者配合，才是完整的配置体系。

---

四个作用域，一个优先级链

和 CLAUDE.md 一样，settings.json 也有多个层级，对应不同的使用场景：

作用域	文件位置	影响范围	提交 git？
Managed（托管）	系统目录或服务端下发	这台机器上的所有人	由 IT 部署
User（用户）	~/.claude/settings.json	你的所有项目	否
Project（项目）	.claude/settings.json	这个项目的所有协作者	是
Local（本地）	.claude/settings.local.json	只有你，只在这个项目	否（自动 gitignore）

优先级从高到低： Managed > 命令行参数 > Local > Project > User

更具体的设置会覆盖更宽泛的设置。比如项目里的 deny 规则会覆盖你个人 allow 规则——你的 User 设置允许跑 curl，但项目 settings 里禁止了，那就是禁止。

怎么选用哪个层级？

• 个人偏好（主题、模型、快捷方式）→ User
• 团队统一要求（权限规则、MCP 服务器）→ Project（提交到 git）
• 只有你在用的临时配置 → Local
• 公司统一策略（安全合规）→ Managed（IT 部署）

---

文件位置速查

~/.claude/settings.json          # User 级：你的全局配置
.claude/settings.json            # Project 级：团队共享，提交 git
.claude/settings.local.json      # Local 级：本地私有，自动 gitignore

另外，~/.claude.json 存放的是另一类东西：你的登录状态、主题偏好、MCP 服务器配置、每个项目的授权记录。这个文件不要手动编辑，Claude Code 自己维护它。

小技巧：在 settings.json 第一行加上 "$schema" 引用，VS Code 和 Cursor 会自动提供字段补全和校验：

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

---

权限控制：最重要的配置

permissions 是 settings.json 里你最应该花时间设置的部分。它决定 Claude Code 能读什么文件、能跑什么命令、能访问什么网站。

三档权限：allow / ask / deny

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

• allow：直接放行，不需要你确认
• ask：每次都问你一遍
• deny：直接拒绝，没得商量

规则按顺序匹配：deny 优先，然后 ask，最后 allow。第一个匹配的规则生效。

规则语法

规则的格式是 工具名 或 工具名(限定符)：

规则	含义
Bash	所有 Bash 命令
Bash(npm run *)	以 npm run 开头的命令
Read(./.env)	读取 .env 文件
Read(./secrets/**)	读取 secrets/ 下的所有文件
WebFetch(domain:github.com)	访问 github.com
Edit(./src/**)	编辑 src/ 下的文件

保护敏感文件

这是 最应该在每个项目都配置的东西。把你的密钥、环境变量、证书通通挡在外面：

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

配置完之后，就算你不小心说了"读一下 .env 文件"，它也会拒绝。

defaultMode：默认权限模式

除了单条规则，还可以设置整体的默认权限模式：

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

可选值：

• "default"：每次危险操作都问你
• "acceptEdits"：文件读写自动放行，只有命令执行才问
• "bypassPermissions"：完全自动化，什么都不问（危险，慎用）

---

环境变量注入

env 字段让你在每个会话里自动注入环境变量，不需要在 shell 里手动 export：

{
  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

这和在 shell 里 export FOO=bar 的区别在于：这里设置的变量只在 Claude Code 会话里生效，不会污染你的 shell 环境。适合放一些"只有 Claude Code 需要知道"的配置。

注意：不要在这里放密钥或 API Key——这个文件可能会提交到 git。敏感信息用 deny 规则挡住，或者放在 Local scope 的 settings.local.json 里。

---

常用行为配置速查

除了权限和环境变量，还有一批常用设置值得了解：

配置项	作用	示例值
model	指定默认使用的模型	"claude-sonnet-4-6"
language	Claude 回复使用的语言	"chinese" / "japanese"
effortLevel	思考深度（影响速度和质量）	"low" / "medium" / "high"
cleanupPeriodDays	会话记录保留天数	30（默认）
autoUpdatesChannel	更新频道	"stable" / "latest"
spinnerTipsEnabled	是否显示加载提示	false
prefersReducedMotion	减少动画（无障碍）	true

自定义 git 提交署名

默认情况下，Claude Code 会在每次提交里加上一行 Co-Authored-By: Claude。如果你不想要这个，或者想换成自定义格式：

{
  "attribution": {
    "commit": "",
    "pr": ""
  }
}

两个都设成空字符串，就彻底去掉署名了。

---

企业场景：Managed 配置

如果你在公司里部署 Claude Code 给团队用，Managed 层级的配置能让你统一管控所有人的行为——而且用户无法覆盖。

部署方式取决于操作系统：

系统	部署方式
macOS	MDM 配置文件（Jamf/Kandji）或 /Library/Application Support/ClaudeCode/managed-settings.json
Windows	组策略 / Intune 注册表，或 C:\Program Files\ClaudeCode\managed-settings.json
Linux / WSL	/etc/claude-code/managed-settings.json

常见的企业用途：

{
  "forceLoginMethod": "claudeai",
  "disableBypassPermissionsMode": "disable",
  "allowManagedPermissionRulesOnly": true,
  "permissions": {
    "deny": [
      "WebFetch",
      "Bash(curl *)"
    ]
  },
  "companyAnnouncements": [
    "欢迎使用公司统一部署的 Claude Code，使用前请阅读安全规范：docs.example.com/ai-policy"
  ]
}

companyAnnouncements 里的内容会在每次启动时随机显示一条——可以用来推送安全提醒或公告。

---

用 /status 验证配置生效

改完配置之后，不确定有没有生效？在 Claude Code 里运行：

/status

它会列出当前加载的所有配置来源、每一层的设置是什么、有没有冲突或解析错误。

如果某个配置文件格式有问题（比如 JSON 语法错误），/status 也会直接告诉你哪个文件出了什么问题。

---

一个推荐的起步配置

如果你不知道从哪里开始，这是一份适合大多数个人项目的最小化起步配置，放在项目的 .claude/settings.json 里：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git status)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git reset *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

提交到 git，团队里的所有人都会自动继承这份安全基线。

---

下一章，我们进入进阶篇，深入讲上下文管理——CLAUDE.md 的完整写法、Auto Memory 机制，以及当上下文塞满了该怎么办。