Use Claude Code with your ChatGPT, Kimi, Cursor or Grok subscription via a local Anthropic-compatible proxy
Rust
docs: describe model-routed OpenAI APIs
Raine Virta123f8c095aeb
diff --git a/docs/src/content/docs/how-it-works.md b/docs/src/content/docs/how-it-works.mdindex 9b3375e..9cb90ba 100644--- a/docs/src/content/docs/how-it-works.md+++ b/docs/src/content/docs/how-it-works.md@@ -3,10 +3,10 @@ title: How it worksdescription: Follow authentication, routing, protocol translation, streaming, session state, and diagnostics through claude-code-proxy.----claude-code-proxy exposes an Anthropic-compatible HTTP surface to Claude Code and translates each request into the selected provider's native protocol.+claude-code-proxy exposes Anthropic Messages and optional OpenAI-compatible creation APIs. Every route selects a provider from the request model and translates through that provider's native protocol.<div class="route-rail" aria-label="claude-code-proxy request architecture">- <div class="route-node"><strong>Claude Code</strong><span>POST /v1/messages<br/>Anthropic SSE</span></div>+ <div class="route-node"><strong>API client</strong><span>Anthropic Messages<br/>OpenAI Chat or Responses</span></div><div class="route-arrow" aria-hidden="true">→</div><div class="route-node"><strong>Proxy pipeline</strong><span>route model<br/>refresh auth<br/>translate events</span></div><div class="route-arrow" aria-hidden="true">→</div>@@ -23,13 +23,21 @@ claude-code-proxy exposes an Anthropic-compatible HTTP surface to Claude Code an6. 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 lifecycle++`POST /v1/chat/completions` and `POST /v1/responses` use the same model registry as Anthropic Messages. Codex retains dedicated paths: Responses requests pass through natively, while Chat Completions uses the Codex compatibility translator.++Kimi, Grok, and Cursor requests pass through a strict OpenAI ingress adapter into an Anthropic Messages request. The selected provider returns typed buffered or live Anthropic SSE. One egress adapter decodes those events into the requested OpenAI surface, which keeps buffered and streaming text, reasoning, tools, usage, citations, completion status, and errors aligned.++This shared intermediate stream avoids decoding an already-built HTTP response. It also gives monitoring and traffic capture named stages for the OpenAI request, translated request, provider traffic, intermediate events, and downstream output.+## Authentication boundaryEach provider login belongs to claude-code-proxy. The proxy does not read native Codex, Grok, or Cursor Agent credentials. Credentials live in the platform credential store described in [Files and storage](/reference/files-and-storage/). Incoming `ANTHROPIC_AUTH_TOKEN` values are accepted for client compatibility and are not used as upstream credentials.## Routing boundary-Routing happens per request, not per server process. Codex IDs, Kimi IDs, Grok IDs, Cursor prefixes, and configured Anthropic-style aliases can share one listener. Unknown model IDs return HTTP 400 with the supported catalog.+Routing happens per request, not per server process or API surface. Codex IDs, Kimi IDs, Grok 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 statediff --git a/docs/src/content/docs/providers/codex.md b/docs/src/content/docs/providers/codex.mdindex 9862c53..c14ad89 100644--- a/docs/src/content/docs/providers/codex.md+++ b/docs/src/content/docs/providers/codex.md@@ -100,7 +100,7 @@ While the native request is active, the monitor shows `compacting`. Structured l## OpenAI-compatible APIs-`CCP_CODEX_RESPONSES_API=1` enables both `POST /v1/responses` and `POST /v1/chat/completions`.+`CCP_CODEX_RESPONSES_API=1` enables both `POST /v1/responses` and `POST /v1/chat/completions`. The route gate lives under Codex configuration, while model routing on both endpoints also supports Kimi, Grok, and Cursor Agent.The Responses route preserves native JSON or SSE response bodies for registered Codex models. The Chat Completions route translates standard text messages, reasoning effort, JSON object or JSON Schema output, and buffered or streaming responses. Its omitted reasoning effort defaults to `medium`; the proxy-wide Codex effort override still takes precedence.diff --git a/docs/src/content/docs/providers/cursor-agent.md b/docs/src/content/docs/providers/cursor-agent.mdindex 0db5061..3e9b67c 100644--- a/docs/src/content/docs/providers/cursor-agent.md+++ b/docs/src/content/docs/providers/cursor-agent.md@@ -50,6 +50,10 @@ Claude Code's `/effort` selects matching Cursor catalog variants when available.- The native tool bridge recognizes Cursor requests for `Read`, `Write`, and `Bash` when matching Claude tools are advertised and a Claude Code session ID is present. It pauses the stream, emits an Anthropic tool call, accepts the next tool result, and resumes stored events.- Other Cursor workspace callbacks and native tool forms do not have a general Claude tool bridge.+## OpenAI-compatible APIs++When the OpenAI routes are enabled, Cursor model IDs and prefixes work on both `POST /v1/chat/completions` and `POST /v1/responses`. The shared adapter maps OpenAI input into Cursor's prompt and selected-image protocol, then converts Cursor events into buffered or streaming OpenAI output. The `Read`, `Write`, and `Bash` bridge requires `stream: true`, matching function definitions, and a stable `x-claude-code-session-id`, `session_id`, or `x-client-request-id` header. Other function names are rejected when tool bridging is requested.+## Session continuationThe proxy maps `x-claude-code-session-id` to a Cursor conversation ID in memory. Request metadata can resume a known Cursor chat through `cursor_chat_id`, `cursorChatId`, `cursor_resume`, or `cursorResume`. A proxy restart clears the in-memory mapping.diff --git a/docs/src/content/docs/providers/grok.md b/docs/src/content/docs/providers/grok.mdindex d634db8..8d2caaa 100644--- a/docs/src/content/docs/providers/grok.md+++ b/docs/src/content/docs/providers/grok.md@@ -42,6 +42,10 @@ Claude Code hosted search tools map to Grok-native tools:- X queries use hosted `x_search`.- Citations and search usage return in Anthropic-compatible content and usage fields.+## OpenAI-compatible APIs++When the OpenAI routes are enabled, Grok model IDs work on both `POST /v1/chat/completions` and `POST /v1/responses`. Grok retains live upstream streaming through the shared adapter. Text, reasoning, function tools, tool calls, tool results, token limits, usage, and errors map to the selected OpenAI surface. Responses output includes native `web_search_call` items and flat URL citation annotations. Chat Completions output includes citation annotations without a hosted-search output item.+## Multimodal support`CCP_GROK_TOOL_IMAGE` controls image blocks in user messages and tool results:diff --git a/docs/src/content/docs/providers/kimi.md b/docs/src/content/docs/providers/kimi.mdindex 536955f..5119300 100644--- a/docs/src/content/docs/providers/kimi.md+++ b/docs/src/content/docs/providers/kimi.md@@ -37,6 +37,10 @@ Claude Code's `/effort` setting maps to Kimi `reasoning_effort` at `low`, `mediu- Images inside tool results map to `image_url` parts in tool messages.- Supported video input maps to Kimi video content.+## OpenAI-compatible APIs++When the OpenAI routes are enabled, Kimi model IDs work on both `POST /v1/chat/completions` and `POST /v1/responses`. The proxy validates the OpenAI request, translates it to Kimi's native Chat Completions protocol, and maps the buffered provider stream into buffered or streaming OpenAI output. Text, supported images, reasoning effort, function tools, tool calls, tool results, token limits, and usage are supported within the shared adapter's documented field subset.+## Configuration`CCP_KIMI_BASE_URL`, `CCP_KIMI_OAUTH_HOST`, and `CCP_KIMI_USER_AGENT` provide explicit endpoint and client overrides. `CCP_USER_AGENT` is the fallback user-agent override. These settings are intended for compatibility and controlled debugging. See [Configuration](/reference/configuration/) for defaults and file keys.diff --git a/docs/src/content/docs/reference/compatibility-and-limitations.md b/docs/src/content/docs/reference/compatibility-and-limitations.mdindex 9267f6e..bb1dab4 100644--- a/docs/src/content/docs/reference/compatibility-and-limitations.md+++ b/docs/src/content/docs/reference/compatibility-and-limitations.md@@ -26,9 +26,19 @@ claude-code-proxy targets Claude Code's practical Anthropic API usage rather tha- Token counts are local estimates, not exact upstream tokenizer or billing counts.- Claude Code title generation and other structured background requests are forwarded and consume provider tokens.- Anthropic-specific fields without a provider mapping can be dropped.-- Native OpenAI Responses passthrough is opt-in and limited to registered Codex models and response creation.+- Native OpenAI Responses passthrough is opt-in and applies to registered Codex models.- Codex Images passthrough is separately opt-in, restricted to `gpt-image-2`, and supports generation plus JSON or multipart edits. Variations, masks, remote image URLs, and URL-formatted outputs are unsupported.+## OpenAI API scope++- `/v1/chat/completions` and `/v1/responses` are enabled together by the Codex Responses API setting, but route Codex, Kimi, Grok, and Cursor models.+- Codex Responses requests preserve the provider's native Responses payload. Other providers use the shared strict compatibility adapter.+- The shared adapter rejects unsupported non-null request fields instead of silently discarding them.+- Chat Completions and Responses support streaming and buffered output, usage, reasoning, function tools, tool results, provider errors, aliases, and `[1m]` normalization within the documented field subset.+- Grok hosted search has a native Responses representation. Chat Completions exposes returned citations but has no standard hosted-search output item.+- Cursor OpenAI tool bridging is limited to `Read`, `Write`, and `Bash`, and requires streaming plus stable session identity.+- Stored Responses operations, WebSocket ingress, multiple choices, audio, log probabilities, and arbitrary hosted tools are unsupported.+## Models and context- Local registration does not guarantee account access to a model.diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.mdindex c5ccc1d..6d21df5 100644--- a/docs/src/content/docs/reference/configuration.md+++ b/docs/src/content/docs/reference/configuration.md@@ -106,7 +106,7 @@ Proxy URLs may use `http`, `https`, `socks4`, `socks4a`, `socks5`, or `socks5h`.| `CCP_CODEX_TRANSPORT` | `codex.transport` | `websocket` | Selects `websocket`, `http`, or `auto`. || `CCP_CODEX_PREVIOUS_RESPONSE_ID` | `codex.previousResponseId` | `false` | Enables append-only WebSocket continuation for `1`, `true`, or `yes`. || `CCP_CODEX_SERVER_COMPACTION` | `codex.serverCompaction` | `false` | Enables or disables native compaction for standard boolean words. |-| `CCP_CODEX_RESPONSES_API` | `codex.responsesApi` | `false` | Enables `/v1/responses` and `/v1/chat/completions` for `1`, `true`, or `yes`. |+| `CCP_CODEX_RESPONSES_API` | `codex.responsesApi` | `false` | Enables model-routed `/v1/responses` and `/v1/chat/completions` for `1`, `true`, or `yes`. The routes support every registered provider. || `CCP_CODEX_IMAGES_API` | `codex.imagesApi` | `false` | Enables `/v1/images/generations` and `/v1/images/edits` for `1`, `true`, or `yes`. || `CCP_CODEX_IMAGES_BASE_URL` | `codex.imagesBaseUrl` | `https://chatgpt.com/backend-api/codex` | Sets the trusted Codex Images API root; production use is restricted to HTTPS `chatgpt.com/backend-api/codex`. || `CCP_CODEX_ORIGINATOR` | `codex.originator` | `claude-code-proxy` | Changes the Codex `originator` header. |diff --git a/docs/src/content/docs/reference/http-api.md b/docs/src/content/docs/reference/http-api.mdindex aebd405..4f50926 100644--- a/docs/src/content/docs/reference/http-api.md+++ b/docs/src/content/docs/reference/http-api.md@@ -1,6 +1,6 @@---title: HTTP API-description: Canonical local HTTP routes for liveness, Anthropic Messages, token counting, model discovery, and optional Codex-backed OpenAI APIs.+description: Canonical local HTTP routes for liveness, Anthropic Messages, token counting, model discovery, routed OpenAI APIs, and Codex images.---The server speaks the Anthropic and OpenAI protocol subsets needed by Claude Code and Codex-backed OpenAI-compatible clients.@@ -64,23 +64,32 @@ Claude Code gateway discovery filters IDs according to its own model rules. See## `POST /v1/chat/completions`-This route exists only when `CCP_CODEX_RESPONSES_API=1` or `codex.responsesApi` is true. It translates OpenAI Chat Completions requests into Codex Responses Lite requests. Incoming bearer credentials are accepted and replaced with the proxy's stored Codex authentication.+This route exists when `CCP_CODEX_RESPONSES_API=1` or `codex.responsesApi` is true. Despite the setting name, the request `model` can select Codex, Kimi, Grok, or Cursor Agent. Incoming bearer credentials are accepted for client compatibility and replaced with the selected provider's proxy-owned authentication.-The compatibility surface supports:+Codex keeps its dedicated Chat Completions translator and supports:- text messages with `system`, `developer`, `user`, and `assistant` roles- streaming and buffered responses- `reasoning_effort` values `none`, `low`, `medium`, `high`, `xhigh`, and `max`- `response_format` values `text`, `json_object`, and strict `json_schema`- `stream_options.include_usage`-- `temperature` and `top_p` on Codex models that use the full Responses lane+- `temperature` and `top_p` on models that use the full Responses lane- `user` as a Responses safety identifier-Omitted reasoning effort defaults to `medium`. `CCP_CODEX_EFFORT` or `codex.effort` takes precedence over the request. Every translated request uses `store: false`, upstream streaming, and `reasoning.context: "all_turns"`.+Omitted Codex reasoning effort defaults to `medium`. `CCP_CODEX_EFFORT` or `codex.effort` takes precedence over the request. Every translated Codex request uses `store: false`, upstream streaming, and `reasoning.context: "all_turns"`.-A buffered response uses the standard `chat.completion` object. A streaming response emits `chat.completion.chunk` events and ends with `data: [DONE]`.+Kimi, Grok, and Cursor use the shared OpenAI compatibility adapter. It supports:-Function calls, hosted tools, images, audio, log probabilities, multiple choices, storage, and output token limits are outside this compatibility surface. Unsupported fields, including `max_tokens` and `max_completion_tokens`, return an OpenAI `invalid_request_error` with the field in `error.param`.+- `system`, `developer`, `user`, `assistant`, and `tool` messages+- text, supported user images, assistant function calls, and tool results+- function tools and named, automatic, required, or disabled tool choice+- `max_tokens` or `max_completion_tokens`+- `reasoning_effort`+- streaming, buffered responses, and `stream_options.include_usage`++A buffered response uses the standard `chat.completion` object. A streaming response emits `chat.completion.chunk` events and ends with `data: [DONE]`. Tool-call indexes are contiguous even when provider reasoning or text blocks precede them. Grok citations appear as Chat Completions annotations.++The adapter validates each provider's capabilities before making an upstream request. Unsupported non-null fields return an OpenAI `invalid_request_error` with `error.code` set to `unsupported_parameter` and the field in `error.param`. Supported fields differ between the dedicated Codex translator and the shared provider adapter. Cursor's `Read`, `Write`, and `Bash` tool bridge requires `stream: true` and a stable session header.## `POST /v1/images/generations`@@ -111,17 +120,33 @@ The Images API is an internal ChatGPT Codex integration, not the public OpenAI P## `POST /v1/responses`-This route exists only when `CCP_CODEX_RESPONSES_API=1` or `codex.responsesApi` is true. It accepts a native OpenAI Responses request for a registered Codex model.+This route exists when `CCP_CODEX_RESPONSES_API=1` or `codex.responsesApi` is true. The request `model` selects Codex, Kimi, Grok, or Cursor Agent through the same registry used by `/v1/messages` and `/v1/chat/completions`.++Registered Codex models use native Responses passthrough. The proxy validates the Codex model, replaces incoming auth with proxy-owned ChatGPT Codex auth, refreshes rejected access tokens, and preserves native JSON responses and SSE bodies.++Kimi, Grok, and Cursor use the shared OpenAI compatibility adapter. It accepts:++- string input or message input items+- `instructions`+- function calls and function-call outputs+- function tools and tool choice+- `max_output_tokens`+- `reasoning.effort`+- streaming or buffered output++The adapter maps provider text, reasoning, function calls, usage, finish status, and errors into Responses objects and lifecycle events. Grok hosted search emits `web_search_call` output items, and Grok citations use Responses URL citation annotations. Responses echo the accepted tool list and tool choice. A provider `max_tokens` stop produces an incomplete response with reason `max_output_tokens`.++`store: true` and unsupported non-null fields are rejected rather than ignored. Stored response retrieval or deletion and WebSocket client ingress are not implemented.++## OpenAI routing, sessions, and errors++Both OpenAI creation routes normalize a trailing `[1m]`, resolve configured model aliases, and select the provider from the model ID. Unknown IDs return HTTP 400 with the supported catalog. Aliases follow `aliasProvider`, while explicit provider IDs keep their provider.-The proxy:+The first non-empty `x-claude-code-session-id`, `session_id`, or `x-client-request-id` header supplies session identity. Stable session identity is required for Cursor tool bridging and supports provider affinity where applicable. Shared OpenAI request validation completes before session state changes.-- validates the model against the Codex catalog-- replaces incoming auth with proxy-owned ChatGPT Codex auth-- refreshes rejected access tokens before forwarding a response-- preserves native JSON responses and SSE bodies-- records the request in the monitor and optional traffic capture+Authentication, permission, rate-limit, invalid-request, and provider API failures use OpenAI error envelopes. Rate-limit responses preserve `Retry-After`. Malformed provider streams and provider response-size violations return gateway errors rather than blaming the client.-It does not implement stored response retrieval or deletion, image variations, or WebSocket client ingress.+The monitor and structured logs record the selected provider and resolved model. Optional traffic capture records the OpenAI request, translated Anthropic request, provider request and response where available, intermediate Anthropic SSE, and bounded downstream OpenAI output. Traffic artifacts preserve prompts and tool content.## Other routesdiff --git a/docs/src/content/docs/using/models-and-routing.md b/docs/src/content/docs/using/models-and-routing.mdindex ead16dd..bff6b47 100644--- a/docs/src/content/docs/using/models-and-routing.md+++ b/docs/src/content/docs/using/models-and-routing.md@@ -3,7 +3,7 @@ title: Models and routingdescription: Understand provider model patterns, aliases, Codex fast mode, context hints, small models, model listing, and Claude Code gateway discovery.----The model ID in each request selects its provider. One proxy listener can serve every provider.+The model ID in each request selects its provider. One proxy listener can serve every provider through Anthropic Messages and the enabled OpenAI-compatible routes.## Routing patterns