跳到主要内容

CC Switch

:::tip Codex 用户推荐做法

请在 CC Switch 中添加并切换 HangToken Provider，让 CC Switch 生成完整配置。不要只把 HangToken 控制台展示的单行 model_provider 手动粘贴到 ~/.codex/config.toml，否则可能因缺少对应 Provider 定义而导致 Codex 无法启动。

:::

控制台快捷入口​

在 HangToken 控制台的系统设置->聊天设置中，可添加如下快捷选项，便于在令牌管理页一键填充到 CC Switch：

{ "CC Switch": "ccswitch" }

🔀 CC Switch 是一款开源、跨平台的 AI CLI 统一管理工具，支持 Claude Code、Codex 和 Gemini CLI 的 Provider 配置一键切换、MCP 服务器统一管理、系统提示词（Prompts）管理以及 Skills 扩展管理， 让你在多个 AI 编程助手之间自由切换，无需手动编辑配置文件。

核心特性​

🔌 Provider 管理​

  • 一键切换 — 在 Claude Code、Codex、Gemini 的 API 配置之间一键切换，无需手动修改环境变量或配置文件
  • 多端点支持 — 每个 Provider 可配置多个端点，支持 API Key 管理与延迟测速
  • 4 层模型配置 — 支持 Haiku / Sonnet / Opus / Custom 四级模型粒度配置

🛠️ MCP 服务器管理​

  • 跨应用统一管理 — 单面板管理 Claude / Codex / Gemini 三端的 MCP 服务器
  • 三种传输类型 — 支持 stdio、HTTP、SSE（Server-Sent Events）
  • 自动同步 — 统一导入导出 + 双向同步

💬 Prompts 管理​

  • 多预设系统提示词 — 无限预设、快速切换
  • 跨应用支持 — Claude（CLAUDE.md）、Codex（AGENTS.md）、Gemini（GEMINI.md）
  • Markdown 编辑器 — CodeMirror 6 + 实时预览

🌐 多平台支持​

  • 桌面应用 — Windows、macOS、Linux 原生安装包
  • Web 版本 — 适用于无头服务器 / SSH 远程环境的浏览器访问方案
  • CLI 版本 — 命令行交互模式与命令模式双支持

HangToken 接入方法​

CC Switch 支持 ccswitch:// Deep Link 协议，可从 HangToken 令牌管理页一键导入 Provider 配置。

从 HangToken 控制台导入​

  1. 在 HangToken 令牌管理页，点击对应令牌的下拉菜单 在菜单中选择 CC Switch 选项，系统会自动唤起 CC Switch 应用并弹出配置弹窗。

  2. 在弹窗中完成配置 填入 CC Switch 弹窗

    弹窗各字段说明：

    • 应用：顶部切换应用类型 — Claude / Codex / Gemini，根据需要选择目标应用
    • 名称：为该配置填写一个名称（例如 My Claude），方便后续在 CC Switch 中识别和切换
    • 主模型（必填）— 默认使用的主力模型
    • Haiku 模型 — 轻量快速模型
    • Sonnet 模型 — 均衡模型
    • Opus 模型 — 最强模型

    所有模型均为下拉选择，未选择时显示「请选择模型」。

  3. 完成配置 点击 「打开 CC Switch」 即可将配置导入 CC Switch 并开始使用；点击 「取消」 放弃本次操作。

:::warning 导入后还要切换 Provider

控制台快捷入口负责把配置交给 CC Switch。导入完成后，请回到 CC Switch 的 Codex 页面，确认 HangToken Provider 已保存并点击启用或切换。若快捷入口没有生成完整配置，请按下方“Codex 推荐配置流程”手动在 CC Switch 中添加，不要只修补 config.toml 的第一行。

:::

Codex 推荐配置流程​

以下方式适用于 macOS、Windows 和 Linux，也是出现 Model provider not found 时的首选修复方法。

1. 在 CC Switch 中添加 HangToken Provider​

打开 CC Switch，进入 Codex 页面并新增 Provider。至少填写：

  • 名称：例如 HangToken Codex
  • API Key：从 HangToken 令牌管理页 复制
  • Base URL：https://hangtoken.com/v1
  • 模型：填写控制台中实际可用、且支持 Responses API 的模型 ID

