AI Agent / 系统课时
认识设置文件与作用域
认识设置文件与作用域
Claude Code 的同一项配置可能来自个人、项目、本机或组织策略。只有先弄清文件位置、共享范围与优先级,才能避免“明明改了却没生效”,并把团队规则与个人偏好放到正确位置。
学习目标
- 识别用户、项目、本地和托管设置的保存位置
- 理解设置覆盖与数组合并规则
- 能通过状态与诊断命令确认实际加载来源
四类设置分别解决什么问题
用户设置位于 ~/.claude/settings.json,适合放跨项目生效的个人偏好,例如默认权限模式。项目设置位于 .claude/settings.json,通常提交到版本库,用于共享团队规则。本地设置位于 .claude/settings.local.json,只服务当前机器和当前项目,适合个人试验或永久授权。组织还可以部署不可被普通设置覆盖的托管设置。:contentReference[oaicite:0]{index=0}

| 作用域 | 位置 | 适合内容 | 是否共享 |
|---|---|---|---|
| 用户 | ~/.claude/settings.json |
个人全局偏好 | 否 |
| 项目 | .claude/settings.json |
团队权限、Hooks、插件开关 | 通常是 |
| 本地 | .claude/settings.local.json |
当前机器的例外与试验 | 否 |
| 托管 | 由组织策略下发 | 强制安全边界 | 由管理员控制 |
在 Windows 中,~ 通常解析为 %USERPROFILE%。不要把访问令牌、密码或私钥直接写进任何可提交的设置文件;设置文件负责行为配置,不应充当密钥仓库。
配置一个最小项目设置
下面的项目设置允许执行测试,同时拒绝读取常见密钥文件。$schema 用于编辑器补全和校验,不会改变运行行为。
{
"$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}
claude doctor预期结果
<检查摘要>
Settings: OK实际输出可能包含版本、认证和环境检查;若设置无效,会列出对应文件路径与字段。修正后重新执行,直到设置检查不再报错。
选择作用域的实用判断
团队必须统一的最小权限、Hooks 和插件开关放项目设置;仅你需要的默认模式或显示偏好放用户设置;机器相关路径和临时授权放本地设置;组织级禁用项和强制隔离策略交给托管设置。最危险的做法,是为了省一次确认把宽泛授权提交到项目设置,让所有克隆仓库的人都继承。