最近我同时在用 Codex、Claude Code 和 Gemini CLI，最让我头疼的已经不是模型能力，而是配置。

Codex 使用 config.toml，Claude Code 主要读取环境变量和自己的配置，Gemini CLI 又是另一套规则。

工具装得越多，电脑里散落的 API Key、Base URL 和模型名也越多。某个工具突然报 401、404 或模型不存在时，第一件事往往不是解决报错，而是先猜：

它现在到底在用哪一个 Key、哪一个地址、哪一个模型？

后来我把这三套配置统一交给 CC Switch 管理，模型接口则统一接到 Genvis。现在切换工具或模型，不需要反复打开配置文件，一套 Key 就能管理常用的 AI 编程工具。

这篇文章从零演示完整过程：

1. 安装 CC Switch；

2. 创建 Genvis API Key；

3. 一键导入 Provider；

4. 分别跑通 Codex、Claude Code、Gemini CLI；

5. 解决 401、404、配置不生效等常见问题。

如果你只使用其中一个工具，也可以直接跳到对应章节。

---

一、CC Switch 到底解决什么问题

先说清楚：CC Switch 不是大模型，也不是 API 中转站。

它更像一台安装在本地的“AI 编程工具配置总控台”，负责管理不同工具的 Provider、Base URL、API Key、模型、MCP、Skills 和系统提示词。

目前它支持的工具已经不止名字里的 Claude Code，还包括：

• Claude Code

• Claude Desktop

• Codex

• Gemini CLI

• Grok Build

• OpenCode

• OpenClaw

• Hermes Agent

对普通开发者最实用的是三点：

1. 不再手改多份配置文件

以前切换接口，需要找到 .toml、.json 或 .env 文件再逐项修改。CC Switch 把这些操作变成图形化表单。

2. 一个 Provider 可以同步给多个工具

同一个 API 入口，可以分别生成 Codex、Claude Code 和 Gemini CLI 所需要的配置，不必在三个工具里重新输入。

3. 切换和排错更直观

当前启用了哪个 Provider、使用哪个模型、连接测试是否成功，都可以在同一个界面确认。

需要注意：CC Switch 负责“管理和转换配置”，真正提供模型调用能力的仍然是 API 服务。

本文使用 Genvis 作为统一 API 入口：CC Switch 管本地配置，Genvis 管 Key、模型和调用记录，两边分工非常清楚。

---

二、开始前准备这三样东西

1. 安装 CC Switch

项目地址：

https://github.com/farion1231/cc-switch

进入 Releases 页面后，按照系统下载：

• Windows：.msi 安装包或便携版 .zip

• macOS：.dmg，也可以通过 Homebrew 安装

• Linux：.deb、.rpm 或 .AppImage

macOS 使用 Homebrew：

brew tap farion1231/ccswitch
brew install --cask cc-switch

第一次打开时，CC Switch 会自动识别电脑上已经安装的 AI 编程工具。没有安装的工具显示为不可用属于正常现象。

2. 准备一个 API Key

本文使用 Genvis 演示。

进入 Genvis 控制台后：

1. 打开“令牌管理”；

2. 创建一个新令牌；

3. 给令牌设置容易识别的名称，例如 cc-switch；

4. 复制并妥善保存 API Key。

接口基础地址为：

https://genvis.xyz/v1

建议单独创建一个用于 AI 编程工具的 Key。以后查看调用记录、统计消耗或停用权限时，不会影响其他项目。

3. 至少安装一个目标工具

你不必同时安装三个。可以先配置自己正在使用的工具，后面需要时再增加。

检查命令：

codex --version
claude --version
gemini --version

哪一个命令能够返回版本号，就说明对应 CLI 已经安装。

---

三、最快方式：从令牌页一键导入 CC Switch

如果 Genvis 令牌管理页面已经显示“CC Switch”入口，优先使用一键导入。

操作流程：

1. 在 Genvis 的令牌管理页面找到刚才创建的 Key；

2. 打开该令牌右侧的应用或快捷配置菜单；

3. 选择“CC Switch”；

4. 浏览器会尝试唤起本地 CC Switch；

