官方教程中文版核心配置与能力
配置 Claude Code
基于 Anthropic 官方 Claude Code settings 文档，帮助新手理解 managed、user、project、local scope 和配置验证。
Claude Code 的配置不要只记一个 settings.json。官方把配置拆成多个 scope：managed、user、project、local。新手先决定“这条配置属于谁”，再决定写到哪里。
先理解四个 scope
Managed scope：企业或团队管理员下发，不能被用户或项目覆盖。适合安全策略、合规要求、统一权限和统一登录方式。
User scope：当前用户的全局配置，通常在 ~/.claude/。适合个人偏好、跨项目常用工具和个人默认权限。
Project scope：仓库里的 .claude/，应该提交到 git。适合团队共享的权限、hooks、插件、MCP 结构和项目标准。
Local scope：当前仓库里的本机私有配置，例如 .claude/settings.local.json。适合个人路径、临时实验和只在本机存在的设置。
优先级怎么理解
官方优先级从高到低是：
- Managed。
- 命令行参数。
- Local project settings。
- Shared project settings。
- User settings。
Managed 不能被覆盖。项目层可以压过用户层。Local 只应该处理本机例外。
另一个容易忽略的点：数组类设置会跨 scope 合并、去重，不是简单替换。比如 permissions.allow 在多个层级出现时，会合并为最终列表。要真正阻断某个能力，用明确 deny 或 managed policy。
新手应该怎么放配置
建议分工：
- 个人默认习惯放 user。
- 团队必须一致的规则放 project。
- 本机路径和临时实验放 local。
- 必须强制执行的安全策略放 managed。
不要把所有配置都塞进 ~/.claude/settings.json。这样会让不同项目互相污染，也会让团队协作变得不可复现。
settings.json 管什么
settings.json 适合管理：
- permissions。
- 环境变量。
- 默认权限模式。
- plugins。
- additionalDirectories。
- hooks 可访问的 URL 和环境变量。
- 更新通道和部分客户端行为。
它不是所有 Claude Code 配置的唯一入口。官方还把 MCP、subagents、CLAUDE.md、project state 等放在不同位置。新手不要看到“配置”就都往 settings 里写。
敏感文件应该怎么处理
官方当前推荐用 permissions.deny 阻止 Claude Code 读取敏感文件。常见目标包括 .env、密钥目录、凭据文件和私有配置。
但这只是 Claude Code 工具层限制，不是操作系统级隔离。如果你允许 Bash，子进程仍可能读取文件。因此敏感文件治理要同时考虑 permissions、Bash 规则、sandbox 和系统文件权限。
怎么确认配置生效
在 Claude Code 里先看 /status。它会显示当前加载了哪些 settings source，以及配置来自哪里。如果某个 settings 文件 JSON 错误，也会在这里暴露。
如果是权限问题，继续看 /permissions。如果是记忆或规则问题，再看 /memory。
排错时不要猜。先确认加载源，再确认优先级，再确认数组是否被合并。
新手常见坑
- 把团队规则放进 user scope。
- 把本机路径提交到 project scope。
- 以为 project 写空数组能清掉 user 层配置。
- 把密钥写进 settings。
- 不看
/status就判断配置没生效。 - 忽略 managed policy，反复改 user 或 project 文件。
怎么判断配置健康
健康标准：
- 每条配置都知道属于 user、project、local 还是 managed。
- 团队共享配置能提交，个人配置不会污染仓库。
- 敏感文件有明确 deny。
- 高风险权限不靠口头约束。
/status能看到预期来源。/permissions里的规则来源可解释。
配置系统的目标是让 Claude Code 在不同项目里行为可预期，而不是把所有开关集中到一个文件。
官方来源
最近更新：2026年5月4日