ChatGPT & Codex Provider
Relevant source files
The following files were used as context for generating this wiki page:
The ChatGPT & Codex Provider within the shunt gateway enables the diversion of inference requests from Claude Code to the ChatGPT/Codex backend. This system acts as a bridge, allowing users to leverage their existing ChatGPT/Codex subscriptions (such as GPT-5.6 Sol, Terra, or Luna models) while maintaining the toolset and skills native to the Claude Code environment.
The provider is implemented using the responses adapter kind, which translates Anthropic Messages into the OpenAI Responses API format used by the ChatGPT backend. It features a sophisticated transport layer that includes both standard HTTP/SSE and a specialized WebSocket v2 implementation for streaming inference.
Sources: ARCHITECTURE.md:46-51, README.md:14-22, plugins/shunt-codex/README.md:1-12
Architecture and Transport
The Codex provider architecture is built around the Responses adapter but includes a highly specialized WebSocket transport (v2) to handle ChatGPT's backend API. The system manages the lifecycle of a request from translation to streaming delivery.
Transport Mechanisms
The provider utilizes two primary transport methods for interacting with the chatgpt.com/backend-api:
- HTTP/SSE: Used for standard request-response cycles and fallback scenarios.
- WebSocket v2: A stateful transport designed for streaming inference. It handles complex states such as mid-stream HTTP fallbacks and continuation logic.
Sources: ARCHITECTURE.md:73-77, src/adapters/responses/codex_ws.rs:1-20
Request Flow
When a request is routed to the Codex provider, it undergoes protocol translation where Anthropic Messages are converted into the OpenAI Responses format. The codex_ws.rs module then manages the delivery via WebSocket if configured.
The diagram shows the request pipeline from initial receipt to upstream dispatch via either WebSocket or HTTP.
Sources: ARCHITECTURE.md:20-30, src/adapters/responses/codex_ws.rs
Authentication and Account Pooling
The Codex provider utilizes chatgpt_oauth for authentication, allowing the reuse of credentials obtained via codex login.
Credential Management
Shunt manages ChatGPT credentials by reading and auto-refreshing the ~/.codex/auth.json file. The auth/codex module handles the lookup and refresh logic, ensuring that sessions remain valid without manual intervention.
| Component | Description |
|---|---|
codex login | CLI command to authenticate and generate ~/.codex/auth.json. |
chatgpt_oauth | The auth mode used to inject bearer tokens into upstream requests. |
| Account Pooling | Supports multiple accounts with proactive rotation based on 5-hour/7-day usage windows. |
Sources: README.md:82-95, src/auth/codex/mod.rs, plugins/shunt-codex/README.md:46-52
Quota-Aware Selection
The gateway tracks usage headers (x-codex-*) returned by the backend. This data is used for "proactive selection," where the gateway rotates to a different account in a pool before a quota-rejected 429 error occurs.
Sources: README.md:118-128, ARCHITECTURE.md:115-120
Codex WebSocket v2 Implementation
The src/adapters/responses/codex_ws.rs file contains the logic for the stateful WebSocket v2 transport. This is one of the most complex parts of the provider, managing streaming state and connection-level transitions.
Key Logic and Transitions
- Crypto Provider: Installations of the
rustlsdefault provider happen on the first WebSocket handshake viaensure_crypto_provider. - Continuation: The
codex_continuation.rsmodule handles cases where a stream must be resumed or continued across transport boundaries. - Error Handling: On the inbound Codex endpoint, gateway-owned errors are reshaped into the OpenAI Responses error format so that OpenAI-protocol clients can parse them correctly.
Sources: src/adapters/responses/codex_ws.rs:1880-1895, ARCHITECTURE.md:104-106, src/adapters/responses/codex_continuation.rs
Model Mapping and Configuration
Models are mapped to the Codex provider via the shunt.toml configuration. The provider supports several GPT-5.6 tiers.
Supported Models
| Public ID | Native Effort | Upstream ID |
|---|---|---|
gpt-5.6-sol | Low (Fast) | gpt-5.6-sol |
gpt-5.6-terra | Medium | gpt-5.6-terra |
gpt-5.6-luna | Medium | gpt-5.6-luna |
Sources: plugins/shunt-codex/README.md:14-22
Configuration Example
The following snippet demonstrates how to route specific models to the Codex provider:
[[routes]]
model = "gpt-5.6-sol"
provider = "codex"
[[routes]]
model = "gpt-5.6-terra"
provider = "codex"
Sources: plugins/shunt-codex/README.md:54-65
Sequence Diagram: Inference Flow
The sequence shows the interaction between the gateway's internal modules and the external ChatGPT backend during a streaming inference request.
Sources: src/adapters/responses/codex_ws.rs, ARCHITECTURE.md:20-40
Summary
The ChatGPT & Codex Provider is a critical component of shunt that enables high-performance inference through the ChatGPT subscription backend. By combining protocol translation, WebSocket v2 transport, and proactive account/quota management, it provides a seamless experience for Claude Code users wishing to utilize OpenAI's models as subagents or main inference models. Its implementation ensures that streaming remains unbuffered and that error shapes remain compatible with the expected client protocols.
Sources: ARCHITECTURE.md:145-155, README.md:200-210