chore(merge): prepare workspace for vitual cherry-pick

2026-10-17 15:34:54 +00:00 · 2025-10-01 04:11:40 +10:00
parent 1acc930db9 5a8f545d05
commit b0e445a4ef
173 changed files with 16633 additions and 941 deletions
@@ -359,11 +359,11 @@ Codex provides three main Approval Presets:

 You can further customize how Codex runs at the command line using the `--ask-for-approval` and `--sandbox` options.

-## mcp_servers
+## MCP Servers

-Defines the list of MCP servers that Codex can consult for tool use. Currently, only servers that are launched by executing a program that communicate over stdio are supported. For servers that use the SSE transport, consider an adapter like [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy).
+You can configure Codex to use [MCP servers](https://modelcontextprotocol.io/about) to give Codex access to external applications, resources, or services such as [Playwright](https://github.com/microsoft/playwright-mcp), [Figma](https://www.figma.com/blog/design-context-everywhere-you-build/), [documentation](https://context7.com/), and  [more](https://github.com/mcp?utm_source=blog-source&utm_campaign=mcp-registry-server-launch-2025).

-**Note:** Codex may cache the list of tools and resources from an MCP server so that Codex can include this information in context at startup without spawning all the servers. This is designed to save resources by loading MCP servers lazily.
+### Server transport configuration

 Each server may set `startup_timeout_sec` to adjust how long Codex waits for it to start and respond to a tools listing. The default is `10` seconds.
 Similarly, `tool_timeout_sec` limits how long individual tool calls may run (default: `60` seconds), and Codex will fall back to the default when this value is omitted.
@@ -387,11 +387,33 @@ This config option is comparable to how Claude and Cursor define `mcpServers` in
 Should be represented as follows in `~/.code/config.toml` (Code will also read the legacy `~/.codex/config.toml` if it exists):

 ```toml
-# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
+# The top-level table name must be `mcp_servers`
+# The sub-table name (`server-name` in this example) can be anything you would like.
 [mcp_servers.server-name]
 command = "npx"
+# Optional
 args = ["-y", "mcp-server"]
+# Optional: propagate additional env vars to the MVP server.
+# A default whitelist of env vars will be propagated to the MCP server.
+# https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/utils.rs#L82
 env = { "API_KEY" = "value" }
+```
+
+#### Streamable HTTP
+
+```toml
+# Streamable HTTP requires the experimental rmcp client
+experimental_use_rmcp_client = true
+[mcp_servers.figma]
+url = "http://127.0.0.1:3845/mcp"
+# Optional bearer token to be passed into an `Authorization: Bearer <token>` header
+# Use this with caution because the token is in plaintext.
+bearer_token = "<token>"
+```
+
+### Other configuration options
+
+```toml
 # Optional: override the default 10s startup timeout
 startup_timeout_sec = 20
 # Optional: override the default 60s per-tool timeout
@@ -539,6 +561,117 @@ set = { PATH = "/usr/bin", MY_FLAG = "1" }

 Currently, `CODEX_SANDBOX_NETWORK_DISABLED=1` is also added to the environment, assuming network is disabled. This is not configurable.

+## 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 = $ORIGINATOR` (the same
+value sent in the `originator` header, `codex_cli_rs` by default), 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.conversation_starts`
+  - `provider_name`
+  - `reasoning_effort` (optional)
+  - `reasoning_summary`
+  - `context_window` (optional)
+  - `max_output_tokens` (optional)
+  - `auto_compact_token_limit` (optional)
+  - `approval_policy`
+  - `sandbox_policy`
+  - `mcp_servers` (comma-separated list)
+  - `active_profile` (optional)
+- `codex.api_request`
+  - `attempt`
+  - `duration_ms`
+  - `http.response.status_code` (optional)
+  - `error.message` (failures)
+- `codex.sse_event`
+  - `event.kind`
+  - `duration_ms`
+  - `error.message` (failures)
+  - `input_token_count` (responses only)
+  - `output_token_count` (responses only)
+  - `cached_token_count` (responses only, optional)
+  - `reasoning_token_count` (responses only, optional)
+  - `tool_token_count` (responses 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` (optional)
+  - `arguments` (optional)
+  - `duration_ms` (execution time for the tool)
+  - `success` (`"true"` or `"false"`)
+  - `output`
+
+These event shapes may change as we iterate.
+
+### 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.
+
 ## notify

 Specify a program that will be executed to get notified about events generated by Codex. Note that the program will receive the notification argument as a string of JSON, e.g.:
@@ -6,6 +6,11 @@ Save frequently used prompts as Markdown files and reuse them quickly from the s
 - File type: Only Markdown files with the `.md` extension are recognized.
 - Name: The filename without the `.md` extension becomes the slash entry. For a file named `my-prompt.md`, type `/my-prompt`.
 - Content: The file contents are sent as your message when you select the item in the slash popup and press Enter.
+- Arguments: Local prompts support placeholders in their content:
+  - `$1..$9` expand to the first nine positional arguments typed after the slash name
+  - `$ARGUMENTS` expands to all arguments joined by a single space
+  - `$$` is preserved literally
+  - Quoted args: Wrap a single argument in double quotes to include spaces, e.g. `/review "docs/My File.md"`.
 - How to use:
  - Start a new session (Codex loads custom prompts on session start).
  - In the composer, type `/` to open the slash popup and begin typing your prompt name.