文档中心DOCS

CC Switch 接入教程

使用 CC Switch 统一管理 Codex、Claude Code、OpenCode 等编程工具的 服务平台 接入配置

≡ ON THIS PAGE
适合什么场景一、准备 服务平台 参数二、下载和安装 CC Switch三、添加 服务平台 Provider四、按目标工具选择用法五、Windows / macOS / Linux 的配置差异六、验证是否成功七、常见问题参考入口

适合什么场景

CC Switch 适合已经同时使用多个编程 AI 工具的用户。它不是模型服务本身，而是一个本地配置管理器，可以帮助你在 Codex、Claude Code、OpenCode、OpenClaw 等工具之间集中管理 Provider、密钥和模型。

多工具切换

同一台电脑上同时使用 Codex、Claude Code、OpenCode 时更方便。

统一管理密钥

把不同工具的 Provider、API Key、模型集中整理，减少手动改文件。

新手少改配置

通过界面添加和切换配置，降低写错 JSON/TOML 的概率。

排查更直观

能快速确认当前工具到底使用了哪组 Provider 和模型。

一、准备 服务平台 参数

如果你要通过 OpenAI 兼容工具接入 服务平台，准备下面三项：

Base URL

https://your-api-host.example

API Key

服务平台 控制台创建的真实密钥。

模型名称

以 服务平台 当前可用模型为准，示例使用 gpt-5.4。

目标工具

先决定要让 Codex、OpenCode 还是 Claude Code 使用这组配置。

二、下载和安装 CC Switch

官方入口：

推荐从官网或 GitHub Releases 下载 Windows 安装包。

安装后先打开 CC Switch，确认界面能正常启动。随后在 PowerShell 中确认你要管理的 CLI 是否可用：

codex --version
opencode --version
claude --version

哪个工具提示命令找不到，就先回到对应工具教程完成安装。Codex CLI 通常还需要先准备 Node.js/npm。

推荐从官网或 GitHub Releases 下载 macOS 安装包。

如果系统提示来自未识别开发者，请按 macOS 安全设置允许打开。随后在 Terminal 中确认目标 CLI：

codex --version
opencode --version
claude --version

Finder 默认隐藏点开头目录，但 CC Switch 通常会帮你减少手动进入这些目录的次数。

Linux 用户优先查看 GitHub Releases 是否提供适合当前发行版的包。

如果你在服务器或 WSL 中使用，先确认图形环境是否可用。纯服务器场景通常更适合继续使用各工具自己的 CLI 配置文件。

codex --version
opencode --version
claude --version

三、添加 服务平台 Provider

CC Switch 不同版本的界面名称可能略有差异。只要能找到 Provider、API、Model、Base URL、Key 这类入口，就按下面思路填写。

1
打开 CC Switch，进入 Provider、API Providers、Models 或类似配置页。
2
新增一个 Provider，名称填写 服务平台。
3
协议类型优先选择 OpenAI Compatible、OpenAI 或允许自定义 Base URL 的选项。
4
Base URL 填写 https://your-api-host.example。
5
API Key 填写 服务平台 控制台创建的密钥。
6
模型填写 服务平台 当前可用模型，例如 gpt-5.4。
7
保存配置后，切换到你要使用的目标工具。

四、按目标工具选择用法

适合 OpenAI 兼容配置，推荐新手优先跑通。

操作思路：

  1. 在 CC Switch 中选择 Codex 或对应配置入口。
  2. 选择刚创建的 服务平台 Provider。
  3. 确认模型为 服务平台 可用模型。
  4. 应用或写入配置。
  5. 重启 Codex UI 客户端，或重新打开终端运行 Codex CLI。

验证命令：

codex --version

进入项目后输入：

请只阅读当前项目，不要修改文件。先说明这个项目的目录结构。

适合 OpenAI 兼容配置，也适合终端开发用户。

操作思路：

  1. 在 CC Switch 中选择 OpenCode 或对应配置入口。
  2. 选择 服务平台 Provider。
  3. 确认 Base URL、API Key、模型名称都正确。
  4. 应用配置后重启 OpenCode。

验证命令：

opencode --version
opencode

第一次任务建议只读项目，不要直接让它修改文件。

先确认你手上的入口是否支持 Anthropic/Claude 兼容。

如果 CC Switch 当前版本提供本地代理或协议转换能力，请按它的界面说明启用对应功能；如果没有，请不要直接把 https://your-api-host.example 填成 Claude Code 的 Anthropic Base URL。

验证命令：

claude --version
claude

第一次任务建议：

请只阅读当前项目，不要修改文件。先说明项目使用了什么技术栈。

五、Windows / macOS / Linux 的配置差异

Windows 上最容易混淆的是 PowerShell 和 WSL。

  1. 如果 Codex/OpenCode 在 Windows 原生环境运行，就在 Windows 里用 CC Switch 配置。
  2. 如果工具在 WSL 里运行，Windows 图形界面写入的配置不一定会自动进入 WSL。
  3. 遇到不生效时，先确认目标 CLI 到底从哪个用户目录读取配置。

macOS 的隐藏目录容易让新手找不到配置文件。

  1. ~/.codex、~/.claude、~/.config 默认可能不在 Finder 中直接显示。
  2. 如果 CC Switch 写入后工具不生效，先重启目标工具。
  3. 仍不生效时，再打开对应配置目录检查是否写入成功。

Linux / WSL 更推荐优先用 CLI 环境变量验证。

  1. 纯服务器环境通常没有图形界面，不一定适合 CC Switch 桌面版。
  2. WSL 和 Windows 原生环境默认不共享用户目录。
  3. 如果你在 WSL 中运行工具，请在 WSL 内完成安装和验证。

六、验证是否成功

1
确认目标 CLI 能输出版本号。
2
确认 CC Switch 当前选中的是 服务平台 Provider。
3
确认 Base URL、API Key、模型名称没有多余空格。
4
重启目标工具。
5
在一个普通项目中执行只读任务。

认证通过

没有出现 401、unauthorized、invalid API key。

模型可用

没有出现 model not found 或模型不可用。

工具读到配置

重启后仍然使用 服务平台 Provider。

能读项目

可以正常回答项目结构、技术栈或启动命令。

七、常见问题

Q.CC Switch 配置后 Codex/OpenCode 仍然不生效

先确认目标工具是否已经完全退出并重启，再确认 CC Switch 写入的是当前工具真正读取的用户目录。Windows 原生和 WSL 默认不是同一套配置。

Q.Claude Code 配置 服务平台 OpenAI 地址失败

Claude Code 默认需要 Anthropic/Claude 兼容入口。除非你明确启用了 CC Switch 的协议转换或本地代理能力，否则不要直接把 OpenAI 兼容地址当成 Anthropic Base URL。

Q.提示命令找不到

CC Switch 不等于安装目标 CLI。请先按对应教程安装 Codex CLI、OpenCode 或 Claude Code，并确认 codex --version、opencode --version、claude --version 能输出版本号。

Q.多个工具共用同一个 API Key 可以吗

技术上可以，但不推荐。建议为不同工具分别创建 API Key，方便定位用量和单独停用。

参考入口