#CCSwitch 接入万模API

适用工具：Claude Code / Codex / Gemini CLI | 适合：同时使用多个编码 CLI、频繁切换模型供应商的开发者

CCSwitch 是一个跨平台桌面工具，用来统一管理 Claude Code、Codex、Gemini CLI 等编码工具的 provider 配置。它适合已经在本机使用多个 AI 编码工具的人：不用反复手改配置文件，也能把不同工具切到万模API。

#准备信息

不同工具的协议不同。Codex 通常走 Responses，Claude Code 走 Claude Messages，Gemini CLI 走 Gemini 原生协议。不要把所有工具都强行配成 OpenAI Chat。

#第一步：安装 CCSwitch

#macOS

brew install --cask cc-switch

安装后从应用程序里打开 CC Switch。如果系统提示来自互联网下载，按 macOS 正常安全提示确认即可。

#Windows

1. 打开官方 Release 页面：https://github.com/farion1231/cc-switch/releases。
2. 下载最新的 Windows .msi 安装包。
3. 双击安装，完成后从开始菜单打开 CC Switch。

如果不想安装，也可以下载 Portable 压缩包，解压后运行 CC-Switch.exe。

#Linux

Debian / Ubuntu 可以下载 .deb 包后安装：

sudo dpkg -i CC-Switch-v*-Linux-*.deb
sudo apt-get install -f

也可以使用 AppImage：

chmod +x CC-Switch-v*-Linux-*.AppImage
./CC-Switch-v*-Linux-*.AppImage

安装完成后，确认桌面窗口能打开，系统托盘里能看到 CCSwitch 图标。

#第二步：创建专用令牌

建议给 CCSwitch 单独创建一个令牌，例如 ccswitch-dev。

这样做有三个好处：

1. 可以单独限制额度。
2. 可以在调用日志里快速过滤 CCSwitch 相关请求。
3. 不用和 ChatBox、Dify、生产应用共用同一个 Key。

#第三步：添加万模API Provider

在 CCSwitch 里点击添加 provider，然后按你要接管的工具选择配置。可以选择自动接入，也可以按字段手动添加。

#方式一：自动接入

1. 在创建好的 API Key 那一行，点击最右侧的接入或切换按钮。

2. 选择接入的应用，填写自定义名称，并选择默认模型。名称可以使用默认值，模型应选择控制台可用模型。

3. 回到 CCSwitch 面板，选择对应应用，将新加入的 Provider 设置为使用中。

#方式二：手动接入

#Codex / OpenAI Responses

保存后切换到这个 provider。CCSwitch 会把 Codex 相关配置写入用户级配置区域，避免你手动编辑 ~/.codex/config.toml。

#Claude Code / Claude Messages

Claude Code 不要填 https://www.wanmoapi.com/v1/chat/completions。它需要的是 Claude Messages 协议，最终请求路径应落到 /v1/messages。

#Gemini CLI / Gemini 原生

Gemini 原生请求通常由 CLI 拼出 /v1beta/models/{model}:generateContent，Base URL 不要手动补到完整接口路径。

#第四步：切换并验证

切换 provider 后，关闭并重新打开对应终端，再运行目标工具。

#验证 Codex

codex --version
codex

进入一个测试项目，先让 Codex 做只读任务：

请只读取当前目录，概括这个项目的结构，不要修改文件。

成功标志：

• Codex 能返回项目结构说明。
• 控制台调用日志出现请求。
• 日志路径是 /v1/responses 或 Codex 当前版本使用的 Responses 兼容路径。

#验证 Claude Code

claude --version
claude doctor
claude

成功标志：

• Claude Code 能启动并回答只读问题。
• 控制台调用日志出现 /v1/messages。
• 没有 401、404 model not found、协议不匹配等错误。

#验证 Gemini CLI

gemini --version
gemini

成功标志：

• Gemini CLI 能正常返回。
• 日志里能看到 Gemini 原生路径。
• 模型名和控制台可用模型一致。

#常见问题

#切换后工具还是走旧地址

1. 关闭并重新打开终端。
2. 在 CCSwitch 里确认当前 provider 已激活。
3. 检查是否有旧环境变量覆盖配置，例如 OPENAI_BASE_URL、ANTHROPIC_BASE_URL、GEMINI_API_KEY。
4. 如果工具在 WSL 内运行，需要在 WSL 环境里也完成配置。

#Codex 显示 model not found

先确认模型属于 Responses 可用模型。不要直接拿 ChatBox 里的 Chat 模型去跑 Codex，具体以控制台和 /v1/models 返回为准。

#Claude Code 请求无日志

请求没有打到万模API。重点检查 Base URL 是否误填成完整 Chat 路径，或者 Claude Code 是否被本机其他环境变量接管。

#多个工具能不能共用一个 Key

能用，但不推荐。更好的方式是给 ccswitch-codex、ccswitch-claude、ccswitch-gemini 分别创建令牌，这样额度、日志和排障都更清楚。

#相关链接

• 官方项目
• Codex 单独教程：Codex 接入万模API
• Claude Code 单独教程：Claude Code 接入万模API
• 协议选择：协议选择指南
• 排障：常见问题排查