快速开始

这一页带你从零跑通第一条经过 AI Switch 的请求。全程大约五分钟，你需要准备一个可用的上游账号（base URL + API key），比如某个中转站的 key，或者官方 API key。

下面以 Codex 为例。其他平台流程一样，只是接口格式的默认值不同。

第 1 步：添加路由账号

打开 AI Switch，左侧边栏 Agents 分组里点 Codex（启动时默认就在这个界面）。

点顶部工具栏的 + 按钮（提示文字「新增账号」），弹出新增账号对话框。对话框顶部有三个标签，保持在 「API 账号」（「批量导入」是导入官方登录态用的，「导入其他客户端」可以直接读本机 CC Switch 的账号）。

按顺序填这几项：

账号名称 —— 随便起个能认出来的名字，比如 中转站-主力。这个名字后面会出现在统计的请求列表里，起得有意义一点方便对账。

API Key —— 填你的上游 key。这是个多行输入框，一行一个 key，粘贴多行会一次创建多个账号并归为同一批量。只加一个账号就填一行。

旁边有两个辅助按钮：key 是 base64 编码的可以点「Base64 解码」；key 在截图里可以点「OCR识别」选图片识别出来。

Base URL —— 上游的接口地址，比如 https://your-relay.example.com/v1。填上游文档给你的那个地址。

接口格式 —— 这是上游协议，也就是你的账号说哪种话。四个选项：

选项	dialect	上游接口
OpenAI Chat Completions	openai	Chat Completions
OpenAI Responses	openai-responses	Responses API
Claude Messages	anthropic	Messages API
Gemini	gemini	generateContent

照上游实际支持的协议选，不用管你要用哪个 CLI。 协议不一致由 AI Switch 桥接，所以一个 Chat Completions 的账号完全可以喂给 Codex。

Codex 平台默认选中 openai。选 anthropic 时会多出一个 「Claude 鉴权字段」 选择：ANTHROPIC_AUTH_TOKEN 走 Authorization: Bearer（多数中转站是这个），ANTHROPIC_API_KEY 走 x-api-key（Anthropic 官方的方式）。不确定先试前者。

模型映射（可选） —— 客户端请求的模型名和上游实际支持的模型名不一样时用。比如 CLI 会请求 gpt-5.5，你的中转站只有 gpt-4o，就在这里加一条 gpt-5.5 → gpt-4o。上游模型名和 CLI 请求的一致就不用填。

模型映射同时决定路由

映射不只是改名。代理会检查请求的模型有没有池内账号支持，一个都没有就直接返回 route_pool.model_unmatched 而不会瞎发。所以映射填对了，路由才能命中。

底部还有一个 「创建后加入算力池」 复选框，默认已勾选，保持勾选。

点 「保存账号」。成功后会提示「已新增 N 个账号并加入算力池」。

第 2 步：设优先级和并发上限，确认在算力池里

账号已经在池子里了，现在调它的路由参数。

在账号列表里找到刚创建的账号，点行末的 「编辑账号」，右侧滑出编辑面板，切到 「高级」 分区。这里有两个关键字段：

路由优先级 —— 1 到 5，默认 3，数字越小优先级越高。代理严格按优先级分层：优先级 1 的账号全部不可用了才会用到优先级 2。

单个账号先不用改。有多个账号时这样分配：

• 主力账号（便宜、稳定、额度多）设 1
• 备用账号设 3
• 兜底账号（贵，或者只在紧急时用）设 5

主力被限流的时候，代理自动降到备用，不需要你做任何事。

最大并发数 —— 默认 5，最小 1。这个账号同时最多跑几个请求。

上游对并发敏感（常见于官方账号）就往下调，最保守是 1。注意这是硬限制：账号跑满了会被跳过，代理去找同层的下一个账号；同层所有账号都跑满则报 route_pool.concurrency_exhausted。

失败处理策略（同一面板里）—— 默认额外重试 2 次、间隔 200 毫秒、连续 10 次同样的语义错误才把账号标记为异常、失败冷却 10 秒（冷却默认关闭）。默认值适用于大多数情况，先不用动。这些规则在代理请求和模型测试里共用。

改完关掉面板即可保存。

账号不在池子里怎么办