5. 选择需要配置的应用；

6. 选择主模型并确认导入；

7. 点击启用 Provider。

第一次唤起时，浏览器可能询问是否允许打开 CC Switch，选择允许即可。

CC Switch 导入窗口一般会让你确认：

字段	应该怎么填
Application	Codex、Claude Code 或 Gemini CLI
Name	建议填写 Genvis
Base URL	https://genvis.xyz/v1
API Key	使用刚创建的独立 Key
Main Model	从当前可用模型列表中选择

同一个 Key 可以分别导入三个应用。完成第一次导入后，切换 Application，再为另外两个工具保存配置即可。

如果令牌页面暂时没有 CC Switch 入口，不影响使用，按照下一节手动添加 Provider。

---

四、手动添加 Genvis Provider

打开 CC Switch，选择目标应用，然后点击“添加 Provider”或左上角的加号。

选择“自定义 Provider”，填写：

名称：Genvis
Base URL：https://genvis.xyz/v1
API Key：你在控制台创建的 Key

模型名称不要凭记忆填写，应当从 Genvis 控制台的模型列表复制。

不同 AI 工具使用的协议并不完全一样，这也是很多人“同一个地址在聊天软件能用，放进 Coding Agent 就报错”的根本原因。

Codex 的设置重点

Codex 当前使用 Responses 协议。配置生成后，核心结构应该类似：

model = "gpt-5.6-sol"
model_provider = "genvis"

[model_providers.genvis]
name = "Genvis"
base_url = "https://genvis.xyz/v1"
env_key = "GENVIS_API_KEY"
wire_api = "responses"

其中 gpt-5.6-sol 是本文示例，实际模型名以控制台当前列表为准。

不要把自定义 Provider 命名为 openai、ollama 或 lmstudio，这些是 Codex 的保留 Provider ID。

Claude Code 的设置重点

Claude Code 原生协议与 OpenAI 兼容协议不同。如果选择的接口不是 Anthropic 原生格式，需要在 CC Switch 中开启本地代理或路由模式，由它完成格式转换。

操作时重点确认：

1. 当前应用选择的是 Claude Code；

2. Provider 类型与 Genvis 接口协议匹配；

3. 使用 OpenAI 兼容接口时，已开启对应的路由转换；

4. 主模型和不同角色模型都来自实际可用模型列表；

5. 保存后执行一次连接测试。

不要把 Codex 的 wire_api = "responses" 原样复制进 Claude Code 配置，这两套工具读取的配置格式不同。

Gemini CLI 的设置重点

切换到 Gemini CLI 页面，添加同一个 Genvis Provider，再选择需要使用的模型。

如果使用 Universal Provider，可以复用已经填写的地址和 Key，但仍应检查 Gemini CLI 页面最终生成的模型映射。

保存后启用 Provider。Gemini CLI、Codex 等工具可能会缓存启动时读取的配置，建议关闭旧终端并重新打开。

---

五、分别验证三个工具

不要配置完就直接让 Agent 修改大型项目。先用最小任务验证链路。

1. 验证 Codex

进入一个测试目录：

mkdir cc-switch-test
cd cc-switch-test
codex

进入 Codex 后先运行：

/status

确认当前模型和 Provider 已经切换为 Genvis，然后输入：

只读取当前目录，并告诉我目录中有多少个文件，不要创建或修改任何内容。

能够返回结果，说明模型请求和基础工具调用已经跑通。

2. 验证 Claude Code

新开终端运行：

claude

测试指令：

只分析当前目录结构，用三句话说明这个项目可能是什么，不要修改文件。

如果简单对话正常，但读取文件或工具调用失败，应优先检查路由模式、模型兼容性和工具调用字段是否被正常转换。

3. 验证 Gemini CLI

新开终端运行：

gemini

测试指令：

读取当前目录的文件名，按文件类型进行分类，不要修改文件。

三个工具都建议先做只读测试，再逐步尝试写文件和运行命令。

---

六、切换 Provider 后为什么没有生效

这是 CC Switch 新手最常遇到的问题。

