Use Claude Code with your ChatGPT, Kimi, Cursor or Grok subscription via a local Anthropic-compatible proxy
Rust
docs: simplify OpenAI routing guidance
Raine Virta5ca5596e5495
diff --git a/docs/src/content/docs/how-it-works.md b/docs/src/content/docs/how-it-works.mdindex 9cb90ba..1bb537e 100644--- a/docs/src/content/docs/how-it-works.md+++ b/docs/src/content/docs/how-it-works.md@@ -3,7 +3,7 @@ title: How it worksdescription: Follow authentication, routing, protocol translation, streaming, session state, and diagnostics through claude-code-proxy.----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.+claude-code-proxy exposes Anthropic Messages and optional OpenAI-compatible routes. 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>API client</strong><span>Anthropic Messages<br/>OpenAI Chat or Responses</span></div>@@ -13,7 +13,7 @@ claude-code-proxy exposes Anthropic Messages and optional OpenAI-compatible crea<div class="route-node provider-stack"><code>Codex Responses</code><code>Kimi Chat Completions</code><code>Grok Responses</code><code>Cursor Connect</code></div></div>-## Request lifecycle+## Anthropic requests1. 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.@@ -23,13 +23,11 @@ claude-code-proxy exposes Anthropic Messages and optional OpenAI-compatible crea6. 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+## OpenAI-compatible requests-`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.+Enable the OpenAI routes to use `/v1/chat/completions` or `/v1/responses`. The `model` field chooses Codex, Kimi, Grok, or Cursor in the same way it does on `/v1/messages`.-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.+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 boundarydiff --git a/docs/src/content/docs/providers/codex.md b/docs/src/content/docs/providers/codex.mdindex c14ad89..0541c0c 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`. The route gate lives under Codex configuration, while model routing on both endpoints also supports Kimi, Grok, and Cursor Agent.+`CCP_CODEX_RESPONSES_API=1` enables both `POST /v1/responses` and `POST /v1/chat/completions`. The setting is under Codex configuration, but the routes also accept Kimi, Grok, and Cursor models.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 3e9b67c..a44c2fa 100644--- a/docs/src/content/docs/providers/cursor-agent.md+++ b/docs/src/content/docs/providers/cursor-agent.md@@ -52,7 +52,7 @@ Claude Code's `/effort` selects matching Cursor catalog variants when available.## 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.+When the OpenAI routes are enabled, Cursor models work with both `POST /v1/chat/completions` and `POST /v1/responses`. To use the `Read`, `Write`, or `Bash` tool bridge, send `stream: true`, define the matching function tools, and include a stable session header. The proxy accepts `x-claude-code-session-id`, `session_id`, or `x-client-request-id`. Other function names are not supported by the Cursor bridge.## Session continuationdiff --git a/docs/src/content/docs/providers/grok.md b/docs/src/content/docs/providers/grok.mdindex 8d2caaa..8d703d0 100644--- a/docs/src/content/docs/providers/grok.md+++ b/docs/src/content/docs/providers/grok.md@@ -44,7 +44,7 @@ Claude Code hosted search tools map to Grok-native tools:## 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.+When the OpenAI routes are enabled, Grok models work with both `POST /v1/chat/completions` and `POST /v1/responses`. Text, reasoning, function tools, tool results, token limits, streaming, usage, and errors use the standard shape for the chosen route. Responses requests also return Grok searches as `web_search_call` items. Citations are available on both routes.## Multimodal supportdiff --git a/docs/src/content/docs/providers/kimi.md b/docs/src/content/docs/providers/kimi.mdindex 5119300..4baf50c 100644--- a/docs/src/content/docs/providers/kimi.md+++ b/docs/src/content/docs/providers/kimi.md@@ -39,7 +39,7 @@ Claude Code's `/effort` setting maps to Kimi `reasoning_effort` at `low`, `mediu## 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.+When the OpenAI routes are enabled, Kimi models work with both `POST /v1/chat/completions` and `POST /v1/responses`. You can use text, supported images, reasoning effort, function tools, tool results, token limits, streaming, and usage reporting. See [HTTP API](/reference/http-api/) for the accepted request fields.## Configurationdiff --git a/docs/src/content/docs/reference/compatibility-and-limitations.md b/docs/src/content/docs/reference/compatibility-and-limitations.mdindex bb1dab4..bd39757 100644--- a/docs/src/content/docs/reference/compatibility-and-limitations.md+++ b/docs/src/content/docs/reference/compatibility-and-limitations.md@@ -31,12 +31,11 @@ claude-code-proxy targets Claude Code's practical Anthropic API usage rather tha## 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.+- `CCP_CODEX_RESPONSES_API=1` enables `/v1/chat/completions` and `/v1/responses` for Codex, Kimi, Grok, and Cursor models.+- Codex Responses requests use native passthrough. Requests for the other providers support text, reasoning, function tools, tool results, token limits, usage, streaming, aliases, and `[1m]` model hints.+- Unsupported non-null request fields return an error instead of being ignored.+- Grok search calls appear as Responses `web_search_call` items. Chat Completions returns the citations without a separate search item.+- Cursor tool bridging supports `Read`, `Write`, and `Bash`. It requires streaming and a stable session ID.- Stored Responses operations, WebSocket ingress, multiple choices, audio, log probabilities, and arbitrary hosted tools are unsupported.## Models and contextdiff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.mdindex 6d21df5..90c2161 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 model-routed `/v1/responses` and `/v1/chat/completions` for `1`, `true`, or `yes`. The routes support every registered provider. |+| `CCP_CODEX_RESPONSES_API` | `codex.responsesApi` | `false` | Enables `/v1/responses` and `/v1/chat/completions` for every registered provider. Accepts `1`, `true`, or `yes`. || `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 4f50926..489cbce 100644--- a/docs/src/content/docs/reference/http-api.md+++ b/docs/src/content/docs/reference/http-api.md@@ -1,9 +1,9 @@---title: HTTP API-description: Canonical local HTTP routes for liveness, Anthropic Messages, token counting, model discovery, routed OpenAI APIs, and Codex images.+description: Local routes for health checks, Anthropic Messages, token counts, model discovery, OpenAI-compatible requests, and Codex images.----The server speaks the Anthropic and OpenAI protocol subsets needed by Claude Code and Codex-backed OpenAI-compatible clients.+The server exposes the Anthropic and OpenAI routes supported by the proxy. Each route uses the stored login for the model's provider.<div class="security-callout"><strong>No client authentication.</strong> The listener accepts requests without validating `Authorization` or `x-api-key`. Loopback is the default. Protect every non-loopback listener with a firewall or authenticating reverse proxy.@@ -64,32 +64,28 @@ Claude Code gateway discovery filters IDs according to its own model rules. See## `POST /v1/chat/completions`-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.+Enable this route with `CCP_CODEX_RESPONSES_API=1` or `codex.responsesApi: true`. The `model` field selects Codex, Kimi, Grok, or Cursor. The proxy ignores incoming bearer credentials and uses the stored login for that provider.-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 models that use the full Responses lane-- `user` as a Responses safety identifier--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"`.+```sh+curl http://127.0.0.1:18765/v1/chat/completions \+ -H 'Content-Type: application/json' \+ -d '{"model":"kimi-k2.6","messages":[{"role":"user","content":"Hello"}]}'+```-Kimi, Grok, and Cursor use the shared OpenAI compatibility adapter. It supports:+For Kimi, Grok, and Cursor, the route accepts:- `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+- text, supported user images, function calls, and tool results+- function tools and `tool_choice`- `max_tokens` or `max_completion_tokens`- `reasoning_effort`-- streaming, buffered responses, and `stream_options.include_usage`+- streaming, non-streaming responses, and `stream_options.include_usage`++Codex uses its own compatibility path. It supports text messages, `reasoning_effort`, `response_format`, `stream_options.include_usage`, `temperature`, `top_p`, and `user`. Reasoning effort defaults to `medium`, and the proxy-wide Codex effort setting takes precedence. Function calls, images, audio, log probabilities, multiple choices, storage, and output token limits are not supported on the Codex Chat Completions path.-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.+Non-streaming requests return a `chat.completion` object. Streaming requests return `chat.completion.chunk` events followed by `data: [DONE]`. Grok citations are included in message 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.+Unsupported non-null fields return `invalid_request_error` with the field named in `error.param`. Cursor tools are limited to `Read`, `Write`, and `Bash`. They require `stream: true` and a stable session header.## `POST /v1/images/generations`@@ -120,33 +116,42 @@ The Images API is an internal ChatGPT Codex integration, not the public OpenAI P## `POST /v1/responses`-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`.+Enable this route with `CCP_CODEX_RESPONSES_API=1` or `codex.responsesApi: true`. The `model` field selects Codex, Kimi, Grok, or Cursor.-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.+```sh+curl http://127.0.0.1:18765/v1/responses \+ -H 'Content-Type: application/json' \+ -d '{"model":"grok-4.5","input":"Hello"}'+```-Kimi, Grok, and Cursor use the shared OpenAI compatibility adapter. It accepts:+Codex models use native Responses passthrough, including native JSON and SSE output. For Kimi, Grok, and Cursor, the route accepts:-- string input or message input items+- string input or message items- `instructions`-- function calls and function-call outputs-- function tools and tool choice+- function calls, function-call outputs, tools, and `tool_choice`- `max_output_tokens`- `reasoning.effort`-- streaming or buffered output+- streaming or non-streaming 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`.+Responses include the accepted tool settings. Grok search appears as a `web_search_call`, with sources in URL citation annotations. When a provider reaches its output token limit, the response status is `incomplete` and the reason is `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.+`store: true` and other unsupported non-null fields return an error. Stored response retrieval, deletion, and WebSocket client connections are not supported.## 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.+Both OpenAI routes strip a trailing `[1m]`, resolve configured aliases, and choose the provider from `model`. Aliases follow `aliasProvider`, while explicit provider model IDs keep their provider. Unknown models return HTTP 400 with the supported model list.++For requests that need a stable session, set one of these headers:++- `x-claude-code-session-id`+- `session_id`+- `x-client-request-id`-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.+The proxy uses the first non-empty value. Cursor tool calls require a stable session. Session affinity also applies to providers that support it.-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.+Authentication, permission, rate-limit, invalid-request, and provider failures use the OpenAI error format. Rate-limit responses keep the provider's `Retry-After` header. Malformed or oversized provider streams return a gateway error.-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.+The monitor and logs show the selected provider and model. Traffic capture records request and response data for debugging, including prompts and tool content, so treat the capture directory as sensitive.## Other routes