AI Agent / 系统课时

认识设置文件与作用域

认识设置文件与作用域

Claude Code 的同一项配置可能来自个人、项目、本机或组织策略。只有先弄清文件位置、共享范围与优先级,才能避免“明明改了却没生效”,并把团队规则与个人偏好放到正确位置。

学习目标

  • 识别用户、项目、本地和托管设置的保存位置
  • 理解设置覆盖与数组合并规则
  • 能通过状态与诊断命令确认实际加载来源

四类设置分别解决什么问题

用户设置位于 ~/.claude/settings.json,适合放跨项目生效的个人偏好,例如默认权限模式。项目设置位于 .claude/settings.json,通常提交到版本库,用于共享团队规则。本地设置位于 .claude/settings.local.json,只服务当前机器和当前项目,适合个人试验或永久授权。组织还可以部署不可被普通设置覆盖的托管设置。:contentReference[oaicite:0]{index=0}

Claude Code 设置作用域与加载关系

作用域 位置 适合内容 是否共享
用户 ~/.claude/settings.json 个人全局偏好 否
项目 .claude/settings.json 团队权限、Hooks、插件开关 通常是
本地 .claude/settings.local.json 当前机器的例外与试验 否
托管 由组织策略下发 强制安全边界 由管理员控制

在 Windows 中,~ 通常解析为 %USERPROFILE%。不要把访问令牌、密码或私钥直接写进任何可提交的设置文件;设置文件负责行为配置,不应充当密钥仓库。

配置一个最小项目设置

下面的项目设置允许执行测试,同时拒绝读取常见密钥文件。$schema 用于编辑器补全和校验,不会改变运行行为。

json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm test)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

把它保存为项目根目录下的 .claude/settings.json。该文件适合随代码提交,因为其中只包含团队共同接受的规则。若某个授权只适用于你自己的机器,应放进 .claude/settings.local.json,而不是扩大整个团队的能力边界。

设置如何合并与覆盖

优先级从高到低依次是托管设置、当前会话的 --settings 覆盖、本地项目设置、共享项目设置、用户设置。标量值由高优先级来源覆盖;多数数组值会跨作用域拼接并去重,因此低层的 allow、ask 或 deny 规则不会因为高层出现同名数组就自动消失。:contentReference[oaicite:1]{index=1}

这意味着权限规则要按“叠加”理解。例如用户设置允许 Bash(npm test),项目设置又拒绝 Bash(npm *),最终拒绝规则仍会生效。不要试图用更具体的低层允许规则绕过高层限制。

验证当前会话实际读取了什么

在 Claude Code 会话中运行 /status,查看 Setting sources,可以确认用户、项目、本地或托管来源是否被加载。若 JSON 格式错误或字段无效,再运行诊断命令定位文件和字段。:contentReference[oaicite:2]{index=2}

bash
claude doctor

预期结果

text
<检查摘要>
Settings: OK

实际输出可能包含版本、认证和环境检查;若设置无效,会列出对应文件路径与字段。修正后重新执行,直到设置检查不再报错。

选择作用域的实用判断

团队必须统一的最小权限、Hooks 和插件开关放项目设置;仅你需要的默认模式或显示偏好放用户设置;机器相关路径和临时授权放本地设置;组织级禁用项和强制隔离策略交给托管设置。最危险的做法,是为了省一次确认把宽泛授权提交到项目设置,让所有克隆仓库的人都继承。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

认识设置文件与作用域

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通