diff --git a/.github/codex-cli-login.png b/.github/codex-cli-login.png deleted file mode 100644 index 0d4543ee1a..0000000000 Binary files a/.github/codex-cli-login.png and /dev/null differ diff --git a/.github/codex-cli-permissions.png b/.github/codex-cli-permissions.png deleted file mode 100644 index bb48e4a53b..0000000000 Binary files a/.github/codex-cli-permissions.png and /dev/null differ diff --git a/.github/codex-cli-splash.png b/.github/codex-cli-splash.png index 06e625ca4a..d0f50e55bd 100644 Binary files a/.github/codex-cli-splash.png and b/.github/codex-cli-splash.png differ diff --git a/.github/demo.gif b/.github/demo.gif deleted file mode 100644 index 12752744c6..0000000000 Binary files a/.github/demo.gif and /dev/null differ diff --git a/README.md b/README.md index 78eaf9eb35..202ab0620a 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,11 @@

npm i -g @openai/codex
or brew install --cask codex

-

Codex CLI is a coding agent from OpenAI that runs locally on your computer. -
-
If you want Codex in your code editor (VS Code, Cursor, Windsurf), install in your IDE -
If you are looking for the cloud-based agent from OpenAI, Codex Web, go to chatgpt.com/codex

-

Codex CLI splash -

+

+
+If you want Codex in your code editor (VS Code, Cursor, Windsurf), install in your IDE. +
If you are looking for the cloud-based agent from OpenAI, Codex Web, go to chatgpt.com/codex.

