接口总览：入口与出口
cc-router 夹在你的工具和大模型厂商之间：
- 入口：你的工具怎么连 cc-router。cc-router 对外开放三种协议的端点，工具讲哪种就接哪个。
- 出口：cc-router 怎么连厂商。每条订阅按厂商支持的协议配置，cc-router 负责发出正确格式的请求。
两侧互不绑定，可以任意组合。比如 Codex 从 OpenAI Responses 入口进来，最终由 DeepSeek 的 Anthropic 端点作答。
Claude Code OpenCode OpenClaw pi ... Codex ... Open WebUI / Cherry Studio ...
| | | | | |
------------------------------------- | |
| | |
Anthropic OpenAI OpenAI
Messages API Responses API Chat Completions API
(/v1/messages) (/v1/responses) (/v1/chat/completions)
| | |
-------------------------------------------------------
| 入口 · 虚拟模型
|
cc-router
(本地 127.0.0.1:23456)
|
| 出口 · 真实模型
-----------------------------------------------------------------------------
| | | | | | |
DeepSeek GLM Kimi Anthropic OpenAI Gemini ......
API Coding Coding Messages Responses & API
Plan Plan API Completions内部统一：一切都先变成 Anthropic Messages
cc-router 内部只有一条调度 pipeline，它讲的是 Anthropic Messages 协议：
- 请求从任一入口进来。非 Anthropic 入口先翻译成 Anthropic Messages。
- pipeline 把
model解析成虚拟模型（model-fable/model-opus/model-sonnet/model-haiku），按该槽位绑定的订阅列表与调度模式（顺序 / 轮询 / 会话亲和）选一家订阅。 - 按这家订阅的出口协议发出请求。非 Anthropic 出口再翻译成对应协议。
- 响应沿原路翻译回去，以客户端入口的协议格式返回。
所以三个入口共用同一套订阅、虚拟模型、限额与会话亲和；限流、失败时的自动重试和切换订阅也对所有入口生效。请求日志详情里的「入口接口」能看到每条请求从哪个入口进来。
入口：你的工具怎么连 cc-router
| 入口（点击查看详细参考） | 典型客户端 | Base URL | 协议翻译 |
|---|---|---|---|
Anthropic MessagesPOST /v1/messages | Claude Code、Claude Desktop、OpenCode、OpenClaw、pi、Kimi Code CLI | http://127.0.0.1:23456 | 无，原样透传 |
OpenAI ResponsesPOST /v1/responses | Codex CLI、Codex Desktop | http://127.0.0.1:23456/v1 | Responses ⇄ Messages |
OpenAI Chat CompletionsPOST /v1/chat/completions | Open WebUI、Cherry Studio、Cline、LobeChat | http://127.0.0.1:23456/v1 | Chat ⇄ Messages |
三个入口之外还有两个公共端点：
| 端点 | 用途 | 鉴权 |
|---|---|---|
GET /v1/models | 虚拟模型清单，字段同时兼容 Anthropic 与 OpenAI SDK | 不需要 |
GET /health | 存活探测，返回纯文本 ok | 不需要 |
详见 GET /v1/models。
三个入口的差异速查
/v1/messages | /v1/responses | /v1/chat/completions | |
|---|---|---|---|
| 最低版本 | v3.0.0 | v3.0.0 | v5.0.0 |
| 推荐模型名 | model-opus 等 | gpt-5.5 等 | 两种都行 |
| 思考强度 | thinking / output_config.effort 原样透传 | reasoning.effort → thinking 预算 | reasoning_effort → thinking 预算 |
| 思考内容返回 | thinking 块（带签名） | reasoning item（带签名，可回传） | reasoning_content 字段（回传会被丢弃） |
| 图片输入 | 支持 | 不支持 | 支持（data: base64 与 http(s) URL） |
| 工具调用 | 支持 | 支持（function 类型） | 支持（tools / tool_choice，不支持旧版 functions） |
| 流式终止标志 | message_stop | response.completed（无 [DONE]） | data: [DONE] |
| 流式 usage | message_start / message_delta 中 | response.completed 中 | 末尾固定一帧 usage |
| 错误体风格 | Anthropic | OpenAI | OpenAI |
| 会话亲和依据 | x-claude-code-session-id → metadata.user_id → 首条用户消息 | prompt_cache_key → session_id 请求头 | user → x-session-id 请求头 → 首条用户消息 |
选哪个入口？ 工具支持 Anthropic Messages 就优先用它：零翻译，thinking、
cache_control、图片、工具调用都按原生语义工作。只有工具只讲 OpenAI 协议时才用另外两个入口。
公共约定
监听与端口
| 配置 | 默认值 | 说明 |
|---|---|---|
| 监听地址 | 127.0.0.1 | 设置 → 代理服务 → 监听地址切到「局域网」后变为 0.0.0.0 |
| HTTP 端口 | 23456 | 被占用时自动 +1，最多尝试 100 次 |
| HTTPS 端口 | 23457 | 监听协议选「仅 HTTPS」或「HTTP + HTTPS」时启用，同样自动 +1 |
| 请求体上限 | 32 MB | 多图 base64 请求可能超限返回 413，可在设置里调大 |
端口、协议、监听地址、请求体上限修改后都需要重启 cc-router 生效。
鉴权
- 「Token 鉴权」默认开启（设置 → 鉴权与跨域）。开启时所有入口都从
x-api-key: <token>或Authorization: Bearer <token>读取 token（x-api-key优先），必须与设置页的 token 完全一致。 /v1/models、/health与所有OPTIONS预检请求不需要鉴权。- 鉴权失败的
401响应体固定是 Anthropic 风格，与入口无关，因为鉴权发生在入口 handler 之前。 - 这个 token 只用于访问 cc-router，与上游厂商的 API Key 无关。上游 Key 由 cc-router 在转发时按订阅替换。
HTTPS
HTTPS 端口使用 cc-router 本地自签 CA 签发的证书，客户端需要先信任这张 CA。只接受 HTTPS 的客户端（如 Claude Desktop）才需要开启，配置方法见 与 Claude Desktop 集成（macOS）和 Windows 版。
CORS
默认开启，Access-Control-Allow-Origin: *，允许 GET / POST / OPTIONS，预检直接返回 204。401 响应同样带 CORS 头，浏览器里能读到错误体。
虚拟模型与别名
所有入口共用一套模型名解析规则，不同入口的模型名可以混用：
| 虚拟模型 | 可用别名 |
|---|---|
model-fable | claude-fable*、gpt-5.6、gpt-*-sol |
model-opus | claude-opus*、gpt-5.5、gpt-*-terra |
model-sonnet | claude-sonnet*、gpt-5.4、gpt-*-luna |
model-haiku | claude-haiku*、gpt-*-mini |
- 以上所有写法都可以加
anthropic/或openai/前缀（LiteLLM 风格），效果相同。 claude-opus*是前缀匹配，claude-opus-4-7、claude-opus-4-7-20260101都命中model-opus。gpt-*-sol按-分段匹配档位，gpt-5.6-sol、gpt-6-sol-20261201都命中model-fable；gpt-5.4-mini命中model-haiku。- 不匹配任何规则的模型名走 fallback：
model原样透传给 fallback 槽位的订阅。
出口：cc-router 怎么连厂商
出口按上游协议分四类。内置厂商预设和自定义端点走的是同一条路，区别只是内置预设已经填好了地址、鉴权方式和模型列表。完整内置清单以 app 内「添加订阅」页为准。
| 出口类型 | 上游协议 | 内置预设（节选） | 自定义端点 | 协议翻译 |
|---|---|---|---|---|
| Anthropic Messages 兼容 | /v1/messages | Anthropic 官方、DeepSeek、智谱 GLM、Kimi、MiniMax、小米 MiMo、阿里云百炼、火山方舟、腾讯云、百度千帆、阶跃星辰、ModelScope、优云智算、Fireworks、OpenRouter、xAI、Ollama 等 | 任意 Anthropic Messages 兼容端点 | 无，原样透传 |
| OpenAI 兼容 | /v1/responses、/v1/chat/completions | OpenAI 官方 API | one-api / new-api 中转、Groq、Together、本地 vLLM / llama.cpp 等 | Messages → OpenAI |
| Gemini 兼容 | generateContent、/v1beta/interactions | Google AI Studio、Gemini Interactions API | 任意 Gemini 兼容端点 | Messages → Gemini |
| 订阅账号（OAuth） | 各家私有协议 | Codex（ChatGPT Plus/Pro）、Kiro（AWS） | 不适用 | Messages → 私有协议 |
各类出口的行为要点：
- Anthropic Messages 兼容：主路径。不做协议翻译，thinking、
output_config.effort、cache_control、图片、工具调用全部按原生语义工作。厂商提供原生 Anthropic 端点时优先配这一类。 - OpenAI 兼容：thinking 与 OpenAI reasoning 双向映射，多轮推理上下文自动回灌；Chat Completions 上游返回的
reasoning_content（DeepSeek R1 等）会转成 thinking 块。翻译层表达不了的内容（如cache_control）会被丢弃。 - Gemini 兼容：thinking 双向映射，工具调用往返时自动携带 thought signature。
- 订阅账号（OAuth）：不用 API Key，通过 OAuth 设备码登录。属于灰色地带，有封号风险，不建议当主力，只适合兜底。
入口 × 出口组合
任意入口都能搭配任意出口，差别在于中间经过几次协议翻译：
| 入口 ↓ / 出口 → | Anthropic 兼容 | OpenAI 兼容 / Gemini 兼容 / OAuth |
|---|---|---|
/v1/messages | 0 次，完全透传，保真度最高 | 1 次（出口翻译） |
/v1/responses | 1 次（入口翻译） | 2 次 |
/v1/chat/completions | 1 次（入口翻译） | 2 次 |
翻译次数越多，协议专有特性丢失的可能越大（例如 cache_control 只在全程 Anthropic 时有效）。实际使用中 1～2 次翻译对日常对话和工具调用影响不大，但如果你在意 prompt cache 命中率或推理细节，尽量让入口和出口都走 Anthropic 协议。