CC Switch CLI

准备工作

开始前请准备：

• 一个 CoffeeRouter 令牌。建议为每个 Agent 工具创建独立令牌，方便限制模型、额度和 IP，并可单独撤销。
• 当前令牌允许使用的准确模型 ID。模型名必须与 CoffeeRouter 令牌管理页中显示的名称完全一致。
• 已安装需要接入的目标工具。
• 受支持的终端。Windows 建议使用 Windows Terminal 或 PowerShell，macOS/Linux 使用常用终端即可。

首次切换 Provider 前，请至少运行一次目标工具，让它创建本地配置目录：

claude --help
codex --help
gemini --help
opencode --help
openclaw --help

Hermes 用户可以先运行 Hermes，或确认 ~/.hermes 目录已经存在。目标工具尚未初始化时，CC Switch CLI 会出于安全考虑跳过实时配置写入。

地址与协议对照

不同工具会自行拼接不同的请求路径，请严格按照下表填写：

目标应用	Base URL	API 格式	本地代理
Claude Code	https://www.coffeerouter.ai	Anthropic	关闭
Codex	https://www.coffeerouter.ai/v1	Responses	关闭
Gemini CLI	https://www.coffeerouter.ai	Gemini 原生 API	关闭
OpenCode	https://www.coffeerouter.ai/v1	OpenAI Compatible	不支持，也不需要
Hermes	https://www.coffeerouter.ai/v1	chat_completions	不支持，也不需要
OpenClaw	https://www.coffeerouter.ai/v1	openai-completions	不支持，也不需要

Claude Code 和 Gemini CLI 接收站点根地址，并自行拼接 Anthropic Messages 或 Gemini /v1beta 路径。其余 OpenAI 兼容工具需要保留一个 /v1。

安装 CC Switch CLI

CC Switch CLI 不提供 npm 或 npx 安装方式。请使用官方发布的二进制文件。

macOS 或 Linux

使用官方安装脚本：

curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash

默认安装到 ~/.local/bin。macOS 也可以使用 Homebrew：

brew install cc-switch-cli

通过 Homebrew 安装后，请使用 brew upgrade cc-switch-cli 更新，不要混用 CC Switch CLI 内置更新功能。

Windows

从 CC Switch CLI Releases 下载 cc-switch-cli-windows-x64.zip，解压后运行 cc-switch.exe，或将其放入由你管理的 PATH 目录。

安装完成后检查：

cc-switch --version
cc-switch --help

启动并选择目标应用

运行：

cc-switch

进入全屏界面后，按照界面底部的按键提示完成以下操作：

1. 切换到需要配置的应用，例如 Claude、Codex 或 Gemini。
2. 打开 Providers / 供应商。
3. 选择 Add Provider / 新增供应商。
4. Provider 模板选择 Custom。

TUI 快捷键可能随版本调整，请以当前界面底部显示的提示为准。

接入 Claude Code

切换到 Claude 应用并添加 Custom Provider，填写：

配置项	填写内容
Name	CoffeeRouter
Base URL	https://www.coffeerouter.ai
API Key	CoffeeRouter 令牌，例如 sk-your-api-key
API Key Field	ANTHROPIC_API_KEY
API Format	Anthropic
Main / Haiku / Sonnet / Opus	按需填写当前令牌允许使用的 Claude 模型 ID
Local Proxy	关闭

Base URL 不要添加 /v1。CoffeeRouter 已提供 Anthropic Messages 兼容接口，因此无需选择 OpenAI Chat/Responses 转换，也无需启用本地代理。

如果令牌只允许一个 Claude 模型，可以先把同一模型 ID 用作主模型，并按需设置 Haiku、Sonnet、Opus 映射。

接入 Codex

切换到 Codex 应用并添加 Custom Provider，填写：

配置项	填写内容
Name	CoffeeRouter
Base URL	https://www.coffeerouter.ai/v1
API Key	CoffeeRouter 令牌，例如 sk-your-api-key
Upstream API Format	Responses
Model Mapping / Model Catalog	至少添加一个当前令牌允许使用的模型 ID
Proxy Takeover / Local Proxy	关闭

当前版本主要通过 Model Mapping / Model Catalog 管理 Codex 模型。在 Responses 模式下，它用于直连选择上游模型，并不代表启用协议转换或本地代理。如果界面显示 Model 字段，也应填写相同的完整模型 ID。不要选择 Chat 格式，也不要把地址写成 /v1/v1。

接入 Gemini CLI

切换到 Gemini 应用并添加 Custom Provider，填写：

配置项	填写内容
Name	CoffeeRouter
Auth Type	API Key
API Key	CoffeeRouter 令牌，例如 sk-your-api-key
Base URL	https://www.coffeerouter.ai
Model	当前令牌允许使用的 Gemini 模型 ID

Gemini CLI 会把 Base URL 写入 GOOGLE_GEMINI_BASE_URL，并自行请求 /v1beta/models/...，因此这里不要添加 /v1 或 /v1beta。

接入其他工具

