/v1/chat/completions을 제공합니다. 하지만 실제로 해당 모델을 사용하려는 클라이언트들이 모두 이 형식을 따르지는 않습니다. Claude Code는 Anthropic Messages 형식을 사용하며 OpenAI Codex는 OpenAI Responses 형식을 사용합니다. 이 둘 모두 Chat Completions 형식이 아니며 사용자의 백엔드에 맞춰 변경될 가능성도 없습니다
Tokios는 요청이 사용자의 머신에 도달하기 전에 게이트웨이 단계에서 이 간극을 메웁니다. 그 결과 세 개의 서버를 따로 운영하거나 별도의 번역 레이어를 직접 구현할 필요 없이 동일한 배포 환경에서 Claude Code와 Codex, 그리고 일반 OpenAI SDK 호출까지 모두 처리할 수 있습니다
세 가지 클라이언트 형식이 게이트웨이에 모여 하나의 로컬 모델을 위해 모두 Chat Completions 형식으로 변환됩니다
형식 불일치 문제
Three wire formats show up atapi.tokios.com, and only one of them is what your backend understands:
Ollama, llama.cpp, vLLM, LM Studio는 오직 세 번째 형식만을 지원합니다. 만약 Tokios가 터널을 통해 수신된 바이트 데이터를 그대로 전달하기만 한다면, Claude Code와 Codex의 요청들은 로컬 서버가 인식할 수 없는 형태로 도착해 즉시 실패하게 됩니다.
번역이 이루어지는 위치
Tokios converts the client’s request to OpenAI Chat Completions at the gateway — the public, cloud-side component atapi.tokios.com — before anything travels down the tunnel to your machine. For the full request lifecycle, see How Tokios routes requests to your local models.
- 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이며, 로컬 런타임 내부에서 사용되는 실제 ID와는 다릅니다. 번역 과정을 거친 뒤 두 요청은 결국 동일한 터널을 통해 동일한 로컬 모델에 전달되는 단일 Chat Completions 요청으로 귀결됩니다. 모델 입장에서는 클라이언트가 어떤 프로토콜을 사용했는지 알 수 없습니다.
OpenAI Codex follows the same pattern through the Responses API — see Use OpenAI Codex with your own local models via Tokios for the config.toml setup.
에이전트 도구 환경에서 이 문제가 중요한 이유
코딩 에이전트 분야에서 바로 이 프로토콜 차이가 실제로 드러납니다. Claude Code는 Anthropic Messages를 표준으로 채택했고, Codex는 OpenAI Responses를 채택했으며, LangChain을 비롯한 대부분의 채팅 UI와 SDK들은 Chat Completions를 표준으로 삼고 있습니다. 로컬 모델을 운용하면서 여러 도구와 연동해보고 싶다면 각 도구가 사용자의 백엔드 형식을 기본적으로 지원하거나 별도의 어댑터를 구현해야만 합니다. Tokios를 활용하면 이 문제가 전혀 발생하지 않습니다. 배포 환경을 한 번만 등록해두면 모든 지원되는 클라이언트 형식이 동일한 백엔드 호출로 연결됩니다. 어떤 로컬 모델을 배포 환경에 연결할지 변경하더라도 클라이언트 설정을 수정할 필요가 없습니다. 번역 단계와 배포 환경 탐색 과정이 모두 게이트웨이 단계에서 처리되기 때문이며 에이전트 설정 파일에는 아무것도 기록되지 않습니다. 현재 호환되는 클라이언트의 전체 목록은 OpenAI 또는 Anthropic과 호환되는 모든 클라이언트를 Tokios에 연결하기 문서를 참고하시기 바랍니다.빠른 시작 가이드
커넥터를 연동한 뒤 몇 분 내에 첫 요청을 보낼 수 있습니다.
Tokios가 요청을 라우팅하는 방식
클라이언트에서 게이트웨이, 커넥터를 거쳐 모델에 이르기까지의 전체 요청 처리 과정을 확인해보세요.
호환 가능한 클라이언트 목록
사용 중인 클라이언트에 필요한 기본 URL과 API 인터페이스가 무엇인지 확인하세요.
Claude Code와 Tokios 연동 방법
ANTHROPIC_BASE_URL 값을 설정한 뒤 Claude Code의 요청을 사용자의 모델로 라우팅할 수 있습니다.