官方说明中，Claude Code 可以热切换 Provider；大多数其他工具切换后需要重新启动 CLI 或终端。

推荐操作顺序：

1. 在 CC Switch 中启用 Genvis；

2. 完全退出正在运行的 Codex 或 Gemini CLI；

3. 关闭旧终端；

4. 新开终端重新运行工具；

5. 使用状态命令核对模型和 Provider。

如果仍然没有生效，检查 CC Switch 是否识别到了正确的配置目录。

---

七、常见报错排查

1. 401 Unauthorized

常见原因：

• API Key 复制不完整；

• Key 已被禁用；

• 环境变量没有在当前终端生效；

• 切换 Provider 后仍在使用旧配置。

先在 Genvis 控制台确认 Key 状态和调用记录。如果完全没有请求记录，问题通常还在本地配置阶段。

2. 404 Not Found

优先检查：

• Base URL 是否正确包含 /v1；

• Codex 接口是否支持 /responses；

• Claude Code 是否选择了正确协议或开启路由模式；

• 地址末尾是否重复拼接了路径。

3. model not found

模型显示名称和接口实际 ID 可能不同。不要根据文章截图手打，直接从当前模型列表复制。

4. CC Switch 测试成功，CLI 仍使用旧模型

关闭 CLI 和终端后重开。Codex、Gemini CLI 等工具可能在启动时加载配置，仅点击 CC Switch 的“启用”并不一定让旧进程立即刷新。

5. 切换 Provider 后 MCP 或插件配置不见了

可以使用 CC Switch 的 Shared Config Snippet 功能，把公共配置提取出来，并在创建新 Provider 时启用“写入共享配置”。

6. 简单问答正常，改代码时却失败

说明“文字生成”已经跑通，但工具调用或协议转换还没有完全兼容。重点检查：

• 当前模型是否支持工具调用；

• Provider 是否选择了正确协议；

• 本地路由是否正常运行；

• 长连接是否被代理或网络提前断开；

• 控制台调用日志返回了什么状态码。

---

八、为什么我最后选择统一入口，而不是分别申请三个 Key

分别对接官方当然可以，但工具一多，管理成本会迅速上升：

• 每个平台单独充值；

• 每个工具单独维护 Key；

• 模型切换时重新改地址；

• 出错后分别检查余额和调用日志；

• 离开电脑一段时间后，很难记住每个工具正在用什么配置。

我现在的方案是：

CC Switch 统一管理本地工具，Genvis 统一管理 API Key、模型和调用记录。

这样做最大的好处不是“模型更多”，而是整个配置链路变得可见：使用哪一个 Key、调用哪一个模型、产生多少消耗、哪里返回错误，都能更快定位。

如果你已经有其他可用接口，也可以按照本文结构导入；如果还没有统一 Key，可以直接使用本文演示的 Genvis。接口地址已经放在配置中，入口在我的个人主页。

---

九、最终配置思路

整套方案可以概括成四步：

1. 在 Genvis 创建一个 AI 编程专用 Key；

2. 从令牌页一键导入 CC Switch，或手动添加 Provider；

3. 分别为 Codex、Claude Code、Gemini CLI 选择合适模型；

4. 用只读小任务验证，再进入真实项目。

以前需要反复编辑三种配置文件，现在可以在一个界面里完成切换、检查和恢复。

更重要的是，CC Switch 与 API 平台解决的是两层不同的问题：前者管理本地工具配置，后者提供实际模型能力。把两层分开，出错时才知道应该查本地、查协议，还是查接口。

如果你正在同时使用多个 AI 编程工具，这套方案值得先收藏。下一篇我会继续整理：如何在使用第三方 API 的同时，保留 Codex 官方登录、插件和手机远程能力。

---

参考资料

• CC Switch 官方 GitHub 项目与使用说明

• New API：CC Switch 一键导入说明

• OpenAI Docs：Codex 自定义 Model Provider 与配置字段说明

第三方工具、模型列表和界面可能随版本更新。本文配置以 2026 年 8 月可用版本为基础，实际操作请以 CC Switch、Codex 和服务控制台当前界面为准。