Skip to content
claude-code-proxy

How it works

claude-code-proxy exposes Anthropic Messages and optional OpenAI-compatible routes. Messages, Chat Completions, and Responses select a provider from the request model and translate through its native protocol. Separately enabled image and audio transcription routes use Codex.

API clientAnthropic Messages
OpenAI Chat or Responses
Proxy pipelineroute model
refresh auth
translate events
Codex ResponsesKimi Chat CompletionsGrok ResponsesOpenCode Chat / Messages / ResponsesCursor Connect

Anthropic requests

Section titled “Anthropic requests”
  1. Claude Code sends an Anthropic Messages request to /v1/messages.
  2. The registry normalizes a trailing [1m], resolves aliases, and selects a provider from the model ID.
  3. The provider loads its proxy-owned credential and refreshes an expiring access token when needed.
  4. The request translator maps system content, user and assistant messages, images, tools, tool results, thinking controls, and output settings into the upstream shape.
  5. The upstream stream is reduced into typed text, thinking, tool, usage, and completion events.
  6. The proxy emits Anthropic SSE events or accumulates a non-streaming Anthropic response.
  7. The monitor, JSONL logger, and optional traffic capture record operational details.

OpenAI-compatible requests

Section titled “OpenAI-compatible requests”

Enable the OpenAI routes to use /v1/chat/completions or /v1/responses. The model field chooses Codex, Kimi, Grok, OpenCode Go, or Cursor in the same way it does on /v1/messages.

Codex Responses requests go directly to the native Codex API. The proxy translates other OpenAI requests to the selected provider and returns either Chat Completions or Responses output. Streaming and non-streaming requests use the same translation rules, and unsupported fields return an error instead of being ignored.

Authentication boundary

Section titled “Authentication boundary”

Each provider login belongs to claude-code-proxy. The proxy does not read native Codex, Grok, or Cursor Agent credentials. Credentials live in the proxy profile files described in Files and storage. OpenCode Go instead uses the configured subscription API key. Incoming ANTHROPIC_AUTH_TOKEN values are accepted for client compatibility and are not used as upstream credentials.

Local setup and container boundary

Section titled “Local setup and container boundary”

The same Rust service embeds the local setup UI. Management uses its own bearer key, loopback Host checks, and same origin requests. The unused token in a Claude Code launch command grants no management access.

Guided sign in runs the existing provider authorization flows in bounded, cancellable workers. Provider tokens are saved to the proxy profile; only authorization instructions and credential status reach the browser. Credential changes exclude active inference and token refresh, including blocking work whose caller has disconnected.

Docker packages those native provider clients with the proxy. The host browser completes sign in and host Claude Code runs tools. The named volume persists credentials, the Kimi device ID, the management key, and model selections. Pending provider conversations and verification results remain in memory and reset on restart.

Routing boundary

Section titled “Routing boundary”

Routing happens per request, not per server process or API surface. Codex IDs, Kimi IDs, Grok IDs, OpenCode Go IDs, Cursor prefixes, and configured Anthropic-style aliases can share one listener across /v1/messages, /v1/chat/completions, and /v1/responses. Unknown model IDs return HTTP 400 with the supported catalog.

Session state

Section titled “Session state”

Claude Code sends x-claude-code-session-id. The proxy uses it for monitor grouping and provider features that need continuity. Cursor conversation IDs, optional Codex previous_response_id, and optional Codex server compaction state live in memory. A proxy restart clears that state and portable Claude Code history remains the fallback.

Count tokens

Section titled “Count tokens”

POST /v1/messages/count_tokens stays local and does not make an upstream request. Codex uses o200k_base for text plus estimates for images, encrypted reasoning, and protocol framing. Other providers use their own local estimators. The result supports Claude Code’s compaction decisions but is not a provider billing count.

See HTTP API for route contracts and Compatibility and limitations for translation boundaries.