Codex
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(ormetadata.agent_id, oruser); the session isx-petrova-session-id,metadata.session_id, or Codex's ownsession-idheader. Ids must match[A-Za-z0-9_:.-]{1,128}; a malformed one is refused with a 400, never ignored. - A crossed cap is a
429with"type": "insufficient_quota"andx-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", headerx-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.completedwith 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=...afterresponse.completed.
Known limits
- Petrova stores no responses:
previous_response_idis refused. Codex sends the full input withstore = 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_patchare passed to Claude as a tool with one string field and the grammar in its description; their calls come back ascustom_tool_callitems. 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/completionswith 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.