保存后，在 CC Switch 中点击启用或切换到这个 Provider。请确认当前编辑的是 Codex 配置，而不是 Claude Code 或 Gemini 配置。

2. 启用本地路由（推荐）​

进入 设置 → 路由 → 本地路由：

  1. 打开本地路由总开关。
  2. 启用 Codex 路由。
  3. 保持默认监听地址 127.0.0.1:15721；如已被其他程序占用，再更换端口。
  4. 再次切换到 HangToken Provider。

启用后，CC Switch 会把 Codex 的请求地址指向本地代理：

http://127.0.0.1:15721/v1

真实 API Key 由 CC Switch 管理并转发，无需把密钥写进教程、截图或项目文件。

3. 完全重启 Codex​

关闭所有 Codex 窗口和后台进程，再重新打开 Codex 并创建一个新对话。已经因配置加载失败而中断的对话，通常需要在修复后重新打开。

Model provider not found 故障排查​

报错原因​

如果看到以下提示：

ChatGPT 无法加载 config.toml，因此此对话串无法继续。
Model provider `hangtoken` not found.

它表示配置顶层引用了一个 Provider ID，但文件中没有同名定义。下面两个位置的 ID 必须完全一致，包括大小写：

model_provider = "hangtoken"

[model_providers.hangtoken]
name = "HangToken"
base_url = "https://hangtoken.com/v1"
wire_api = "responses"

例如，model_provider = "hangtoken" 与 [model_providers.HangToken] 不匹配。只有第一行、却没有 [model_providers.hangtoken] 整段，也会触发同类错误。

:::info 使用本地路由时的正常差异

不同版本的 CC Switch 可能使用 custom 等内部 Provider ID，而不是 hangtoken。这是正常现象；不要为了让名称看起来一致而手工改名。重点是 model_provider 的值与 [model_providers.<id>] 的 <id> 完全一致，并且本地路由的 base_url 指向 http://127.0.0.1:15721/v1。

:::

推荐修复步骤​

  1. 退出 Codex，避免它继续读取错误配置。

  2. 备份配置：

    cp ~/.codex/config.toml ~/.codex/config.toml.backup

  3. 在 CC Switch 的 Codex 页面重新保存并切换 HangToken Provider。

  4. 如果使用本地路由，确认路由总开关和 Codex 开关均已启用。

  5. 检查生成结果：

    grep -nE 'model_provider|^\[model_providers\.|base_url|wire_api' ~/.codex/config.toml

  6. 确认 Provider ID 成对存在、大小写相同；本地路由模式下确认 base_url 为 http://127.0.0.1:15721/v1。

  7. 完全退出并重启 Codex，然后新建对话测试。

Windows 用户的配置文件通常位于 %USERPROFILE%\.codex\config.toml，可使用文本编辑器检查相同字段。

本地路由没有启动​

macOS 或 Linux：

lsof -nP -iTCP:15721 -sTCP:LISTEN

Windows PowerShell：

netstat -ano | findstr 15721

如果没有输出，先启动 CC Switch 并打开本地路由，再重启 Codex。如果端口已被其他程序占用，请在 CC Switch 中更换端口，并以 CC Switch 最新生成的配置为准。

:::caution 不要覆盖其他 Codex 设置

~/.codex/config.toml 还可能包含 MCP、权限、项目和界面偏好。排障前先备份，优先让 CC Switch 重新生成 Provider 配置，不要用本文示例覆盖整个文件。

:::

安装方式​

macOS（推荐 Homebrew）​

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

Windows​

从 Releases 下载 .msi 安装包或便携版 .zip。

Linux​

从 Releases 下载 .deb 包或 .AppImage。

ArchLinux 用户：

paru -S cc-switch-bin

Web 版本（无头 / SSH 服务器）​

wget https://github.com/farion1231/cc-switch/releases/latest/download/cc-switch-web-linux-x64.tar.gz
tar -xzf cc-switch-web-linux-x64.tar.gz
cd cc-switch-web/
./cc-switch-web

默认端口 17666，通过浏览器访问 http://localhost:17666。

相关链接​

来源经 HangToken 整理：查看上游原始页面