Claude Code 多项目 API 配置管理实践

背景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-projectcc-config anthropic-directcd~/personal-projectcc-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 switchprojectconfig设计决策为什么不用环境变量覆盖: 有的场景需要持久化配置如团队共享 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-confignpm: www.npmjs.com/package/cc-switch-config使用文档: USAGE.md