/v1/chat/completions。然而您希望连接该模型的客户端并非全都支持这种格式。Claude Code 使用的是 Anthropic 的 Messages 格式,而 OpenAI Codex 则使用 OpenAI 的 Responses 格式。这两种格式均不属于 Chat Completions,而且它们也不会为了适配您的后端而做出调整。
Tokios 在网关层面填补了这一差异,在请求抵达您的机器之前完成格式转换。这样一来,同一次部署即可响应 Claude Code、Codex 以及普通 OpenAI SDK 的调用,而您无需运行三套服务器或自行编写格式转换层。
三种客户端格式在网关处汇聚,随后被统一转换为 Chat Completions 格式以供本地模型处理。
格式不匹配的问题
三种数据格式最终都会出现在api.tokios.com 处,但只有其中一种格式能被您的后端识别。
Ollama、llama.cpp、vLLM 和 LM Studio 仅实现了第三种格式。倘若 Tokios 只是将字节数据原样通过通道转发,那么来自 Claude Code 与 Codex 的请求到达本地服务器时便会因格式不符而立刻失败。
翻译处理发生的位置
Tokios 会在客户端请求抵达您的机器之前,于 网关处 将其转换为符合 OpenAI 聊天补全格式的请求;该网关即为位于api.tokios.com 处的云端公共组件。如需了解完整的请求处理流程,请参阅 Tokios 如何将请求路由至本地模型。
- Anthropic Messages (
POST /v1/messages,即 Claude Code 发送的请求格式) 会被转换为 Chat Completions 格式。 - OpenAI Responses (
POST /v1/responses,即 Codex 发送的请求格式) 同样会被转换为 Chat Completions 格式。 - OpenAI Chat Completions (
POST /v1/chat/completions) 格式的请求则无需任何转换即可直接通过。
tokios-connector 永远不会接收到 Anthropic 或 Responses 格式的请求内容;它仅接收 Chat Completions 请求并将其原样转发至你配置的 BaseUrl(例如针对 Ollama 时即为 http://127.0.0.1:11434/v1)。该连接器不会对请求内容做任何转换,仅负责转发。所有与格式相关的处理逻辑均集中在网关端,且针对每一次部署仅执行一次即可。
这种集中化处理机制正是实现部署配置可移植性的关键:后端服务完全无需适配 Anthropic 或 OpenAI 的新版数据格式规范,只需维持原有运行逻辑即可。
工具调用相关的字段会在转换过程中被完整保留,不过底层模型是否真正支持这些功能则取决于模型本身——转换操作仅调整请求结构,并不会提升模型原有能力。
同一部署配置可通过两种不同方式访问
假设你已创建了一个名为gemma-tunnel 的部署配置并指向本地运行的模型。此时该配置可同时响应符合 Anthropic 协议规范的客户端请求以及符合 OpenAI 协议规范的请求,而后端服务无需做任何额外调整。
Claude Code(Anthropic Messages 协议)
Claude Code 基于 Anthropic Messages 协议通信,因此会使用根基础 URL——无需指定/v1 参数:
claude* 格式的模型 ID,因此 gemma-tunnel 不会出现在该列表中——需按上述方式显式传入 --model 参数。完整的配置流程可参阅 通过 Tokios 将 Claude Code 与本地模型结合使用。
OpenAI SDK(Chat Completions 协议)
符合 OpenAI 协议规范的客户端会使用/v1 格式的基础 URL进行通信:
model 参数:即公开的部署配置名称(gemma-tunnel),而非本地运行环境内部使用的模型标识符。经过必要的格式转换后,两类请求最终均会以单一 Chat Completions 请求的形式通过同一通道转发至本地模型。该模型完全无法感知发起请求时客户端所使用的协议类型。
OpenAI Codex 也遵循相同的模式,通过 Responses API 进行调用——详见通过 Tokios 将 OpenAI Codex 与本地模型结合使用中的 config.toml 配置说明。
为何这对智能体工具链至关重要
编码类智能体正是该协议分歧在现实场景中的体现:Claude Code选用了Anthropic Messages协议,Codex则采用OpenAI Responses协议;而其余绝大多数工具——包括LangChain、各类聊天用户界面以及多数软件开发工具包——均使用Chat Completions协议。若你打算在本地运行模型并让多个此类工具共同调用它,就必须确保每个工具要么原生支持你的后端格式,要么配备专属适配器才行。 Tokios彻底解决了这一难题:只需完成一次部署注册,所有受支持的客户端协议均可指向同一后端调用。若要更换负责响应请求的本地模型,也无需修改任何客户端配置,因为协议转换与部署定位功能均集成在网关层面,而非智能体配置文件中。 当前兼容的客户端完整列表,请参阅将任意兼容OpenAI或Anthropic协议的客户端接入Tokios。快速入门
完成连接器配对后,数分钟内即可发起首次请求。
Tokios的请求路由机制
了解从客户端发起请求到网关处理,最终传递至连接器并调用模型的完整流程。
兼容客户端清单
确认你的客户端所需的基础URL地址及API功能范围。
在Tokios环境中使用Claude Code
设置ANTHROPIC_BASE_URL参数后,即可将Claude Code的请求定向至指定模型。