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.
This commit is contained in:
Thibault Sottiaux
committed by
GitHub
GitHub
parent
1d9b27387b
commit
c127062b40
561
docs/config.md
561
docs/config.md
@@ -1,5 +1,16 @@
|
||||
# Config
|
||||
|
||||
Codex configuration gives you fine-grained control over the model, execution environment, and integrations available to the CLI. Use this guide alongside the workflows in [`codex exec`](./exec.md), the guardrails in [Sandbox & approvals](./sandbox.md), and project guidance from [AGENTS.md discovery](./agents_md.md).
|
||||
|
||||
## Quick navigation
|
||||
|
||||
- [Model selection](#model-selection)
|
||||
- [Execution environment](#execution-environment)
|
||||
- [MCP integration](#mcp-integration)
|
||||
- [Observability and telemetry](#observability-and-telemetry)
|
||||
- [Profiles and overrides](#profiles-and-overrides)
|
||||
- [Reference table](#config-reference)
|
||||
|
||||
Codex supports several mechanisms for setting config values:
|
||||
|
||||
- Config-specific command-line flags, such as `--model o3` (highest precedence).
|
||||
@@ -15,15 +26,17 @@ Codex supports several mechanisms for setting config values:
|
||||
|
||||
Both the `--config` flag and the `config.toml` file support the following options:
|
||||
|
||||
## model
|
||||
## Model selection
|
||||
|
||||
### model
|
||||
|
||||
The model that Codex should use.
|
||||
|
||||
```toml
|
||||
model = "o3" # overrides the default of "gpt-5-codex"
|
||||
model = "gpt-5" # overrides the default of "gpt-5-codex"
|
||||
```
|
||||
|
||||
## model_providers
|
||||
### model_providers
|
||||
|
||||
This option lets you override and amend the default set of model providers bundled with Codex. This value is a map where the key is the value to use with `model_provider` to select the corresponding provider.
|
||||
|
||||
@@ -84,7 +97,7 @@ http_headers = { "X-Example-Header" = "example-value" }
|
||||
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }
|
||||
```
|
||||
|
||||
### Azure model provider example
|
||||
#### Azure model provider example
|
||||
|
||||
Note that Azure requires `api-version` to be passed as a query parameter, so be sure to specify it as part of `query_params` when defining the Azure provider:
|
||||
|
||||
@@ -100,7 +113,7 @@ wire_api = "responses"
|
||||
|
||||
Export your key before launching Codex: `export AZURE_OPENAI_API_KEY=…`
|
||||
|
||||
### Per-provider network tuning
|
||||
#### Per-provider network tuning
|
||||
|
||||
The following optional settings control retry behaviour and streaming idle timeouts **per model provider**. They must be specified inside the corresponding `[model_providers.<id>]` block in `config.toml`. (Older releases accepted top‑level keys; those are now ignored.)
|
||||
|
||||
@@ -117,19 +130,19 @@ stream_max_retries = 10 # retry dropped SSE streams
|
||||
stream_idle_timeout_ms = 300000 # 5m idle timeout
|
||||
```
|
||||
|
||||
#### request_max_retries
|
||||
##### request_max_retries
|
||||
|
||||
How many times Codex will retry a failed HTTP request to the model provider. Defaults to `4`.
|
||||
|
||||
#### stream_max_retries
|
||||
##### stream_max_retries
|
||||
|
||||
Number of times Codex will attempt to reconnect when a streaming response is interrupted. Defaults to `5`.
|
||||
|
||||
#### stream_idle_timeout_ms
|
||||
##### stream_idle_timeout_ms
|
||||
|
||||
How long Codex will wait for activity on a streaming response before treating the connection as lost. Defaults to `300_000` (5 minutes).
|
||||
|
||||
## model_provider
|
||||
### model_provider
|
||||
|
||||
Identifies which provider to use from the `model_providers` map. Defaults to `"openai"`. You can override the `base_url` for the built-in `openai` provider via the `OPENAI_BASE_URL` environment variable.
|
||||
|
||||
@@ -142,7 +155,73 @@ model_provider = "ollama"
|
||||
model = "mistral"
|
||||
```
|
||||
|
||||
## approval_policy
|
||||
### model_reasoning_effort
|
||||
|
||||
If the selected model is known to support reasoning (for example: `o3`, `o4-mini`, `codex-*`, `gpt-5`, `gpt-5-codex`), reasoning is enabled by default when using the Responses API. As explained in the [OpenAI Platform documentation](https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning), this can be set to:
|
||||
|
||||
- `"minimal"`
|
||||
- `"low"`
|
||||
- `"medium"` (default)
|
||||
- `"high"`
|
||||
|
||||
Note: to minimize reasoning, choose `"minimal"`.
|
||||
|
||||
### model_reasoning_summary
|
||||
|
||||
If the model name starts with `"o"` (as in `"o3"` or `"o4-mini"`) or `"codex"`, reasoning is enabled by default when using the Responses API. As explained in the [OpenAI Platform documentation](https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries), this can be set to:
|
||||
|
||||
- `"auto"` (default)
|
||||
- `"concise"`
|
||||
- `"detailed"`
|
||||
|
||||
To disable reasoning summaries, set `model_reasoning_summary` to `"none"` in your config:
|
||||
|
||||
```toml
|
||||
model_reasoning_summary = "none" # disable reasoning summaries
|
||||
```
|
||||
|
||||
### model_verbosity
|
||||
|
||||
Controls output length/detail on GPT‑5 family models when using the Responses API. Supported values:
|
||||
|
||||
- `"low"`
|
||||
- `"medium"` (default when omitted)
|
||||
- `"high"`
|
||||
|
||||
When set, Codex includes a `text` object in the request payload with the configured verbosity, for example: `"text": { "verbosity": "low" }`.
|
||||
|
||||
Example:
|
||||
|
||||
```toml
|
||||
model = "gpt-5"
|
||||
model_verbosity = "low"
|
||||
```
|
||||
|
||||
Note: This applies only to providers using the Responses API. Chat Completions providers are unaffected.
|
||||
|
||||
### model_supports_reasoning_summaries
|
||||
|
||||
By default, `reasoning` is only set on requests to OpenAI models that are known to support them. To force `reasoning` to set on requests to the current model, you can force this behavior by setting the following in `config.toml`:
|
||||
|
||||
```toml
|
||||
model_supports_reasoning_summaries = true
|
||||
```
|
||||
|
||||
### model_context_window
|
||||
|
||||
The size of the context window for the model, in tokens.
|
||||
|
||||
In general, Codex knows the context window for the most common OpenAI models, but if you are using a new model with an old version of the Codex CLI, then you can use `model_context_window` to tell Codex what value to use to determine how much context is left during a conversation.
|
||||
|
||||
### model_max_output_tokens
|
||||
|
||||
This is analogous to `model_context_window`, but for the maximum number of output tokens for the model.
|
||||
|
||||
> See also [`codex exec`](./exec.md) to see how these model settings influence non-interactive runs.
|
||||
|
||||
## Execution environment
|
||||
|
||||
### approval_policy
|
||||
|
||||
Determines when the user should be prompted to approve whether Codex can execute a command:
|
||||
|
||||
@@ -179,104 +258,7 @@ Alternatively, you can have the model run until it is done, and never ask to run
|
||||
approval_policy = "never"
|
||||
```
|
||||
|
||||
## profiles
|
||||
|
||||
A _profile_ is a collection of configuration values that can be set together. Multiple profiles can be defined in `config.toml` and you can specify the one you
|
||||
want to use at runtime via the `--profile` flag.
|
||||
|
||||
Here is an example of a `config.toml` that defines multiple profiles:
|
||||
|
||||
```toml
|
||||
model = "o3"
|
||||
approval_policy = "untrusted"
|
||||
|
||||
# Setting `profile` is equivalent to specifying `--profile o3` on the command
|
||||
# line, though the `--profile` flag can still be used to override this value.
|
||||
profile = "o3"
|
||||
|
||||
[model_providers.openai-chat-completions]
|
||||
name = "OpenAI using Chat Completions"
|
||||
base_url = "https://api.openai.com/v1"
|
||||
env_key = "OPENAI_API_KEY"
|
||||
wire_api = "chat"
|
||||
|
||||
[profiles.o3]
|
||||
model = "o3"
|
||||
model_provider = "openai"
|
||||
approval_policy = "never"
|
||||
model_reasoning_effort = "high"
|
||||
model_reasoning_summary = "detailed"
|
||||
|
||||
[profiles.gpt3]
|
||||
model = "gpt-3.5-turbo"
|
||||
model_provider = "openai-chat-completions"
|
||||
|
||||
[profiles.zdr]
|
||||
model = "o3"
|
||||
model_provider = "openai"
|
||||
approval_policy = "on-failure"
|
||||
```
|
||||
|
||||
Users can specify config values at multiple levels. Order of precedence is as follows:
|
||||
|
||||
1. custom command-line argument, e.g., `--model o3`
|
||||
2. as part of a profile, where the `--profile` is specified via a CLI (or in the config file itself)
|
||||
3. as an entry in `config.toml`, e.g., `model = "o3"`
|
||||
4. the default value that comes with Codex CLI (i.e., Codex CLI defaults to `gpt-5-codex`)
|
||||
|
||||
## model_reasoning_effort
|
||||
|
||||
If the selected model is known to support reasoning (for example: `o3`, `o4-mini`, `codex-*`, `gpt-5`, `gpt-5-codex`), reasoning is enabled by default when using the Responses API. As explained in the [OpenAI Platform documentation](https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning), this can be set to:
|
||||
|
||||
- `"minimal"`
|
||||
- `"low"`
|
||||
- `"medium"` (default)
|
||||
- `"high"`
|
||||
|
||||
Note: to minimize reasoning, choose `"minimal"`.
|
||||
|
||||
## model_reasoning_summary
|
||||
|
||||
If the model name starts with `"o"` (as in `"o3"` or `"o4-mini"`) or `"codex"`, reasoning is enabled by default when using the Responses API. As explained in the [OpenAI Platform documentation](https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries), this can be set to:
|
||||
|
||||
- `"auto"` (default)
|
||||
- `"concise"`
|
||||
- `"detailed"`
|
||||
|
||||
To disable reasoning summaries, set `model_reasoning_summary` to `"none"` in your config:
|
||||
|
||||
```toml
|
||||
model_reasoning_summary = "none" # disable reasoning summaries
|
||||
```
|
||||
|
||||
## model_verbosity
|
||||
|
||||
Controls output length/detail on GPT‑5 family models when using the Responses API. Supported values:
|
||||
|
||||
- `"low"`
|
||||
- `"medium"` (default when omitted)
|
||||
- `"high"`
|
||||
|
||||
When set, Codex includes a `text` object in the request payload with the configured verbosity, for example: `"text": { "verbosity": "low" }`.
|
||||
|
||||
Example:
|
||||
|
||||
```toml
|
||||
model = "gpt-5"
|
||||
model_verbosity = "low"
|
||||
```
|
||||
|
||||
Note: This applies only to providers using the Responses API. Chat Completions providers are unaffected.
|
||||
|
||||
## model_supports_reasoning_summaries
|
||||
|
||||
By default, `reasoning` is only set on requests to OpenAI models that are known to support them. To force `reasoning` to set on requests to the current model, you can force this behavior by setting the following in `config.toml`:
|
||||
|
||||
```toml
|
||||
model_supports_reasoning_summaries = true
|
||||
```
|
||||
|
||||
## sandbox_mode
|
||||
### sandbox_mode
|
||||
|
||||
Codex executes model-generated shell commands inside an OS-level sandbox.
|
||||
|
||||
@@ -325,7 +307,7 @@ This is reasonable to use if Codex is running in an environment that provides it
|
||||
|
||||
Though using this option may also be necessary if you try to use Codex in environments where its native sandboxing mechanisms are unsupported, such as older Linux kernels or on Windows.
|
||||
|
||||
## Approval presets
|
||||
### approval_presets
|
||||
|
||||
Codex provides three main Approval Presets:
|
||||
|
||||
@@ -335,123 +317,9 @@ 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.
|
||||
|
||||
## Connecting to MCP servers
|
||||
> See also [Sandbox & approvals](./sandbox.md) for in-depth examples and platform-specific behaviour.
|
||||
|
||||
You can configure Codex to use [MCP servers](https://modelcontextprotocol.io/about) to give Codex access to external applications, resources, or services.
|
||||
|
||||
### Server configuration
|
||||
|
||||
#### STDIO
|
||||
|
||||
[STDIO servers](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) are MCP servers that you can launch directly via commands on your computer.
|
||||
|
||||
```toml
|
||||
# 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" }
|
||||
# or
|
||||
[mcp_servers.server_name.env]
|
||||
API_KEY = "value"
|
||||
# Optional: Additional list of environment variables that will be whitelisted in the MCP server's environment.
|
||||
env_vars = ["API_KEY2"]
|
||||
|
||||
# Optional: cwd that the command will be run from
|
||||
cwd = "/Users/<user>/code/my-server"
|
||||
```
|
||||
|
||||
#### Streamable HTTP
|
||||
|
||||
[Streamable HTTP servers](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) enable Codex to talk to resources that are accessed via a http url (either on localhost or another domain).
|
||||
|
||||
```toml
|
||||
# Streamable HTTP requires the experimental rmcp client
|
||||
experimental_use_rmcp_client = true
|
||||
[mcp_servers.figma]
|
||||
url = "https://mcp.linear.app/mcp"
|
||||
# Optional environment variable containing a bearer token to use for auth
|
||||
bearer_token_env_var = "<token>"
|
||||
# Optional map of headers with hard-coded values.
|
||||
http_headers = { "HEADER_NAME" = "HEADER_VALUE" }
|
||||
# Optional map of headers whose values will be replaced with the environment variable.
|
||||
env_http_headers = { "HEADER_NAME" = "ENV_VAR" }
|
||||
```
|
||||
|
||||
For oauth login, you must enable `experimental_use_rmcp_client = true` and then run `codex mcp login server_name`
|
||||
|
||||
### Other configuration options
|
||||
|
||||
```toml
|
||||
# Optional: override the default 10s startup timeout
|
||||
startup_timeout_sec = 20
|
||||
# Optional: override the default 60s per-tool timeout
|
||||
tool_timeout_sec = 30
|
||||
# Optional: disable a server without removing it
|
||||
enabled = false
|
||||
```
|
||||
|
||||
### Experimental RMCP client
|
||||
|
||||
Codex is transitioning to the [official Rust MCP SDK](https://github.com/modelcontextprotocol/rust-sdk).
|
||||
|
||||
The flag enabled OAuth support for streamable HTTP servers and uses a new STDIO client implementation.
|
||||
|
||||
Please try and report issues with the new client. To enable it, add this to the top level of your `config.toml`
|
||||
|
||||
```toml
|
||||
experimental_use_rmcp_client = true
|
||||
|
||||
[mcp_servers.server_name]
|
||||
…
|
||||
```
|
||||
|
||||
### MCP CLI commands
|
||||
|
||||
```shell
|
||||
# List all available commands
|
||||
codex mcp --help
|
||||
|
||||
# Add a server (env can be repeated; `--` separates the launcher command)
|
||||
codex mcp add docs -- docs-server --port 4000
|
||||
|
||||
# List configured servers (pretty table or JSON)
|
||||
codex mcp list
|
||||
codex mcp list --json
|
||||
|
||||
# Show one server (table or JSON)
|
||||
codex mcp get docs
|
||||
codex mcp get docs --json
|
||||
|
||||
# Remove a server
|
||||
codex mcp remove docs
|
||||
|
||||
# Log in to a streamable HTTP server that supports oauth
|
||||
codex mcp login SERVER_NAME
|
||||
|
||||
# Log out from a streamable HTTP server that supports oauth
|
||||
codex mcp logout SERVER_NAME
|
||||
```
|
||||
|
||||
## Examples of useful MCPs
|
||||
|
||||
There is an ever growing list of useful MCP servers that can be helpful while you are working with Codex.
|
||||
|
||||
Some of the most common MCPs we've seen are:
|
||||
|
||||
- [Context7](https://github.com/upstash/context7) — connect to a wide range of up-to-date developer documentation
|
||||
- Figma [Local](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/) and [Remote](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) - access to your Figma designs
|
||||
- [Playwright](https://www.npmjs.com/package/@playwright/mcp) - control and inspect a browser using Playwright
|
||||
- [Chrome Developer Tools](https://github.com/ChromeDevTools/chrome-devtools-mcp/) — control and inspect a Chrome browser
|
||||
- [Sentry](https://docs.sentry.io/product/sentry-mcp/#codex) — access to your Sentry logs
|
||||
- [GitHub](https://github.com/github/github-mcp-server) — Control over your GitHub account beyond what git allows (like controlling PRs, issues, etc.)
|
||||
|
||||
## shell_environment_policy
|
||||
### shell_environment_policy
|
||||
|
||||
Codex spawns subprocesses (e.g. when executing a `local_shell` tool-call suggested by the assistant). By default it now passes **your full environment** to those subprocesses. You can tune this behavior via the **`shell_environment_policy`** block in `config.toml`:
|
||||
|
||||
@@ -493,7 +361,127 @@ 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
|
||||
## MCP integration
|
||||
|
||||
### mcp_servers
|
||||
|
||||
You can configure Codex to use [MCP servers](https://modelcontextprotocol.io/about) to give Codex access to external applications, resources, or services.
|
||||
|
||||
#### Server configuration
|
||||
|
||||
##### STDIO
|
||||
|
||||
[STDIO servers](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) are MCP servers that you can launch directly via commands on your computer.
|
||||
|
||||
```toml
|
||||
# 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" }
|
||||
# or
|
||||
[mcp_servers.server_name.env]
|
||||
API_KEY = "value"
|
||||
# Optional: Additional list of environment variables that will be whitelisted in the MCP server's environment.
|
||||
env_vars = ["API_KEY2"]
|
||||
|
||||
# Optional: cwd that the command will be run from
|
||||
cwd = "/Users/<user>/code/my-server"
|
||||
```
|
||||
|
||||
##### Streamable HTTP
|
||||
|
||||
[Streamable HTTP servers](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) enable Codex to talk to resources that are accessed via a http url (either on localhost or another domain).
|
||||
|
||||
```toml
|
||||
# Streamable HTTP requires the experimental rmcp client
|
||||
experimental_use_rmcp_client = true
|
||||
[mcp_servers.figma]
|
||||
url = "https://mcp.linear.app/mcp"
|
||||
# Optional environment variable containing a bearer token to use for auth
|
||||
bearer_token_env_var = "<token>"
|
||||
# Optional map of headers with hard-coded values.
|
||||
http_headers = { "HEADER_NAME" = "HEADER_VALUE" }
|
||||
# Optional map of headers whose values will be replaced with the environment variable.
|
||||
env_http_headers = { "HEADER_NAME" = "ENV_VAR" }
|
||||
```
|
||||
|
||||
For oauth login, you must enable `experimental_use_rmcp_client = true` and then run `codex mcp login server_name`
|
||||
|
||||
#### Other configuration options
|
||||
|
||||
```toml
|
||||
# Optional: override the default 10s startup timeout
|
||||
startup_timeout_sec = 20
|
||||
# Optional: override the default 60s per-tool timeout
|
||||
tool_timeout_sec = 30
|
||||
# Optional: disable a server without removing it
|
||||
enabled = false
|
||||
```
|
||||
|
||||
#### Experimental RMCP client
|
||||
|
||||
Codex is transitioning to the [official Rust MCP SDK](https://github.com/modelcontextprotocol/rust-sdk).
|
||||
|
||||
The flag enabled OAuth support for streamable HTTP servers and uses a new STDIO client implementation.
|
||||
|
||||
Please try and report issues with the new client. To enable it, add this to the top level of your `config.toml`
|
||||
|
||||
```toml
|
||||
experimental_use_rmcp_client = true
|
||||
|
||||
[mcp_servers.server_name]
|
||||
…
|
||||
```
|
||||
|
||||
#### MCP CLI commands
|
||||
|
||||
```shell
|
||||
# List all available commands
|
||||
codex mcp --help
|
||||
|
||||
# Add a server (env can be repeated; `--` separates the launcher command)
|
||||
codex mcp add docs -- docs-server --port 4000
|
||||
|
||||
# List configured servers (pretty table or JSON)
|
||||
codex mcp list
|
||||
codex mcp list --json
|
||||
|
||||
# Show one server (table or JSON)
|
||||
codex mcp get docs
|
||||
codex mcp get docs --json
|
||||
|
||||
# Remove a server
|
||||
codex mcp remove docs
|
||||
|
||||
# Log in to a streamable HTTP server that supports oauth
|
||||
codex mcp login SERVER_NAME
|
||||
|
||||
# Log out from a streamable HTTP server that supports oauth
|
||||
codex mcp logout SERVER_NAME
|
||||
```
|
||||
|
||||
### Examples of useful MCPs
|
||||
|
||||
There is an ever growing list of useful MCP servers that can be helpful while you are working with Codex.
|
||||
|
||||
Some of the most common MCPs we've seen are:
|
||||
|
||||
- [Context7](https://github.com/upstash/context7) — connect to a wide range of up-to-date developer documentation
|
||||
- Figma [Local](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/) and [Remote](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) - access to your Figma designs
|
||||
- [Playwright](https://www.npmjs.com/package/@playwright/mcp) - control and inspect a browser using Playwright
|
||||
- [Chrome Developer Tools](https://github.com/ChromeDevTools/chrome-devtools-mcp/) — control and inspect a Chrome browser
|
||||
- [Sentry](https://docs.sentry.io/product/sentry-mcp/#codex) — access to your Sentry logs
|
||||
- [GitHub](https://github.com/github/github-mcp-server) — Control over your GitHub account beyond what git allows (like controlling PRs, issues, etc.)
|
||||
|
||||
## Observability and telemetry
|
||||
|
||||
### otel
|
||||
|
||||
Codex can emit [OpenTelemetry](https://opentelemetry.io/) **log events** that
|
||||
describe each run: outbound API requests, streamed responses, user input,
|
||||
@@ -604,7 +592,7 @@ 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
|
||||
### 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.:
|
||||
|
||||
@@ -689,7 +677,79 @@ notify = ["python3", "/Users/mbolin/.codex/notify.py"]
|
||||
> [!NOTE]
|
||||
> Use `notify` for automation and integrations: Codex invokes your external program with a single JSON argument for each event, independent of the TUI. If you only want lightweight desktop notifications while using the TUI, prefer `tui.notifications`, which uses terminal escape codes and requires no external program. You can enable both; `tui.notifications` covers in‑TUI alerts (e.g., approval prompts), while `notify` is best for system‑level hooks or custom notifiers. Currently, `notify` emits only `agent-turn-complete`, whereas `tui.notifications` supports `agent-turn-complete` and `approval-requested` with optional filtering.
|
||||
|
||||
## history
|
||||
### hide_agent_reasoning
|
||||
|
||||
Codex intermittently emits "reasoning" events that show the model's internal "thinking" before it produces a final answer. Some users may find these events distracting, especially in CI logs or minimal terminal output.
|
||||
|
||||
Setting `hide_agent_reasoning` to `true` suppresses these events in **both** the TUI as well as the headless `exec` sub-command:
|
||||
|
||||
```toml
|
||||
hide_agent_reasoning = true # defaults to false
|
||||
```
|
||||
|
||||
### show_raw_agent_reasoning
|
||||
|
||||
Surfaces the model’s raw chain-of-thought ("raw reasoning content") when available.
|
||||
|
||||
Notes:
|
||||
|
||||
- Only takes effect if the selected model/provider actually emits raw reasoning content. Many models do not. When unsupported, this option has no visible effect.
|
||||
- Raw reasoning may include intermediate thoughts or sensitive context. Enable only if acceptable for your workflow.
|
||||
|
||||
Example:
|
||||
|
||||
```toml
|
||||
show_raw_agent_reasoning = true # defaults to false
|
||||
```
|
||||
|
||||
## Profiles and overrides
|
||||
|
||||
### profiles
|
||||
|
||||
A _profile_ is a collection of configuration values that can be set together. Multiple profiles can be defined in `config.toml` and you can specify the one you
|
||||
want to use at runtime via the `--profile` flag.
|
||||
|
||||
Here is an example of a `config.toml` that defines multiple profiles:
|
||||
|
||||
```toml
|
||||
model = "o3"
|
||||
approval_policy = "untrusted"
|
||||
|
||||
# Setting `profile` is equivalent to specifying `--profile o3` on the command
|
||||
# line, though the `--profile` flag can still be used to override this value.
|
||||
profile = "o3"
|
||||
|
||||
[model_providers.openai-chat-completions]
|
||||
name = "OpenAI using Chat Completions"
|
||||
base_url = "https://api.openai.com/v1"
|
||||
env_key = "OPENAI_API_KEY"
|
||||
wire_api = "chat"
|
||||
|
||||
[profiles.o3]
|
||||
model = "o3"
|
||||
model_provider = "openai"
|
||||
approval_policy = "never"
|
||||
model_reasoning_effort = "high"
|
||||
model_reasoning_summary = "detailed"
|
||||
|
||||
[profiles.gpt3]
|
||||
model = "gpt-3.5-turbo"
|
||||
model_provider = "openai-chat-completions"
|
||||
|
||||
[profiles.zdr]
|
||||
model = "o3"
|
||||
model_provider = "openai"
|
||||
approval_policy = "on-failure"
|
||||
```
|
||||
|
||||
Users can specify config values at multiple levels. Order of precedence is as follows:
|
||||
|
||||
1. custom command-line argument, e.g., `--model o3`
|
||||
2. as part of a profile, where the `--profile` is specified via a CLI (or in the config file itself)
|
||||
3. as an entry in `config.toml`, e.g., `model = "o3"`
|
||||
4. the default value that comes with Codex CLI (i.e., Codex CLI defaults to `gpt-5-codex`)
|
||||
|
||||
### history
|
||||
|
||||
By default, Codex CLI records messages sent to the model in `$CODEX_HOME/history.jsonl`. Note that on UNIX, the file permissions are set to `o600`, so it should only be readable and writable by the owner.
|
||||
|
||||
@@ -700,7 +760,7 @@ To disable this behavior, configure `[history]` as follows:
|
||||
persistence = "none" # "save-all" is the default value
|
||||
```
|
||||
|
||||
## file_opener
|
||||
### file_opener
|
||||
|
||||
Identifies the editor/URI scheme to use for hyperlinking citations in model output. If set, citations to files in the model output will be hyperlinked using the specified URI scheme so they can be ctrl/cmd-clicked from the terminal to open them.
|
||||
|
||||
@@ -716,46 +776,11 @@ Note this is **not** a general editor setting (like `$EDITOR`), as it only accep
|
||||
|
||||
Currently, `"vscode"` is the default, though Codex does not verify VS Code is installed. As such, `file_opener` may default to `"none"` or something else in the future.
|
||||
|
||||
## hide_agent_reasoning
|
||||
|
||||
Codex intermittently emits "reasoning" events that show the model's internal "thinking" before it produces a final answer. Some users may find these events distracting, especially in CI logs or minimal terminal output.
|
||||
|
||||
Setting `hide_agent_reasoning` to `true` suppresses these events in **both** the TUI as well as the headless `exec` sub-command:
|
||||
|
||||
```toml
|
||||
hide_agent_reasoning = true # defaults to false
|
||||
```
|
||||
|
||||
## show_raw_agent_reasoning
|
||||
|
||||
Surfaces the model’s raw chain-of-thought ("raw reasoning content") when available.
|
||||
|
||||
Notes:
|
||||
|
||||
- Only takes effect if the selected model/provider actually emits raw reasoning content. Many models do not. When unsupported, this option has no visible effect.
|
||||
- Raw reasoning may include intermediate thoughts or sensitive context. Enable only if acceptable for your workflow.
|
||||
|
||||
Example:
|
||||
|
||||
```toml
|
||||
show_raw_agent_reasoning = true # defaults to false
|
||||
```
|
||||
|
||||
## model_context_window
|
||||
|
||||
The size of the context window for the model, in tokens.
|
||||
|
||||
In general, Codex knows the context window for the most common OpenAI models, but if you are using a new model with an old version of the Codex CLI, then you can use `model_context_window` to tell Codex what value to use to determine how much context is left during a conversation.
|
||||
|
||||
## model_max_output_tokens
|
||||
|
||||
This is analogous to `model_context_window`, but for the maximum number of output tokens for the model.
|
||||
|
||||
## project_doc_max_bytes
|
||||
### project_doc_max_bytes
|
||||
|
||||
Maximum number of bytes to read from an `AGENTS.md` file to include in the instructions sent with the first turn of a session. Defaults to 32 KiB.
|
||||
|
||||
## project_doc_fallback_filenames
|
||||
### project_doc_fallback_filenames
|
||||
|
||||
Ordered list of additional filenames to look for when `AGENTS.md` is missing at a given directory level. The CLI always checks `AGENTS.md` first; the configured fallbacks are tried in the order provided. This lets monorepos that already use alternate instruction files (for example, `CLAUDE.md`) work out of the box while you migrate to `AGENTS.md` over time.
|
||||
|
||||
@@ -765,7 +790,9 @@ project_doc_fallback_filenames = ["CLAUDE.md", ".exampleagentrules.md"]
|
||||
|
||||
We recommend migrating instructions to AGENTS.md; other filenames may reduce model performance.
|
||||
|
||||
## tui
|
||||
> See also [AGENTS.md discovery](./agents_md.md) for how Codex locates these files during a session.
|
||||
|
||||
### tui
|
||||
|
||||
Options that are specific to the TUI.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user