Trace OpenAI Codex sessions

The langsmith-codex-plugins marketplace ships a tracing plugin that sends OpenAI Codex session data to LangSmith. Use it to inspect agent turns, model metadata, token usage, tool calls, and subagent threads from your Codex workflows.

Prerequisites

Before setting up tracing, ensure you have:

Node.js 22.x or later.
Codex CLI v0.153.4 or later, with synchronous UserPromptSubmit plugin hooks enabled and trusted.
A LangSmith API key.

Install and enable the plugin

Add the marketplace using the Codex CLI:

codex plugin marketplace add langchain-ai/langsmith-codex-plugins

Enable the tracing plugin globally in ~/.codex/config.toml, or only for a specific project in .codex/config.toml:

[plugins."tracing@langsmith-codex-plugins"]
enabled = true

Then trust this plugin’s hooks with /hooks, or in Codex’s plugin UI when prompted. Enabling the plugin alone does not trust its hooks.

Configure tracing

Tracing is disabled until either TRACE_TO_LANGSMITH is "true" or enabled is true in a config file. Configure credentials with environment variables, a JSON config file, or both.

Environment variables

The plugin reads Codex-specific variables first, then falls back to the generic LangSmith SDK variables.

Variable	Required	Default	Description
`TRACE_TO_LANGSMITH`	Yes	-	Set to `"true"` to enable tracing.
`LANGSMITH_CODEX_API_KEY`	Conditional	-	LangSmith API key. Falls back to `LANGSMITH_API_KEY`. Required unless every replica provides its own API key.
`LANGSMITH_CODEX_ENDPOINT`	No	`https://api.smith.langchain.com`	LangSmith API URL. Falls back to `LANGSMITH_ENDPOINT`.
`LANGSMITH_CODEX_PROJECT`	No	`codex`	LangSmith project name. Falls back to `LANGSMITH_PROJECT`.
`LANGSMITH_CODEX_METADATA`	No	-	JSON object merged into root trace metadata. Falls back to `LANGSMITH_METADATA`.
`LANGSMITH_CODEX_RUNS_ENDPOINTS`	No	-	JSON array of replica destinations. Falls back to `LANGSMITH_RUNS_ENDPOINTS`.
`LANGSMITH_CODEX_REDACT`	No	`true`	Set to a falsy value to disable secret redaction. Falls back to `LANGSMITH_REDACT`.
`LANGSMITH_CODEX_REDACT_EXTRA`	No	-	JSON array of extra `{ pattern, replace }` redaction rules. Falls back to `LANGSMITH_REDACT_EXTRA`.

Add the variables to your shell configuration file (~/.zshrc, ~/.bashrc, or ~/.bash_profile):

export TRACE_TO_LANGSMITH="true"
export LANGSMITH_CODEX_API_KEY="<your-langsmith-api-key>"
export LANGSMITH_CODEX_PROJECT="codex"

Config file

Use <project>/.codex/langsmith.json for project-level settings or ~/.codex/langsmith.json for global defaults. The global file loads first, the project file overrides it, and matching environment variables take precedence over both.

{
  "enabled": true,
  "api_key": "<your-langsmith-api-key>",
  "api_url": "https://api.smith.langchain.com",
  "project": "codex",
  "metadata": {
    "team": "agents",
    "environment": "dev"
  }
}

Field	Environment variable	Default	Description
`enabled`	`TRACE_TO_LANGSMITH`	`false`	Set to `true` to enable tracing.
`api_key`	`LANGSMITH_CODEX_API_KEY`, `LANGSMITH_API_KEY`	-	LangSmith API key.
`api_url`	`LANGSMITH_CODEX_ENDPOINT`, `LANGSMITH_ENDPOINT`	LangSmith default	LangSmith API URL.
`project`	`LANGSMITH_CODEX_PROJECT`, `LANGSMITH_PROJECT`	`codex`	LangSmith project name.
`metadata`	`LANGSMITH_CODEX_METADATA`, `LANGSMITH_METADATA`	-	Object merged into root trace metadata.
`replicas`	`LANGSMITH_CODEX_RUNS_ENDPOINTS`, `LANGSMITH_RUNS_ENDPOINTS`	-	Additional LangSmith destinations to replicate traces to.
`redact`	`LANGSMITH_CODEX_REDACT`, `LANGSMITH_REDACT`	`true`	Set to `false` to disable secret redaction.
`redact_extra_rules`	`LANGSMITH_CODEX_REDACT_EXTRA`, `LANGSMITH_REDACT_EXTRA`	-	Extra `{ pattern, replace }` rules applied after the built-in ones.

Keep config files that include API keys out of version control.

Trace to multiple destinations

Set replicas in langsmith.json or LANGSMITH_CODEX_RUNS_ENDPOINTS to send the same trace data to additional LangSmith workspaces or projects. When set, the replica list overrides the other client settings. Tracing to multiple replicas is useful for:

Sending traces to both a production and staging project.
Tracing to multiple workspaces with different API keys.
Adding extra metadata to specific replica destinations.

Config file (recommended)
Shell environment variable

In <project>/.codex/langsmith.json or ~/.codex/langsmith.json:

{
  "enabled": true,
  "replicas": [
    {
      "apiUrl": "https://api.smith.langchain.com",
      "apiKey": "lsv2_pt_workspace_a",
      "projectName": "project-prod"
    },
    {
      "apiUrl": "https://api.smith.langchain.com",
      "apiKey": "lsv2_pt_workspace_b",
      "projectName": "project-staging",
      "updates": { "metadata": { "environment": "staging" } }
    }
  ]
}

export LANGSMITH_CODEX_RUNS_ENDPOINTS='[{"apiUrl":"https://api.smith.langchain.com","apiKey":"lsv2_pt_workspace_a","projectName":"project-prod"},{"apiUrl":"https://api.smith.langchain.com","apiKey":"lsv2_pt_workspace_b","projectName":"project-staging","updates":{"metadata":{"environment":"staging"}}}]'

To generate the escaped JSON string, use:

echo '[{"apiUrl":"...","apiKey":"...","projectName":"..."}]' | jq -c .

Each replica object supports the following fields:

Field	Required	Description
`apiUrl`	Yes	LangSmith API URL (typically `https://api.smith.langchain.com`).
`apiKey`	Yes	API key for the destination workspace.
`projectName`	Yes	Project name in the destination workspace.
`updates`	No	Optional run fields to override on replicated runs, such as extra metadata.

Secret redaction

The plugin redacts detected secrets from run inputs, outputs, errors, and metadata before uploading them to LangSmith. Redaction is on by default. Redaction runs on your machine before upload, so unredacted content never reaches LangSmith. Replica destinations receive the same redacted payload. Detection covers provider API key prefixes, JSON Web Tokens, and PEM private key blocks. It also covers contextual shapes such as API_KEY=<value>, an Authorization header, and a password embedded in a URL. Each match is replaced with [SECRET_DETECTED]. For the rule list, see Redact secrets from traces. Redaction matches known credential shapes, so treat it as a safety net rather than a guarantee. A credential in an unrecognized format still reaches LangSmith, and attachments, run names, and tags do not pass through the anonymizer. A redacted trace also still holds the prompts, file contents, and tool results it was built from, so restrict who can read the tracing project. To turn redaction off, set LANGSMITH_CODEX_REDACT to false, 0, no, or off, or set "redact": false in a config file. Values are trimmed and compared case-insensitively. To redact additional patterns, set LANGSMITH_CODEX_REDACT_EXTRA to a JSON array of { "pattern": ..., "replace": ... } rules, or set redact_extra_rules in a config file. Each pattern is a regular expression string, applied globally and case-sensitively. replace is optional and falls back to [redacted]. Extra rules run after the built-in ones.

{
  "enabled": true,
  "project": "codex",
  "redact": true,
  "redact_extra_rules": [{ "pattern": "ACME-[A-Z0-9]{16}", "replace": "[REDACTED_ACME_KEY]" }]
}

Setting redact_extra_rules to [] clears rules inherited from a lower-priority source. In a config file, one rule with an invalid regular expression discards every setting in that file, so verify the patterns before committing them. Because a project-level .codex/langsmith.json or langsmith-plugins.json can set redact to false, review those files before enabling tracing in a repository you do not control.

What gets traced

Each LLM run includes:

Inputs: accumulated conversation messages.
Outputs: assistant response content.
Metadata: model provider, model name, stop reason, and token usage.

Tool calls (function calls, shell calls, computer calls, file reads, web searches) are included with their inputs and outputs. Subagent threads are resolved and uploaded as nested child runs under the parent turn. Interrupted turns where the user cancels mid-response are still uploaded once the session completes.

View traces in LangSmith

Open the configured LangSmith project and complete a Codex turn. By default traces appear in the codex project. The plugin uploads completed Codex transcript data, including messages, tool call inputs and outputs, model metadata, token usage, and subagent thread structure.

The plugin uploads full Codex transcript data to LangSmith. Do not enable tracing for sessions that contain data you do not want stored in LangSmith.

Troubleshooting

If traces do not appear in LangSmith:

Confirm the tracing plugin is enabled in config.toml and its hooks are trusted (/hooks). [features] hooks is on by default, so set it only to undo a local override.
Confirm TRACE_TO_LANGSMITH=true is visible to the Codex process.
Confirm LANGSMITH_CODEX_API_KEY or LANGSMITH_API_KEY is set and valid.
If runs land in the wrong project, set LANGSMITH_CODEX_PROJECT or the project config key.
If a custom endpoint is not used, set LANGSMITH_CODEX_ENDPOINT or the api_url config key.

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Tracing setup

Configuration & troubleshooting

Prerequisites

Install and enable the plugin

Configure tracing

Environment variables

Config file

Trace to multiple destinations

Secret redaction

What gets traced

View traces in LangSmith

Troubleshooting

​Prerequisites

​Install and enable the plugin

​Configure tracing

​Environment variables

​Config file

​Trace to multiple destinations

​Secret redaction

​What gets traced

​View traces in LangSmith

​Troubleshooting

Prerequisites

Install and enable the plugin

Configure tracing

Environment variables

Config file

Trace to multiple destinations

Secret redaction

What gets traced

View traces in LangSmith

Troubleshooting