> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-docsby-1791319236-3be7a15.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Trace OpenAI Codex sessions

> Capture OpenAI Codex agent turns, tool calls, model metadata, and subagent threads in LangSmith.

The [`langsmith-codex-plugins`](https://github.com/langchain-ai/langsmith-codex-plugins) marketplace ships a tracing plugin that sends [OpenAI Codex](https://developers.openai.com/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](https://nodejs.org/) 22.x or later.
* [Codex CLI](https://developers.openai.com/codex/quickstart?setup=cli) v0.153.4 or later, with synchronous `UserPromptSubmit` plugin hooks enabled and trusted.
* A [LangSmith API key](/langsmith/create-account-api-key).

## Install and enable the plugin

Add the marketplace using the Codex CLI:

```bash theme={null}
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`:

```toml theme={null}
[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`):

```bash theme={null}
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.

```json theme={null}
{
  "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](#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](/langsmith/log-traces-to-project) 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.

<Tabs>
  <Tab title="Config file (recommended)">
    In `<project>/.codex/langsmith.json` or `~/.codex/langsmith.json`:

    ```json theme={null}
    {
      "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" } }
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Shell environment variable">
    ```bash theme={null}
    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:

    ```bash theme={null}
    echo '[{"apiUrl":"...","apiKey":"...","projectName":"..."}]' | jq -c .
    ```
  </Tab>
</Tabs>

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](/langsmith/redact-secrets#rules-in-the-preset).

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.

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

## 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.

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to your agent of choice via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/trace-with-codex.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>