RealRelay.ai
编码智能体

CC Switch 接入指南

用 CC Switch 把 Claude Code 和 Codex 指向 RealRelay.ai：从控制台一键导入提供商，或手动添加，然后检查连接并选择模型。

创建 API 密钥浏览目录
协议
Anthropic Messages · OpenAI Responses
基础地址
https://www.realrelay.ai
官方文档
github.com
已对照工具官方文档核对
2026-10
实验性. 尚未在 RealRelay.ai 上端到端跑通。步骤依据该工具的官方文档；如果某一步失败，请带上错误信息联系支持。

概览

CC Switch 是一款为命令行编码智能体管理提供商设置的桌面应用。你不必逐个编辑各工具的配置文件，只需在 CC Switch 中添加一次提供商并切换过去即可。本指南介绍它在 RealRelay.ai 上最常用的两个目标：Claude Code 和 Codex。

  • Claude Code 使用 Anthropic Messages 协议。它的端点是不带 /v1 的站点地址，因为 Claude Code 会自己拼上 /v1/messages。

  • Codex 使用 OpenAI Responses 协议。它的端点是带 /v1 的站点地址；Codex 会在后面拼上 /responses。

  • 无论哪种，你都需要一个从控制台的 API 密钥页面获取的 API 密钥，以及一个与 GET /v1/models 列出的完全一致的模型 ID。

CC Switch 只负责写配置；请求是由 Claude Code 或 Codex 发出的，所以请先安装它们。Codex 只能使用 RealRelay.ai 在 /v1/responses 上提供的少数模型，例如 openai/gpt-5.3-codex。本配置尚未在 RealRelay.ai 上端到端跑通。

一键配置

控制台可以通过 CC Switch 的 ccswitch:// 链接把密钥直接交给它。请先安装 CC Switch（见下方“安装”），浏览器才知道如何打开该链接。

  1. 1

    打开密钥的菜单

    在API 密钥页面，打开你要使用的密钥在 Actions 列中的 ⋯ 菜单，选择 CC Switch。

  2. 2

    填写 Import to CC Switch 对话框

    选择 Application，为提供商填写 Name，并选择 Primary Model（必填）。对于 Claude，还要设置 Haiku、Sonnet 和 Opus 模型，让 Claude Code 用到的每个槽位都指向你的密钥能调用的模型。

    Console → API Keys → ⋯ → CC Switch
    1Application:   Claude2Name:          RealRelay.ai Claude3Primary Model: anthropic/claude-sonnet-4-64Haiku Model:   anthropic/claude-sonnet-4-65Sonnet Model:  anthropic/claude-sonnet-4-66Opus Model:    anthropic/claude-sonnet-4-6
    Console → API Keys → ⋯ → CC Switch
    Application:   CodexName:          RealRelay.ai CodexPrimary Model: openai/gpt-5.3-codex
  3. 3

    打开 CC Switch 并导入

    点击 Open CC Switch，允许浏览器打开该应用。CC Switch 会显示端点、打码后的密钥和模型。控制台会开启 Switch to this provider after import；如果你只想先保存提供商以后再用，请关闭它。然后点击 Import。

控制台会替你填好正确的端点：Claude 用站点根地址，Codex 用 /v1 地址。不要在对话框中选择 Gemini；RealRelay.ai 没有可供 Gemini CLI 使用的 Gemini 文本模型。如果你的控制台中没有 CC Switch 选项，按下面的手动步骤操作也能得到相同结果。

安装

从 GitHub Releases 页面下载 CC Switch，或使用包管理器安装。它需要 Windows 10、macOS 12，或 glibc 2.35 和 WebKitGTK 4.1 及以上的 Linux（例如 Ubuntu 22.04 或 Debian 12）。

macOS (Homebrew)
brew install --cask cc-switch

或者从 Releases 下载 .dmg。该版本经过签名和公证，可在 Apple 芯片和 Intel 芯片的 Mac 上运行。

从 Releases 下载 .msi 安装程序或便携版 .zip。ARM 版 Windows 有单独的 arm64 版本。

从 Releases 下载适合你架构的 .deb、.rpm 或 .AppImage。在 Arch Linux 上：

Arch Linux (paru)
paru -S cc-switch-bin

首次启动时，CC Switch 会把你当前的 Claude Code 和 Codex 设置保存为一个名为 default 的提供商，方便以后切换回去。

配置

要手动添加提供商，请在侧边栏中选择工具，点击 Add Provider（右上角的 + 按钮），选择 Custom Configuration，填写表单后点击 Add。把 sk-*** 替换成你的密钥。

CC Switch → Claude Code → Add Provider → Custom Configuration
1Provider Name: RealRelay.ai2API Key:       sk-***3API Endpoint:  https://www.realrelay.ai4Upstream Format: Anthropic Messages (Native)5Main Model:    anthropic/claude-sonnet-4-6

表单下方的配置编辑器会显示 CC Switch 将写入 ~/.claude/settings.json 的内容。其中应包含：

