CLI integration · Windows · macOS · Linux

Connect Codex to Observagent.

Use Codex's built-in OpenTelemetry exporter to send runtime logs while keeping raw user prompt content redacted.

Codex CLIRuntime events

OTLP over HTTPSBuilt-in exporter

ObservagentLogs + metrics + traces

How it works

Use Codex's built-in OpenTelemetry export

Codex can export runtime telemetry through its built-in OpenTelemetry integration. Observagent receives logs, metrics, and traces over OTLP/HTTP; no Python SDK or local proxy is required. Export begins only after you configure the exporters and restart Codex.

This guide follows the official OpenAI telemetry documentation and configuration reference. Event availability and fields can change with the installed Codex version.

When you create or configure the Observagent project, set its AI usage source to **User subscription** for Codex using ChatGPT authentication, **Provider API billing** for provider API billing, or **Unknown or mixed** when the project intentionally receives both. Observagent attaches this project default during ingestion; it does not collect billing credentials.

Only mixed-channel applications need an event override. An instrumented application that mixes billing channels in one project may emit ai.usage.channel as api, subscription, local, or unknown. A valid event value overrides the project default. Prefer separate projects and keys when practical; ordinary Codex setup requires no extra telemetry step.

Before you begin

Minimum required plan

ChatGPT Plus (subscription route for OpenAI-hosted Codex CLI).

Plus is the lowest listed subscription with CLI access. Free and Go desktop access does not include the same CLI entitlement.
Alternatively, use an OpenAI API key with billing enabled without a ChatGPT subscription. Managed workspaces must permit Codex.

Observagent accessPrepare an Observagent project with monitoring and the required signals enabled, plus a valid project key with telemetry:write permission.

Requirements reviewed on October 13, 2026.

Select OS

Integration steps

Select a platform to see commands and paths for your computer. Project setup and delivery verification are shared across platforms.

WindowsPowerShell

1
Step 1
Check Codex and open its configuration
Confirm Codex is installed, back up the active config file, and open it in a text editor.
- Edit the config file used by this Codex installation and user account. Remote, WSL, and container sessions can use a different home directory.
- The backup gives you a quick recovery path if existing TOML settings conflict.
PowerShell
```
codex --version
$config = Join-Path $HOME ".codex\config.toml"
New-Item -ItemType Directory -Force (Split-Path $config) | Out-Null
if (Test-Path $config) { Copy-Item $config "$config.backup" }
notepad $config
```

Step 2

Add the OTLP exporters

Merge these values into the existing [otel] table, configure all three signals, and keep raw user prompt content redacted.

Replace YOUR_OBSERVAGENT_PROJECT_KEY in all three exporters with the complete telemetry-write key for the intended project.
Keep one [otel] table. Merge values instead of creating a duplicate heading.
The current Codex configuration uses the inline exporter = { otlp-http = { ... }} form.

PowerShell

[otel]
environment = "production"
log_user_prompt = false
exporter = { otlp-http = {
  endpoint = "https://dashboard.observagent.cloud/v1/logs",
  protocol = "binary",
  headers = { Authorization = "Bearer YOUR_OBSERVAGENT_PROJECT_KEY" }
}}
metrics_exporter = { otlp-http = {
  endpoint = "https://dashboard.observagent.cloud/v1/metrics",
  protocol = "binary",
  headers = { Authorization = "Bearer YOUR_OBSERVAGENT_PROJECT_KEY" }
}}
trace_exporter = { otlp-http = {
  endpoint = "https://dashboard.observagent.cloud/v1/traces",
  protocol = "binary",
  headers = { Authorization = "Bearer YOUR_OBSERVAGENT_PROJECT_KEY" }
}}

3
Step 3
Restart Codex and generate an event
Close active Codex sessions, start a new one, and run a harmless task in a test directory.
- Restarting is required so Codex reloads config.toml.
- Use non-sensitive test content and complete at least one simple tool action.
- Collection starts with new activity and does not backfill earlier conversations.
PowerShell
```
codex
```
4
Step 4
Verify delivery
Allow time for batched export, then verify recent Codex logs, metrics, and traces separately in Observagent.
- Look for logs such as codex.conversation_starts, metrics such as codex.api_request, and recent trace spans.
- The codex.user_prompt event can remain visible while its raw prompt content is redacted.
- Event fields and names can vary with the installed Codex version.

Configuration downloads

Get the Codex integration files

Download the configuration template and setup guide from the public Observagent GitHub repository. Merge the template into your user-level Codex configuration; do not commit a completed configuration containing a real project key.

Prompt privacy

Understand `log_user_prompt = false`

Keep log_user_prompt = false to exclude raw user prompt text from exported Codex logs. Codex can still emit a codex.user_prompt event with metadata such as prompt length. The setting redacts content; it does not remove the event itself.

Tool-result events may contain output snippets even when user prompt content is redacted.
To drop only codex.user_prompt, route logs through an OpenTelemetry Collector and filter that event before export.
Setting exporter = "none" stops all Codex event delivery, not only prompt events.
Review exported records before using the integration with sensitive repositories or data.

Data sent

Review the Codex event boundary

Common metadata can include the service name, Codex version, environment label, conversation ID, model, and sandbox or approval settings.
Request events can include duration, status, and error information.
Tool events can include the tool name, approval decision, duration, success state, and an output snippet.
Supported completion events can include token-usage fields.
The metrics pipeline includes counters and duration histograms for supported API, stream, WebSocket, and tool activity.
Trace spans provide timing and correlation for supported runtime operations; available spans can vary by Codex version.
This is live operational telemetry, not a historical conversation import or a guaranteed complete transcript.

Troubleshooting

Troubleshoot Codex delivery

No records: confirm Logs, Metrics, Traces, and monitoring are enabled, check all three endpoints and project-key headers, then fully restart Codex.
Invalid TOML: keep one [otel] table and use the current inline exporter = { otlp-http = { ... }} form.
401 or 403: verify the complete Bearer key, its telemetry:write permission, and the selected project's status.
Prompt text appears: confirm log_user_prompt = false is in the active config file and restart the runtime.
Only one signal arrives: verify each exporter uses its matching /v1/logs, /v1/metrics, or /v1/traces endpoint and the same complete project key.
No token data: not every event or runtime transport includes recognized token-usage fields.
Old conversations are missing: telemetry starts with new activity after configuration and does not backfill history.

Stop collection

Stop future Codex export

config.toml

[otel]
exporter = "none"
log_user_prompt = false

Set the exporter to none and restart Codex. This stops future delivery; it does not remove telemetry that was already sent. Revoke the project key if it was exposed.