小蓝中转站使用文档

CC-Switch 配置工具 ​

CC-Switch 适合把多套网关配置集中放在一个图形界面里管理。当前官方文档明确支持的主力工具包括：

  • Claude Code
  • Codex
  • Gemini CLI
  • OpenCode
  • OpenClaw

它的作用是帮你改本地配置、切换提供商、统一管理地址和模型，不会替你安装这些 CLI。本机对应的工具、Node.js、Git 该装的还是要先装好。

配置 Cherry Studio 时，直接看 CherryStudio。Cherry Studio 不在 CC-Switch 当前主支持列表里。

什么时候更适合用它 ​

下面这些场景，用 CC-Switch 通常比手改环境变量省心：

  • 一台电脑上经常切多套 Key 或多套网关
  • Claude Code、Codex、Gemini CLI 想共用一套整理过的配置命名
  • 不想反复找 ~/.claude、~/.codex、~/.gemini 这些配置目录
  • 想先用图形界面排除“到底是地址错了，还是 Key 错了，还是模型错了”

安装方法 ​

下载入口：

国内用户优先打开中文首页或官网首页。首页通常会直接给出 Get Latest Release 和手册入口，比自己翻 GitHub 发布页更快。

Windows ​

当前官方发布页常见的 Windows 文件名主要是两种：

  • CC-Switch-v版本-Windows.msi
  • CC-Switch-v版本-Windows-Portable.zip

怎么选很简单：

  • 想正常安装到系统里，优先选 .msi
  • 没有安装权限，或者只想放在某个目录里临时用，选 Portable.zip

安装后如果程序打不开，先排查两件常见事：

  • 没装 WebView2 Runtime
  • 被杀毒软件拦截

macOS ​

已经装好 Homebrew 时，优先直接装：

bash
# 添加 CC-Switch 的 Homebrew tap
brew tap farion1231/ccswitch

# 安装 CC-Switch
brew install --cask cc-switch

不想走 Homebrew 时，也可以下载官方提供的：

  • macOS.dmg
  • macOS.zip
  • macOS.tar.gz

官方手册当前明确写了：macOS 版本已经完成 Apple 签名和公证，正常情况下可以直接安装打开，不需要再按旧教程那样把它一概当成“未知开发者”处理。
如果系统仍然拦截，优先重新从官网、Homebrew 或官方发布页下载，先排除文件下载不完整、来源不一致或隔离属性异常。

Linux ​

当前官方发布页会给出 x86_64 和 arm64 两套 Linux 文件，常见格式包括：

  • .deb
  • .rpm
  • AppImage

选择思路：

  • Ubuntu / Debian：优先 .deb
  • Fedora / RHEL：优先 .rpm
  • 其他发行版：优先 AppImage
  • Arch 系：可以按官方说明走 paru 或 yay

不确定自己是什么架构时，可以先看：

bash
# x86_64 一般表示 Intel / AMD 64 位
# aarch64 或 arm64 一般表示 ARM 设备
uname -m

AppImage 第一次运行前要加执行权限：

bash
# 给 AppImage 增加可执行权限
chmod +x CC-Switch*.AppImage

# 直接运行
./CC-Switch*.AppImage

安装前先确认 ​

CC-Switch 能帮你写配置，但不会替你把 Claude Code、Codex、Gemini CLI 这些工具凭空装出来。

先看三类命令：

bash
# 需要用 npm 安装 CLI 时，Node.js 和 npm 必须可用
node -v
npm -v

# 处理代码仓库时，Git 非常值得先装好
git --version

# 哪个工具要交给 CC-Switch 管理，就先确认哪个命令已经能启动
claude --version
codex --version
gemini --version

命令不存在时，先按系统补环境：

第一次配置 小蓝中转站 ​

在 CC-Switch 里，一条配置至少要把三件事写清楚：

  • 请求发到哪里
  • 用哪把 Key 鉴权
  • 默认想用哪个模型

地址怎么填 ​

不同工具的协议不同，地址不能一把梭：

工具Base URL / Endpoint 应该填什么
Claude Codehttps://xiaolan.ainb.plus
Codexhttps://xiaolan.ainb.plus/v1
Gemini CLIhttps://xiaolan.ainb.plus
OpenCode / OpenClaw（若走 OpenAI 兼容）通常填 https://xiaolan.ainb.plus/v1，以该工具对应协议页为准

Claude Code 和 Gemini CLI 都是“根地址派”；Codex 这类 OpenAI 兼容工具才通常需要 /v1。
这里填错，最常见的结果不是“模型质量变差”，而是模型列表拉不出来、接口 404，或者压根连不上。

Key 怎么建 ​

建议按工具单独建 Key，比如：

  • Claude-Windows
  • Codex-MacBook
  • Gemini-Office

这样做有三个好处：

  • 日志里能一眼分出是哪一个工具在消耗额度
  • 某个工具要停用时，不会牵连其他工具
  • 分组和模型权限更容易收紧

分组怎么选 ​

还不熟悉各分组的价格和路由差异时，第一次先选 auto 或默认分组更稳。

