178 Commits

• fix(core): load custom prompts from symlinked Markdown files (#3643)

  - Discover prompts via fs::metadata to follow symlinks
  
  - Add Unix-only symlink test in custom_prompts.rs
  
  - Update docs/prompts.md to mention symlinks
  
  Fixes #3637
  
  ---------
  
  Signed-off-by: Soroush Yousefpour <h.yusefpour@gmail.com>
  Co-authored-by: dedrisian-oai <dedrisian@openai.com>
  Co-authored-by: Eric Traut <etraut@openai.com>

  Soroush Yousefpour · 2025-11-04 17:44:02 -08:00
  fff576cf98
• fix: Update the deprecation message to link to the docs (#6211)

  The deprecation message is currently a bit confusing. Users may not
  understand what is `[features].x`. I updated the docs and the
  deprecation message for more guidance.
  
  ---------
  
  Co-authored-by: Gabriel Peal <gpeal@users.noreply.github.com>

  Ahmed Ibrahim · 2025-11-04 21:02:27 +00:00
  d40a6b7f73
• docs: add example config.toml (#5175)

  I was missing an example config.toml, and following docs/config.md alone
  was slower. I had GPT-5 scan the codebase for every accepted config key,
  check the defaults, and generate a single example config.toml with
  annotations. It lists all keys Codex reads from TOML, sets each to its
  effective default where it exists, leaves optional ones commented, and
  adds short comments on purpose and valid values. This should make
  onboarding faster and reduce configuration errors. I can rename it to
  config.example.toml or move it under docs/ if you prefer.

  Lucas Freire Sangoi · 2025-11-03 18:19:26 -08:00
  ab63a47173
• Add documentation for slash commands in docs/slash_commands.md. (#5685)

  This pull request adds a new documentation section to explain the
  available slash commands in Codex. The update introduces a clear
  overview and a reference table for built-in commands, making it easier
  for users to understand and utilize these features.
  
  Documentation updates:
  
  * Added a new section to `docs/slash_commands.md` describing what slash
  commands are and listing all built-in commands with their purposes in a
  formatted table.

  pygarap · 2025-11-03 08:27:13 -08:00
  b484672961
• docs: Fix link anchor and markdown format in advanced guide (#5649)

  Hi OpenAI Codex team, this PR fix an rendering issue in the Markdown
  table and anchor link in the
  [docs/advanced.md](https://github.com/openai/codex/blob/main/docs/advanced.md).
  
  Thank you!
  
  Co-authored-by: Eric Traut <etraut@openai.com>

  Vinh Nguyen · 2025-10-31 16:53:09 -07:00
  91e65ac0ce
• Fixing small typo in docs (#5659)

  Fixing a typo in the docs
  
  Co-authored-by: Eric Traut <etraut@openai.com>

  Tony Dong · 2025-10-31 16:41:05 -07:00
  1ac4fb45d2
• docs: fix broken link in contributing guide (#4973)

  ## Summary
  
  This PR fixes a broken self-referencing link in the contributing
  documentation.
  
  ## Changes
  
  - Removed the phrase 'Following the [development
  setup](#development-workflow) instructions above' from the Development
  workflow section
  - The link referenced a non-existent section and the phrase didn't make
  logical sense in context
  
  ## Before
  
  The text referenced 'development setup instructions above' but:
  1. No section called 'development setup' exists
  2. There were no instructions 'above' that point
  3. The link pointed to the same section it was in
  
  ## After
  
  Simplified to: 'Ensure your change is free of lint warnings and test
  failures.'
  
  ## Type
  
  Documentation fix
  
  
  I have read the CLA Document and I hereby sign the CLA
  
  Co-authored-by: Ritesh Chauhan <sagar.chauhn11@gmail.com>

  Ritesh Chauhan · 2025-10-31 15:09:35 -07:00
  d7f8b97541
• Windows Sandbox - Alpha version (#4905)

  - Added the new codex-windows-sandbox crate that builds both a library
  entry point (run_windows_sandbox_capture) and a CLI executable to launch
  commands inside a Windows restricted-token sandbox, including ACL
  management, capability SID provisioning, network lockdown, and output
  capture
  (windows-sandbox-rs/src/lib.rs:167, windows-sandbox-rs/src/main.rs:54).
  - Introduced the experimental WindowsSandbox feature flag and wiring so
  Windows builds can opt into the sandbox:
  SandboxType::WindowsRestrictedToken, the in-process execution path, and
  platform sandbox selection now honor the flag (core/src/features.rs:47,
  core/src/config.rs:1224, core/src/safety.rs:19,
  core/src/sandboxing/mod.rs:69, core/src/exec.rs:79,
  core/src/exec.rs:172).
  - Updated workspace metadata to include the new crate and its
  Windows-specific dependencies so the core crate can link against it
  (codex-rs/
      Cargo.toml:91, core/Cargo.toml:86).
  - Added a PowerShell bootstrap script that installs the Windows
  toolchain, required CLI utilities, and builds the workspace to ease
  development
      on the platform (scripts/setup-windows.ps1:1).
  - Landed a Python smoke-test suite that exercises
  read-only/workspace-write policies, ACL behavior, and network denial for
  the Windows sandbox
      binary (windows-sandbox-rs/sandbox_smoketests.py:1).

  iceweasel-oai · 2025-10-30 15:51:57 -07:00
  87cce88f48
• [Hygiene] Remove include_view_image_tool config (#5976)

  There's still some debate about whether we want to expose
  `tools.view_image` or `feature.view_image` so those are left unchanged
  for now, but this old `include_view_image_tool` config is good-to-go.
  Also updated the doc to reflect that `view_image` tool is now by default
  true.

  Celia Chen · 2025-10-30 13:23:24 -07:00
  6ef658a9f9
• fix advanced.md (#5833)

  table wasn't formatting correctly

  zhao-oai · 2025-10-28 16:32:20 +00:00
  926c89cb20
• [Auth] Choose which auth storage to use based on config (#5792)

  This PR is a follow-up to #5591. It allows users to choose which auth
  storage mode they want by using the new
  `cli_auth_credentials_store_mode` config.

  Celia Chen · 2025-10-27 19:41:49 -07:00
  4a42c4e142
• [MCP] Minor docs clarifications around stdio tokens (#5676)

  Noticed
  [here](https://github.com/openai/codex/issues/4707#issuecomment-3446547561)

  Gabriel Peal · 2025-10-26 13:38:30 -04:00
  7aab45e060
• Add instruction for upgrading codex with brew (#5640)

  Include instruction for upgrading codex with brew when there is switch
  from formula to cask.

  Shijie Rao · 2025-10-24 11:30:34 -07:00
  00c1de0c56
• [MCP] Remove the legacy stdio client in favor of rmcp (#5529)

  I haven't heard of any issues with the studio rmcp client so let's
  remove the legacy one and default to the new one.
  
  Any code changes are moving code from the adapter inline but there
  should be no meaningful functionality changes.

  Gabriel Peal · 2025-10-22 12:06:59 -07:00
  4cd6b01494
• docs: fix agents fallback example (#5396)
  Thibault Sottiaux · 2025-10-22 11:32:35 -07:00
  dd59b16a17
• feat: include cwd in notify payload (#5415)

  Expose the session cwd in the notify payload and update docs so scripts
  and extensions receive the real project path; users get accurate
  project-aware notifications in CLI and VS Code.
  
  Fixes #5387

  Thibault Sottiaux · 2025-10-20 23:53:03 +00:00
  7fc01c6e9b
• docs: correct getting-started behaviors (#5407)
  Thibault Sottiaux · 2025-10-20 16:17:07 -07:00
  bd6ab8c665
• docs: document exec json events (#5399)
  Thibault Sottiaux · 2025-10-20 16:11:36 -07:00
  d2bae07687
• docs: remove stale contribution reference (#5400)
  Thibault Sottiaux · 2025-10-20 16:11:14 -07:00
  9c09094583
• docs: clarify prompt metadata behavior (#5403)
  Thibault Sottiaux · 2025-10-20 16:09:47 -07:00
  7e4ab31488
• [MCP] Add configuration options to enable or disable specific tools (#5367)

  Some MCP servers expose a lot of tools. In those cases, it is reasonable
  to allow/denylist tools for Codex to use so it doesn't get overwhelmed
  with too many tools.
  
  The new configuration options available in the `mcp_server` toml table
  are:
  * `enabled_tools`
  * `disabled_tools`
  
  Fixes #4796

  Gabriel Peal · 2025-10-20 15:35:36 -07:00
  740b4a95f4
• docs: update advanced guide details (#5395)
  Thibault Sottiaux · 2025-10-20 15:00:42 -07:00
  c782f8c68d
• Always enable plan tool in exec (#5380)

  Fixes: https://github.com/openai/codex/issues/5359

  pakrym-oai · 2025-10-20 11:05:55 -07:00
  cda6db6ccf
• Update Homebrew install instructions to use cask (#5377)

  ## Summary
  - update the README install snippets to use `brew install --cask codex`
  - mirror the same change in the Rust CLI README
  
  Address #5317
  
  https://chatgpt.com/codex/tasks/task_i_68f65682543083269254cd64d290df28
  
  ---------
  
  Co-authored-by: pakrym-oai <pakrym@openai.com>

  Shijie Rao · 2025-10-20 17:43:40 +00:00
  73a1787eb8
• Add forced_chatgpt_workspace_id and forced_login_method configuration options (#5303)

  This PR adds support for configs to specify a forced login method
  (chatgpt or api) as well as a forced chatgpt account id. This lets
  enterprises uses [managed
  configs](https://developers.openai.com/codex/security#managed-configuration)
  to force all employees to use their company's workspace instead of their
  own or any other.
  
  When a workspace id is set, a query param is sent to the login flow
  which auto-selects the given workspace or errors if the user isn't a
  member of it.
  
  This PR is large but a large % of it is tests, wiring, and required
  formatting changes.
  
  API login with chatgpt forced
  <img width="1592" height="116" alt="CleanShot 2025-10-19 at 22 40 04"
  src="https://github.com/user-attachments/assets/560c6bb4-a20a-4a37-95af-93df39d057dd"
  />
  
  ChatGPT login with api forced
  <img width="1018" height="100" alt="CleanShot 2025-10-19 at 22 40 29"
  src="https://github.com/user-attachments/assets/d010bbbb-9c8d-4227-9eda-e55bf043b4af"
  />
  
  Onboarding with api forced
  <img width="892" height="460" alt="CleanShot 2025-10-19 at 22 41 02"
  src="https://github.com/user-attachments/assets/cc0ed45c-b257-4d62-a32e-6ca7514b5edd"
  />
  
  Onboarding with ChatGPT forced
  <img width="1154" height="426" alt="CleanShot 2025-10-19 at 22 41 27"
  src="https://github.com/user-attachments/assets/41c41417-dc68-4bb4-b3e7-3b7769f7e6a1"
  />
  
  Logging in with the wrong workspace
  <img width="2222" height="84" alt="CleanShot 2025-10-19 at 22 42 31"
  src="https://github.com/user-attachments/assets/0ff4222c-f626-4dd3-b035-0b7fe998a046"
  />

  Gabriel Peal · 2025-10-20 08:50:54 -07:00
  d87f87e25b
• docs: align sandbox defaults, dedupe sections and improve getting started guide (#5357)

  Tightened the docs so the sandbox guide matches reality, noted the new
  tools.view_image toggle next to web search, and linked the README to the
  getting-started guide which now owns the familiar tips (backtrack, --cd,
  --add-dir, etc.).

  Thibault Sottiaux · 2025-10-19 16:41:10 -07:00
  2d9ee9dbe9
• fix: config.md docs inaccuracies (#5355)

  Updated the configuration guide so it matches the current CLI behavior.
  Clarified the platform-specific default model, explained how custom
  model-providers interact with bundled ones, refreshed the streamable
  HTTP/MCP section with accurate guidance on the RMCP client and OAuth
  flag, and removed stale keys from the reference table.

  Thibault Sottiaux · 2025-10-19 15:32:13 -07:00
  3e071c4c95
• docs: improve overall documentation (#5354)

  Update FAQ, improve general structure for config, add more links across
  the sections in the documentation, remove out of date and duplicate
  content and better explain certain concepts such as approvals and
  sandboxing.

  Thibault Sottiaux · 2025-10-19 15:07:33 -07:00
  c127062b40
• docs: add AGENTS.md discovery guide (#5353)
  Thibault Sottiaux · 2025-10-19 14:07:20 -07:00
  1d9b27387b
• fix: improve custom prompt documentation and actually use prompt descriptions (#5332)

  Expand the custom prompts documentation and link it from other guides. Show saved prompt metadata in the slash-command popup, with tests covering description fallbacks.

  Thibault Sottiaux · 2025-10-18 15:58:31 -07:00
  c81e1477ae
• [MCP] Add support for resources (#5239)

  This PR adds support for [MCP
  resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources)
  by adding three new tools for the model:
  1. `list_resources`
  2. `list_resource_templates`
  3. `read_resource`
  
  These 3 tools correspond to the [three primary MCP resource protocol
  messages](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#protocol-messages).
  
  Example of listing and reading a GitHub resource tempalte
  <img width="2984" height="804" alt="CleanShot 2025-10-15 at 17 31 10"
  src="https://github.com/user-attachments/assets/89b7f215-2e2a-41c5-90dd-b932ac84a585"
  />
  
  `/mcp` with Figma configured
  <img width="2984" height="442" alt="CleanShot 2025-10-15 at 18 29 35"
  src="https://github.com/user-attachments/assets/a7578080-2ed2-4c59-b9b4-d8461f90d8ee"
  />
  
  Fixes #4956

  Gabriel Peal · 2025-10-17 01:05:15 -04:00
  40fba1bb4c
• [MCP] Allow specifying cwd and additional env vars (#5246)

  This makes stdio mcp servers more flexible by allowing users to specify
  the cwd to run the server command from and adding additional environment
  variables to be passed through to the server.
  
  Example config using the test server in this repo:
  ```toml
  [mcp_servers.test_stdio]
  cwd = "/Users/<user>/code/codex/codex-rs"
  command = "cargo"
  args = ["run", "--bin", "test_stdio_server"]
  env_vars = ["MCP_TEST_VALUE"]
  ```
  
  @bolinfest I know you hate these env var tests but let's roll with this
  for now. I may take a stab at the env guard + serial macro at some
  point.

  Gabriel Peal · 2025-10-17 00:24:43 -04:00
  bdda762deb
• Fix notify documentation to use emitted input-messages key (#5071)

  ## Summary
  - align the notify configuration example with the CLI payload by reading
  the `input-messages` key
  
  Fixes #4954
  
  
  ------
  https://chatgpt.com/codex/tasks/task_i_68e95e2be6ec832c8d09d6c65aac7c93

  Jeremy Rose · 2025-10-15 23:22:39 -07:00
  0139f6780c
• [codex][otel] propagate user email in otel events (#5223)

  include user email into otel events for proper user-level attribution in
  case of workspace setup

  Anton Panasenko · 2025-10-15 17:53:33 -07:00
  c146585cdb
• feat: pass codex thread ID in notifier metadata (#4582)
  Javi · 2025-10-14 11:55:10 -07:00
  13035561cd
• fixes #5011: update mcp server doc (#5014)
  Shijie Rao · 2025-10-10 17:23:41 -07:00
  26f7c46856
• [MCP] Add an enabled config field (#4917)

  This lets users more easily toggle MCP servers.

  Gabriel Peal · 2025-10-08 16:24:51 -04:00
  d3820f4782
• Fix event names in exec docs. (#4833)

  Fixes: https://github.com/openai/codex/issues

  pakrym-oai · 2025-10-06 10:07:52 -07:00
  661663c98a
• [MCP] Improve docs (#4811)

  Updated, expanded on, clarified, and deduplicated some MCP docs

  Gabriel Peal · 2025-10-06 11:43:50 -04:00
  721003c552
• add codex sandbox {linux|macos} (#4782)

  ## Summary
  - add a `codex sandbox` subcommand with macOS and Linux targets while
  keeping the legacy `codex debug` aliases
  - update documentation to highlight the new sandbox entrypoints and
  point existing references to the new command
  - clarify the core README about the linux sandbox helper alias
  
  ## Testing
  - just fmt
  - just fix -p codex-cli
  - cargo test -p codex-cli
  
  
  ------
  https://chatgpt.com/codex/tasks/task_i_68e2e00ca1e8832d8bff53aa0b50b49e

  Fouad Matin · 2025-10-05 15:51:57 -07:00
  77a8b7fdeb
• chore: subject docs/*.md to Prettier checks (#4645)

  Apparently we were not running our `pnpm run prettier` check in CI, so
  many files that were covered by the existing Prettier check were not
  well-formatted.
  
  This updates CI and formats the files.

  Michael Bolin · 2025-10-03 11:35:48 -07:00
  c32e9cfe86
• [MCP] Add support for MCP Oauth credentials (#4517)

  This PR adds oauth login support to streamable http servers when
  `experimental_use_rmcp_client` is enabled.
  
  This PR is large but represents the minimal amount of work required for
  this to work. To keep this PR smaller, login can only be done with
  `codex mcp login` and `codex mcp logout` but it doesn't appear in `/mcp`
  or `codex mcp list` yet. Fingers crossed that this is the last large MCP
  PR and that subsequent PRs can be smaller.
  
  Under the hood, credentials are stored using platform credential
  managers using the [keyring crate](https://crates.io/crates/keyring).
  When the keyring isn't available, it falls back to storing credentials
  in `CODEX_HOME/.credentials.json` which is consistent with how other
  coding agents handle authentication.
  
  I tested this on macOS, Windows, WSL (ubuntu), and Linux. I wasn't able
  to test the dbus store on linux but did verify that the fallback works.
  
  One quirk is that if you have credentials, during development, every
  build will have its own ad-hoc binary so the keyring won't recognize the
  reader as being the same as the write so it may ask for the user's
  password. I may add an override to disable this or allow
  users/enterprises to opt-out of the keyring storage if it causes issues.
  
  <img width="5064" height="686" alt="CleanShot 2025-09-30 at 19 31 40"
  src="https://github.com/user-attachments/assets/9573f9b4-07f1-4160-83b8-2920db287e2d"
  />
  <img width="745" height="486" alt="image"
  src="https://github.com/user-attachments/assets/9562649b-ea5f-4f22-ace2-d0cb438b143e"
  />

  Gabriel Peal · 2025-10-03 13:43:12 -04:00
  1d17ca1fa3
• feat: codex exec writes only the final message to stdout (#4644)

  This updates `codex exec` so that, by default, most of the agent's
  activity is written to stderr so that only the final agent message is
  written to stdout. This makes it easier to pipe `codex exec` into
  another tool without extra filtering.
  
  I introduced `#![deny(clippy::print_stdout)]` to help enforce this
  change and renamed the `ts_println!()` macro to `ts_msg()` because (1)
  it no longer calls `println!()` and (2), `ts_eprintln!()` seemed too
  long of a name.
  
  While here, this also adds `-o` as an alias for `--output-last-message`.
  
  Fixes https://github.com/openai/codex/issues/1670

  Michael Bolin · 2025-10-03 16:22:12 +00:00
  042d4d55d9
• fix: replace --api-key with --with-api-key in codex login (#4646)

  Previously, users could supply their API key directly via:
  
  ```shell
  codex login --api-key KEY
  ```
  
  but this has the drawback that `KEY` is more likely to end up in shell
  history, can be read from `/proc`, etc.
  
  This PR removes support for `--api-key` and replaces it with
  `--with-api-key`, which reads the key from stdin, so either of these are
  better options:
  
  ```
  printenv OPENAI_API_KEY | codex login --with-api-key
  codex login --with-api-key < my_key.txt
  ```
  
  Other CLIs, such as `gh auth login --with-token`, follow the same
  practice.

  Michael Bolin · 2025-10-03 06:17:31 +00:00
  69ac5153d4
• Add a separate exec doc (#4583)

  More/better docs.

  pakrym-oai · 2025-10-02 13:33:08 -07:00
  b93cc0f431
• Fall back to configured instruction files if AGENTS.md isn't available (#4544)

  Allow users to configure an agents.md alternative to consume, but warn
  the user it may degrade model performance.
  
  Fixes #4376

  easong-openai · 2025-10-01 18:19:59 +00:00
  400a5a90bf
• fix: separate codex mcp into codex mcp-server and codex app-server (#4471)

  This is a very large PR with some non-backwards-compatible changes.
  
  Historically, `codex mcp` (or `codex mcp serve`) started a JSON-RPC-ish
  server that had two overlapping responsibilities:
  
  - Running an MCP server, providing some basic tool calls.
  - Running the app server used to power experiences such as the VS Code
  extension.
  
  This PR aims to separate these into distinct concepts:
  
  - `codex mcp-server` for the MCP server
  - `codex app-server` for the "application server"
  
  Note `codex mcp` still exists because it already has its own subcommands
  for MCP management (`list`, `add`, etc.)
  
  The MCP logic continues to live in `codex-rs/mcp-server` whereas the
  refactored app server logic is in the new `codex-rs/app-server` folder.
  Note that most of the existing integration tests in
  `codex-rs/mcp-server/tests/suite` were actually for the app server, so
  all the tests have been moved with the exception of
  `codex-rs/mcp-server/tests/suite/mod.rs`.
  
  Because this is already a large diff, I tried not to change more than I
  had to, so `codex-rs/app-server/tests/common/mcp_process.rs` still uses
  the name `McpProcess` for now, but I will do some mechanical renamings
  to things like `AppServer` in subsequent PRs.
  
  While `mcp-server` and `app-server` share some overlapping functionality
  (like reading streams of JSONL and dispatching based on message types)
  and some differences (completely different message types), I ended up
  doing a bit of copypasta between the two crates, as both have somewhat
  similar `message_processor.rs` and `outgoing_message.rs` files for now,
  though I expect them to diverge more in the near future.
  
  One material change is that of the initialize handshake for `codex
  app-server`, as we no longer use the MCP types for that handshake.
  Instead, we update `codex-rs/protocol/src/mcp_protocol.rs` to add an
  `Initialize` variant to `ClientRequest`, which takes the `ClientInfo`
  object we need to update the `USER_AGENT_SUFFIX` in
  `codex-rs/app-server/src/message_processor.rs`.
  
  One other material change is in
  `codex-rs/app-server/src/codex_message_processor.rs` where I eliminated
  a use of the `send_event_as_notification()` method I am generally trying
  to deprecate (because it blindly maps an `EventMsg` into a
  `JSONNotification`) in favor of `send_server_notification()`, which
  takes a `ServerNotification`, as that is intended to be a custom enum of
  all notification types supported by the app server. So to make this
  update, I had to introduce a new variant of `ServerNotification`,
  `SessionConfigured`, which is a non-backwards compatible change with the
  old `codex mcp`, and clients will have to be updated after the next
  release that contains this PR. Note that
  `codex-rs/app-server/tests/suite/list_resume.rs` also had to be update
  to reflect this change.
  
  I introduced `codex-rs/utils/json-to-toml/src/lib.rs` as a small utility
  crate to avoid some of the copying between `mcp-server` and
  `app-server`.

  Michael Bolin · 2025-09-30 07:06:18 +00:00
  d9dbf48828
• Update MCP docs to reference experimental RMCP client (#4422)
  Gabriel Peal · 2025-09-30 02:44:16 -04:00
  2e95e5602d
• Custom prompt args (numeric) (#4470)

  [Cherry picked from /pull/3565]
  
  Adds $1, $2, $3, $ARGUMENTS param parsing for custom prompts.

  dedrisian-oai · 2025-09-29 16:14:37 -07:00
  80ccec6530
• OpenTelemetry events (#2103)

  ### Title
  
  ## otel
  
  Codex can emit [OpenTelemetry](https://opentelemetry.io/) **log events**
  that
  describe each run: outbound API requests, streamed responses, user
  input,
  tool-approval decisions, and the result of every tool invocation. Export
  is
  **disabled by default** so local runs remain self-contained. Opt in by
  adding an
  `[otel]` table and choosing an exporter.
  
  ```toml
  [otel]
  environment = "staging"   # defaults to "dev"
  exporter = "none"          # defaults to "none"; set to otlp-http or otlp-grpc to send events
  log_user_prompt = false    # defaults to false; redact prompt text unless explicitly enabled
  ```
  
  Codex tags every exported event with `service.name = "codex-cli"`, the
  CLI
  version, and an `env` attribute so downstream collectors can distinguish
  dev/staging/prod traffic. Only telemetry produced inside the
  `codex_otel`
  crate—the events listed below—is forwarded to the exporter.
  
  ### Event catalog
  
  Every event shares a common set of metadata fields: `event.timestamp`,
  `conversation.id`, `app.version`, `auth_mode` (when available),
  `user.account_id` (when available), `terminal.type`, `model`, and
  `slug`.
  
  With OTEL enabled Codex emits the following event types (in addition to
  the
  metadata above):
  
  - `codex.api_request`
    - `cf_ray` (optional)
    - `attempt`
    - `duration_ms`
    - `http.response.status_code` (optional)
    - `error.message` (failures)
  - `codex.sse_event`
    - `event.kind`
    - `duration_ms`
    - `error.message` (failures)
    - `input_token_count` (completion only)
    - `output_token_count` (completion only)
    - `cached_token_count` (completion only, optional)
    - `reasoning_token_count` (completion only, optional)
    - `tool_token_count` (completion only)
  - `codex.user_prompt`
    - `prompt_length`
    - `prompt` (redacted unless `log_user_prompt = true`)
  - `codex.tool_decision`
    - `tool_name`
    - `call_id`
  - `decision` (`approved`, `approved_for_session`, `denied`, or `abort`)
    - `source` (`config` or `user`)
  - `codex.tool_result`
    - `tool_name`
    - `call_id`
    - `arguments`
    - `duration_ms` (execution time for the tool)
    - `success` (`"true"` or `"false"`)
    - `output`
  
  ### Choosing an exporter
  
  Set `otel.exporter` to control where events go:
  
  - `none` – leaves instrumentation active but skips exporting. This is
  the
    default.
  - `otlp-http` – posts OTLP log records to an OTLP/HTTP collector.
  Specify the
    endpoint, protocol, and headers your collector expects:
  
    ```toml
    [otel]
    exporter = { otlp-http = {
      endpoint = "https://otel.example.com/v1/logs",
      protocol = "binary",
      headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
    }}
    ```
  
  - `otlp-grpc` – streams OTLP log records over gRPC. Provide the endpoint
  and any
    metadata headers:
  
    ```toml
    [otel]
    exporter = { otlp-grpc = {
      endpoint = "https://otel.example.com:4317",
      headers = { "x-otlp-meta" = "abc123" }
    }}
    ```
  
  If the exporter is `none` nothing is written anywhere; otherwise you
  must run or point to your
  own collector. All exporters run on a background batch worker that is
  flushed on
  shutdown.
  
  If you build Codex from source the OTEL crate is still behind an `otel`
  feature
  flag; the official prebuilt binaries ship with the feature enabled. When
  the
  feature is disabled the telemetry hooks become no-ops so the CLI
  continues to
  function without the extra dependencies.
  
  ---------
  
  Co-authored-by: Anton Panasenko <apanasenko@openai.com>

  vishnu-oai · 2025-09-29 11:30:55 -07:00
  04c1782e52