底部有视图切换：算力池 / 未入池 / 已归档 / 统计。

如果账号在「未入池」里（创建时没勾那个复选框），切到「未入池」，选中账号，点工具栏的 「加入算力池」。

在「算力池」视图里可以拖动行来调整顺序，这个顺序是同优先级内的轮转起点，不会越过优先级分层。

第 3 步：启动本地代理

回到顶部工具栏，点绿色的 ▶ 按钮（提示文字「启动本地路由代理」）。

启动成功后，工具栏的状态条会从「代理未启动」变成显示代理地址：

http://127.0.0.1:19527

代理绑定在 127.0.0.1，默认端口 19527。只监听本机回环地址，局域网里的其他机器连不上。

按平台区分的本地入口路径：

平台	本地入口	协议
Codex	/responses	OpenAI Responses
Claude	/v1/messages	Anthropic Messages
Gemini CLI	Gemini native	generateContent

需要 TLS 的话，设置里有「本地算力池 HTTPS」开关，可以生成并导入根证书，代理地址会变成 https://。

先验一下再往下走

在让 CLI 连过来之前，建议先用内置的测试确认链路是通的。

点工具栏的 ✈ 按钮（提示文字「真实生成测试算力池路由」），弹出对话框。Codex 平台可以选测试接口（/responses 或 /chat/completions），测试模型留空则用平台默认值。点 「开始测试」。

这是真实生成请求，不是简单的可达性探测 —— 它真的会让上游生成一段内容。结果面板会给你：

• 通过 / 失败
• 模型输出（模型实际返回的文本）
• 算力池请求链路：算力池入口 → 命中账号 → 上游接口，带 trace id
• 展开「查看输入输出」能看到请求 JSON 和响应 Body

这一步通了，说明账号、协议、桥接、模型映射全都对。失败的话，报错信息和请求链路能直接告诉你卡在哪一环。

排查更细的问题可以打开工具栏下拉菜单里的 「实时日志」，它按四个阶段展示协议转换：原始请求 / 发往上游 / 上游原始返回 / 最终返回。

第 4 步：让 CLI 指向本地代理

有两种方式，推荐第一种。

方式 A：让 AI Switch 写配置（推荐）

点工具栏的 🔌 按钮（提示文字「对接客户端：把当前算力池写入客户端配置」）。这个按钮要求代理已经在运行。弹窗里勾选要写入的客户端，再点「写入」。

AI Switch 会把当前平台的 CLI 配置指向本地代理。对 Codex 来说，它会改 ~/.codex/config.toml，加一个名为 ai-switch 的 model provider 并选中它，同时写一份 ~/.codex/ai-switch-model-catalog.json 模型目录。

写入是安全直写：先建快照、原子写入、检测并发修改、支持带守卫的回滚。你原有的配置项会保留。

界面下方会出现「配置写入结果」，列出每个目标的路径、状态、操作 id 和快照 id。

各平台写入的目标文件：

平台	文件
Codex	~/.codex/config.toml
Claude Code	~/.claude/settings.json
Gemini CLI	~/.gemini/settings.json
Grok	~/.grok/settings.json

写完直接跑 CLI 就行：

codex

CLI 现在的请求全部经过 AI Switch。

方式 B：手动配置

OpenCode、OpenClaw、Hermes 不支持原生配置写入，或者你想自己控制配置，就手动来。

需要两个值，都在 🔌 按钮（提示文字「写入路由配置文件」）弹出的窗口里，最下面的「在以上客户端之外使用」区域：

• Base URL —— 当前代理地址，比如 http://127.0.0.1:19527（Codex 标签页会带上 /v1，因为 Codex 拿 base URL 直接拼 /responses）
• API Key —— 本地代理 key，形如 sk-ai-switch-<uuid>

两个值都有一键复制按钮。API Key 默认打码，点眼睛图标才显示明文。

开启了本地 HTTPS 的话，同一区域还会多出一个 HTTPS Base URL（比如 https://127.0.0.1:19528）。正常情况用 HTTP 的那个就行；HTTPS 端点只给确实要求 TLS 的客户端，而且它必须信任本地根证书。详见 本地算力池 HTTPS。

代理 key 是每个智能体标签页一个，切到别的标签页要重新复制。

