它到底是什么

--setting-sources 是一个逗号分隔的列表参数，用于控制本次会话加载哪些"设置来源"。官方 CLI 参考文档对它的描述是一句话："Comma-separated list of setting sources to load (user, project, local)"（引自 GitHub issue #92254 对官方文档原文的引用）。

可接受的值只有三个，可任意组合或留空：

• user —— 用户级来源
• project —— 项目共享来源
• local —— 项目本地来源

在 Claude Code 的设置优先级体系里（参见官方 Settings files and precedence），完整的优先级从高到低是：Managed settings（组织/MDM/console 强制）→ Command line(claude --settings)→ Project local(.claude/settings.local.json)→ Shared project(.claude/settings.json)→ User（~/.claude/settings.json）。

用法

claude --setting-sources user,project

也可以只用单个来源，或传空字符串表示完全不加载任何来源：

claude --setting-sources ""

未找到对应的环境变量或 settings.json 字段——已直接查阅官方 Environment variables 文档，其中没有 CLAUDE_CODE_SETTING_SOURCES 或类似条目。这个 flag 本身就是"决定加载哪些配置文件"的入口，自然不能写进它自己要控制的配置文件里。

与其他 flag 的组合 / 互斥

• 可以和 --settings <file-or-json> 一起用，二者作用层级不同：--setting-sources 决定是否读取 user/project/local 这几类文件，而 --settings 传入的 JSON 属于优先级更高的 "Command line" 层，不受 --setting-sources 过滤（引自 issue #92254 的讨论）。

在 settings.json / env 的等价配置

运行约束 / 限制

经典使用场景

• 无人值守 / CI 环境：担心 ~/.claude/ 下的用户级 hooks、plugins、CLAUDE.md 干扰自动化流程时，用 --setting-sources project,local 只保留项目内配置。

常见坑

• 文档一句话严重低估了实际覆盖范围：根据 issue #92254（报告者在 v2.1.261 上实测），省略 user 时被排除的不只是 ~/.claude/settings.json，还包括 ~/.claude/CLAUDE.md、所有 plugins（连带其 hooks 和 skills）、~/.claude/skills/、~/.claude/agents/、~/.claude/commands/；至于省略 project 时具体会排除哪些内容，该 issue 并未做实测，只在讨论中提到自 #78007 起项目规则会在缺少 project 时被跳过。这一细节官方文档正文并未写明，只能从该 issue 的实测描述中得到，请以你所用版本的实际行为为准。
• SDK 里"不设置"不等于"用默认全量加载"：根据 claude-agent-sdk-golang 的示例（该项目属于第三方实现，并非 Anthropic 官方仓库），当 SDK 里的 setting_sources 保持未设置（nil）时，SDK 会当作完全隔离、不加载任何设置来处理，这和直接在终端敲 claude（默认加载全部三层）的体验不同，容易造成"为什么 SDK 跑起来 hooks 和 CLAUDE.md 都不生效"的困惑。
• SDK 与 CLI 版本不兼容：根据 claude-agent-sdk-python 的 issue #186，该 SDK 曾无条件地把 --setting-sources 拼进命令行（哪怕值为空），导致配合某些 CLI 版本时报错 unknown option '--setting-sources'；遇到此类报错应检查 SDK 与 CLI 版本是否匹配，而不是先怀疑自己的参数写错了。

来源

• Settings files and precedence — 官方文档
• Environment variables — 官方文档
• [DOCS] --setting-sources docs do not say what each source value actually gates · Issue #92254
• Claude Code SDK --setting-sources Flag Compatibility Issue · Issue #186
• setting_sources example — claude-agent-sdk-golang
• 10 Claude Code CLI flags you probably aren't using — mager.co