第 23 章 | settings.json 全景

更新于 2026/5/12
💡 进群学习加 wx: agentupdate
(申请发送: agentupdate)

第 23 章：settings.json 全景

学习目标

搞清楚 4 种 settings 文件的优先级和用途，能给团队 / 个人 / 实验各放对地方。

4 种 settings

flowchart TB
    Final["最终生效设置"] --> Override["从高到低 override"]
    Override --> CMD["1. 命令行 flag
(最高优先)"]
    Override --> Local["2. .claude/settings.local.json
(项目本地，gitignore)"]
    Override --> Project["3. .claude/settings.json
(项目共享，进 git)"]
    Override --> User["4. ~/.claude/settings.json
(用户级)"]
    Override --> Default["5. Claude Code 默认
(最低)"]

    style Local fill:#fff9c4
    style Project fill:#c8e6c9

→ 高优先级覆盖低优先级。冲突时 local 赢。

各文件的角色

文件 谁写谁读 内容举例
~/.claude/settings.json 你自己（一次配，到处生效） 默认 model、theme、统一 hook
<project>/.claude/settings.json 团队共享（进 git） 项目级 permission、shared hook、agent 默认
<project>/.claude/settings.local.json 个人项目内（不进 git） 个人凭证、本地路径、实验设置
命令行 flag 临时（一次性） claude --model haiku 跑个 quick task

gitignore 策略

.claude/
├── agents/              ← 进 git（团队共享 agent）
├── commands/            ← 进 git
├── hooks/               ← 进 git
├── settings.json        ← 进 git
├── settings.local.json  ← .gitignore（个人化）
├── telegram-notify.json ← .gitignore（凭证）
└── .notify-sent         ← .gitignore（运行时状态）

我们项目的 .claude/.gitignore：

.notify-sent
telegram-notify.json
settings.local.json

常用字段速查

{
  "model": "claude-opus-4-7",
  
  "permissions": {
    "defaultMode": "bypassPermissions",
    "allow": ["Bash(npm:*)"],
    "deny": ["Bash(sudo:*)"]
  },
  
  "hooks": {
    "PreToolUse": [...],
    "Stop": [...]
  },
  
  "env": {
    "PYTHONPATH": "src/"
  },
  
  "includeCoAuthoredBy": false
}
字段 用途
model 默认模型（main Claude 用的）
permissions 全章 24 详讲
hooks Ch 25/26 详讲
env 注入到所有 Bash 子进程的环境变量
includeCoAuthoredBy 是否在 commit 加 Co-Authored-By: Claude

个人 vs 团队的实例

// ~/.claude/settings.json  (你的个人偏好，跨项目)
{
  "model": "claude-opus-4-7",
  "includeCoAuthoredBy": false
}

// <project>/.claude/settings.json  (团队共享)
{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "deny": ["Bash(sudo:*)", ...]
  },
  "hooks": { ... }
}

// <project>/.claude/settings.local.json  (你个人在这个项目)
{
  "env": {
    "TELEGRAM_BOT_TOKEN": "xxx",
    "TELEGRAM_CHAT_ID": "yyy"
  }
}

验证设置生效

启动 Claude Code 后跑：

/help        看 active 设置
/permissions 看 permission 规则解析后的样子

或者 :

# 看哪份 settings 被加载
ls -la ~/.claude/settings.json
ls -la <project>/.claude/settings.json
ls -la <project>/.claude/settings.local.json

反模式

❌ 把凭证写进项目共享 settings.json   会被 push 到 GitHub
❌ 把团队共识塞进 settings.local      其他人看不到
❌ 在 user 级设 deny 太严             所有项目被影响
❌ JSON 写错（缺逗号、单引号）         settings 静默不生效

你现在能做什么

  • 选对地方放每条设置
  • 配合 .gitignore 让凭证不外泄
  • 验证设置真的生效了

下一章正式讲 permissions 字段——多 agent 系统的安全护栏。