这个 key 的作用是让代理识别请求属于哪个平台。可以放在 Authorization: Bearer、x-api-key 或 x-goog-api-key 头里，也可以放 URL 的 key / api_key 查询参数里。它只用于本地认证，绝不会转发到上游 —— 上游看到的是账号自己的真实 key。

把这两个值填进目标工具的 base URL 和 API key 配置即可。

用 curl 验证

想直接确认，可以自己发一条。菜单里的「复制 curl（PowerShell / Git Bash）」和「复制 CMD curl」会生成现成的命令，也可以照下面写：

curl -X POST http://127.0.0.1:19527/responses \
  -H "Authorization: Bearer sk-ai-switch-你的key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Reply with exactly: ai-switch-ok",
    "stream": false
  }'

$key = "sk-ai-switch-你的key"
$body = @{
  model  = "gpt-5.5"
  input  = "Reply with exactly: ai-switch-ok"
  stream = $false
} | ConvertTo-Json

curl.exe -X POST http://127.0.0.1:19527/responses `
  -H "Authorization: Bearer $key" `
  -H "Content-Type: application/json" `
  -d $body

Claude 平台把路径换成 /v1/messages，请求体用 Anthropic Messages 格式。

代理还提供 OpenAI 风格的模型列表接口，GET 到 models 路径会返回池内所有账号聚合去重后的客户端可见模型 id，不会转发到上游。菜单里的「查看模型列表」就是这个。

第 5 步：看用量统计确认计费

底部视图切换到 「统计」。

顶部有四个时间窗口：当日 / 本周 / 本月 / 累计。

下面六张指标卡：

卡片	含义
请求	请求次数
输入 Token	输入 token 总数
输出 Token	输出 token 总数
缓存 Token	命中缓存的 token 总数
Token 总计	输入 + 输出
总费用（USD）	折算成美元的总花费

再往下是 「请求列表」，每行一条请求：时间、账号名、状态、路径、模型、token 总数、价格、来源，末尾的「详情」可以展开。

这里是你确认计费的地方。刚才那次测试请求应该已经出现在列表里了：

• 账号名告诉你请求实际落到了哪个账号 —— 优先级配对了没有，一看就知道
• 价格是这条请求的花费，按账号返回的币种记录（美元或人民币，各自保留 6 位小数）
• 模型是最终请求的模型名，映射生效的话这里是映射后的值

统计每 5 秒自动刷新，请求列表每页 20 条。

关于费用

费用来自上游在响应里返回的计价信息。上游不返回价格，这里就统计不到。总费用卡片折算成美元展示，人民币按固定汇率 7.1 折算，所以这个数字是参考值，不能当账单用。以供应商后台的实际账单为准。

跑通之后

第一条请求通了，接下来通常是这些事：

加更多账号，把优先级排好。 这是算力池真正发挥作用的地方 —— 主力挂了自动降级，你什么都不用做。见 账号与算力池。

给失败的账号配自动恢复。 编辑面板「故障处理」分区里的「自动恢复」支持每日定时和探活恢复，被限流的账号能自己回到池子里。见 稳定性与自动恢复。

配置其他 CLI。 切到左侧边栏其他平台，重复上面的流程。每个平台有自己独立的算力池和代理 key。先看看 平台支持矩阵 确认支持范围。

理解协议桥接。 想清楚哪些账号能配哪些 CLI，见 协议路由与桥接。

在浏览器或手机上访问。 见 Web 服务模式。

在终端里直接干活。 见 Vibe 终端与皮肤 和 会话管理。

遇到问题

报错	原因
代理未启动	没点启动按钮，或者启动失败
No enabled route credentials in pool	池子里没有可用账号：全部被禁用、归档，或状态不是「正常」
route_pool.model_unmatched	请求的模型没有任何池内账号支持，检查模型映射
route_pool.concurrency_exhausted	所有账号都到并发上限，调高「最大并发数」或加账号
route_proxy.key_invalid	代理 key 无效、过期，或属于另一个 AI Switch 实例，重新复制一次
route_proxy.platform_unresolved	请求里没带代理 key，也没带平台头

更多问题见 FAQ，模型测试的细节见 模型连通性测试。