CC Switch CLI 还可以直接写入 OpenCode、Hermes 和 OpenClaw 的 Provider 配置。

OpenCode

配置项	填写内容
Provider Package	@ai-sdk/openai-compatible
Base URL	https://www.coffeerouter.ai/v1
API Key	CoffeeRouter 令牌
Model ID	当前令牌允许使用的完整模型 ID
Model Name / Context / Output Limit	可选，按模型能力填写

Hermes

配置项	填写内容
API Mode	chat_completions
Base URL	https://www.coffeerouter.ai/v1
API Key	CoffeeRouter 令牌
Models	至少添加一个完整模型 ID；第一个模型作为默认模型

OpenClaw

配置项	填写内容
API Protocol	openai-completions
Base URL	https://www.coffeerouter.ai/v1
API Key	CoffeeRouter 令牌
Models	至少添加一个完整模型 ID

保存 OpenClaw Provider 后，还需要在 CC Switch CLI 中把 CoffeeRouter Provider 和对应模型设为默认值。OpenCode、Hermes 和 OpenClaw 不使用 CC Switch CLI 的本地代理功能。

激活并验证

保存 Provider 后返回供应商列表，选中 CoffeeRouter，再按照界面底部提示执行 Switch / Activate。第一次切换时，如果 CC Switch CLI 检测到现有配置，请先阅读导入或备份提示，避免覆盖仍需保留的配置。

可以在终端中检查当前 Provider：

cc-switch --app claude provider current
cc-switch --app codex provider current
cc-switch --app gemini provider current

然后重启对应 Agent CLI 并发送一条简单测试消息。未指定 --app 时，CC Switch CLI 默认管理 Claude。

可选使用命令行配置

推荐使用 TUI 输入令牌。以下命令适合自动化场景，但真实 API Key 可能出现在终端历史、进程列表或录屏中。示例只使用占位令牌。

Claude Code

cc-switch --app claude provider add --name CoffeeRouter --id coffeerouter --base-url https://www.coffeerouter.ai --api-key sk-your-api-key --model your-claude-model-id --api-format anthropic --api-key-field api-key
cc-switch --app claude provider switch coffeerouter

Codex

cc-switch --app codex provider add --name CoffeeRouter --id coffeerouter --base-url https://www.coffeerouter.ai/v1 --api-key sk-your-api-key --model your-model-id --api-format responses
cc-switch --app codex provider switch coffeerouter

Gemini CLI

cc-switch --app gemini provider add --name CoffeeRouter --id coffeerouter --base-url https://www.coffeerouter.ai --api-key sk-your-api-key --model your-gemini-model-id
cc-switch --app gemini provider switch coffeerouter

provider add 是非交互命令，不能省略必要字段后等待向导继续；需要交互式添加时，请直接运行 cc-switch。

配置文件与安全

内容	默认路径
CC Switch CLI 主数据库	~/.cc-switch/cc-switch.db
CC Switch CLI 设置	~/.cc-switch/settings.json
自动备份	~/.cc-switch/backups/
Claude Code	~/.claude/settings.json
Codex	~/.codex/config.toml、~/.codex/auth.json
Gemini CLI	~/.gemini/.env、~/.gemini/settings.json
OpenCode	~/.config/opencode/opencode.json
Hermes	~/.hermes/config.yaml
OpenClaw	~/.openclaw/openclaw.json

Windows 中的 ~ 表示当前用户目录，通常是 %USERPROFILE%。可以运行 cc-switch config path 查看本机实际使用的配置路径。

常见问题

切换后为什么没有生效

确认目标工具已经运行过一次并创建配置目录，然后检查环境变量是否覆盖了 CC Switch CLI 写入的配置：

cc-switch env check --app claude
cc-switch env list --app claude

将 claude 替换为实际应用标识，再重启终端和目标工具。

为什么有些地址带 /v1 有些不带

Claude Code 和 Gemini CLI 会自行拼接协议路径，所以使用站点根地址；Codex、OpenCode、Hermes 和 OpenClaw 接收 OpenAI 兼容 Base URL，需要保留一个 /v1。

提示 401 或 API Key 无效

确认令牌复制完整、尚未过期、未被禁用且有可用额度，同时检查 IP 白名单等限制。建议从 TUI 重新输入令牌，避免命令行转义或空格问题。

提示 404 或路径不存在

检查目标工具是否使用了正确地址，不要重复添加 /v1、/v1beta 或完整请求路径。

提示模型不存在或不可用

返回 CoffeeRouter 令牌管理页，复制当前令牌允许使用的模型 ID，并原样填写到 CC Switch CLI。不要使用展示名称或自行缩写模型名。

CC Switch CLI 会转发我的请求吗

默认不会。它主要负责保存和切换本地配置，目标 Agent 直接请求 CoffeeRouter。只有显式启用 Claude、Codex 或 Gemini 的本地 Proxy 时，请求才会先经过本机 CC Switch CLI 代理；本教程不需要启用该功能。

官方资料

• CC Switch CLI 官方仓库
• CC Switch CLI 中文 README
• 最新版本与下载
• Provider 命令源码