跳转到主要内容
您的本地模型服务器几乎肯定只支持一种格式:OpenAI 的 Chat Completions。Ollama、llama.cpp、vLLM 以及 LM Studio 均提供 /v1/chat/completions。然而您希望连接该模型的客户端并非全都支持这种格式。Claude Code 使用的是 Anthropic 的 Messages 格式,而 OpenAI Codex 则使用 OpenAI 的 Responses 格式。这两种格式均不属于 Chat Completions,而且它们也不会为了适配您的后端而做出调整。 Tokios 在网关层面填补了这一差异,在请求抵达您的机器之前完成格式转换。这样一来,同一次部署即可响应 Claude Code、Codex 以及普通 OpenAI SDK 的调用,而您无需运行三套服务器或自行编写格式转换层。
Claude Code(使用 Anthropic Messages 格式)、OpenAI Codex(使用 Responses 格式)以及普通 OpenAI SDK(使用 Chat Completions 格式)均向 Tokios 网关发送请求,网关随即将所有格式转换为 Chat Completions 格式并转发至本地模型。

三种客户端格式在网关处汇聚,随后被统一转换为 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) 格式的请求则无需任何转换即可直接通过。
只有符合 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 Code 的模型选择界面仅显示 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的请求定向至指定模型。