背景
Claude Code 的项目级配置文件.claude/settings.json中包含 API 提供商相关的环境变量。当同时维护多个项目，每个项目使用不同的 API 提供商（Anthropic 直连、OpenRouter 代理、自建转发等）时，每次切换项目都需要手动修改这些配置。这个过程重复且容易出错。
现状分析
Claude Code 使用以下环境变量控制 API 行为：
ANTHROPIC_BASE_URL— API 端点地址ANTHROPIC_AUTH_TOKEN— 认证令牌ANTHROPIC_MODEL— 主模型ANTHROPIC_DEFAULT_SONNET_MODEL— Sonnet 默认模型ANTHROPIC_DEFAULT_HAIKU_MODEL— Haiku 默认模型ANTHROPIC_DEFAULT_OPUS_MODEL— Opus 默认模型ANTHROPIC_REASONING_MODEL— 推理模型CLAUDE_CODE_SUBAGENT_MODEL— Subagent 模型
这些变量写在.claude/settings.json或.claude/settings.local.json的env块中。不同项目对这些变量的取值各不相同，手动维护成本较高。
工具：cc-switch-config
基于上述场景，我写了一个 CLI/TUI 工具：cc-switch-config。核心思路是：将 API 配置抽象为模板，按需应用到项目。
# 安装npminstall-gcc-switch-config# 使用cd~/team-project&&cc-config anthropic-directcd~/personal-project&&cc-config openrouter-proxy设计原则
精确替换：只修改.claude/settings.local.json中的env和model字段，permissions、hooks、mcpServers等其他配置完全保留。这样可以隔离 API 配置变更与其他项目配置的副作用。
注：cc-switch-config 对项目级配置写入的是
settings.local.json。这是 Claude Code 的项目级覆盖文件，读取优先级高于settings.json。唯一例外是当目标为全局~/.claude目录时，才会直接写入settings.json。这项设计保证了项目级 API 配置变更不会干扰 Claude Code 的全局配置。
原子写入：通过 write-rename 模式保证配置文件不会处于中间状态。每次操作前自动备份，支持cc-config undo回滚。
安全约束：API Key 以 password 类型输入，显示时脱敏，不传入 CLI 参数，不写入日志。
数据流
~/.config/cc-config/templates.json ← 全局配置模板 └── cc-config switch → 精确替换 .claude/settings.local.json 的 env/model 字段 ~/.local/share/cc-config/backups/ ← 操作前自动备份 └── cc-config undo → 恢复最近一次备份使用流程
# 1. 创建配置模板cc-config configadd# 可选统一模式（单模型名自动映射 6 个 env var）或独立模式（逐项指定）# 2. 注册项目cc-config register /path/to/project# 或批量扫描cc-config scan ~/code--register# 3. 切换cc-config switch<project><config>设计决策
为什么不用环境变量覆盖: 有的场景需要持久化配置（如团队共享 settings.json），有的是因为
.claude/settings.json中的 env 优先级更高。直接写文件适用于所有场景。为什么不改其他字段: 配置隔离——API 提供商变更不应影响权限、钩子、MCP 服务器等独立配置。最小修改原则降低了出问题的面和排查成本。
为什么不做单文件全量替换: 备份 + 精确字段替换 + 撤销的组合提供了足够的回退能力，全量替换反而增加了意外覆盖的风险。
Shell 集成
auto_cc_config() { [[ -f .claude/settings.json ]] && cc-config auto-check 2>/dev/null } chpwd_functions+=(auto_cc_config)目录切换时自动校验配置是否正确。
适用场景
- 维护多个 Claude Code 项目，使用不同 API 提供商
- 团队需要共享配置模板
- 在直连、代理、转发间频繁切换
- 希望将 API 配置纳入版本控制或团队分发流程
链接
- GitHub: github.com/HosheaLi/cc-switch-config
- npm: www.npmjs.com/package/cc-switch-config
- 使用文档: USAGE.md