--- @@ -15,25 +13,19 @@ ### Installing and running Codex CLI -Install globally with your preferred package manager. If you use npm: +Install globally with your preferred package manager: ```shell +# Install using npm npm install -g @openai/codex ``` -Alternatively, if you use Homebrew: - ```shell +# Install using Homebrew brew install --cask codex ``` -Then simply run `codex` to get started: - -```shell -codex -``` - -If you're running into upgrade issues with Homebrew, see the [FAQ entry on brew upgrade codex](./docs/faq.md#brew-upgrade-codex-isnt-upgrading-me). +Then simply run `codex` to get started.
You can also go to the latest GitHub Release and download the appropriate binary for your platform. @@ -53,60 +45,15 @@ Each archive contains a single entry with the platform baked into the name (e.g. ### Using Codex with your ChatGPT plan -

- Codex CLI login -

- Run `codex` and select **Sign in with ChatGPT**. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. [Learn more about what's included in your ChatGPT plan](https://help.openai.com/en/articles/11369540-codex-in-chatgpt). You can also use Codex with an API key, but this requires [additional setup](./docs/authentication.md#usage-based-billing-alternative-use-an-openai-api-key). If you previously used an API key for usage-based billing, see the [migration steps](./docs/authentication.md#migrating-from-usage-based-billing-api-key). If you're having trouble with login, please comment on [this issue](https://github.com/openai/codex/issues/1243). -### Model Context Protocol (MCP) +## Docs -Codex can access MCP servers. To configure them, refer to the [config docs](./docs/config.md#mcp_servers). - -### Configuration - -Codex CLI supports a rich set of configuration options, with preferences stored in `~/.codex/config.toml`. For full configuration options, see [Configuration](./docs/config.md). - -### Execpolicy - -See the [Execpolicy quickstart](./docs/execpolicy.md) to set up rules that govern what commands Codex can execute. - -### Docs & FAQ - -- [**Getting started**](./docs/getting-started.md) - - [CLI usage](./docs/getting-started.md#cli-usage) - - [Slash Commands](./docs/slash_commands.md) - - [Running with a prompt as input](./docs/getting-started.md#running-with-a-prompt-as-input) - - [Example prompts](./docs/getting-started.md#example-prompts) - - [Custom prompts](./docs/prompts.md) - - [Memory with AGENTS.md](./docs/getting-started.md#memory-with-agentsmd) -- [**Configuration**](./docs/config.md) - - [Example config](./docs/example-config.md) -- [**Sandbox & approvals**](./docs/sandbox.md) -- [**Execpolicy quickstart**](./docs/execpolicy.md) -- [**Authentication**](./docs/authentication.md) - - [Auth methods](./docs/authentication.md#forcing-a-specific-auth-method-advanced) - - [Login on a "Headless" machine](./docs/authentication.md#connecting-on-a-headless-machine) -- **Automating Codex** - - [GitHub Action](https://github.com/openai/codex-action) - - [TypeScript SDK](./sdk/typescript/README.md) - - [Non-interactive mode (`codex exec`)](./docs/exec.md) -- [**Advanced**](./docs/advanced.md) - - [Tracing / verbose logging](./docs/advanced.md#tracing--verbose-logging) - - [Model Context Protocol (MCP)](./docs/advanced.md#model-context-protocol-mcp) -- [**Zero data retention (ZDR)**](./docs/zdr.md) +- [**Codex Documentation**](https://developers.openai.com/codex) - [**Contributing**](./docs/contributing.md) -- [**Install & build**](./docs/install.md) - - [System Requirements](./docs/install.md#system-requirements) - - [DotSlash](./docs/install.md#dotslash) - - [Build from source](./docs/install.md#build-from-source) -- [**FAQ**](./docs/faq.md) +- [**Installing & building**](./docs/install.md) - [**Open source fund**](./docs/open-source-fund.md) ---- - -## License - This repository is licensed under the [Apache-2.0 License](LICENSE). diff --git a/docs/advanced.md b/docs/advanced.md deleted file mode 100644 index 26ffca8a92..0000000000 --- a/docs/advanced.md +++ /dev/null @@ -1,74 +0,0 @@ -## Advanced - -If you already lean on Codex every day and just need a little more control, this page collects the knobs you are most likely to reach for: tweak defaults in [Config](./config.md), add extra tools through [Model Context Protocol support](#model-context-protocol), and script full runs with [`codex exec`](./exec.md). Jump to the section you need and keep building. - -## Config quickstart - -Most day-to-day tuning lives in `config.toml`: set approval + sandbox presets, pin model defaults, and add MCP server launchers. The [Config guide](./config.md) walks through every option and provides copy-paste examples for common setups. - -## Tracing / verbose logging - -Because Codex is written in Rust, it honors the `RUST_LOG` environment variable to configure its logging behavior. - -The TUI defaults to `RUST_LOG=codex_core=info,codex_tui=info,codex_rmcp_client=info` and log messages are written to `~/.codex/log/codex-tui.log`, so you can leave the following running in a separate terminal to monitor log messages as they are written: - -```bash -tail -F ~/.codex/log/codex-tui.log -``` - -By comparison, the non-interactive mode (`codex exec`) defaults to `RUST_LOG=error`, but messages are printed inline, so there is no need to monitor a separate file. - -See the Rust documentation on [`RUST_LOG`](https://docs.rs/env_logger/latest/env_logger/#enabling-logging) for more information on the configuration options. - -## Model Context Protocol (MCP) - -The Codex CLI and IDE extension is a MCP client which means that it can be configured to connect to MCP servers. For more information, refer to the [`config docs`](./config.md#mcp-integration). - -## Using Codex as an MCP Server - -The Codex CLI can also be run as an MCP _server_ via `codex mcp-server`. For example, you can use `codex mcp-server` to make Codex available as a tool inside of a multi-agent framework like the OpenAI [Agents SDK](https://platform.openai.com/docs/guides/agents). Use `codex mcp` separately to add/list/get/remove MCP server launchers in your configuration. - -### Codex MCP Server Quickstart - -You can launch a Codex MCP server with the [Model Context Protocol Inspector](https://modelcontextprotocol.io/legacy/tools/inspector): - -```bash -npx @modelcontextprotocol/inspector codex mcp-server -``` - -Send a `tools/list` request and you will see that there are two tools available: - -**`codex`** - Run a Codex session. Accepts configuration parameters matching the Codex Config struct. The `codex` tool takes the following properties: - -| Property | Type | Description | -| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **`prompt`** (required) | string | The initial user prompt to start the Codex conversation. | -| `approval-policy` | string | Approval policy for shell commands generated by the model: `untrusted`, `on-failure`, `on-request`, `never`. | -| `base-instructions` | string | The set of instructions to use instead of the default ones. | -| `config` | object | Individual [config settings](https://github.com/openai/codex/blob/main/docs/config.md#config) that will override what is in `$CODEX_HOME/config.toml`. | -| `cwd` | string | Working directory for the session. If relative, resolved against the server process's current directory. | -| `model` | string | Optional override for the model name (e.g. `o3`, `o4-mini`). | -| `profile` | string | Configuration profile from `config.toml` to specify default options. | -| `sandbox` | string | Sandbox mode: `read-only`, `workspace-write`, or `danger-full-access`. | - -**`codex-reply`** - Continue a Codex session by providing the conversation id and prompt. The `codex-reply` tool takes the following properties: - -| Property | Type | Description | -| ------------------------------- | ------ | -------------------------------------------------------- | -| **`prompt`** (required) | string | The next user prompt to continue the Codex conversation. | -| **`conversationId`** (required) | string | The id of the conversation to continue. | - -### Trying it Out - -> [!TIP] -> Codex often takes a few minutes to run. To accommodate this, adjust the MCP inspector's Request and Total timeouts to 600000ms (10 minutes) under ⛭ Configuration. - -Use the MCP inspector and `codex mcp-server` to build a simple tic-tac-toe game with the following settings: - -**approval-policy:** never - -**prompt:** Implement a simple tic-tac-toe game with HTML, JavaScript, and CSS. Write the game in a single file called index.html. - -**sandbox:** workspace-write - -Click "Run Tool" and you should see a list of events emitted from the Codex MCP server as it builds the game. diff --git a/docs/agents_md.md b/docs/agents_md.md index ff2243a0ca..4fa02abd1d 100644 --- a/docs/agents_md.md +++ b/docs/agents_md.md @@ -1,50 +1,3 @@ -# AGENTS.md Discovery +# AGENTS.md -Codex uses [`AGENTS.md`](https://agents.md/) files to gather helpful guidance before it starts assisting you. This page explains how those files are discovered and combined, so you can decide where to place your instructions. - -## Global Instructions (`~/.codex`) - -- Codex looks for global guidance in your Codex home directory (usually `~/.codex`; set `CODEX_HOME` to change it). For a quick overview, see the [Memory with AGENTS.md section](../docs/getting-started.md#memory-with-agentsmd) in the getting started guide. -- If an `AGENTS.override.md` file exists there, it takes priority. If not, Codex falls back to `AGENTS.md`. -- Only the first non-empty file is used. Other filenames, such as `instructions.md`, have no effect unless Codex is specifically instructed to use them. -- Whatever Codex finds here stays active for the whole session, and Codex combines it with any project-specific instructions it discovers. - -## Project Instructions (per-repository) - -When you work inside a project, Codex builds on those global instructions by collecting project docs: - -- The search starts at the repository root and continues down to your current directory. If a Git root is not found, only the current directory is checked. -- In each directory along that path, Codex looks for `AGENTS.override.md` first, then `AGENTS.md`, and then any fallback names listed in your Codex configuration (see [`project_doc_fallback_filenames`](../docs/config.md#project_doc_fallback_filenames)). At most one file per directory is included. -- Files are read in order from root to leaf and joined together with blank lines. Empty files are skipped, and very large files are truncated once the combined size reaches 32 KiB (the default [`project_doc_max_bytes`](../docs/config.md#project_doc_max_bytes) limit). If you need more space, split guidance across nested directories or raise the limit in your configuration. - -## How They Come Together - -Before Codex gets to work, the instructions are ingested in precedence order: global guidance from `~/.codex` comes first, then each project doc from the repository root down to your current directory. Guidance in deeper directories overrides earlier layers, so the most specific file controls the final behavior. - -### Priority Summary - -1. Global `AGENTS.override.md` (if present), otherwise global `AGENTS.md`. -2. For each directory from the repository root to your working directory: `AGENTS.override.md`, then `AGENTS.md`, then configured fallback names. - -Only these filenames are considered. To use a different name, add it to the fallback list in your Codex configuration or rename the file accordingly. - -## Fallback Filenames - -Codex can look for additional instruction filenames beyond the two defaults if you add them to `project_doc_fallback_filenames` in your Codex configuration. Each fallback is checked after `AGENTS.override.md` and `AGENTS.md` in every directory along the search path. - -Example: suppose your configuration lists `["TEAM_GUIDE.md", ".agents.md"]`. Inside each directory Codex will look in this order: - -1. `AGENTS.override.md` -2. `AGENTS.md` -3. `TEAM_GUIDE.md` -4. `.agents.md` - -If the repository root contains `TEAM_GUIDE.md` and the `backend/` directory contains `AGENTS.override.md`, the overall instructions will combine the root `TEAM_GUIDE.md` (because no override or default file was present there) with the `backend/AGENTS.override.md` file (which takes precedence over the fallback names). - -You can configure those fallbacks in `~/.codex/config.toml` (or another profile) like this: - -```toml -project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] -``` - -For additional configuration details, see [Config](../docs/config.md) and revisit the [Memory with AGENTS.md guide](../docs/getting-started.md#memory-with-agentsmd) for practical usage tips. +For information about AGENTS.md, see [this documentation](https://developers.openai.com/codex/guides/agents-md). diff --git a/docs/authentication.md b/docs/authentication.md index 617161f648..c307349766 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,68 +1,3 @@ # Authentication -## Usage-based billing alternative: Use an OpenAI API key - -If you prefer to pay-as-you-go, you can still authenticate with your OpenAI API key: - -```shell -printenv OPENAI_API_KEY | codex login --with-api-key -``` - -Alternatively, read from a file: - -```shell -codex login --with-api-key < my_key.txt -``` - -The legacy `--api-key` flag now exits with an error instructing you to use `--with-api-key` so that the key never appears in shell history or process listings. - -This key must, at minimum, have write access to the Responses API. - -## Migrating to ChatGPT login from API key - -If you've used the Codex CLI before with usage-based billing via an API key and want to switch to using your ChatGPT plan, follow these steps: - -1. Update the CLI and ensure `codex --version` is `0.20.0` or later -2. Delete `~/.codex/auth.json` (on Windows: `C:\\Users\\USERNAME\\.codex\\auth.json`) -3. Run `codex login` again - -## Connecting on a "Headless" Machine - -Today, the login process entails running a server on `localhost:1455`. If you are on a "headless" server, such as a Docker container or are `ssh`'d into a remote machine, loading `localhost:1455` in the browser on your local machine will not automatically connect to the webserver running on the _headless_ machine, so you must use one of the following workarounds: - -### Authenticate locally and copy your credentials to the "headless" machine - -The easiest solution is likely to run through the `codex login` process on your local machine such that `localhost:1455` _is_ accessible in your web browser. When you complete the authentication process, an `auth.json` file should be available at `$CODEX_HOME/auth.json` (on Mac/Linux, `$CODEX_HOME` defaults to `~/.codex` whereas on Windows, it defaults to `%USERPROFILE%\\.codex`). - -Because the `auth.json` file is not tied to a specific host, once you complete the authentication flow locally, you can copy the `$CODEX_HOME/auth.json` file to the headless machine and then `codex` should "just work" on that machine. Note to copy a file to a Docker container, you can do: - -```shell -# substitute MY_CONTAINER with the name or id of your Docker container: -CONTAINER_HOME=$(docker exec MY_CONTAINER printenv HOME) -docker exec MY_CONTAINER mkdir -p "$CONTAINER_HOME/.codex" -docker cp auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json" -``` - -whereas if you are `ssh`'d into a remote machine, you likely want to use [`scp`](https://en.wikipedia.org/wiki/Secure_copy_protocol): - -```shell -ssh user@remote 'mkdir -p ~/.codex' -scp ~/.codex/auth.json user@remote:~/.codex/auth.json -``` - -or try this one-liner: - -```shell -ssh user@remote 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json -``` - -### Connecting through VPS or remote - -If you run Codex on a remote machine (VPS/server) without a local browser, the login helper starts a server on `localhost:1455` on the remote host. To complete login in your local browser, forward that port to your machine before starting the login flow: - -```bash -# From your local machine -ssh -L 1455:localhost:1455 @ -``` - -Then, in that SSH session, run `codex` and select "Sign in with ChatGPT". When prompted, open the printed URL (it will be `http://localhost:1455/...`) in your local browser. The traffic will be tunneled to the remote server. +For information about Codex CLI authentication, see [this documentation](https://developers.openai.com/codex/auth). diff --git a/docs/config.md b/docs/config.md index 8452a831e2..950a631fc5 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,1071 +1,7 @@ -# Config +# Configuration -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). +For basic configuration instructions, see [this documentation](https://developers.openai.com/codex/config-basic). -## Quick navigation +For advanced configuration instructions, see [this documentation](https://developers.openai.com/codex/config-advanced). -- [Feature flags](#feature-flags) -- [Model selection](#model-selection) -- [Execution environment](#execution-environment) -- [Project root detection](#project-root-detection) -- [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). -- A generic `-c`/`--config` flag that takes a `key=value` pair, such as `--config model="o3"`. - - The key can contain dots to set a value deeper than the root, e.g. `--config model_providers.openai.wire_api="chat"`. - - For consistency with `config.toml`, values are a string in TOML format rather than JSON format, so use `key='{a = 1, b = 2}'` rather than `key='{"a": 1, "b": 2}'`. - - The quotes around the value are necessary, as without them your shell would split the config argument on spaces, resulting in `codex` receiving `-c key={a` with (invalid) additional arguments `=`, `1,`, `b`, `=`, `2}`. - - Values can contain any TOML object, such as `--config shell_environment_policy.include_only='["PATH", "HOME", "USER"]'`. - - If `value` cannot be parsed as a valid TOML value, it is treated as a string value. This means that `-c model='"o3"'` and `-c model=o3` are equivalent. - - In the first case, the value is the TOML string `"o3"`, while in the second the value is `o3`, which is not valid TOML and therefore treated as the TOML string `"o3"`. - - Because quotes are interpreted by one's shell, `-c key="true"` will be correctly interpreted in TOML as `key = true` (a boolean) and not `key = "true"` (a string). If for some reason you needed the string `"true"`, you would need to use `-c key='"true"'` (note the two sets of quotes). -- The `$CODEX_HOME/config.toml` configuration file where the `CODEX_HOME` environment value defaults to `~/.codex`. (Note `CODEX_HOME` will also be where logs and other Codex-related information are stored.) - -Both the `--config` flag and the `config.toml` file support the following options: - -## Feature flags - -Optional and experimental capabilities are toggled via the `[features]` table in `$CODEX_HOME/config.toml`. If you see a deprecation notice mentioning a legacy key (for example `experimental_use_exec_command_tool`), move the setting into `[features]` or pass `--enable `. - -```toml -[features] -web_search_request = true # allow the model to request web searches -# view_image_tool defaults to true; omit to keep defaults -``` - -Supported features: - -| Key | Default | Stage | Description | -| ------------------------------------- | :-----: | ------------ | ----------------------------------------------------- | -| `unified_exec` | false | Experimental | Use the unified PTY-backed exec tool | -| `apply_patch_freeform` | false | Beta | Include the freeform `apply_patch` tool | -| `view_image_tool` | true | Stable | Include the `view_image` tool | -| `web_search_request` | false | Stable | Allow the model to issue web searches | -| `enable_experimental_windows_sandbox` | false | Experimental | Use the Windows restricted-token sandbox | -| `tui2` | false | Experimental | Use the experimental TUI v2 (viewport) implementation | -| `skills` | false | Experimental | Enable discovery and injection of skills | - -Notes: - -- Omit a key to accept its default. -- Legacy booleans such as `experimental_use_exec_command_tool`, `experimental_use_unified_exec_tool`, `include_apply_patch_tool`, and similar `experimental_use_*` keys are deprecated; setting the corresponding `[features].` avoids repeated warnings. - -## Model selection - -### model - -The model that Codex should use. - -```toml -model = "gpt-5.1" # overrides the default ("gpt-5.1-codex-max" across platforms) -``` - -### model_providers - -This option lets you add to the default set of model providers bundled with Codex. The map key becomes the value you use with `model_provider` to select the provider. - -> [!NOTE] -> Built-in providers are not overwritten when you reuse their key. Entries you add only take effect when the key is **new**; for example `[model_providers.openai]` leaves the original OpenAI definition untouched. To customize the bundled OpenAI provider, prefer the dedicated knobs (for example the `OPENAI_BASE_URL` environment variable) or register a new provider key and point `model_provider` at it. - -For example, if you wanted to add a provider that uses the OpenAI 4o model via the chat completions API, then you could add the following configuration: - -```toml -# Recall that in TOML, root keys must be listed before tables. -model = "gpt-4o" -model_provider = "openai-chat-completions" - -[model_providers.openai-chat-completions] -# Name of the provider that will be displayed in the Codex UI. -name = "OpenAI using Chat Completions" -# The path `/chat/completions` will be amended to this URL to make the POST -# request for the chat completions. -base_url = "https://api.openai.com/v1" -# If `env_key` is set, identifies an environment variable that must be set when -# using Codex with this provider. The value of the environment variable must be -# non-empty and will be used in the `Bearer TOKEN` HTTP header for the POST request. -env_key = "OPENAI_API_KEY" -# Valid values for wire_api are "chat" and "responses". Defaults to "chat" if omitted. -wire_api = "chat" -# If necessary, extra query params that need to be added to the URL. -# See the Azure example below. -query_params = {} -``` - -Note this makes it possible to use Codex CLI with non-OpenAI models, so long as they use a wire API that is compatible with the OpenAI chat completions API. For example, you could define the following provider to use Codex CLI with Ollama running locally: - -```toml -[model_providers.ollama] -name = "Ollama" -base_url = "http://localhost:11434/v1" -``` - -Or a third-party provider (using a distinct environment variable for the API key): - -```toml -[model_providers.mistral] -name = "Mistral" -base_url = "https://api.mistral.ai/v1" -env_key = "MISTRAL_API_KEY" -``` - -It is also possible to configure a provider to include extra HTTP headers with a request. These can be hardcoded values (`http_headers`) or values read from environment variables (`env_http_headers`): - -```toml -[model_providers.example] -# name, base_url, ... - -# This will add the HTTP header `X-Example-Header` with value `example-value` -# to each request to the model provider. -http_headers = { "X-Example-Header" = "example-value" } - -# This will add the HTTP header `X-Example-Features` with the value of the -# `EXAMPLE_FEATURES` environment variable to each request to the model provider -# _if_ the environment variable is set and its value is non-empty. -env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" } -``` - -#### 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: - -```toml -[model_providers.azure] -name = "Azure" -# Make sure you set the appropriate subdomain for this URL. -base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai" -env_key = "AZURE_OPENAI_API_KEY" # Or "OPENAI_API_KEY", whichever you use. -query_params = { api-version = "2025-04-01-preview" } -wire_api = "responses" -``` - -Export your key before launching Codex: `export AZURE_OPENAI_API_KEY=…` - -#### 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.]` block in `config.toml`. (Older releases accepted top‑level keys; those are now ignored.) - -Example: - -```toml -[model_providers.openai] -name = "OpenAI" -base_url = "https://api.openai.com/v1" -env_key = "OPENAI_API_KEY" -# network tuning overrides (all optional; falls back to built‑in defaults) -request_max_retries = 4 # retry failed HTTP requests -stream_max_retries = 10 # retry dropped SSE streams -stream_idle_timeout_ms = 300000 # 5m idle timeout -``` - -##### request_max_retries - -How many times Codex will retry a failed HTTP request to the model provider. Defaults to `4`. - -##### stream_max_retries - -Number of times Codex will attempt to reconnect when a streaming response is interrupted. Defaults to `5`. - -##### 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 - -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. - -Note that if you override `model_provider`, then you likely want to override -`model`, as well. For example, if you are running ollama with Mistral locally, -then you would need to add the following to your config in addition to the new entry in the `model_providers` map: - -```toml -model_provider = "ollama" -model = "mistral" -``` - -### model_reasoning_effort - -If the selected model is known to support reasoning (for example: `o3`, `o4-mini`, `codex-*`, `gpt-5.1-codex-max`, `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.2`), 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"` -- `"xhigh"` (available on `gpt-5.1-codex-max` and `gpt-5.2`) - -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.1" -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. - -### oss_provider - -Specifies the default OSS provider to use when running Codex. This is used when the `--oss` flag is provided without a specific provider. - -Valid values are: - -- `"lmstudio"` - Use LM Studio as the local model provider -- `"ollama"` - Use Ollama as the local model provider - -```toml -# Example: Set default OSS provider to LM Studio -oss_provider = "lmstudio" -``` - -## Execution environment - -### approval_policy - -Determines when the user should be prompted to approve whether Codex can execute a command: - -```toml -# Codex has hardcoded logic that defines a set of "trusted" commands. -# Setting the approval_policy to `untrusted` means that Codex will prompt the -# user before running a command not in the "trusted" set. -# -# See https://github.com/openai/codex/issues/1260 for the plan to enable -# end-users to define their own trusted commands. -approval_policy = "untrusted" -``` - -If you want to be notified whenever a command fails, use "on-failure": - -```toml -# If the command fails when run in the sandbox, Codex asks for permission to -# retry the command outside the sandbox. -approval_policy = "on-failure" -``` - -If you want the model to run until it decides that it needs to ask you for escalated permissions, use "on-request": - -```toml -# The model decides when to escalate -approval_policy = "on-request" -``` - -Alternatively, you can have the model run until it is done, and never ask to run a command with escalated permissions: - -```toml -# User is never prompted: if the command fails, Codex will automatically try -# something out. Note the `exec` subcommand always uses this mode. -approval_policy = "never" -``` - -### sandbox_mode - -Codex executes model-generated shell commands inside an OS-level sandbox. - -In most cases you can pick the desired behaviour with a single option: - -```toml -# same as `--sandbox read-only` -sandbox_mode = "read-only" -``` - -The default policy is `read-only`, which means commands can read any file on -disk, but attempts to write a file or access the network will be blocked. - -A more relaxed policy is `workspace-write`. When specified, the current working directory for the Codex task will be writable (as well as `$TMPDIR` on macOS). Note that the CLI defaults to using the directory where it was spawned as `cwd`, though this can be overridden using `--cwd/-C`. - -On macOS (and soon Linux), all writable roots (including `cwd`) that contain a `.git/` or `.codex/` folder _as an immediate child_ will configure those folders to be read-only while the rest of the root stays writable. This means that commands like `git commit` will fail, by default (as it entails writing to `.git/`), and will require Codex to ask for permission. - -```toml -# same as `--sandbox workspace-write` -sandbox_mode = "workspace-write" - -# Extra settings that only apply when `sandbox = "workspace-write"`. -[sandbox_workspace_write] -# By default, the cwd for the Codex session will be writable as well as $TMPDIR -# (if set) and /tmp (if it exists). Setting the respective options to `true` -# will override those defaults. -exclude_tmpdir_env_var = false -exclude_slash_tmp = false - -# Optional list of _additional_ writable roots beyond $TMPDIR and /tmp. -writable_roots = ["/Users/YOU/.pyenv/shims"] - -# Allow the command being run inside the sandbox to make outbound network -# requests. Disabled by default. -network_access = false -``` - -To disable sandboxing altogether, specify `danger-full-access` like so: - -```toml -# same as `--sandbox danger-full-access` -sandbox_mode = "danger-full-access" -``` - -This is reasonable to use if Codex is running in an environment that provides its own sandboxing (such as a Docker container) such that further sandboxing is unnecessary. - -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. - -### tools.\* - -These `[tools]` configuration options are deprecated. Use `[features]` instead (see [Feature flags](#feature-flags)). - -Use the optional `[tools]` table to toggle built-in tools that the agent may call. `web_search` stays off unless you opt in, while `view_image` is now enabled by default: - -```toml -[tools] -web_search = true # allow Codex to issue first-party web searches without prompting you (deprecated) -view_image = false # disable image uploads (they're enabled by default) -``` - -The `view_image` toggle is useful when you want to include screenshots or diagrams from your repo without pasting them manually. Codex still respects sandboxing: it can only attach files inside the workspace roots you allow. - -### approval_presets - -Codex provides three main Approval Presets: - -- Read Only: Codex can read files and answer questions; edits, running commands, and network access require approval. -- Auto: Codex can read files, make edits, and run commands in the workspace without approval; asks for approval outside the workspace or for network access. -- Full Access: Full disk and network access without prompts; extremely risky. - -You can further customize how Codex runs at the command line using the `--ask-for-approval` and `--sandbox` options. - -> See also [Sandbox & approvals](./sandbox.md) for in-depth examples and platform-specific behaviour. - -### 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`: - -```toml -[shell_environment_policy] -# inherit can be "all" (default), "core", or "none" -inherit = "core" -# set to true to *skip* the filter for `"*KEY*"`, `"*SECRET*"`, and `"*TOKEN*"` -ignore_default_excludes = true -# exclude patterns (case-insensitive globs) -exclude = ["AWS_*", "AZURE_*"] -# force-set / override values -set = { CI = "1" } -# if provided, *only* vars matching these patterns are kept -include_only = ["PATH", "HOME"] -``` - -| Field | Type | Default | Description | -| ------------------------- | -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `inherit` | string | `all` | Starting template for the environment:
`all` (clone full parent env), `core` (`HOME`, `PATH`, `USER`, …), or `none` (start empty). | -| `ignore_default_excludes` | boolean | `true` | When `false`, Codex removes any var whose **name** contains `KEY`, `SECRET`, or `TOKEN` (case-insensitive) before other rules run. | -| `exclude` | array | `[]` | Case-insensitive glob patterns to drop after the default filter.
Examples: `"AWS_*"`, `"AZURE_*"`. | -| `set` | table | `{}` | Explicit key/value overrides or additions – always win over inherited values. | -| `include_only` | array | `[]` | If non-empty, a whitelist of patterns; only variables that match _one_ pattern survive the final step. (Generally used with `inherit = "all"`.) | - -The patterns are **glob style**, not full regular expressions: `*` matches any -number of characters, `?` matches exactly one, and character classes like -`[A-Z]`/`[^0-9]` are supported. Matching is always **case-insensitive**. This -syntax is documented in code as `EnvironmentVariablePattern` (see -`core/src/config_types.rs`). - -If you just need a clean slate with a few custom entries you can write: - -```toml -[shell_environment_policy] -inherit = "none" -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. - -## Project root detection - -Codex discovers `.codex/` project layers by walking up from the working directory until it hits a project marker. By default it looks for `.git`. You can override the marker list in user/system/MDM config: - -```toml -# $CODEX_HOME/config.toml -project_root_markers = [".git", ".hg", ".sl"] -``` - -Set `project_root_markers = []` to skip searching parent directories and treat the current working directory as the project root. - -## 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 MCP 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//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 -[mcp_servers.figma] -url = "https://mcp.figma.com/mcp" -# Optional environment variable containing a bearer token to use for auth -bearer_token_env_var = "ENV_VAR" -# 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" } -``` - -Streamable HTTP connections always use the Rust MCP client under the hood. Run `codex mcp login ` to authenticate for servers supporting OAuth. - -#### 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 -# Optional: only expose a subset of tools from this server -enabled_tools = ["search", "summarize"] -# Optional: hide specific tools (applied after `enabled_tools`, if set) -disabled_tools = ["search"] -``` - -When both `enabled_tools` and `disabled_tools` are specified, Codex first restricts the server to the allow-list and then removes any tools that appear in the deny-list. - -#### 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, -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), `user.email` (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_execpolicy_amendment`, `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" - - [otel.exporter."otlp-http".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" }}} - ``` - -Both OTLP exporters accept an optional `tls` block so you can trust a custom CA -or enable mutual TLS. Relative paths are resolved against `~/.codex/`: - -```toml -[otel.exporter."otlp-http"] -endpoint = "https://otel.example.com/v1/logs" -protocol = "binary" - -[otel.exporter."otlp-http".headers] -"x-otlp-api-key" = "${OTLP_TOKEN}" - -[otel.exporter."otlp-http".tls] -ca-certificate = "certs/otel-ca.pem" -client-certificate = "/etc/codex/certs/client.pem" -client-private-key = "/etc/codex/certs/client-key.pem" -``` - -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.: - -```json -{ - "type": "agent-turn-complete", - "thread-id": "b5f6c1c2-1111-2222-3333-444455556666", - "turn-id": "12345", - "cwd": "/Users/alice/projects/example", - "input-messages": ["Rename `foo` to `bar` and update the callsites."], - "last-assistant-message": "Rename complete and verified `cargo build` succeeds." -} -``` - -The `"type"` property will always be set. Currently, `"agent-turn-complete"` is the only notification type that is supported. - -`"thread-id"` contains a string that identifies the Codex session that produced the notification; you can use it to correlate multiple turns that belong to the same task. - -`"cwd"` reports the absolute working directory for the session so scripts can disambiguate which project triggered the notification. - -As an example, here is a Python script that parses the JSON and decides whether to show a desktop push notification using [terminal-notifier](https://github.com/julienXX/terminal-notifier) on macOS: - -```python -#!/usr/bin/env python3 - -import json -import subprocess -import sys - - -def main() -> int: - if len(sys.argv) != 2: - print("Usage: notify.py ") - return 1 - - try: - notification = json.loads(sys.argv[1]) - except json.JSONDecodeError: - return 1 - - match notification_type := notification.get("type"): - case "agent-turn-complete": - assistant_message = notification.get("last-assistant-message") - if assistant_message: - title = f"Codex: {assistant_message}" - else: - title = "Codex: Turn Complete!" - input_messages = notification.get("input-messages", []) - message = " ".join(input_messages) - title += message - case _: - print(f"not sending a push notification for: {notification_type}") - return 0 - - thread_id = notification.get("thread-id", "") - - subprocess.check_output( - [ - "terminal-notifier", - "-title", - title, - "-message", - message, - "-group", - "codex-" + thread_id, - "-ignoreDnD", - "-activate", - "com.googlecode.iterm2", - ] - ) - - return 0 - - -if __name__ == "__main__": - sys.exit(main()) -``` - -To have Codex use this script for notifications, you would configure it via `notify` in `~/.codex/config.toml` using the appropriate path to `notify.py` on your computer: - -```toml -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. - -When Codex detects WSL 2 inside Windows Terminal (the session exports `WT_SESSION`), `tui.notifications` automatically switches to a Windows toast backend by spawning `powershell.exe`. This ensures both approval prompts and completed turns trigger native toasts even though Windows Terminal ignores OSC 9 escape sequences. Terminals that advertise OSC 9 support (iTerm2, WezTerm, kitty, etc.) continue to use the existing escape-sequence backend, and the `notify` hook remains unchanged. - -### 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.1-codex-max`) - -### 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. - -To disable this behavior, configure `[history]` as follows: - -```toml -[history] -persistence = "none" # "save-all" is the default value -``` - -To cap the size of `history.jsonl`, set `history.max_bytes` to a positive byte -count. When the file grows beyond the limit, Codex removes the oldest entries, -compacting the file down to roughly 80% of the hard cap while keeping the newest -record intact. Omitting the option—or setting it to `0`—disables pruning. - -### 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. - -For example, if the model output includes a reference such as `【F:/home/user/project/main.py†L42-L50】`, then this would be rewritten to link to the URI `vscode://file/home/user/project/main.py:42`. - -Note this is **not** a general editor setting (like `$EDITOR`), as it only accepts a fixed set of values: - -- `"vscode"` (default) -- `"vscode-insiders"` -- `"windsurf"` -- `"cursor"` -- `"none"` to explicitly disable this feature - -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. - -### 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 - -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. - -```toml -project_doc_fallback_filenames = ["CLAUDE.md", ".exampleagentrules.md"] -``` - -We recommend migrating instructions to AGENTS.md; other filenames may reduce model performance. - -> 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. - -```toml -[tui] -# Send desktop notifications when approvals are required or a turn completes. -# Defaults to true. -notifications = true - -# You can optionally filter to specific notification types. -# Available types are "agent-turn-complete" and "approval-requested". -notifications = [ "agent-turn-complete", "approval-requested" ] - -# Disable terminal animations (welcome screen, status shimmer, spinner). -# Defaults to true. -animations = false - -# TUI2 mouse scrolling (wheel + trackpad) -# -# Terminals emit different numbers of raw scroll events per physical wheel notch (commonly 1, 3, -# or 9+). TUI2 normalizes raw event density into consistent wheel behavior (default: ~3 lines per -# wheel notch) while keeping trackpad input higher fidelity via fractional accumulation. -# -# See `codex-rs/tui2/docs/scroll_input_model.md` for the model and probe data. - -# Override *wheel* event density (raw events per physical wheel notch). TUI2 only. -# -# Wheel-like per-event contribution is: -# - `scroll_wheel_lines / scroll_events_per_tick` -# -# Trackpad-like streams use `min(scroll_events_per_tick, 3)` as the divisor so dense wheel ticks -# (e.g. 9 events per notch) do not make trackpads feel artificially slow. -scroll_events_per_tick = 3 - -# Override wheel scroll lines per physical wheel notch (classic feel). TUI2 only. -scroll_wheel_lines = 3 - -# Override baseline trackpad sensitivity (lines per tick-equivalent). TUI2 only. -# -# Trackpad-like per-event contribution is: -# - `scroll_trackpad_lines / min(scroll_events_per_tick, 3)` -scroll_trackpad_lines = 1 - -# Trackpad acceleration (optional). TUI2 only. -# These keep small swipes precise while letting large/faster swipes cover more content. -# -# Concretely, TUI2 computes: -# - `multiplier = clamp(1 + abs(events) / scroll_trackpad_accel_events, 1..scroll_trackpad_accel_max)` -# -# The multiplier is applied to the trackpad-like stream’s computed line delta (including any -# carried fractional remainder). -scroll_trackpad_accel_events = 30 -scroll_trackpad_accel_max = 3 - -# Force scroll interpretation. TUI2 only. -# Valid values: "auto" (default), "wheel", "trackpad" -scroll_mode = "auto" - -# Auto-mode heuristic tuning. TUI2 only. -scroll_wheel_tick_detect_max_ms = 12 -scroll_wheel_like_max_duration_ms = 200 - -# Invert scroll direction for mouse wheel/trackpad. TUI2 only. -scroll_invert = false -``` - -> [!NOTE] -> Codex emits desktop notifications using terminal escape codes. Not all terminals support these (notably, macOS Terminal.app and VS Code's terminal do not support custom notifications. iTerm2, Ghostty and WezTerm do support these notifications). - -> [!NOTE] > `tui.notifications` is built‑in and limited to the TUI session. For programmatic or cross‑environment notifications—or to integrate with OS‑specific notifiers—use the top‑level `notify` option to run an external program that receives event JSON. The two settings are independent and can be used together. - -Scroll settings (`tui.scroll_events_per_tick`, `tui.scroll_wheel_lines`, `tui.scroll_trackpad_lines`, `tui.scroll_trackpad_accel_*`, `tui.scroll_mode`, `tui.scroll_wheel_*`, `tui.scroll_invert`) currently apply to the TUI2 viewport scroll implementation. - -> [!NOTE] > `tui.scroll_events_per_tick` has terminal-specific defaults derived from mouse scroll probe logs -> collected on macOS for a small set of terminals: -> -> - Terminal.app: 3 -> - Warp: 9 -> - WezTerm: 1 -> - Alacritty: 3 -> - Ghostty: 3 (stopgap; one probe measured ~9) -> - iTerm2: 1 -> - VS Code terminal: 1 -> - Kitty: 3 -> -> We should augment these defaults with data from more terminals and other platforms over time. -> Unknown terminals fall back to 3 and can be overridden via `tui.scroll_events_per_tick`. - -## Authentication and authorization - -### Forcing a login method - -To force users on a given machine to use a specific login method or workspace, use a combination of [managed configurations](https://developers.openai.com/codex/security#managed-configuration) as well as either or both of the following fields: - -```toml -# Force the user to log in with ChatGPT or via an api key. -forced_login_method = "chatgpt" or "api" -# When logging in with ChatGPT, only the specified workspace ID will be presented during the login -# flow and the id will be validated during the oauth callback as well as every time Codex starts. -forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000" -``` - -If the active credentials don't match the config, the user will be logged out and Codex will exit. - -If `forced_chatgpt_workspace_id` is set but `forced_login_method` is not set, API key login will still work. - -### Control where login credentials are stored - -```toml -cli_auth_credentials_store = "keyring" -``` - -Valid values: - -- `file` (default) – Store credentials in `auth.json` under `$CODEX_HOME`. -- `keyring` – Store credentials in the operating system keyring via the [`keyring` crate](https://crates.io/crates/keyring); the CLI reports an error if secure storage is unavailable. Backends by OS: - - macOS: macOS Keychain - - Windows: Windows Credential Manager - - Linux: DBus‑based Secret Service, the kernel keyutils, or a combination - - FreeBSD/OpenBSD: DBus‑based Secret Service -- `auto` – Save credentials to the operating system keyring when available; otherwise, fall back to `auth.json` under `$CODEX_HOME`. - -## Config reference - -| Key | Type / Values | Notes | -| ------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `model` | string | Model to use (e.g., `gpt-5.1-codex-max`). | -| `model_provider` | string | Provider id from `model_providers` (default: `openai`). | -| `model_context_window` | number | Context window tokens. | -| `tool_output_token_limit` | number | Token budget for stored function/tool outputs in history (default: 2,560 tokens). | -| `approval_policy` | `untrusted` \| `on-failure` \| `on-request` \| `never` | When to prompt for approval. | -| `sandbox_mode` | `read-only` \| `workspace-write` \| `danger-full-access` | OS sandbox policy. | -| `sandbox_workspace_write.writable_roots` | array | Extra writable roots in workspace‑write. | -| `sandbox_workspace_write.network_access` | boolean | Allow network in workspace‑write (default: false). | -| `sandbox_workspace_write.exclude_tmpdir_env_var` | boolean | Exclude `$TMPDIR` from writable roots (default: false). | -| `sandbox_workspace_write.exclude_slash_tmp` | boolean | Exclude `/tmp` from writable roots (default: false). | -| `notify` | array | External program for notifications. | -| `tui.animations` | boolean | Enable terminal animations (welcome screen, shimmer, spinner). Defaults to true; set to `false` to disable visual motion. | -| `instructions` | string | Currently ignored; use `experimental_instructions_file` or `AGENTS.md`. | -| `developer_instructions` | string | The additional developer instructions. | -| `features.` | boolean | See [feature flags](#feature-flags) for details | -| `ghost_snapshot.disable_warnings` | boolean | Disable every warnings around ghost snapshot (large files, directory, ...) | -| `ghost_snapshot.ignore_large_untracked_files` | number | Exclude untracked files larger than this many bytes from ghost snapshots (default: 10 MiB). Set to `0` to disable. | -| `ghost_snapshot.ignore_large_untracked_dirs` | number | Ignore untracked directories with at least this many files (default: 200). Set to `0` to disable. | -| `mcp_servers..command` | string | MCP server launcher command (stdio servers only). | -| `mcp_servers..args` | array | MCP server args (stdio servers only). | -| `mcp_servers..env` | map | MCP server env vars (stdio servers only). | -| `mcp_servers..url` | string | MCP server url (streamable http servers only). | -| `mcp_servers..bearer_token_env_var` | string | environment variable containing a bearer token to use for auth (streamable http servers only). | -| `mcp_servers..enabled` | boolean | When false, Codex skips starting the server (default: true). | -| `mcp_servers..startup_timeout_sec` | number | Startup timeout in seconds (default: 10). Timeout is applied both for initializing MCP server and initially listing tools. | -| `mcp_servers..tool_timeout_sec` | number | Per-tool timeout in seconds (default: 60). Accepts fractional values; omit to use the default. | -| `mcp_servers..enabled_tools` | array | Restrict the server to the listed tool names. | -| `mcp_servers..disabled_tools` | array | Remove the listed tool names after applying `enabled_tools`, if any. | -| `model_providers..name` | string | Display name. | -| `model_providers..base_url` | string | API base URL. | -| `model_providers..env_key` | string | Env var for API key. | -| `model_providers..wire_api` | `chat` \| `responses` | Protocol used (default: `chat`). | -| `model_providers..query_params` | map | Extra query params (e.g., Azure `api-version`). | -| `model_providers..http_headers` | map | Additional static headers. | -| `model_providers..env_http_headers` | map | Headers sourced from env vars. | -| `model_providers..request_max_retries` | number | Per‑provider HTTP retry count (default: 4). | -| `model_providers..stream_max_retries` | number | SSE stream retry count (default: 5). | -| `model_providers..stream_idle_timeout_ms` | number | SSE idle timeout (ms) (default: 300000). | -| `project_doc_max_bytes` | number | Max bytes to read from `AGENTS.md`. | -| `profile` | string | Active profile name. | -| `profiles..*` | various | Profile‑scoped overrides of the same keys. | -| `history.persistence` | `save-all` \| `none` | History file persistence (default: `save-all`). | -| `history.max_bytes` | number | Maximum size of `history.jsonl` in bytes; when exceeded, history is compacted to ~80% of this limit by dropping oldest entries. | -| `file_opener` | `vscode` \| `vscode-insiders` \| `windsurf` \| `cursor` \| `none` | URI scheme for clickable citations (default: `vscode`). | -| `tui` | table | TUI‑specific options. | -| `tui.notifications` | boolean \| array | Enable desktop notifications in the tui (default: true). | -| `tui.scroll_events_per_tick` | number | Raw events per wheel notch (normalization input; default: terminal-specific; fallback: 3). | -| `tui.scroll_wheel_lines` | number | Lines per physical wheel notch in wheel-like mode (default: 3). | -| `tui.scroll_trackpad_lines` | number | Baseline trackpad sensitivity in trackpad-like mode (default: 1). | -| `tui.scroll_trackpad_accel_events` | number | Trackpad acceleration: events per +1x speed in TUI2 (default: 30). | -| `tui.scroll_trackpad_accel_max` | number | Trackpad acceleration: max multiplier in TUI2 (default: 3). | -| `tui.scroll_mode` | `auto` \| `wheel` \| `trackpad` | How to interpret scroll input in TUI2 (default: `auto`). | -| `tui.scroll_wheel_tick_detect_max_ms` | number | Auto-mode threshold (ms) for promoting a stream to wheel-like behavior (default: 12). | -| `tui.scroll_wheel_like_max_duration_ms` | number | Auto-mode fallback duration (ms) used for 1-event-per-tick terminals (default: 200). | -| `tui.scroll_invert` | boolean | Invert mouse scroll direction in TUI2 (default: false). | -| `hide_agent_reasoning` | boolean | Hide model reasoning events. | -| `check_for_update_on_startup` | boolean | Check for Codex updates on startup (default: true). Set to `false` only if updates are centrally managed. | -| `show_raw_agent_reasoning` | boolean | Show raw reasoning (when available). | -| `model_reasoning_effort` | `minimal` \| `low` \| `medium` \| `high`\|`xhigh` | Responses API reasoning effort. | -| `model_reasoning_summary` | `auto` \| `concise` \| `detailed` \| `none` | Reasoning summaries. | -| `model_verbosity` | `low` \| `medium` \| `high` | GPT‑5 text verbosity (Responses API). | -| `model_supports_reasoning_summaries` | boolean | Force‑enable reasoning summaries. | -| `chatgpt_base_url` | string | Base URL for ChatGPT auth flow. | -| `experimental_instructions_file` | string (path) | Replace built‑in instructions (experimental). | -| `experimental_use_exec_command_tool` | boolean | Use experimental exec command tool. | -| `projects..trust_level` | string | Mark project/worktree as trusted (only `"trusted"` is recognized). | -| `tools.web_search` | boolean | Enable web search tool (deprecated) (default: false). | -| `tools.view_image` | boolean | Enable or disable the `view_image` tool so Codex can attach local image files from the workspace (default: true). | -| `forced_login_method` | `chatgpt` \| `api` | Only allow Codex to be used with ChatGPT or API keys. | -| `forced_chatgpt_workspace_id` | string (uuid) | Only allow Codex to be used with the specified ChatGPT workspace. | -| `cli_auth_credentials_store` | `file` \| `keyring` \| `auto` | Where to store CLI login credentials (default: `file`). | +For a full configuration reference, see [this documentation](https://developers.openai.com/codex/config-reference). diff --git a/docs/contributing.md b/docs/contributing.md index ec188631d1..8e73119910 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -2,9 +2,11 @@ This project is under active development and the code will likely change pretty significantly. -**At the moment, we only plan to prioritize reviewing external contributions for bugs or security fixes.** +**At the moment, we are generally accepting external contributions only for bugs fixes.** -If you want to add a new feature or change the behavior of an existing one, please open an issue proposing the feature and get approval from an OpenAI team member before spending time building it. +If you want to add a new feature or change the behavior of an existing one, please open an issue proposing the feature or upvote an existing enhancement request. We will generally prioritize new features based on community feedback. New features must compose well with existing and upcoming features and fit into our roadmap. They must also be implemented consistently across all Codex surfaces (CLI, IDE extension, web, etc.). + +If you want to contribute a bug fix, please open a bug report first - or verify that there is an existing bug report that discusses the issue. All bug fix PRs should include a link to a bug report. **New contributions that don't go through this process may be closed** if they aren't aligned with our current roadmap or conflict with other priorities/upcoming features. @@ -17,8 +19,8 @@ If you want to add a new feature or change the behavior of an existing one, plea ### Writing high-impact code changes 1. **Start with an issue.** Open a new one or comment on an existing discussion so we can agree on the solution before code is written. -2. **Add or update tests.** Every new feature or bug-fix should come with test coverage that fails before your change and passes afterwards. 100% coverage is not required, but aim for meaningful assertions. -3. **Document behaviour.** If your change affects user-facing behaviour, update the README, inline help (`codex --help`), or relevant example projects. +2. **Add or update tests.** A bug fix should generally come with test coverage that fails before your change and passes afterwards. 100% coverage is not required, but aim for meaningful assertions. +3. **Document behavior.** If your change affects user-facing behavior, update the README, inline help (`codex --help`), or relevant example projects. 4. **Keep commits atomic.** Each commit should compile and the tests should pass. This makes reviews and potential rollbacks easier. ### Opening a pull request @@ -32,8 +34,8 @@ If you want to add a new feature or change the behavior of an existing one, plea ### Review process 1. One maintainer will be assigned as a primary reviewer. -2. If your PR adds a new feature that was not previously discussed and approved, we may choose to close your PR (see [Contributing](#contributing)). -3. We may ask for changes - please do not take this personally. We value the work, but we also value consistency and long-term maintainability. +2. If your PR adds a new feature that was not previously discussed and approved, we may close your PR (see [Contributing](#contributing)). +3. We may ask for changes. Please do not take this personally. We value the work, but we also value consistency and long-term maintainability. 4. When there is consensus that the PR meets the bar, a maintainer will squash-and-merge. ### Community values @@ -44,7 +46,7 @@ If you want to add a new feature or change the behavior of an existing one, plea ### Getting help -If you run into problems setting up the project, would like feedback on an idea, or just want to say _hi_ - please open a Discussion or jump into the relevant issue. We are happy to help. +If you run into problems setting up the project, would like feedback on an idea, or just want to say _hi_ - please open a Discussion topic or jump into the relevant issue. We are happy to help. Together we can make Codex CLI an incredible tool. **Happy hacking!** :rocket: @@ -63,14 +65,6 @@ All contributors **must** accept the CLA. The process is lightweight: No special Git commands, email attachments, or commit footers required. -#### Quick fixes - -| Scenario | Command | -| ----------------- | ------------------------------------------------ | -| Amend last commit | `git commit --amend -s --no-edit && git push -f` | - -The **DCO check** blocks merges until every commit in the PR carries the footer (with squash this is just the one). - ### Security & responsible AI Have you discovered a vulnerability or have concerns about model output? Please e-mail **security@openai.com** and we will respond promptly. diff --git a/docs/example-config.md b/docs/example-config.md index 795b290390..84b11436c5 100644 --- a/docs/example-config.md +++ b/docs/example-config.md @@ -1,362 +1,3 @@ -# Example config.toml +# Sample configuration -Use this example configuration as a starting point. For an explanation of each field and additional context, see [Configuration](./config.md). Copy the snippet below to `~/.codex/config.toml` and adjust values as needed. - -```toml -# Codex example configuration (config.toml) -# -# This file lists all keys Codex reads from config.toml, their default values, -# and concise explanations. Values here mirror the effective defaults compiled -# into the CLI. Adjust as needed. -# -# Notes -# - Root keys must appear before tables in TOML. -# - Optional keys that default to "unset" are shown commented out with notes. -# - MCP servers, profiles, and model providers are examples; remove or edit. - -################################################################################ -# Core Model Selection -################################################################################ - -# Primary model used by Codex. Default: "gpt-5.1-codex-max" on all platforms. -model = "gpt-5.1-codex-max" - -# Model used by the /review feature (code reviews). Default: "gpt-5.1-codex-max". -review_model = "gpt-5.1-codex-max" - -# Provider id selected from [model_providers]. Default: "openai". -model_provider = "openai" - -# Optional manual model metadata. When unset, Codex auto-detects from model. -# Uncomment to force values. -# model_context_window = 128000 # tokens; default: auto for model -# model_auto_compact_token_limit = 0 # disable/override auto; default: model family specific -# tool_output_token_limit = 10000 # tokens stored per tool output; default: 10000 for gpt-5.1-codex-max - -################################################################################ -# Reasoning & Verbosity (Responses API capable models) -################################################################################ - -# Reasoning effort: minimal | low | medium | high | xhigh (default: medium; xhigh on gpt-5.1-codex-max and gpt-5.2) -model_reasoning_effort = "medium" - -# Reasoning summary: auto | concise | detailed | none (default: auto) -model_reasoning_summary = "auto" - -# Text verbosity for GPT-5 family (Responses API): low | medium | high (default: medium) -model_verbosity = "medium" - -# Force-enable reasoning summaries for current model (default: false) -model_supports_reasoning_summaries = false - -################################################################################ -# Instruction Overrides -################################################################################ - -# Additional user instructions inject before AGENTS.md. Default: unset. -# developer_instructions = "" - -# (Ignored) Optional legacy base instructions override (prefer AGENTS.md). Default: unset. -# instructions = "" - -# Inline override for the history compaction prompt. Default: unset. -# compact_prompt = "" - -# Override built-in base instructions with a file path. Default: unset. -# experimental_instructions_file = "/absolute/or/relative/path/to/instructions.txt" - -# Load the compact prompt override from a file. Default: unset. -# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt" - -################################################################################ -# Approval & Sandbox -################################################################################ - -# When to ask for command approval: -# - untrusted: only known-safe read-only commands auto-run; others prompt -# - on-failure: auto-run in sandbox; prompt only on failure for escalation -# - on-request: model decides when to ask (default) -# - never: never prompt (risky) -approval_policy = "on-request" - -# Filesystem/network sandbox policy for tool calls: -# - read-only (default) -# - workspace-write -# - danger-full-access (no sandbox; extremely risky) -sandbox_mode = "read-only" - -# Extra settings used only when sandbox_mode = "workspace-write". -[sandbox_workspace_write] -# Additional writable roots beyond the workspace (cwd). Default: [] -writable_roots = [] -# Allow outbound network access inside the sandbox. Default: false -network_access = false -# Exclude $TMPDIR from writable roots. Default: false -exclude_tmpdir_env_var = false -# Exclude /tmp from writable roots. Default: false -exclude_slash_tmp = false - -################################################################################ -# Shell Environment Policy for spawned processes -################################################################################ - -[shell_environment_policy] -# inherit: all (default) | core | none -inherit = "all" -# Skip default excludes for names containing KEY/SECRET/TOKEN (case-insensitive). Default: true -ignore_default_excludes = true -# Case-insensitive glob patterns to remove (e.g., "AWS_*", "AZURE_*"). Default: [] -exclude = [] -# Explicit key/value overrides (always win). Default: {} -set = {} -# Whitelist; if non-empty, keep only matching vars. Default: [] -include_only = [] -# Experimental: run via user shell profile. Default: false -experimental_use_profile = false - -################################################################################ -# History & File Opener -################################################################################ - -[history] -# save-all (default) | none -persistence = "save-all" -# Maximum bytes for history file; oldest entries are trimmed when exceeded. Example: 5242880 -# max_bytes = 0 - -# URI scheme for clickable citations: vscode (default) | vscode-insiders | windsurf | cursor | none -file_opener = "vscode" - -################################################################################ -# UI, Notifications, and Misc -################################################################################ - -[tui] -# Desktop notifications from the TUI: boolean or filtered list. Default: true -# Examples: false | ["agent-turn-complete", "approval-requested"] -notifications = false - -# Enables welcome/status/spinner animations. Default: true -animations = true - -# Suppress internal reasoning events from output. Default: false -hide_agent_reasoning = false - -# Show raw reasoning content when available. Default: false -show_raw_agent_reasoning = false - -# Disable burst-paste detection in the TUI. Default: false -disable_paste_burst = false - -# Track Windows onboarding acknowledgement (Windows only). Default: false -windows_wsl_setup_acknowledged = false - -# External notifier program (argv array). When unset: disabled. -# Example: notify = ["notify-send", "Codex"] -# notify = [ ] - -# In-product notices (mostly set automatically by Codex). -[notice] -# hide_full_access_warning = true -# hide_rate_limit_model_nudge = true - -################################################################################ -# Authentication & Login -################################################################################ - -# Where to persist CLI login credentials: file (default) | keyring | auto -cli_auth_credentials_store = "file" - -# Base URL for ChatGPT auth flow (not OpenAI API). Default: -chatgpt_base_url = "https://chatgpt.com/backend-api/" - -# Restrict ChatGPT login to a specific workspace id. Default: unset. -# forced_chatgpt_workspace_id = "" - -# Force login mechanism when Codex would normally auto-select. Default: unset. -# Allowed values: chatgpt | api -# forced_login_method = "chatgpt" - -# Preferred store for MCP OAuth credentials: auto (default) | file | keyring -mcp_oauth_credentials_store = "auto" - -################################################################################ -# Project Documentation Controls -################################################################################ - -# Max bytes from AGENTS.md to embed into first-turn instructions. Default: 32768 -project_doc_max_bytes = 32768 - -# Ordered fallbacks when AGENTS.md is missing at a directory level. Default: [] -project_doc_fallback_filenames = [] - -################################################################################ -# Tools (legacy toggles kept for compatibility) -################################################################################ - -[tools] -# Enable web search tool (alias: web_search_request). Default: false -web_search = false - -# Enable the view_image tool so the agent can attach local images. Default: true -view_image = true - -# (Alias accepted) You can also write: -# web_search_request = false - -################################################################################ -# Centralized Feature Flags (preferred) -################################################################################ - -[features] -# Leave this table empty to accept defaults. Set explicit booleans to opt in/out. -unified_exec = false -apply_patch_freeform = false -view_image_tool = true -web_search_request = false -enable_experimental_windows_sandbox = false -skills = false - -################################################################################ -# Experimental toggles (legacy; prefer [features]) -################################################################################ - -# Include apply_patch via freeform editing path (affects default tool set). Default: false -experimental_use_freeform_apply_patch = false - -# Define MCP servers under this table. Leave empty to disable. -[mcp_servers] - -# --- Example: STDIO transport --- -# [mcp_servers.docs] -# command = "docs-server" # required -# args = ["--port", "4000"] # optional -# env = { "API_KEY" = "value" } # optional key/value pairs copied as-is -# env_vars = ["ANOTHER_SECRET"] # optional: forward these from the parent env -# cwd = "/path/to/server" # optional working directory override -# startup_timeout_sec = 10.0 # optional; default 10.0 seconds -# # startup_timeout_ms = 10000 # optional alias for startup timeout (milliseconds) -# tool_timeout_sec = 60.0 # optional; default 60.0 seconds -# enabled_tools = ["search", "summarize"] # optional allow-list -# disabled_tools = ["slow-tool"] # optional deny-list (applied after allow-list) - -# --- Example: Streamable HTTP transport --- -# [mcp_servers.github] -# url = "https://github-mcp.example.com/mcp" # required -# bearer_token_env_var = "GITHUB_TOKEN" # optional; Authorization: Bearer -# http_headers = { "X-Example" = "value" } # optional static headers -# env_http_headers = { "X-Auth" = "AUTH_ENV" } # optional headers populated from env vars -# startup_timeout_sec = 10.0 # optional -# tool_timeout_sec = 60.0 # optional -# enabled_tools = ["list_issues"] # optional allow-list - -################################################################################ -# Model Providers (extend/override built-ins) -################################################################################ - -# Built-ins include: -# - openai (Responses API; requires login or OPENAI_API_KEY via auth flow) -# - oss (Chat Completions API; defaults to http://localhost:11434/v1) - -[model_providers] - -# --- Example: override OpenAI with explicit base URL or headers --- -# [model_providers.openai] -# name = "OpenAI" -# base_url = "https://api.openai.com/v1" # default if unset -# wire_api = "responses" # "responses" | "chat" (default varies) -# # requires_openai_auth = true # built-in OpenAI defaults to true -# # request_max_retries = 4 # default 4; max 100 -# # stream_max_retries = 5 # default 5; max 100 -# # stream_idle_timeout_ms = 300000 # default 300_000 (5m) -# # experimental_bearer_token = "sk-example" # optional dev-only direct bearer token -# # http_headers = { "X-Example" = "value" } -# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" } - -# --- Example: Azure (Chat/Responses depending on endpoint) --- -# [model_providers.azure] -# name = "Azure" -# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai" -# wire_api = "responses" # or "chat" per endpoint -# query_params = { api-version = "2025-04-01-preview" } -# env_key = "AZURE_OPENAI_API_KEY" -# # env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment" - -# --- Example: Local OSS (e.g., Ollama-compatible) --- -# [model_providers.ollama] -# name = "Ollama" -# base_url = "http://localhost:11434/v1" -# wire_api = "chat" - -################################################################################ -# Profiles (named presets) -################################################################################ - -# Active profile name. When unset, no profile is applied. -# profile = "default" - -[profiles] - -# [profiles.default] -# model = "gpt-5.1-codex-max" -# model_provider = "openai" -# approval_policy = "on-request" -# sandbox_mode = "read-only" -# model_reasoning_effort = "medium" -# model_reasoning_summary = "auto" -# model_verbosity = "medium" -# chatgpt_base_url = "https://chatgpt.com/backend-api/" -# experimental_compact_prompt_file = "./compact_prompt.txt" -# include_apply_patch_tool = false -# experimental_use_freeform_apply_patch = false -# tools_web_search = false -# tools_view_image = true -# features = { unified_exec = false } - -################################################################################ -# Projects (trust levels) -################################################################################ - -# Mark specific worktrees as trusted. Only "trusted" is recognized. -[projects] -# [projects."/absolute/path/to/project"] -# trust_level = "trusted" - -################################################################################ -# OpenTelemetry (OTEL) – disabled by default -################################################################################ - -[otel] -# Include user prompt text in logs. Default: false -log_user_prompt = false -# Environment label applied to telemetry. Default: "dev" -environment = "dev" -# Exporter: none (default) | otlp-http | otlp-grpc -exporter = "none" - -# Example OTLP/HTTP exporter configuration -# [otel.exporter."otlp-http"] -# endpoint = "https://otel.example.com/v1/logs" -# protocol = "binary" # "binary" | "json" - -# [otel.exporter."otlp-http".headers] -# "x-otlp-api-key" = "${OTLP_TOKEN}" - -# Example OTLP/gRPC exporter configuration -# [otel.exporter."otlp-grpc"] -# endpoint = "https://otel.example.com:4317", -# headers = { "x-otlp-meta" = "abc123" } - -# Example OTLP exporter with mutual TLS -# [otel.exporter."otlp-http"] -# endpoint = "https://otel.example.com/v1/logs" -# protocol = "binary" - -# [otel.exporter."otlp-http".headers] -# "x-otlp-api-key" = "${OTLP_TOKEN}" - -# [otel.exporter."otlp-http".tls] -# ca-certificate = "certs/otel-ca.pem" -# client-certificate = "/etc/codex/certs/client.pem" -# client-private-key = "/etc/codex/certs/client-key.pem" -``` +For a sample configuration file, see [this documentation](https://developers.openai.com/codex/config-sample). diff --git a/docs/exec.md b/docs/exec.md index 5a17155a82..57e432305b 100644 --- a/docs/exec.md +++ b/docs/exec.md @@ -1,114 +1,3 @@ -## Non-interactive mode +# Non-interactive mode -Use Codex in non-interactive mode to automate common workflows. - -```shell -codex exec "count the total number of lines of code in this project" -``` - -In non-interactive mode, Codex does not ask for command or edit approvals. By default it runs in `read-only` mode, so it cannot edit files or run commands that require network access. - -Use `codex exec --full-auto` to allow file edits. Use `codex exec --sandbox danger-full-access` to allow edits and networked commands. - -### Default output mode - -By default, Codex streams its activity to stderr and only writes the final message from the agent to stdout. This makes it easier to pipe `codex exec` into another tool without extra filtering. - -To write the output of `codex exec` to a file, in addition to using a shell redirect like `>`, there is also a dedicated flag to specify an output file: `-o`/`--output-last-message`. - -### JSON output mode - -`codex exec` supports a `--json` mode that streams events to stdout as JSON Lines (JSONL) while the agent runs. - -Supported event types: - -- `thread.started` - when a thread is started or resumed. -- `turn.started` - when a turn starts. A turn encompasses all events between the user message and the assistant response. -- `turn.completed` - when a turn completes; includes token usage. -- `turn.failed` - when a turn fails; includes error details. -- `item.started`/`item.updated`/`item.completed` - when a thread item is added/updated/completed. -- `error` - when the stream reports an unrecoverable error; includes the error message. - -Supported item types: - -- `agent_message` - assistant message. -- `reasoning` - a summary of the assistant's thinking. -- `command_execution` - assistant executing a command. -- `file_change` - assistant making file changes. -- `mcp_tool_call` - assistant calling an MCP tool. -- `web_search` - assistant performing a web search. -- `todo_list` - the agent's running plan when the plan tool is active, updating as steps change. - -Typically, an `agent_message` is added at the end of the turn. - -Sample output: - -```jsonl -{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"} -{"type":"turn.started"} -{"type":"item.completed","item":{"id":"item_0","type":"reasoning","text":"**Searching for README files**"}} -{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","aggregated_output":"","status":"in_progress"}} -{"type":"item.completed","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","aggregated_output":"2025-09-11\nAGENTS.md\nCHANGELOG.md\ncliff.toml\ncodex-cli\ncodex-rs\ndocs\nexamples\nflake.lock\nflake.nix\nLICENSE\nnode_modules\nNOTICE\npackage.json\npnpm-lock.yaml\npnpm-workspace.yaml\nPNPM.md\nREADME.md\nscripts\nsdk\ntmp\n","exit_code":0,"status":"completed"}} -{"type":"item.completed","item":{"id":"item_2","type":"reasoning","text":"**Checking repository root for README**"}} -{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Yep — there’s a `README.md` in the repository root."}} -{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}} -``` - -### Structured output - -By default, the agent responds with natural language. Use `--output-schema` to provide a JSON Schema that defines the expected JSON output. - -The JSON Schema must follow the [strict schema rules](https://platform.openai.com/docs/guides/structured-outputs). - -Sample schema: - -```json -{ - "type": "object", - "properties": { - "project_name": { "type": "string" }, - "programming_languages": { "type": "array", "items": { "type": "string" } } - }, - "required": ["project_name", "programming_languages"], - "additionalProperties": false -} -``` - -```shell -codex exec "Extract details of the project" --output-schema ~/schema.json -... - -{"project_name":"Codex CLI","programming_languages":["Rust","TypeScript","Shell"]} -``` - -Combine `--output-schema` with `-o` to only print the final JSON output. You can also pass a file path to `-o` to save the JSON output to a file. - -### Git repository requirement - -Codex requires a Git repository to avoid destructive changes. To disable this check, use `codex exec --skip-git-repo-check`. - -### Resuming non-interactive sessions - -Resume a previous non-interactive session with `codex exec resume ` or `codex exec resume --last`. This preserves conversation context so you can ask follow-up questions or give new tasks to the agent. - -```shell -codex exec "Review the change, look for use-after-free issues" -codex exec resume --last "Fix use-after-free issues" -``` - -Only the conversation context is preserved; you must still provide flags to customize Codex behavior. - -```shell -codex exec --model gpt-5.1-codex-max --json "Review the change, look for use-after-free issues" -codex exec --model gpt-5.1 --json resume --last "Fix use-after-free issues" -``` - -## Authentication - -By default, `codex exec` will use the same authentication method as Codex CLI and VSCode extension. You can override the api key by setting the `CODEX_API_KEY` environment variable. - -```shell -CODEX_API_KEY=your-api-key-here codex exec "Fix merge conflict" -``` - -NOTE: `CODEX_API_KEY` is only supported in `codex exec`. +For information about non-interactive mode, see [this documentation](https://developers.openai.com/codex/noninteractive). diff --git a/docs/execpolicy.md b/docs/execpolicy.md index ecc79f33d2..cafebb32ee 100644 --- a/docs/execpolicy.md +++ b/docs/execpolicy.md @@ -1,74 +1,3 @@ -# Execpolicy quickstart +# Execution policy -Codex can enforce your own rules-based execution policy before it runs shell commands. Policies live in `.rules` files under `~/.codex/rules`. - -## How to create and edit rules - -### TUI interactions - -Codex CLI will present the option to whitelist commands when a command causes a prompt. - -Screenshot 2025-12-04 at 9 23 54 AM - -Whitelisted commands will no longer require your permission to run in current and subsequent sessions. - -Under the hood, when you approve and whitelist a command, codex will edit `~/.codex/rules/default.rules`. - -### Editing `.rules` files - -1. Create a policy directory: `mkdir -p ~/.codex/rules`. -2. Add one or more `.rules` files in that folder. Codex automatically loads every `.rules` file in there on startup. -3. Write `prefix_rule` entries to describe the commands you want to allow, prompt, or block: - -```starlark -prefix_rule( - pattern = ["git", ["push", "fetch"]], - decision = "prompt", # allow | prompt | forbidden - match = [["git", "push", "origin", "main"]], # examples that must match - not_match = [["git", "status"]], # examples that must not match -) -``` - -- `pattern` is a list of shell tokens, evaluated from left to right; wrap tokens in a nested list to express alternatives (for example, match both `push` and `fetch`). -- `decision` sets the severity; Codex picks the strictest decision when multiple rules match (forbidden > prompt > allow). -- `match` and `not_match` act as optional unit tests. Codex validates them when it loads your policy, so you get feedback if an example has unexpected behavior. - -In this example rule, if Codex wants to run commands with the prefix `git push` or `git fetch`, it will first ask for user approval. - -## Preview decisions - -Use the `codex execpolicy check` subcommand to preview decisions before you save a rule (see the [`codex-execpolicy` README](../codex-rs/execpolicy/README.md) for syntax details): - -```shell -codex execpolicy check --rules ~/.codex/rules/default.rules git push origin main -``` - -Pass multiple `--rules` flags to test how several files combine, and use `--pretty` for formatted JSON output. See the [`codex-rs/execpolicy` README](../codex-rs/execpolicy/README.md) for a more detailed walkthrough of the available syntax. - -Example output when a rule matches: - -```json -{ - "matchedRules": [ - { - "prefixRuleMatch": { - "matchedPrefix": ["git", "push"], - "decision": "prompt" - } - } - ], - "decision": "prompt" -} -``` - -When no rules match, `matchedRules` is an empty array and `decision` is omitted. - -```json -{ - "matchedRules": [] -} -``` - -## Status - -`execpolicy` commands are still in preview. The API may have breaking changes in the future. +For an overview of execution policy rules, see [this documentation](https://developers.openai.com/codex/exec-policy). diff --git a/docs/experimental.md b/docs/experimental.md deleted file mode 100644 index 358a23409d..0000000000 --- a/docs/experimental.md +++ /dev/null @@ -1,10 +0,0 @@ -## Experimental technology disclaimer - -Codex CLI is an experimental project under active development. It is not yet stable, may contain bugs, incomplete features, or undergo breaking changes. We're building it in the open with the community and welcome: - -- Bug reports -- Feature requests -- Pull requests -- Good vibes - -Help us improve by filing issues or submitting PRs (see [contributing.md](./contributing.md) for guidance)! diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index 93776b957a..0000000000 --- a/docs/faq.md +++ /dev/null @@ -1,55 +0,0 @@ -## FAQ - -This FAQ highlights the most common questions and points you to the right deep-dive guides in `docs/`. - -### OpenAI released a model called Codex in 2021 - is this related? - -In 2021, OpenAI released Codex, an AI system designed to generate code from natural language prompts. That original Codex model was deprecated as of March 2023 and is separate from the CLI tool. - -### Which models are supported? - -We recommend using Codex with GPT-5.1 Codex Max, our best coding model. The default reasoning level is medium, and you can upgrade to high or xhigh (where supported, e.g. `gpt-5.1-codex-max` and `gpt-5.2`) for complex tasks with the `/model` command. - -You can also use older models by using API-based auth and launching codex with the `--model` flag. - -### How do approvals and sandbox modes work together? - -Approvals are the mechanism Codex uses to ask before running a tool call with elevated permissions - typically to leave the sandbox or re-run a failed command without isolation. Sandbox mode provides the baseline isolation (`Read Only`, `Workspace Write`, or `Danger Full Access`; see [Sandbox & approvals](./sandbox.md)). - -### Can I automate tasks without the TUI? - -Yes. [`codex exec`](./exec.md) runs Codex in non-interactive mode with streaming logs, JSONL output, and structured schema support. The command respects the same sandbox and approval settings you configure in the [Config guide](./config.md). - -### How do I stop Codex from editing my files? - -By default, Codex can modify files in your current working directory (Auto mode). To prevent edits, run `codex` in read-only mode with the CLI flag `--sandbox read-only`. Alternatively, you can change the approval level mid-conversation with `/approvals`. - -### How do I connect Codex to MCP servers? - -Configure MCP servers through your `config.toml` using the examples in [Config -> Connecting to MCP servers](./config.md#connecting-to-mcp-servers). - -### I'm having trouble logging in. What should I check? - -Confirm your setup in three steps: - -1. Walk through the auth flows in [Authentication](./authentication.md) to ensure the correct credentials are present in `~/.codex/auth.json`. -2. If you're on a headless or remote machine, make sure port-forwarding is configured as described in [Authentication -> Connecting on a "Headless" Machine](./authentication.md#connecting-on-a-headless-machine). - -### Does it work on Windows? - -Running Codex directly on Windows may work, but is not officially supported. We recommend using [Windows Subsystem for Linux (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/install). - -### Where should I start after installation? - -Follow the quick setup in [Install & build](./install.md) and then jump into [Getting started](./getting-started.md) for interactive usage tips, prompt examples, and AGENTS.md guidance. - -### `brew upgrade codex` isn't upgrading me - -If you're running Codex v0.46.0 or older, `brew upgrade codex` will not move you to the latest version because we migrated from a Homebrew formula to a cask. To upgrade, uninstall the existing oudated formula and then install the new cask: - -```bash -brew uninstall --formula codex -brew install --cask codex -``` - -After reinstalling, `brew upgrade --cask codex` will keep future releases up to date. diff --git a/docs/getting-started.md b/docs/getting-started.md index 923eb09568..b2ea5f2642 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,120 +1,3 @@ -## Getting started +# Getting started with Codex CLI -Looking for something specific? Jump ahead: - -- [Tips & shortcuts](#tips--shortcuts) – hotkeys, resume flow, prompts -- [Non-interactive runs](./exec.md) – automate with `codex exec` -- Ready for deeper customization? Head to [`advanced.md`](./advanced.md) - -### CLI usage - -| Command | Purpose | Example | -| ------------------ | ---------------------------------- | ------------------------------- | -| `codex` | Interactive TUI | `codex` | -| `codex "..."` | Initial prompt for interactive TUI | `codex "fix lint errors"` | -| `codex exec "..."` | Non-interactive "automation mode" | `codex exec "explain utils.ts"` | - -Key flags: `--model/-m`, `--ask-for-approval/-a`. - -### Resuming interactive sessions - -- Run `codex resume` to display the session picker UI -- Resume most recent: `codex resume --last` -- Resume by id: `codex resume ` (You can get session ids from /status or `~/.codex/sessions/`) -- The picker shows the session's recorded Git branch when available. -- To show the session's original working directory (CWD), run `codex resume --all` (this also disables cwd filtering and adds a `CWD` column). - -Examples: - -```shell -# Open a picker of recent sessions -codex resume - -# Resume the most recent session -codex resume --last - -# Resume a specific session by id -codex resume 7f9f9a2e-1b3c-4c7a-9b0e-123456789abc -``` - -### Running with a prompt as input - -You can also run Codex CLI with a prompt as input: - -```shell -codex "explain this codebase to me" -``` - -### Example prompts - -Below are a few bite-size examples you can copy-paste. Replace the text in quotes with your own task. - -| ✨ | What you type | What happens | -| --- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| 1 | `codex "Refactor the Dashboard component to React Hooks"` | Codex rewrites the class component, runs `npm test`, and shows the diff. | -| 2 | `codex "Generate SQL migrations for adding a users table"` | Infers your ORM, creates migration files, and runs them in a sandboxed DB. | -| 3 | `codex "Write unit tests for utils/date.ts"` | Generates tests, executes them, and iterates until they pass. | -| 4 | `codex "Bulk-rename *.jpeg -> *.jpg with git mv"` | Safely renames files and updates imports/usages. | -| 5 | `codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$"` | Outputs a step-by-step human explanation. | -| 6 | `codex "Carefully review this repo, and propose 3 high impact well-scoped PRs"` | Suggests impactful PRs in the current codebase. | -| 7 | `codex "Look for vulnerabilities and create a security review report"` | Finds and explains security bugs. | - -Looking to reuse your own instructions? Create slash commands with [custom prompts](./prompts.md). - -### Memory with AGENTS.md - -You can give Codex extra instructions and guidance using `AGENTS.md` files. Codex looks for them in the following places, and merges them top-down: - -1. `~/.codex/AGENTS.md` - personal global guidance -2. Every directory from the repository root down to your current working directory (inclusive). In each directory, Codex first looks for `AGENTS.override.md` and uses it if present; otherwise it falls back to `AGENTS.md`. Use the override form when you want to replace inherited instructions for that directory. - -For more information on how to use AGENTS.md, see the [official AGENTS.md documentation](https://agents.md/). - -### Tips & shortcuts - -#### Use `@` for file search - -Typing `@` triggers a fuzzy-filename search over the workspace root. Use up/down to select among the results and Tab or Enter to replace the `@` with the selected path. You can use Esc to cancel the search. - -#### Esc–Esc to edit a previous message - -When the chat composer is empty, press Esc to prime “backtrack” mode. Press Esc again to open a transcript preview highlighting the last user message; press Esc repeatedly to step to older user messages. Press Enter to confirm and Codex will fork the conversation from that point, trim the visible transcript accordingly, and pre‑fill the composer with the selected user message so you can edit and resubmit it. - -In the transcript preview, the footer shows an `Esc edit prev` hint while editing is active. - -#### `--cd`/`-C` flag - -Sometimes it is not convenient to `cd` to the directory you want Codex to use as the "working root" before running Codex. Fortunately, `codex` supports a `--cd` option so you can specify whatever folder you want. You can confirm that Codex is honoring `--cd` by double-checking the **workdir** it reports in the TUI at the start of a new session. - -#### `--add-dir` flag - -Need to work across multiple projects in one run? Pass `--add-dir` one or more times to expose extra directories as writable roots for the current session while keeping the main working directory unchanged. For example: - -```shell -codex --cd apps/frontend --add-dir ../backend --add-dir ../shared -``` - -Codex can then inspect and edit files in each listed directory without leaving the primary workspace. - -#### Shell completions - -Generate shell completion scripts via: - -```shell -codex completion bash -codex completion zsh -codex completion fish -``` - -#### Image input - -Paste images directly into the composer (Ctrl+V / Cmd+V) to attach them to your prompt. You can also attach files via the CLI using `-i/--image` (comma‑separated): - -```bash -codex -i screenshot.png "Explain this error" -codex --image img1.png,img2.jpg "Summarize these diagrams" -``` - -#### Environment variables and executables - -Make sure your environment is already set up before launching Codex so it does not spend tokens probing what to activate. For example, source your Python virtualenv (or other language runtimes), start any required daemons, and export the env vars you expect to use ahead of time. +For an overview of Codex CLI features, see [this documentation](https://developers.openai.com/codex/cli/features#running-in-interactive-mode). diff --git a/docs/install.md b/docs/install.md index b54b74f16c..a9905144e3 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,4 +1,4 @@ -## Install & build +## Installing & building ### System requirements @@ -46,3 +46,17 @@ just test # Otherwise, fall back to: cargo test --all-features ``` + +## Tracing / verbose logging + +Codex is written in Rust, so it honors the `RUST_LOG` environment variable to configure its logging behavior. + +The TUI defaults to `RUST_LOG=codex_core=info,codex_tui=info,codex_rmcp_client=info` and log messages are written to `~/.codex/log/codex-tui.log`, so you can leave the following running in a separate terminal to monitor log messages as they are written: + +```bash +tail -F ~/.codex/log/codex-tui.log +``` + +By comparison, the non-interactive mode (`codex exec`) defaults to `RUST_LOG=error`, but messages are printed inline, so there is no need to monitor a separate file. + +See the Rust documentation on [`RUST_LOG`](https://docs.rs/env_logger/latest/env_logger/#enabling-logging) for more information on the configuration options. diff --git a/docs/platform-sandboxing.md b/docs/platform-sandboxing.md deleted file mode 100644 index e635520401..0000000000 --- a/docs/platform-sandboxing.md +++ /dev/null @@ -1,3 +0,0 @@ -## Platform sandboxing - -This content now lives alongside the rest of the sandbox guidance. See [Sandbox mechanics by platform](./sandbox.md#sandbox-mechanics-by-platform) for up-to-date details. diff --git a/docs/prompts.md b/docs/prompts.md index c995cb912f..fa3da5b3bd 100644 --- a/docs/prompts.md +++ b/docs/prompts.md @@ -1,96 +1,3 @@ -## Custom Prompts +# Custom prompts -Custom prompts turn your repeatable instructions into reusable slash commands, so you can trigger them without retyping or copy/pasting. Each prompt is a Markdown file that Codex expands into the conversation the moment you run it. - -### Where prompts live - -- Location: store prompts in `$CODEX_HOME/prompts/` (defaults to `~/.codex/prompts/`). Set `CODEX_HOME` if you want to use a different folder. -- File type: Codex only loads `.md` files. Non-Markdown files are ignored. Both regular files and symlinks to Markdown files are supported. -- Naming: The filename (without `.md`) becomes the prompt name. A file called `review.md` registers the prompt `review`. -- Refresh: Prompts are loaded when a session starts. Restart Codex (or start a new session) after adding or editing files. -- Conflicts: Files whose names collide with built-in commands (like `init`) stay hidden in the slash popup, but you can still invoke them with `/prompts:`. - -### File format - -- Body: The file contents are sent verbatim when you run the prompt (after placeholder expansion). -- Frontmatter (optional): Add YAML-style metadata at the top of the file to improve the slash popup. - - ```markdown - --- - description: Request a concise git diff review - argument-hint: FILE= [FOCUS=
] - --- - ``` - - - `description` shows under the entry in the popup. - - `argument-hint` (or `argument_hint`) lets you document expected inputs, though the current UI ignores this metadata. - -### Placeholders and arguments - -- Numeric placeholders: `$1`–`$9` insert the first nine positional arguments you type after the command. `$ARGUMENTS` inserts all positional arguments joined by a single space. Use `$$` to emit a literal dollar sign (Codex leaves `$$` untouched). -- Named placeholders: Tokens such as `$FILE` or `$TICKET_ID` expand from `KEY=value` pairs you supply. Keys are case-sensitive—use the same uppercase name in the command (for example, `FILE=...`). -- Quoted arguments: Double-quote any value that contains spaces, e.g. `TICKET_TITLE="Fix logging"`. -- Invocation syntax: Run prompts via `/prompts: ...`. When the slash popup is open, typing either `prompts:` or the bare prompt name will surface `/prompts:` suggestions. -- Error handling: If a prompt contains named placeholders, Codex requires them all. You will see a validation message if any are missing or malformed. - -### Running a prompt - -1. Start a new Codex session (ensures the prompt list is fresh). -2. In the composer, type `/` to open the slash popup. -3. Type `prompts:` (or start typing the prompt name) and select it with ↑/↓. -4. Provide any required arguments, press Enter, and Codex sends the expanded content. - -### Examples - -### Example 1: Basic named arguments - -**File**: `~/.codex/prompts/ticket.md` - -```markdown ---- -description: Generate a commit message for a ticket -argument-hint: TICKET_ID= TICKET_TITLE= ---- - -Please write a concise commit message for ticket $TICKET_ID: $TICKET_TITLE -``` - -**Usage**: - -``` -/prompts:ticket TICKET_ID=JIRA-1234 TICKET_TITLE="Fix login bug" -``` - -**Expanded prompt sent to Codex**: - -``` -Please write a concise commit message for ticket JIRA-1234: Fix login bug -``` - -**Note**: Both `TICKET_ID` and `TICKET_TITLE` are required. If either is missing, Codex will show a validation error. Values with spaces must be double-quoted. - -### Example 2: Mixed positional and named arguments - -**File**: `~/.codex/prompts/review.md` - -```markdown ---- -description: Review code in a specific file with focus area -argument-hint: FILE=<path> [FOCUS=<section>] ---- - -Review the code in $FILE. Pay special attention to $FOCUS. -``` - -**Usage**: - -``` -/prompts:review FILE=src/auth.js FOCUS="error handling" -``` - -**Expanded prompt**: - -``` -Review the code in src/auth.js. Pay special attention to error handling. - -``` +For an overview of custom prompts, see [this documentation](https://developers.openai.com/codex/custom-prompts). diff --git a/docs/sandbox.md b/docs/sandbox.md index 94f9c8280c..f5ca8d89bd 100644 --- a/docs/sandbox.md +++ b/docs/sandbox.md @@ -1,96 +1,3 @@ ## Sandbox & approvals -What Codex is allowed to do is governed by a combination of **sandbox modes** (what Codex is allowed to do without supervision) and **approval policies** (when you must confirm an action). This page explains the options, how they interact, and how the sandbox behaves on each platform. - -### Approval policies - -Codex starts conservatively. Until you explicitly tell it a working directory is trusted, the CLI defaults to **read-only**. Codex can inspect files and answer questions, but every edit or command requires approval. - -When you mark a working directory as trusted (for example via the onboarding prompt or `/approvals` → “Trust this directory”), Codex upgrades the default preset to **Agent**, which allows writes inside the workspace. Codex only interrupts you when it needs to leave the workspace or rerun something outside the sandbox. Note that the workspace includes the working directory plus temporary directories like `/tmp`. Use `/status` to confirm the exact writable roots. - -If you want maximum guardrails for a trusted repo, switch back to Read Only from the `/approvals` picker. If you truly need hands-off automation, use `Full Access`—but be deliberate, because that skips both the sandbox and approvals. - -### Can I run without ANY approvals? - -Yes, you can disable all approval prompts with `--ask-for-approval never`. This option works with all `--sandbox` modes, so you still have full control over Codex's level of autonomy. It will make its best attempt with whatever constraints you provide. - -### Common sandbox + approvals combinations - -| Intent | Flags | Effect | -| ---------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. | -| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Reads only; never escalates | -| Let it edit the repo, ask if risky | `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval for actions outside the workspace or for network access. | -| Auto (preset; trusted repos) | `--full-auto` (equivalent to `--sandbox workspace-write` + `--ask-for-approval on-request`) | Codex runs sandboxed commands that can write inside the workspace without prompting. Escalates only when it must leave the sandbox. | -| YOLO (not recommended) | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | No sandbox; no prompts | - -> Note: In `workspace-write`, network is disabled by default unless enabled in config (`[sandbox_workspace_write].network_access = true`). - -#### Fine-tuning in `config.toml` - -```toml -# approval mode -approval_policy = "untrusted" -sandbox_mode = "read-only" - -# full-auto mode -approval_policy = "on-request" -sandbox_mode = "workspace-write" - -# Optional: allow network in workspace-write mode -[sandbox_workspace_write] -network_access = true -``` - -You can also save presets as **profiles**: - -```toml -[profiles.full_auto] -approval_policy = "on-request" -sandbox_mode = "workspace-write" - -[profiles.readonly_quiet] -approval_policy = "never" -sandbox_mode = "read-only" -``` - -### Sandbox mechanics by platform - -The mechanism Codex uses to enforce the sandbox policy depends on your OS: - -#### macOS 12+ - -Uses **Apple Seatbelt**. Codex invokes `sandbox-exec` with a profile that corresponds to the selected `--sandbox` mode, constraining filesystem and network access at the OS level. - -#### Linux - -Combines **Landlock** and **seccomp** APIs to approximate the same guarantees. Kernel support is required; older kernels may not expose the necessary features. - -In containerized Linux environments (for example Docker), sandboxing may not work when the host or container configuration does not expose Landlock/seccomp. In those cases, configure the container to provide the isolation you need and run Codex with `--sandbox danger-full-access` (or the shorthand `--dangerously-bypass-approvals-and-sandbox`) inside that container. - -#### Windows - -Windows sandbox support remains experimental. How it works: - -- Launches commands inside a restricted token derived from an AppContainer profile. -- Grants only specifically requested filesystem capabilities by attaching capability SIDs to that profile. -- Disables outbound network access by overriding proxy-related environment variables and inserting stub executables for common network tools. - -Its primary limitation is that it cannot prevent file writes, deletions, or creations in any directory where the Everyone SID already has write permissions (for example, world-writable folders). -See more discussion and limitations at [Windows Sandbox Security Details](./windows_sandbox_security.md). - -## Experimenting with the Codex Sandbox - -To test how commands behave under Codex's sandbox, use the CLI helpers: - -``` -# macOS -codex sandbox macos [--full-auto] [COMMAND]... - -# Linux -codex sandbox linux [--full-auto] [COMMAND]... - -# Legacy aliases -codex debug seatbelt [--full-auto] [COMMAND]... -codex debug landlock [--full-auto] [COMMAND]... -``` +For information about Codex sandboxing and approvals, see [this documentation](https://developers.openai.com/codex/security). diff --git a/docs/slash_commands.md b/docs/slash_commands.md index 03c4049b52..4db63f7f6e 100644 --- a/docs/slash_commands.md +++ b/docs/slash_commands.md @@ -1,33 +1,3 @@ -## Slash Commands +# Slash commands -### What are slash commands? - -Slash commands are special commands you can type that start with `/`. - ---- - -### Built-in slash commands - -Control Codex’s behavior during an interactive session with slash commands. - -| Command | Purpose | -| --------------- | -------------------------------------------------------------------------- | -| `/model` | choose what model and reasoning effort to use | -| `/approvals` | choose what Codex can do without approval | -| `/review` | review my current changes and find issues | -| `/new` | start a new chat during a conversation | -| `/resume` | resume an old chat | -| `/init` | create an AGENTS.md file with instructions for Codex | -| `/compact` | summarize conversation to prevent hitting the context limit | -| `/diff` | show git diff (including untracked files) | -| `/mention` | mention a file | -| `/status` | show current session configuration and token usage | -| `/mcp` | list configured MCP tools | -| `/experimental` | open the experimental menu to enable features from our beta program | -| `/skills` | browse and insert skills (experimental; see [docs/skills.md](./skills.md)) | -| `/logout` | log out of Codex | -| `/quit` | exit Codex | -| `/exit` | exit Codex | -| `/feedback` | send logs to maintainers | - ---- +For an overview of Codex CLI slash commands, see [this documentation](https://developers.openai.com/codex/cli/slash-commands). diff --git a/docs/windows_sandbox_security.md b/docs/windows_sandbox_security.md deleted file mode 100644 index 79f8f781b1..0000000000 --- a/docs/windows_sandbox_security.md +++ /dev/null @@ -1,22 +0,0 @@ -# Windows Sandbox Security Details - -For overall context on sandboxing in Codex, see [sandbox.md](./sandbox.md). - -## Implementation Overview - -When commands run via `codex sandbox windows …` (or when the CLI/TUI calls into the same crate in-process for sandboxed turns), the launcher configures a restricted Windows token and an allowlist policy scoped to the declared workspace roots. Writes are blocked everywhere except inside those roots (plus `%TEMP%` when workspace-write mode is requested), and common escape vectors such as alternate data streams, UNC paths, and device handles are denied proactively. The CLI also injects stub executables (for example, wrapping `ssh`) ahead of the host PATH so we can intercept dangerous tools before they ever leave the sandbox. - -## Known Security Limitations - -Running `python windows-sandbox-rs/sandbox_smoketests.py` with full filesystem and network access currently results in **37/41** passing cases. The list below focuses on the four high-value failures numbered #32 and higher in the smoketests (earlier tests are less security-focused). - -| Test | Purpose | -| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| ADS write denied (#32) | Ensures alternate data streams cannot be written inside the workspace, preventing tools from hiding payloads in ADS. The sandbox currently allows the write (process returns `rc=0`). | -| protected path case-variation denied (#33) | Confirms that protected directories such as `.git` remain blocked even when attackers use case tricks like `.GiT`. The current allowlist treats `.GiT` as distinct, so the write succeeds. | -| PATH stub bypass denied (#35) | Verifies that a workspace-provided `ssh.bat` shim placed ahead of the host PATH runs instead of the real `ssh`. The sandbox exits early before emitting the shim's `stubbed` output, so we cannot prove the interception works. | -| Start-Process https denied (KNOWN FAIL) (#41) | Validates that read-only runs cannot launch the host's default browser via `Start-Process 'https://...'`. Today the command succeeds (exit code 0) because Explorer handles the ShellExecute request outside the sandbox. The failure is captured by `windows-sandbox-rs/sandbox_smoketests.py` (last case). | - -## Want to Help? - -If you are a security-minded Windows user, help us get these tests passing! Improved implementations that make these smoke tests pass meaningfully reduce Codex's escape surface. After iterating, rerun `python windows-sandbox-rs/sandbox_smoketests.py` to validate the fixes and help us drive the suite toward 41/41. diff --git a/docs/zdr.md b/docs/zdr.md deleted file mode 100644 index d030e8d07f..0000000000 --- a/docs/zdr.md +++ /dev/null @@ -1,3 +0,0 @@ -## Zero data retention (ZDR) usage - -Codex CLI natively supports OpenAI organizations with [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) enabled.