CC Switch → Claude Code → config (settings.json)
1{2  "env": {3    "ANTHROPIC_BASE_URL": "https://www.realrelay.ai",4    "ANTHROPIC_AUTH_TOKEN": "sk-***",5    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-4-6",6    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-sonnet-4-6",7    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-4-6",8    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-sonnet-4-6"9  }10}
CC Switch → Codex → Add Provider → Custom Configuration
1Provider Name:   RealRelay.ai2API Key:         sk-***3API Endpoint:    https://www.realrelay.ai/v14Upstream Format: Responses (native)5Default Model:   openai/gpt-5.3-codex

编辑器分为两部分：auth.json 存放密钥，config.toml 存放端点和模型：

CC Switch → Codex → auth.json
{  "OPENAI_API_KEY": "sk-***"}
CC Switch → Codex → config.toml
1model_provider = "custom"2model = "openai/gpt-5.3-codex"3model_context_window = 40000045[model_providers.custom]6name = "RealRelay.ai"7base_url = "https://www.realrelay.ai/v1"8wire_api = "responses"9requires_openai_auth = true

  • 两者之间唯一不同的值是 API Endpoint：Claude Code 不带 /v1，Codex 带 /v1。

  • Upstream Format 保持为原生选项。这样两个工具都会直接与 RealRelay.ai 通信，不需要 CC Switch 的本地路由。

  • 对于 Claude Code，RealRelay.ai 接受以 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY 传入的密钥。对于 Codex，CC Switch 会在切换时把密钥写入 ~/.codex/config.toml，而不是 auth.json。

  • model_context_window 告诉 Codex 该模型的上下文窗口有多大，因为 RealRelay.ai 的模型列表不提供这项信息。400,000 适用于 openai/gpt-5.3-codex。

然后在该提供商的卡片上点击 Enable。Claude Code 无需重启即可识别改动。切换后请重启 Codex 或你的终端。

验证

  1. 1

    直接调用端点

    用你的密钥运行与所配置工具对应的请求。如果返回的 JSON 包含 id（Claude Code 为 msg_…，Codex 为 resp_…），说明地址、密钥和模型都没问题。

    Terminal · Claude Code endpoint
    1curl -sS "https://www.realrelay.ai/v1/messages" \2  -H "Authorization: Bearer sk-***" \3  -H "anthropic-version: 2023-06-01" \4  -H "content-type: application/json" \5  -d '{"model": "anthropic/claude-sonnet-4-6", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'
    Terminal · Codex endpoint
    1curl -sS "https://www.realrelay.ai/v1/responses" \2  -H "Authorization: Bearer sk-***" \3  -H "content-type: application/json" \4  -d '{"model": "openai/gpt-5.3-codex", "input": "Reply with OK"}'
  2. 2

    确认当前生效的提供商

    在 CC Switch 中，该工具下启用的应是 RealRelay.ai 卡片。

  3. 3

    启动工具

    在项目中启动它并运行 /status。基础地址应为 RealRelay.ai，模型应是你选择的那个。发一条简短消息；收到回复即说明整条链路畅通，该请求也会出现在控制台的用量日志中。

    Claude Code
    claude/status
    Codex
    codex/status

模型

  • Claude Code：在提供商上设置主模型以及 Haiku、Sonnet 和 Opus 模型。Claude Code 会把标题等后台任务发给 Haiku 槽位，如果留空，发出的就是 RealRelay.ai 列表中没有的模型名。模型字段旁的 Fetch Models 会从 RealRelay.ai 的模型列表填充一个选择器。

  • Codex：把每个想在 /model 中使用的模型连同其上下文窗口添加到提供商的 Model Mapping 表中。Default Model 为空时，使用第一行。Codex 只在启动时读取该列表，所以修改后请重启它。

  • 要更改所有新会话使用的模型，请在 CC Switch 中编辑提供商，而不要改工具自己的文件；下次切换时，CC Switch 会重写那些文件。

各端点提供哪些模型，请见选择模型。Claude Code 本身的配置请参阅 Claude Code 接入指南。

故障排查

  • 点击 Open CC Switch 后没有任何反应。CC Switch 没有安装，或者浏览器拦截了该链接。安装并启动一次 CC Switch，然后再点击该按钮，并允许浏览器打开应用。

  • 出现两张 RealRelay.ai 卡片。每点击一次导入链接都会新增一个提供商。删掉多余的卡片即可。

  • Claude Code 返回 404。Claude 的端点以 /v1 结尾。把它去掉。

  • Codex 返回 404。Codex 的端点缺少 /v1。把它加上。

  • Codex 报模型错误。该模型不在 /v1/responses 上提供。请使用 Responses 模型，例如 openai/gpt-5.3-codex；普通的 openai/gpt-5.x、Claude 和 GLM 模型只支持 Chat Completions。

  • 卡片显示“Needs Routing”。上游格式不是该工具的原生格式。Claude Code 请改回 Anthropic Messages (Native)，Codex 请改回 Responses (native)。

  • Codex 仍在使用旧的提供商或模型列表。重启 Codex。如果 CC Switch 提示重启 Codex 守护进程，请按提示操作。

  • 401。密钥有误、已被禁用或额度已用完。在API 密钥页面检查它。

  • Claude Code 返回 400 并指出未知字段，例如 context_management：把下面的内容添加到提供商的配置中，以关闭实验性请求字段。

    CC Switch → Claude Code → config → env
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"