Codex with the Langfuse AI Gateway
Beta. The Langfuse AI Gateway is in public beta and can still change.
Requires Codex CLI 0.157 or later and an OPENAI provider credential. Verified with Codex 0.157.0.
For tracing Codex without the gateway, see the Codex integration.
Setup
Create a gateway API key
Create a gateway API key under Organization settings → AI Gateway → Gateway keys. See API keys.
Export the gateway key
Codex reads the key from this variable when it starts:
export LANGFUSE_GATEWAY_KEY="<your-gateway-key>"The leading space keeps the key out of shell history if your shell ignores commands that start with a space. To keep the setup across sessions, add the export lines to ~/.zshrc.
Add the gateway provider
Add this to ~/.codex/config.toml ($CODEX_HOME/config.toml if you set CODEX_HOME). Put model_provider next to your other top-level keys, before any [table] section, and the [model_providers.langfuse] table after them:
model_provider = "langfuse"
[model_providers.langfuse]
name = "Langfuse AI Gateway"
base_url = "https://gateway.cloud.langfuse.com/openai/v1"
env_key = "LANGFUSE_GATEWAY_KEY" # sent as Authorization: Bearer
wire_api = "responses"To pick a model, add model = "<model-id>" next to model_provider, using an ID from /models. To add tags or other headers, use http_headers. See request headers.
Start Codex
codexEach turn appears in Langfuse as one trace.
Turn grouping
Codex sends its own turn ID, so the gateway groups all model rounds of a turn into one trace named codex, with no extra setup. Each model round is an openai.responses generation, and the session is codex:<thread id>.
- The trace's input and output are copied from the turn's last round.
- Compaction calls appear in the same trace with
agent.request_kind=compaction.
Troubleshooting and FAQ
Codex still uses old credentials after a change
Restart the Codex app-server daemon with codex app-server daemon restart. The daemon can keep using credentials loaded before the change until it restarts.
Why is the input missing on long sessions?
Codex sends store: false and replays the whole conversation on every round. Each generation's input is the full history, so long sessions can exceed the 5 MiB input capture limit, and the input is then dropped. See known limitations.
A model fails with a 400 error
A global model_reasoning_effort makes non-reasoning models fail with a 400. Some small models reject Codex's tool_search tool.
Why does a trace contain several generations for one call?
Codex retries failed requests (request_max_retries, stream_max_retries). Each retry is its own generation in the same trace.
Why do cancelled or failed calls show high cost?
Cancelled or failed Codex calls currently show inflated, estimated usage and cost. Ignore cost on ERROR and WARNING generations until the fix ships.
Can I use websocket features?
No. Keep websocket features off for this provider. The gateway serves HTTP server-sent events only.
Why can't Codex generate images through the gateway?
Codex offers its built-in image_gen tool only when the model provider is OpenAI itself, so it hides the tool for the gateway provider. Codex may then suggest the imagegen skill's CLI fallback instead. Support for custom providers in Codex is tracked in openai/codex#24465.
The imagegen CLI fallback calls OpenAI directly with OPENAI_API_KEY, so
those calls bypass the gateway and are not traced in Langfuse. The gateway
does not serve the OpenAI Images API (/images/generations, /images/edits)
yet either; see supported endpoints.
Last updated on
