它到底是什么

--settings 是 Claude Code CLI 的启动 flag，用于为当次会话临时加载一份设置（settings），覆盖已保存的配置。

根据官方 CLI 参考文档（code.claude.com/docs/en/cli-reference），--settings 接受的值可以是：

• 一个指向设置文件的文件路径，或
• 一段内联 JSON 字符串

官方 headless 文档（code.claude.com/docs/en/headless）在描述 --bare 模式下如何补齐各类配置时，把它列为：

同一篇文档还给出一个具体用法场景：在 --bare 模式下（该模式不读取用户目录下的登录凭据），如果要用 Anthropic API 而不是订阅登录，可以"通过 --settings 的 JSON 里提供 apiKeyHelper"来提供密钥获取方式。

用法

claude --settings ./settings.json

也可以直接传内联 JSON:

claude --settings '{"model":"claude-haiku-4-5-20251001"}'

官方文档未提及与之对应的环境变量或 settings.json 字段——--settings 本身就是"命令行级别的一次性覆盖机制"。如果想让同样的配置长期生效，需要把内容写入 ~/.claude/settings.json（用户级）或 .claude/settings.json（项目级）等真实的设置文件。

与其他 flag 的组合 / 互斥

在 --bare 模式下（跳过 hooks、skills、自定义命令、已安装插件、MCP servers、auto memory 和 CLAUDE.md 的自动发现），官方文档把 --settings 列为在该模式下补充配置的正规途径之一，与它并列的还有：

可以看到 --mcp-config 采用了和 --settings 相同的"文件路径或内联 JSON"设计，分别管理设置和 MCP server 配置。

在 settings.json / env 的等价配置

--settings 本质上就是把一份设置内容临时插入到设置的优先级链条里，而不是某个具体 key 的等价写法。官方文档（code.claude.com/docs/en/settings）给出的优先级图示中，把 claude --settings 明确列为独立的一层：

也就是说，--settings 会覆盖项目和用户级别的持久化配置，但不会覆盖组织下发的 managed settings。

官方 settings-reference 文档中还给出一个具体例子：对于 remote.defaultEnvironmentId 这个 key，一个自托管的 ccpool_ ID"只能从 user 和 managed settings 以及 --settings 读取"——即某些 key 明确把项目级文件排除在外，只认用户级、管理员级和命令行这三条路径。

运行约束 / 限制

经典使用场景

• CI / headless 运行：在流水线里通过 --settings 传一段内联 JSON，对当次运行做临时覆盖，而不用改动仓库里提交的 .claude/settings.json。
• --bare 模式下补齐配置：--bare 会跳过对用户目录和项目目录里 hooks/CLAUDE.md 等内容的自动发现，此时用 --settings 显式传入所需配置（例如 apiKeyHelper）是官方文档给出的标准做法。

常见坑

• 以为 --settings 优先级最高：实际上它排在 managed settings 之下——组织管理员通过 managed-settings.json / MDM / claude.ai 控制台下发的策略，始终会覆盖你在命令行传入的 --settings 内容。
• 以为改的是持久配置：--settings 只对当次会话生效，退出后不会保留，下次不带这个 flag 启动就恢复原状。

来源

• CLI reference - Claude Code Docs
• Settings files and precedence - Claude Code Docs
• Run Claude Code programmatically - Claude Code Docs
• All settings - Claude Code Docs
• Configure the sandboxed Bash tool - Claude Code Docs