这样做的意义是先把真实链路跑通：

  • 不会一开始就因为分组选窄了，把问题误判成客户端配置错
  • 网关在允许范围内更容易帮你处理同模型下的渠道切换
  • 等到确认各工具都能正常返回，再按成本和模型类型把分组细分

还没想清楚分组和模型的关系时，可以先这样理解：

  • 分组 决定这把 Key 大概能走哪些可用渠道
  • 模型 决定当前工具实际请求哪一个模型名

第一次先别同时把两层都收得太死。先跑通，再慢慢收紧，排障会清楚很多。

模型怎么选 ​

模型名一律从 模型广场 复制。

不要手敲，也不要直接抄别人的旧教程。最容易出错的地方通常不是“模型太弱”，而是模型名已经变了、这把 Key 没权限，或者分组根本不允许这条模型。

第一次接入建议这样选：

  1. 先按工具用途选模型家族，例如 Claude Code 先看 Claude 系列，Gemini CLI 先看 Gemini 系列。
  2. 先用一个当前可用、响应更快的模型把配置跑通。
  3. 真实工作再切到更强、更贵或上下文更长的模型。

在 CC-Switch 里新建配置 ​

打开 CC-Switch 后：

  1. 进入对应工具标签页
  2. 点击新增配置
  3. 填入 Base URL、API Key、模型名
  4. 保存并启用

建议配置名直接写清用途和设备：

  • 小蓝中转站-Claude-MacBook
  • 小蓝中转站-Codex-Windows
  • 小蓝中转站-Gemini-Server

以后看列表、日志和切换记录时，不容易混。

如果界面里能正常获取模型，优先从列表里选；如果拉取失败，再回模型广场手动复制。
这样做的好处是：先证明地址和 Key 本身可用，再去看是不是模型权限问题。

应用后先怎么验证 ​

CC-Switch 保存成功，不等于底层工具一定已经能正常对话。
更稳的顺序是：

  1. 应用配置
  2. 完全关闭当前终端窗口
  3. 重新打开一个新终端
  4. 只测试一个工具
  5. 先发最短的一条消息

这样做的好处，是你能把“CC-Switch 有没有写进去”和“底层工具自己能不能正常读到配置”拆开看。

第一次验证时，可以按用途去测：

  • Claude Code：先让它概括当前目录，不修改文件
  • Codex：先开一个测试目录，发一句最短消息
  • Gemini CLI：先问一句简单问候
  • OpenCode：先做只读任务，不要一上来就改代码

先把一条链路跑通，再去切第二个工具，问题范围会清楚很多。

切换后多久生效 ​

不同工具读取配置的方式不完全一样：

  • Claude Code：对配置变化通常感知比较快，很多场景不必完全重启；如果当前会话还是旧配置，开一个新终端最稳
  • Codex：通常需要关掉当前终端，再开一个新终端
  • Gemini CLI：很多场景会重新读取配置；如果表现不对，同样重新开终端
  • OpenCode / OpenClaw：按“新开终端重新读取配置”来理解最稳

和手动改环境变量一样，最怕的是“你以为已经切过去了，实际旧进程还在读旧值”。

旧环境变量冲突怎么办 ​

以前手动写过 ANTHROPIC_BASE_URL、OPENAI_API_KEY、GEMINI_API_KEY 这类变量时，CC-Switch 当前官方文档会主动检测冲突，并给出黄色提示。

这个提示非常有用，因为很多“明明切了新配置却不生效”的问题，本质上不是 CC-Switch 没写进去，而是终端优先读到了你以前留下的旧环境变量。

遇到冲突时，优先处理掉旧变量，再切配置。

使用习惯建议 ​

  • 每种工具单独一把 Key
  • 配置名称带上设备名或用途
  • 模型名始终从模型广场复制
  • 切换后优先开一个新终端再测试
  • 只从官网、中文首页或官方 GitHub 发布页下载
  • 不导入来路不明的配置包

常见问题 ​

应用后没有生效 ​

先不要急着删配置。先排查三层：

  1. 当前 CLI 进程是不是还没重读配置
  2. 本机是否还保留着旧环境变量
  3. 这把 Key 是否根本没有当前模型权限

Windows 上不要只关一个标签页，直接关闭整个 PowerShell 窗口更稳。

模型列表为空 ​

先看：

  1. 地址是否填对
  2. Key 是否完整
  3. 这把 Key 是否真有对应模型权限

如果地址和 Key 都对，但列表仍然拉不出来，常见原因是当前接口本身不暴露模型列表。这时直接去模型广场复制模型名，手动填入即可。

地址都填对了，还是明显走错模型 ​

这类问题通常优先不是看 CC-Switch，而是看当前工具有没有重新读取配置。

先检查：

  1. 旧终端是不是还没关掉
  2. 当前工具是不是还在读旧环境变量
  3. 你在 CC-Switch 里保存的是不是另一份配置档案

Windows 安装后打不开 ​

优先排查：

  • WebView2 Runtime 是否缺失
  • 杀毒软件是否拦截

下载慢 ​

先从中文首页或官网首页点 Get Latest Release。官网也慢时，再去官方 GitHub 发布页。不要下载第三方二次打包的安装包。

下一步 ​

小蓝中转站使用文档

© 2026 小蓝中转站