Compatibility and limitations

claude-code-proxy targets Claude Code’s practical Anthropic API usage rather than complete protocol equivalence.

Accounts and provider policy

• Provider subscriptions, allowed models, regions, quotas, and enforcement remain under each provider’s control.
• OpenAI has publicly welcomed using Codex through other coding harnesses, but public statements do not guarantee future policy or account treatment.
• Kimi, Grok, and Cursor use unofficial client integrations. Review the terms and account risk for your use.
• Upstream rate limits are shared with other clients on the same account.

Listener security

• Inference clients are not authenticated. Local setup management requires its separate bearer key and local origin checks.
• The default bind address is 127.0.0.1.
• A non-loopback listener requires an external firewall or authenticating reverse proxy.
• The proxy stores subscription credentials and can consume account quota, so an exposed listener is equivalent to exposing that capability.

Local setup and Docker

• The UI is for one user on one local machine. Compose publishes only to host loopback.
• Guided login uses the proxy’s provider clients and its own credentials; native application logins are not imported.
• A registered model or saved login does not establish inference access. Verification sends a short request and consumes provider quota.
• Environment supplied credentials take precedence and must be changed in the server environment.
• Credential changes return HTTP 409 while provider inference or refresh work is active. Blocking refresh work can outlive a disconnected caller and retains its protection until it finishes.
• The private named volume survives container replacement. Pending conversations and verification results reset on restart.
• Updates replace the application image. Runtime self updates are unsupported.
• Lifecycle fixtures verify refresh, cancellation, and persistence across recreation and a distinct image of the same application version. Live account authorization and future schema migrations require their own checks.

Anthropic API scope

• Messages supports streaming and non-streaming responses for the fields exercised by Claude Code.
• ?beta=true does not select a separate implementation.
• 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 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

• CCP_CODEX_RESPONSES_API=1 enables /v1/chat/completions and /v1/responses for Codex, Kimi, Grok, OpenCode Go, and Cursor models.
• Codex Responses requests use native passthrough. Requests for the other providers support their mapped subsets of text, reasoning, function tools, tool results, token limits, usage, streaming, aliases, and [1m] model hints; exact support depends on the selected provider and model.
• 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 in Chat or Responses requests, log probabilities, and arbitrary hosted tools are unsupported.
• A separately enabled Codex transcription route accepts bounded multipart audio and returns text JSON. It does not support streaming, timestamp formats, or model selection. See HTTP API.

Models and context

• Local registration does not guarantee account access to a model.
• Unknown model IDs have no implicit provider fallback.
• Anthropic-style aliases route only to the configured Codex or Kimi alias provider.
• [1m] is a Claude Code client hint and does not change upstream context.
• Provider context limits can be lower than Claude Code’s local threshold.
• Switching provider or model can clear provider-specific continuation assumptions while Claude Code retains portable history.

Codex

• Base64 user images and supported base64 tool-result images map to Responses images. Remote URLs and malformed or unsupported nested images remain text placeholders.
• Reasoning summaries can appear as thinking blocks. Codex decides whether a summary is emitted.
• Encrypted reasoning and compaction items remain provider continuation data and are not exposed as raw chain of thought.
• Hosted web search supports mapped domain filters, but the Anthropic max_uses value is not enforced because Codex exposes no equivalent limit.
• Strict JSON schema output is translated. Other Anthropic-only output settings can be omitted.
• previous_response_id and server compaction state are in memory and require stable session routing.
• Automatic transport fallback occurs only before an upstream request is sent, which avoids replaying possible side effects.

Kimi

• The proxy exposes one Kimi Code wire model plus local aliases.
• Reasoning effort supports Kimi’s low, medium, and high levels.
• Images in tool results use Kimi tool-message image parts.
• The persistent device ID is part of the login identity and must remain stable.

Grok

• Model availability varies by account and region.
• Hosted general web search and X search are translated with citations and usage.
• Hosted web search omits max_uses because the Grok CLI endpoint exposes no equivalent cap. Non-null domain filters and user location are rejected because dropping them would weaken the caller’s requested search scope.
• The implemented multimodal path does not claim general image or video compatibility.

Cursor Agent

• The native Rust provider speaks Cursor’s protocol directly; no JavaScript bundle is loaded for inference or model discovery.
• The dynamic catalog reflects the proxy’s authenticated Cursor account. Advertised parameter combinations come from Cursor’s metadata, and account aliases bound which families are exposed.
• Cursor choices use readable claude-cursor:<id> names in HTTP discovery, preserving exact model and parameter selections. Corresponding raw cursor:<id> requests remain valid.
• The native tool bridge covers recognized Read, Write, and Bash calls when matching tools and a session ID are present.
• Cursor workspace callbacks and arbitrary native tool forms do not have a general Claude tool bridge.
• Pending tool state is in memory. Restarts clear it, and changes to model, parameters, mode, credential, or endpoint start a new run using Claude Code’s history.
• Cursor count-tokens uses a rough rendered-prompt estimate.

Diagnostics and privacy

• Structured logs redact known credential keys, but user-provided strings can still contain secrets.
• Error captures contain complete redacted failed responses.
• Traffic captures intentionally preserve prompts and tool content for message/Responses diagnostics.
• Image generation and edit routes never create traffic captures or persist prompts, uploads, data URLs, generated base64, or upstream error bodies.
• Verbose logging and traffic capture should be scoped to a focused local investigation.

For provider-specific behavior, use the provider pages. For historical upstream releases, see the Changelog.