Codex

Fixture onlyChecked 16 November 2026

In short

  • The exact settings for this tool.
  • Set the base URL and a Petrova key.
  • Caps and receipts work with no extra setup.

Codex CLI talks to Petrova over the OpenAI Responses API (POST /v1/responses). Since February 2026 that is the only wire format Codex supports for custom providers (wire_api = "responses"; "chat" was removed). Petrova translates each request into the Anthropic Messages gateway, so a Codex call gets the same quote -> hold -> settle, caps, loop pause and failover as a Claude Code call, and is paid from the same balance.

Fixture build. Today the gateway answers from in-process fixture upstreams: Codex connects, streams and shows the fixture reply, and the ledger records the call, but no real model is called.

~/.codex/config.toml:

model = "claude-opus-5-5"
model_provider = "petrova"

[model_providers.petrova]
name = "Petrova"
# later: https://api.petrova.sh/v1
base_url = "http://127.0.0.1:4100/v1"
env_key = "PETROVA_API_KEY"
wire_api = "responses"
# Optional: name this agent so its own cap applies (set one with POST /v1/budgets).
http_headers = { "x-petrova-agent-id" = "codex-main" }
# a key with quote:write (npm run sandbox:key -- --spend)
export PETROVA_API_KEY=ptrv_test_...
codex

What Petrova does with a Codex request

  • Caps. The agent is x-petrova-agent-id (or metadata.agent_id, or user); the session is x-petrova-session-id, metadata.session_id, or Codex's own session-id header. Ids must match [A-Za-z0-9_:.-]{1,128}; a malformed one is refused with a 400, never ignored.
  • A crossed cap is a 429 with "type": "insufficient_quota" and x-should-retry: false; Codex treats it as final and stops instead of retrying. An empty balance answers the same way.
  • Loop pause. If the same tool call keeps repeating, Petrova answers 429 (code: "loop_paused", header x-petrova-loop: pause) before paying for it again.
  • Failover. If a supplier fails before the first content, Petrova tries the next one; Codex sees one clean stream ending in response.completed with usage.
  • Receipt. Every answer carries x-petrova-receipt (the reservation id); a stream also ends with an SSE comment : x-petrova-receipt <id> outcome=... charged_nusd=... after response.completed.

Known limits

  • Petrova stores no responses: previous_response_id is refused. Codex sends the full input with store = false, so this does not affect it.
  • Reasoning settings (model_reasoning_effort) are not mapped to extended thinking yet, and reasoning items in the input are dropped.
  • Freeform tools such as apply_patch are passed to Claude as a tool with one string field and the grammar in its description; their calls come back as custom_tool_call items. Hosted tools (web_search) are dropped.
  • With no max_output_tokens (Codex sends none) the hold is sized for 32,000 output tokens; only real usage is charged.
  • Chat Completions clients can use POST /v1/chat/completions with the same key and rules.

Last checked against the code: 16 November 2026. Something wrong? The source of this page is in the repository, so a fix is one edit.