跳转至

5.4 环境变量冲突

功能说明

CC Switch 会自动检测系统环境变量与应用配置的冲突,避免配置被意外覆盖。

检测的环境变量:

应用 检测范围 常见变量
Claude Code 以 ANTHROPIC 开头的变量 ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL
Codex 以 OPENAI 开头的变量 OPENAI_API_KEY
Gemini CLI 以 GEMINI、GOOGLE_GEMINI 开头的变量 GEMINI_API_KEY
Grok Build XAI_API_KEY、GROK_DEFAULT_MODEL —

冲突警告

当检测到冲突时,界面顶部会显示黄色警告横幅:

⚠️ 检测到系统环境变量冲突
发现 X 个环境变量可能会覆盖您的配置
[查看详情] [×]

查看冲突详情

点击「查看详情」按钮查看详细信息:

字段 说明
变量名 环境变量名称
变量值 当前设置的值
来源 变量的来源位置

来源类型

来源 说明
用户环境变量 (注册表) Windows 用户级环境变量
系统环境变量 (注册表) Windows 系统级环境变量
系统环境变量 macOS/Linux 当前进程环境里的变量
Shell 配置文件 macOS/Linux 的 shell 配置文件(如 ~/.zshrc),界面里显示为文件路径

处理冲突

选择要删除的变量

  1. 勾选要删除的环境变量
  2. 或点击「全选」选择所有冲突变量

删除变量

  1. 点击「删除选中」按钮
  2. 在「确认删除环境变量」对话框里点「确认删除」
  3. CC Switch 会自动备份并删除选中的变量;删除后需要重启应用或终端才能生效

自动备份

删除前会自动备份:

  • 备份位置:~/.cc-switch/backups/env-backup-<时间戳>.json
  • 备份格式:JSON 文件
  • 包含变量名、值、来源等信息
  • 可在「设置 → 数据 → 备份与恢复」下方的「其他备份」里查看这类备份(名称为「环境变量清理备份」),也可以在那里清理;清理后无法再查到被删变量的原值

忽略警告

如果确认冲突不影响使用,可以:

  1. 点击警告横幅右侧的关闭按钮(×)
  2. 警告会在本次运行期间隐藏
  3. 下次启动时会重新检测

手动处理

如果不想通过 CC Switch 删除,可以手动处理:

Windows

  1. 打开「系统属性 → 高级 → 环境变量」
  2. 在用户变量或系统变量中找到冲突变量
  3. 删除或修改变量

macOS / Linux

  1. 编辑 shell 配置文件(如 ~/.zshrc、~/.bashrc)
  2. 删除或注释掉相关的 export 语句
  3. 重新加载配置:source ~/.zshrc

为什么会冲突

环境变量的优先级通常高于配置文件,可能导致:

  • CC Switch 设置的供应商配置被覆盖
  • API 请求发送到错误的端点
  • 使用错误的 API 密钥

最佳实践

  1. 使用 CC Switch 管理配置:避免在系统环境变量中设置 API 密钥
  2. 定期检查:关注冲突警告,及时处理
  3. 备份重要变量:删除前确认已备份

恢复已删除的变量

如果误删了环境变量:

  1. 找到备份文件:~/.cc-switch/backups/ 下的 env-backup-<时间戳>.json
  2. 打开对应的 JSON 文件
  3. 手动恢复变量到系统环境

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cc/cc-switch