OpenAI - Codex Docs Changes

agent-approvals-security.md +69 −2

Details

73- `<writable_root>/.codex` is protected as read-only when it exists as a directory.73- `<writable_root>/.codex` is protected as read-only when it exists as a directory.

74- Protection is recursive, so everything under those paths is read-only.74- Protection is recursive, so everything under those paths is read-only.

75 75

76### Deny reads with filesystem profiles

78Named permission profiles can also deny reads for exact paths or glob patterns.

79This is useful when a workspace should stay writable but specific sensitive

80files, such as local environment files, must stay unreadable:

82```toml

83default_permissions = "workspace"

85[permissions.workspace.filesystem]

86":project_roots" = { "." = "write", "**/*.env" = "none" }

87glob_scan_max_depth = 3

88```

90Use `"none"` for paths or globs that Codex shouldn't read. The sandbox policy

91evaluates globs for local macOS and Linux command execution. On platforms that

92pre-expand glob matches before the sandbox starts, set `glob_scan_max_depth` for

93unbounded `**` patterns, or list explicit depths such as `*.env`, `*/*.env`, and

94`*/*/*.env`.

76### Run without approval prompts96### Run without approval prompts

77 97

78You can disable approval prompts with `--ask-for-approval never` or `-a never` (shorthand).98You can disable approval prompts with `--ask-for-approval never` or `-a never` (shorthand).

153Codex enforces the sandbox differently depending on your OS:173Codex enforces the sandbox differently depending on your OS:

154 174

155- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.175- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.

156- **Linux** uses the `bwrap` pipeline plus `seccomp` by default. `use_legacy_landlock` is available when you need the older path. In managed proxy mode, the default `bwrap` pipeline routes egress through a proxy-only bridge and fails closed if it can’t build valid local proxy routes.176- **Linux** uses `bwrap` plus `seccomp` by default.

157- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux 2 (WSL2)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). WSL1 was supported through Codex `0.114`; starting in `0.115`, the Linux sandbox moved to `bwrap`, so WSL1 is no longer supported. When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.177- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux 2 (WSL2)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). WSL1 was supported through Codex `0.114`; starting in `0.115`, the Linux sandbox moved to `bwrap`, so WSL1 is no longer supported. When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.

158 178

159If you use the Codex IDE extension on Windows, it supports WSL2 directly. Set the following in your VS Code settings to keep the agent inside WSL2 whenever it's available:179If you use the Codex IDE extension on Windows, it supports WSL2 directly. Set the following in your VS Code settings to keep the agent inside WSL2 whenever it's available:

176 196

177See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.197See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.

178 198

179When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.199When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration blocks the namespace, setuid `bwrap`, or `seccomp` operations that Codex needs.

180 200

181In that case, configure your Docker container to provide the isolation you need, then run `codex` with `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag) inside the container.201In that case, configure your Docker container to provide the isolation you need, then run `codex` with `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag) inside the container.

182 202

203### Run Codex in Dev Containers

204

205If your host cannot run the Linux sandbox directly, or if your organization already standardizes on containerized development, run Codex with Dev Containers and let Docker provide the outer isolation boundary. This works with Visual Studio Code Dev Containers and compatible tools.

206

207Use the [Codex secure devcontainer example](https://github.com/openai/codex/tree/main/.devcontainer) as a reference implementation. The example installs Codex, common development tools, `bubblewrap`, and firewall-based outbound controls.

208

209Devcontainers provide substantial protection, but they do not prevent every

210 attack. If you run Codex with `--sandbox danger-full-access` or

211 `--dangerously-bypass-approvals-and-sandbox` inside the container, a malicious

212 project can exfiltrate anything available inside the devcontainer, including

213 Codex credentials. Use this pattern only with trusted repositories, and

214 monitor Codex activity as you would in any other elevated environment.

215

216The reference implementation includes:

217

218- an Ubuntu 24.04 base image with Codex and common development tools installed;

219- an allowlist-driven firewall profile for outbound access;

220- VS Code settings and extension recommendations for reopening the workspace in a container;

221- persistent mounts for command history and Codex configuration;

222- `bubblewrap`, so Codex can still use its Linux sandbox when the container grants the needed capabilities.

223

224To try it:

225

2261. Install Visual Studio Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).

2272. Copy the Codex example `.devcontainer` setup into your repository, or start from the Codex repository directly.

2283. In VS Code, run **Dev Containers: Open Folder in Container…** and select `.devcontainer/devcontainer.secure.json`.

2294. After the container starts, open a terminal and run `codex`.

230

231You can also start the container from the CLI:

232

233```bash

234devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json

235```

236

237The example has three main pieces:

238

239- `.devcontainer/devcontainer.secure.json` controls container settings, capabilities, mounts, environment variables, and VS Code extensions.

240- `.devcontainer/Dockerfile.secure` defines the Ubuntu-based image and installed tools.

241- `.devcontainer/init-firewall.sh` applies the outbound network policy.

242

243The reference firewall is intentionally a starting point. If you depend on domain allowlisting for isolation, implement DNS rebinding and DNS refresh protections that fit your environment, such as TTL-aware refreshes or a DNS-aware firewall.

244

245Inside the container, choose one of these modes:

246

247- Keep Codex's Linux sandbox enabled if the Dev Container profile grants the capabilities needed for `bwrap` to create the inner sandbox.

248- If the container is your intended security boundary, run Codex with `--sandbox danger-full-access` inside the container so Codex does not try to create a second sandbox layer.

249

183## Version control250## Version control

184 251

185Codex works best with a version control workflow:252Codex works best with a version control workflow:

app-server.md +22 −4

Details

222- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.222- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.

223- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).223- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).

224- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).224- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).

225- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace errors, featured plugin ids, and the development-only `forceRemoteSync` option.225- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace load errors, featured plugin ids, and local, Git, or remote plugin source metadata.

226- `plugin/read` - read one plugin by marketplace path and plugin name, including bundled skills, apps, and MCP server names.226- `plugin/read` - read one plugin by marketplace path or remote marketplace name and plugin name, including bundled skills, apps, and MCP server names when those details are available.

227- `plugin/install` - install a plugin from a marketplace path.227- `plugin/install` - install a plugin from a marketplace path or remote marketplace name.

228- `plugin/uninstall` - uninstall an installed plugin.228- `plugin/uninstall` - uninstall an installed plugin.

229- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.229- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.

230- `skills/config/write` - enable or disable skills by path.230- `skills/config/write` - enable or disable skills by path.

243- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).243- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).

244- `fs/readFile`, `fs/writeFile`, `fs/createDirectory`, `fs/getMetadata`, `fs/readDirectory`, `fs/remove`, and `fs/copy` - operate on absolute filesystem paths through the app-server v2 filesystem API.244- `fs/readFile`, `fs/writeFile`, `fs/createDirectory`, `fs/getMetadata`, `fs/readDirectory`, `fs/remove`, and `fs/copy` - operate on absolute filesystem paths through the app-server v2 filesystem API.

245 245

246Plugin summaries include a `source` union. Local plugins return

247`{ "type": "local", "path": ... }`, Git-backed marketplace entries return

248`{ "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }`,

249and remote catalog entries return `{ "type": "remote" }`. For remote-only

250catalog entries, `PluginMarketplaceEntry.path` can be `null`; pass

251`remoteMarketplaceName` instead of `marketplacePath` when reading or installing

252those plugins.

253

246## Models254## Models

247 255

248### List models (`model/list`)256### List models (`model/list`)

1222{ "id": 64, "result": {} }1230{ "id": 64, "result": {} }

1223```1231```

1224 1232

1225Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, and `MCP_SERVER_CONFIG`. Detection returns only items that still have work to do. For example, AGENTS migration is skipped when `AGENTS.md` already exists and is non-empty, and skill imports don’t overwrite existing skill directories.1233Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, `PLUGINS`,

1234and `MCP_SERVER_CONFIG`. For `PLUGINS` items, `details.plugins` lists each

1235`marketplaceName` and the `pluginNames` Codex can try to migrate. Detection

1236returns only items that still have work to do. For example, Codex skips AGENTS

1237migration when `AGENTS.md` already exists and is non-empty, and skill imports

1238don't overwrite existing skill directories.

1239

1240When detecting plugins from `.claude/settings.json`, Codex reads configured

1241marketplace sources from `extraKnownMarketplaces`. If `enabledPlugins` contains

1242plugins from `claude-plugins-official` but the marketplace source is missing,

1243Codex infers `anthropics/claude-plugins-official` as the source.

1226 1244

1227## Auth endpoints1245## Auth endpoints

1228 1246

cli/features.md +4 −2

Details

22- Watch Codex explain its plan before making a change, and approve or reject steps inline.22- Watch Codex explain its plan before making a change, and approve or reject steps inline.

23- Read syntax-highlighted markdown code blocks and diffs in the TUI, then use `/theme` to preview and save a preferred theme.23- Read syntax-highlighted markdown code blocks and diffs in the TUI, then use `/theme` to preview and save a preferred theme.

24- Use `/clear` to wipe the terminal and start a fresh chat, or press <kbd>Ctrl</kbd>+<kbd>L</kbd> to clear the screen without starting a new conversation.24- Use `/clear` to wipe the terminal and start a fresh chat, or press <kbd>Ctrl</kbd>+<kbd>L</kbd> to clear the screen without starting a new conversation.

~~25- Use `/copy` to copy the latest completed Codex output. If a turn is still running, Codex copies the most recent finished output instead of in-progress text.~~25- Use `/copy` or press <kbd>Ctrl</kbd>+<kbd>O</kbd> to copy the latest completed Codex output. If a turn is still running, Codex copies the most recent finished output instead of in-progress text.

26- Press <kbd>Tab</kbd> while Codex is running to queue follow-up text, slash commands, or `!` shell commands for the next turn.

26- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.27- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.

28- Press <kbd>Ctrl</kbd>+<kbd>R</kbd> to search prompt history from the composer, then press <kbd>Enter</kbd> to accept a match or <kbd>Esc</kbd> to cancel.

27- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.29- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.

28 30

29## Resuming conversations31## Resuming conversations

271## Tips and shortcuts273## Tips and shortcuts

272 274

273- Type `@` in the composer to open a fuzzy file search over the workspace root; press <kbd>Tab</kbd> or <kbd>Enter</kbd> to drop the highlighted path into your message.275- Type `@` in the composer to open a fuzzy file search over the workspace root; press <kbd>Tab</kbd> or <kbd>Enter</kbd> to drop the highlighted path into your message.

274- Press `Enter` while Codex is running to inject new instructions into the current turn, or press `Tab` to queue a follow-up prompt for the next turn.276- Press <kbd>Enter</kbd> while Codex is running to inject new instructions into the current turn, or press <kbd>Tab</kbd> to queue follow-up input for the next turn. Queued input can be a normal prompt, a slash command such as `/review`, or a `!` shell command. Codex parses queued slash commands when they run.

275- Prefix a line with `!` to run a local shell command (for example, `!ls`). Codex treats the output like a user-provided command result and still applies your approval and sandbox settings.277- Prefix a line with `!` to run a local shell command (for example, `!ls`). Codex treats the output like a user-provided command result and still applies your approval and sandbox settings.

276- Tap <kbd>Esc</kbd> twice while the composer is empty to edit your previous user message. Continue pressing <kbd>Esc</kbd> to walk further back in the transcript, then hit <kbd>Enter</kbd> to fork from that point.278- Tap <kbd>Esc</kbd> twice while the composer is empty to edit your previous user message. Continue pressing <kbd>Esc</kbd> to walk further back in the transcript, then hit <kbd>Enter</kbd> to fork from that point.

277- Launch Codex from any directory using `codex --cd <path>` to set the working root without running `cd` first. The active path appears in the TUI header.279- Launch Codex from any directory using `codex --cd <path>` to set the working root without running `cd` first. The active path appears in the TUI header.

cli/reference.md +66 −8

Details

262| Key | Maturity | Details |262| Key | Maturity | Details |

263| --- | --- | --- |263| --- | --- | --- |

264| [`codex`](https://developers.openai.com/codex/cli/reference#codex-interactive) | Stable | Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments. |264| [`codex`](https://developers.openai.com/codex/cli/reference#codex-interactive) | Stable | Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments. |

265| [`codex app`](https://developers.openai.com/codex/cli/reference#codex-app) | Stable | Launch the Codex desktop app on macOS, optionally opening a specific workspace path. |265| [`codex app`](https://developers.openai.com/codex/cli/reference#codex-app) | Stable | Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open. |

266| [`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server) | Experimental | Launch the Codex app server for local development or debugging. |266| [`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server) | Experimental | Launch the Codex app server for local development or debugging. |

267| [`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply) | Stable | Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`. |267| [`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply) | Stable | Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`. |

268| [`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud) | Experimental | Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`. |268| [`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud) | Experimental | Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`. |

277| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |277| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |

278| [`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server) | Experimental | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex. |278| [`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server) | Experimental | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex. |

279| [`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace) | Experimental | Add, upgrade, or remove plugin marketplaces from Git or local sources. |

279| [`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume) | Stable | Continue a previous interactive session by ID or resume the most recent conversation. |280| [`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume) | Stable | Continue a previous interactive session by ID or resume the most recent conversation. |

280| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes. |281| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes. |

281 282

301 302

302Details303Details

303 304

304Launch the Codex desktop app on macOS, optionally opening a specific workspace path.305Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open.

305 306

306Key307Key

307 308

461 462

462Key463Key

463 464

465[`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace)

466

467Maturity

468

469Experimental

470

471Details

472

473Add, upgrade, or remove plugin marketplaces from Git or local sources.

474

475Key

476

464[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)477[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)

465 478

466Maturity479Maturity

595 608

596### `codex app`609### `codex app`

597 610

598Launch Codex Desktop from the terminal on macOS and optionally open a specific workspace path.611Launch Codex Desktop from the terminal on macOS or Windows. On macOS, Codex can open a specific workspace path; on Windows, Codex prints the path to open.

599 612

600| Key | Type / Values | Details |613| Key | Type / Values | Details |

601| --- | --- | --- |614| --- | --- | --- |

602| `--download-url` | `url` | Advanced override for the Codex desktop DMG download URL used during install. |615| `--download-url` | `url` | Advanced override for the Codex desktop installer URL used during install. |

604 617

605Key618Key

606 619

612 625

613Details626Details

614 627

615Advanced override for the Codex desktop DMG download URL used during install.628Advanced override for the Codex desktop installer URL used during install.

616 629

617Key630Key

618 631

624 637

625Details638Details

626 639

627Workspace path to open in Codex Desktop (`codex app` is available on macOS only).640Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.

628 641

629`codex app` installs/opens the desktop app on macOS, then opens the provided workspace path. This subcommand is macOS-only.642`codex app` opens an installed Codex Desktop app, or starts the installer when

643the app is missing. On macOS, Codex opens the provided workspace path; on

644Windows, it prints the path to open after installation.

630 645

631### `codex debug app-server send-message-v2`646### `codex debug app-server send-message-v2`

632 647

1381 1396

1382OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).1397OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).

1383 1398

1399### `codex plugin marketplace`

1400

1401Manage plugin marketplace sources that Codex can browse and install from.

1402

1403| Key | Type / Values | Details |

1404| --- | --- | --- |

1405| `add <source>` | `[--ref REF] [--sparse PATH]` | Install a plugin marketplace from GitHub shorthand, a Git URL, an SSH URL, or a local marketplace root directory. `--sparse` is supported only for Git sources and can be repeated. |

1406| `remove <marketplace-name>` | | Remove a configured plugin marketplace. |

1407| `upgrade [marketplace-name]` | | Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided. |

1408

1409Key

1410

1411`add <source>`

1412

1413Type / Values

1414

1415`[--ref REF] [--sparse PATH]`

1416

1417Details

1418

1419Install a plugin marketplace from GitHub shorthand, a Git URL, an SSH URL, or a local marketplace root directory. `--sparse` is supported only for Git sources and can be repeated.

1420

1421Key

1422

1423`remove <marketplace-name>`

1424

1425Details

1426

1427Remove a configured plugin marketplace.

1428

1429Key

1430

1431`upgrade [marketplace-name]`

1432

1433Details

1434

1435Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided.

1436

1437`codex plugin marketplace add` accepts GitHub shorthand such as `owner/repo` or

1438`owner/repo@ref`, HTTP or HTTPS Git URLs, SSH Git URLs, and local marketplace

1439root directories. Use `--ref` to pin a Git ref, and repeat `--sparse PATH` to

1440use a sparse checkout for Git-backed marketplace repositories.

1441

1384### `codex mcp-server`1442### `codex mcp-server`

1385 1443

1386Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.1444Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.

cli/slash-commands.md +13 −4

Details

16Codex ships with the following commands. Open the slash popup and start typing16Codex ships with the following commands. Open the slash popup and start typing

17the command name to filter the list.17the command name to filter the list.

18 18

19When a task is already running, you can type a slash command and press `Tab` to

20queue it for the next turn. Codex parses queued slash commands when they run, so

21command menus and errors appear after the current turn finishes. Slash

22completion still works before you queue the command.

20| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |25| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |

21| [`/permissions`](#update-permissions-with-permissions) | Set what Codex can do without asking first. | Relax or tighten approval requirements mid-session, such as switching between Auto and Read Only. |26| [`/permissions`](#update-permissions-with-permissions) | Set what Codex can do without asking first. | Relax or tighten approval requirements mid-session, such as switching between Auto and Read Only. |

25| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |30| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |

26| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a fresh start. |31| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a fresh start. |

27| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |32| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |

~~28| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. |~~33| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. You can also press `Ctrl+O`. |

138the in-progress response. The command is unavailable before the first completed143the in-progress response. The command is unavailable before the first completed

139Codex output and immediately after a rollback.144Codex output and immediately after a rollback.

140 145

146You can also press <kbd>Ctrl</kbd>+<kbd>O</kbd> from the main TUI to copy the

147latest completed response without opening the slash command menu.

148

141### Grant sandbox read access with `/sandbox-add-read-dir`149### Grant sandbox read access with `/sandbox-add-read-dir`

142 150

143This command is available only when running the CLI natively on Windows.151This command is available only when running the CLI natively on Windows.

295### Browse plugins with `/plugins`303### Browse plugins with `/plugins`

296 304

2971. Type `/plugins`.3051. Type `/plugins`.

2982. Pick a plugin from the list to inspect its capabilities or available actions.3062. Choose a marketplace tab, then pick a plugin to inspect its capabilities or available actions.

299 307

300Expected: Codex opens the plugin browser so you can review installed plugins and308Expected: Codex opens the plugin browser so you can review installed plugins,

301discoverable plugins that your configuration allows.309discoverable plugins that your configuration allows, and installed plugin state.

310Press <kbd>Space</kbd> on an installed plugin to toggle its enabled state.

302 311

303### Switch agent threads with `/agent`312### Switch agent threads with `/agent`

304 313

concepts/sandboxing.md +3 −0

Details

131Managed network profiles use map tables such as131Managed network profiles use map tables such as

132`[permissions.<name>.network.domains]` and132`[permissions.<name>.network.domains]` and

133`[permissions.<name>.network.unix_sockets]` for domain and socket rules.133`[permissions.<name>.network.unix_sockets]` for domain and socket rules.

134Filesystem profiles can also deny reads for exact paths or glob patterns by

135setting matching entries to `"none"`; use this to keep files such as local

136secrets unreadable without turning off workspace writes.

134 137

135When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules138When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules

136let you allow, prompt, or forbid command prefixes outside the sandbox, which is139let you allow, prompt, or forbid command prefixes outside the sandbox, which is

config-advanced.md +4 −0

Details

476- `notify` runs an external program (good for webhooks, desktop notifiers, CI hooks).476- `notify` runs an external program (good for webhooks, desktop notifiers, CI hooks).

477- `tui.notifications` is built in to the TUI and can optionally filter by event type (for example, `agent-turn-complete` and `approval-requested`).477- `tui.notifications` is built in to the TUI and can optionally filter by event type (for example, `agent-turn-complete` and `approval-requested`).

478- `tui.notification_method` controls how the TUI emits terminal notifications (`auto`, `osc9`, or `bel`).478- `tui.notification_method` controls how the TUI emits terminal notifications (`auto`, `osc9`, or `bel`).

479- `tui.notification_condition` controls whether TUI notifications fire only when

480 the terminal is `unfocused` or `always`.

479 481

480In `auto` mode, Codex prefers OSC 9 notifications (a terminal escape sequence some terminals interpret as a desktop notification) and falls back to BEL (`\x07`) otherwise.482In `auto` mode, Codex prefers OSC 9 notifications (a terminal escape sequence some terminals interpret as a desktop notification) and falls back to BEL (`\x07`) otherwise.

481 483

522 524

523- `tui.notifications`: enable/disable notifications (or restrict to specific types)525- `tui.notifications`: enable/disable notifications (or restrict to specific types)

524- `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications526- `tui.notification_method`: choose `auto`, `osc9`, or `bel` for terminal notifications

527- `tui.notification_condition`: choose `unfocused` or `always` for when

528 notifications fire

525- `tui.animations`: enable/disable ASCII animations and shimmer effects529- `tui.animations`: enable/disable ASCII animations and shimmer effects

526- `tui.alternate_screen`: control alternate screen usage (set to `never` to keep terminal scrollback)530- `tui.alternate_screen`: control alternate screen usage (set to `never` to keep terminal scrollback)

527- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen531- `tui.show_tooltips`: show or hide onboarding tooltips on the welcome screen

config-basic.md +1 −1

Details

config-reference.md +89 −37

Details

53| `features.guardian_approval` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`. |

~~60| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |~~

~~87| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |~~87| `mcp_servers.<id>.env_vars` | `array<string | { name = string, source = "local" | "remote" }>` | Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio. |

88| `mcp_servers.<id>.experimental_environment` | `local | remote` | Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented. |

98| `memories.disable_on_external_context` | `boolean` | When `true`, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`. |

102| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |104| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |

104| `memories.no_memories_if_mcp_or_web_search` | `boolean` | When `true`, threads that use MCP tool calls or web search are kept out of memory generation. Defaults to `false`. |

163| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |164| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

164| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |165| `permissions.<name>.filesystem.":project_roots".<subpath-or-glob>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`. |

167| `permissions.<name>.filesystem.glob_scan_max_depth` | `number` | Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set. |

227| `tui.notification_method` | `auto | osc9 | bel` | Notification method for terminal notifications (default: auto). |

714 717

715Key718Key

716 719

720`features.guardian_approval`

721

722Type / Values

723

724`boolean`

725

726Details

727

728Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`.

729

730Key

731

717`features.memories`732`features.memories`

718 733

719Type / Values734Type / Values

798 813

799Key814Key

800 815

801`features.smart_approvals`

~~802~~

803Type / Values

~~804~~

805`boolean`

~~806~~

807Details

~~808~~

809Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

~~810~~

811Key

~~812~~

813`features.undo`816`features.undo`

814 817

815Type / Values818Type / Values

1126 1129

1127Type / Values1130Type / Values

1128 1131

1129`array<string>`1132`array<string | { name = string, source = "local" | "remote" }>`

1133

1134Details

1135

1136Additional environment variables to whitelist for an MCP stdio server. String entries default to `source = "local"`; use `source = "remote"` only with executor-backed remote stdio.

1137

1138Key

1139

1140`mcp_servers.<id>.experimental_environment`

1141

1142Type / Values

1143

1144`local | remote`

1130 1145

1131Details1146Details

1132 1147

1133Additional environment variables to whitelist for an MCP stdio server.1148Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.

1134 1149

1135Key1150Key

1136 1151

1242 1257

1243Key1258Key

1244 1259

1260`memories.disable_on_external_context`

1261

1262Type / Values

1263

1264`boolean`

1265

1266Details

1267

1268When `true`, threads that use external context such as MCP tool calls, web search, or tool search are kept out of memory generation. Defaults to `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`.

1269

1270Key

1271

1245`memories.extract_model`1272`memories.extract_model`

1246 1273

1247Type / Values1274Type / Values

1326 1353

1327Key1354Key

1328 1355

1329`memories.no_memories_if_mcp_or_web_search`

~~1330~~

1331Type / Values

~~1332~~

1333`boolean`

~~1334~~

1335Details

~~1336~~

1337When `true`, threads that use MCP tool calls or web search are kept out of memory generation. Defaults to `false`.

~~1338~~

1339Key

~~1340~~

1341`memories.use_memories`1356`memories.use_memories`

1342 1357

1343Type / Values1358Type / Values

2046 2061

2047Key2062Key

2048 2063

2049`permissions.<name>.filesystem.":project_roots".<subpath>`2064`permissions.<name>.filesystem.":project_roots".<subpath-or-glob>`

2050 2065

2051Type / Values2066Type / Values

2052 2067

2054 2069

2055Details2070Details

2056 2071

2057Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.2072Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself; glob subpaths such as `"**/*.env"` can deny reads with `"none"`.

2058 2073

2059Key2074Key

2060 2075

2061`permissions.<name>.filesystem.<path>`2076`permissions.<name>.filesystem.<path-or-glob>`

2062 2077

2063Type / Values2078Type / Values

2064 2079

2066 2081

2067Details2082Details

2068 2083

2069Grant direct access for a path or special token, or scope nested entries under that root.2084Grant direct access for a path, glob pattern, or special token, or scope nested entries under that root. Use `"none"` to deny reads for matching paths.

2085

2086Key

2087

2088`permissions.<name>.filesystem.glob_scan_max_depth`

2089

2090Type / Values

2091

2092`number`

2093

2094Details

2095

2096Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches before sandbox startup. Must be at least `1` when set.

2070 2097

2071Key2098Key

2072 2099

2766 2793

2767Key2794Key

2768 2795

2796`tui.notification_condition`

2797

2798Type / Values

2799

2800`unfocused | always`

2801

2802Details

2803

2804Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`.

2805

2806Key

2807

2769`tui.notification_method`2808`tui.notification_method`

2770 2809

2771Type / Values2810Type / Values

2774 2813

2775Details2814Details

2776 2815

2777Notification method for unfocused terminal notifications (default: auto).2816Notification method for terminal notifications (default: auto).

2778 2817

2779Key2818Key

2780 2819

2960| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |

3048 3088

3049Key3089Key

3050 3090

3091`permissions.filesystem.deny_read`

3092

3093Type / Values

3094

3095`array<string>`

3096

3097Details

3098

3099Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config.

3100

3101Key

3102

3051`rules`3103`rules`

3052 3104

3053Type / Values3105Type / Values

config-sample.md +25 −2

Details

133# Named permissions profile to apply by default. Required before using [permissions.<name>].133# Named permissions profile to apply by default. Required before using [permissions.<name>].

134# default_permissions = "workspace"134# default_permissions = "workspace"

135 135

136# Example filesystem profile. Use `"none"` to deny reads for exact paths or

137# glob patterns. On platforms that need pre-expanded glob matches, set

138# glob_scan_max_depth when using unbounded patterns such as `**`.

139# [permissions.workspace.filesystem]

140# glob_scan_max_depth = 3

141# ":project_roots" = { "." = "write", "**/*.env" = "none" }

142# "/absolute/path/to/secrets" = "none"

143

136################################################################################144################################################################################

137# Authentication & Login145# Authentication & Login

138################################################################################146################################################################################

323# Notification mechanism for terminal alerts: auto | osc9 | bel. Default: "auto"331# Notification mechanism for terminal alerts: auto | osc9 | bel. Default: "auto"

324# notification_method = "auto"332# notification_method = "auto"

325 333

334# When notifications fire: unfocused (default) | always

335# notification_condition = "unfocused"

336

326# Enables welcome/status/spinner animations. Default: true337# Enables welcome/status/spinner animations. Default: true

327animations = true338animations = true

328 339

382# multi_agent = true393# multi_agent = true

383# personality = true394# personality = true

384# fast_mode = true395# fast_mode = true

385# smart_approvals = false396# guardian_approval = false

386# enable_request_compression = true397# enable_request_compression = true

387# skill_mcp_dependency_install = true398# skill_mcp_dependency_install = true

388# prevent_idle_sleep = false399# prevent_idle_sleep = false

389 400

401################################################################################

402# Memories (table)

403################################################################################

404

405# Enable memories with [features].memories, then tune memory behavior here.

406# [memories]

407# generate_memories = true

408# use_memories = true

409# disable_on_external_context = false # legacy alias: no_memories_if_mcp_or_web_search

410

390################################################################################411################################################################################

391# Define MCP servers under this table. Leave empty to disable.412# Define MCP servers under this table. Leave empty to disable.

392################################################################################413################################################################################

400# command = "docs-server" # required421# command = "docs-server" # required

401# args = ["--port", "4000"] # optional422# args = ["--port", "4000"] # optional

402# env = { "API_KEY" = "value" } # optional key/value pairs copied as-is423# env = { "API_KEY" = "value" } # optional key/value pairs copied as-is

403# env_vars = ["ANOTHER_SECRET"] # optional: forward these from the parent env424# env_vars = ["ANOTHER_SECRET"] # optional: forward local parent env vars

425# env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

404# cwd = "/path/to/server" # optional working directory override426# cwd = "/path/to/server" # optional working directory override

427# experimental_environment = "remote" # experimental: run stdio via a remote executor

405# startup_timeout_sec = 10.0 # optional; default 10.0 seconds428# startup_timeout_sec = 10.0 # optional; default 10.0 seconds

406# # startup_timeout_ms = 10000 # optional alias for startup timeout (milliseconds)429# # startup_timeout_ms = 10000 # optional alias for startup timeout (milliseconds)

407# tool_timeout_sec = 60.0 # optional; default 60.0 seconds430# tool_timeout_sec = 60.0 # optional; default 60.0 seconds

enterprise/managed-configuration.md +19 −0

Details

91 91

92Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.92Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.

93 93

94### Enforce deny-read requirements

96Admins can deny reads for exact paths or glob patterns with

97`[permissions.filesystem]`. Users can't weaken these requirements with local

98configuration.

100```toml

101[permissions.filesystem]

102deny_read = [

103 "/Users/alice/.ssh",

104 "./private/**/*.txt",

105]

106```

107

108When deny-read requirements are present, Codex constrains local sandbox mode to

109`read-only` or `workspace-write` so the requirement can be enforced. On native

110Windows, managed `deny_read` applies to direct file tools; shell subprocess

111reads don’t use this sandbox requirement.

112

94### Enforce command rules from requirements113### Enforce command rules from requirements

95 114

96Admins can also enforce restrictive command rules from `requirements.toml`115Admins can also enforce restrictive command rules from `requirements.toml`

hooks.md +85 −15

Details

9- Send the conversation to a custom logging/analytics engine9- Send the conversation to a custom logging/analytics engine

10- Scan your team's prompts to block accidentally pasting API keys10- Scan your team's prompts to block accidentally pasting API keys

11- Summarize conversations to create persistent memories automatically11- Summarize conversations to create persistent memories automatically

~~12- Run a custom validator when a conversation turn stops, enforcing standards~~12- Run a custom validation check when a conversation turn stops, enforcing standards

13- Customize prompting when in a certain directory13- Customize prompting when in a certain directory

14 14

15Hooks are behind a feature flag in `config.toml`:15Hooks are behind a feature flag in `config.toml`:

23 23

24- Matching hooks from multiple files all run.24- Matching hooks from multiple files all run.

25- Multiple matching command hooks for the same event are launched concurrently,25- Multiple matching command hooks for the same event are launched concurrently,

~~26 so one hook cannot prevent another matching hook from starting.~~26 so one hook can’t prevent another matching hook from starting.

~~27- `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, and `Stop` run at turn~~27- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and

~~28 scope.~~28 `Stop` run at turn scope.

29- Hooks are currently disabled on Windows.29- Hooks are currently disabled on Windows.

30 30

31## Where Codex looks for hooks31## Where Codex looks for hooks

38- `<repo>/.codex/hooks.json`38- `<repo>/.codex/hooks.json`

39 39

40If more than one `hooks.json` file exists, Codex loads all matching hooks.40If more than one `hooks.json` file exists, Codex loads all matching hooks.

~~41Higher-precedence config layers do not replace lower-precedence hooks.~~41Higher-precedence config layers don’t replace lower-precedence hooks.

42 42

43## Config shape43## Config shape

44 44

75 ]75 ]

76 }76 }

77 ],77 ],

78 "PermissionRequest": [

79 {

80 "matcher": "Bash",

81 "hooks": [

82 {

83 "type": "command",

84 "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/permission_request.py\"",

85 "statusMessage": "Checking approval request"

86 }

87 ]

88 }

89 ],

78 "PostToolUse": [90 "PostToolUse": [

79 {91 {

80 "matcher": "Bash",92 "matcher": "Bash",

133 145

135| --- | --- | --- |147| --- | --- | --- |

148| `PermissionRequest` | tool name | Current Codex runtime only emits `Bash`. |

146- `Edit|Write`159- `Edit|Write`

147 160

148That last example is still a valid regex, but current Codex `PreToolUse` and161That last example is still a valid regex, but current Codex `PreToolUse` and

149`PostToolUse` events only emit `Bash`, so it will not match anything today.162`PostToolUse` events only emit `Bash`, so it won’t match anything today.

150 163

151## Common input fields164## Common input fields

152 165

189 202

190Exit `0` with no output is treated as success and Codex continues.203Exit `0` with no output is treated as success and Codex continues.

191 204

192`PreToolUse` supports `systemMessage`, but `continue`, `stopReason`, and205`PreToolUse` and `PermissionRequest` support `systemMessage`, but `continue`,

193`suppressOutput` are not currently supported for that event.206`stopReason`, and `suppressOutput` aren't currently supported for those events.

194 207

195`PostToolUse` supports `systemMessage`, `continue: false`, and `stopReason`.208`PostToolUse` supports `systemMessage`, `continue: false`, and `stopReason`.

196`suppressOutput` is parsed but not currently supported for that event.209`suppressOutput` is parsed but not currently supported for that event.

278`updatedInput`, `additionalContext`, `continue: false`, `stopReason`, and291`updatedInput`, `additionalContext`, `continue: false`, `stopReason`, and

279`suppressOutput` are parsed but not supported yet, so they fail open.292`suppressOutput` are parsed but not supported yet, so they fail open.

280 293

294### PermissionRequest

295

296Work in progress

297

298`PermissionRequest` runs when Codex is about to ask for approval, such as a

299shell escalation or managed-network approval. It can allow the request, deny

300the request, or decline to decide and let the normal approval prompt continue.

301It doesn't run for commands that don't need approval.

302

303`matcher` is applied to `tool_name`, which currently always equals `Bash`.

304

305Fields in addition to [Common input fields](#common-input-fields):

306

307| Field | Type | Meaning |

308| --- | --- | --- |

309| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

310| `tool_name` | `string` | Currently always `Bash` |

311| `tool_input.command` | `string` | Shell command associated with the approval request |

313

314Plain text on `stdout` is ignored.

315

316To approve the request, return:

317

318```json

319{

320 "hookSpecificOutput": {

321 "hookEventName": "PermissionRequest",

322 "decision": {

323 "behavior": "allow"

324 }

325 }

326}

327```

328

329To deny the request, return:

330

331```json

332{

333 "hookSpecificOutput": {

334 "hookEventName": "PermissionRequest",

335 "decision": {

336 "behavior": "deny",

337 "message": "Blocked by repository policy."

338 }

339 }

340}

341```

342

343If multiple matching hooks return decisions, any `deny` wins. Otherwise, an

344`allow` lets the request proceed without surfacing the approval prompt. If no

345matching hook decides, Codex uses the normal approval flow.

346

347Don't return `updatedInput`, `updatedPermissions`, or `interrupt` for

348`PermissionRequest`; those fields are reserved for future behavior and fail

349closed today.

350

281### PostToolUse351### PostToolUse

282 352

283Work in progress353Work in progress

284 354

285Currently `PostToolUse` only supports Bash tool results. It is not limited to355Currently `PostToolUse` only supports Bash tool results. It’s not limited to

286commands that exit successfully: non-interactive `exec_command` calls can still356commands that exit successfully: non-interactive `exec_command` calls can still

287trigger `PostToolUse` when Codex emits a Bash post-tool payload. It cannot undo357trigger `PostToolUse` when Codex emits a Bash post-tool payload. It can’t undo

288side effects from the command that already ran.358side effects from the command that already ran.

289 359

290This doesn't intercept all shell calls yet, only the simple ones. The newer360This doesn't intercept all shell calls yet, only the simple ones. The newer

321 391

322That `additionalContext` text is added as extra developer context.392That `additionalContext` text is added as extra developer context.

323 393

324For this event, `decision: "block"` does not undo the completed Bash command.394For this event, `decision: "block"` doesn't undo the completed Bash command.

325Instead, Codex records the feedback, replaces the tool result with that395Instead, Codex records the feedback, replaces the tool result with that

326feedback, and continues the model from the hook-provided message.396feedback, and continues the model from the hook-provided message.

327 397

336 406

337### UserPromptSubmit407### UserPromptSubmit

338 408

339`matcher` is not currently used for this event.409`matcher` isn't currently used for this event.

340 410

341Fields in addition to [Common input fields](#common-input-fields):411Fields in addition to [Common input fields](#common-input-fields):

342 412

344| --- | --- | --- |414| --- | --- | --- |

347 417

348Plain text on `stdout` is added as extra developer context.418Plain text on `stdout` is added as extra developer context.

349 419

374 444

375### Stop445### Stop

376 446

377`matcher` is not currently used for this event.447`matcher` isn't currently used for this event.

378 448

379Fields in addition to [Common input fields](#common-input-fields):449Fields in addition to [Common input fields](#common-input-fields):

380 450

399 469

400You can also use exit code `2` and write the continuation reason to `stderr`.470You can also use exit code `2` and write the continuation reason to `stderr`.

401 471

402For this event, `decision: "block"` does not reject the turn. Instead, it tells472For this event, `decision: "block"` doesn't reject the turn. Instead, it tells

403Codex to continue and automatically creates a new continuation prompt that acts473Codex to continue and automatically creates a new continuation prompt that acts

404as a new user prompt, using your `reason` as that prompt text.474as a new user prompt, using your `reason` as that prompt text.

405 475

mcp.md +14 −1

Details

58- `env` (optional): Environment variables to set for the server.58- `env` (optional): Environment variables to set for the server.

59- `env_vars` (optional): Environment variables to allow and forward.59- `env_vars` (optional): Environment variables to allow and forward.

60- `cwd` (optional): Working directory to start the server from.60- `cwd` (optional): Working directory to start the server from.

61- `experimental_environment` (optional): Set to `remote` to start the stdio

62 server through a remote executor environment when one is available.

64`env_vars` can contain plain variable names or objects with a source:

66```toml

67env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

68```

70String entries and `source = "local"` read from Codex's local environment.

71`source = "remote"` reads from the remote executor environment and requires

72remote MCP stdio.

61 73

62#### Streamable HTTP servers74#### Streamable HTTP servers

63 75

77 89

78If your OAuth provider requires a fixed callback port, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.90If your OAuth provider requires a fixed callback port, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.

79 91

80If your MCP OAuth flow must use a specific callback URL (for example, a remote devbox ingress URL or a custom callback path), set `mcp_oauth_callback_url`. Codex uses this value as the OAuth `redirect_uri` while still using `mcp_oauth_callback_port` for the callback listener port. Local callback URLs (for example `localhost`) bind on loopback; non-local callback URLs bind on `0.0.0.0` so the callback can reach the host.92If your MCP OAuth flow must use a specific callback URL (for example, a remote Devbox ingress URL or a custom callback path), set `mcp_oauth_callback_url`. Codex uses this value as the OAuth `redirect_uri` while still using `mcp_oauth_callback_port` for the callback listener port. Local callback URLs (for example `localhost`) bind on the local interface; non-local callback URLs bind on `0.0.0.0` so the callback can reach the host.

81 93

82If the MCP server advertises `scopes_supported`, Codex prefers those94If the MCP server advertises `scopes_supported`, Codex prefers those

83server-advertised scopes during OAuth login. Otherwise, Codex falls back to the95server-advertised scopes during OAuth login. Otherwise, Codex falls back to the

89[mcp_servers.context7]101[mcp_servers.context7]

90command = "npx"102command = "npx"

91args = ["-y", "@upstash/context7-mcp"]103args = ["-y", "@upstash/context7-mcp"]

104env_vars = ["LOCAL_TOKEN"]

92 105

93[mcp_servers.context7.env]106[mcp_servers.context7.env]

94MY_ENV_VAR = "MY_ENV_VALUE"107MY_ENV_VAR = "MY_ENV_VALUE"

memories.md +7 −0

Details

14memories as a helpful local recall layer, not as the only source for rules that14memories as a helpful local recall layer, not as the only source for rules that

15must always apply.15must always apply.

16 16

17[Chronicle](https://developers.openai.com/codex/memories/chronicle) helps Codex recover recent working

18context from your screen to build up memory.

17## Enable memories20## Enable memories

18 21

19In the Codex app, enable Memories in settings.22In the Codex app, enable Memories in settings.

75 stored as memory-generation inputs.78 stored as memory-generation inputs.

76- `memories.use_memories`: controls whether Codex injects existing memories into79- `memories.use_memories`: controls whether Codex injects existing memories into

77 future sessions.80 future sessions.

81- `memories.disable_on_external_context`: when `true`, keeps threads that used

82 external context such as MCP tool calls, web search, or tool search out of

83 memory generation. The older `memories.no_memories_if_mcp_or_web_search` key

84 is still accepted as an alias.

78- `memories.extract_model`: overrides the model used for per-thread memory85- `memories.extract_model`: overrides the model used for per-thread memory

79 extraction.86 extraction.

80- `memories.consolidation_model`: overrides the model used for global memory87- `memories.consolidation_model`: overrides the model used for global memory

memories/chronicle.md +155 −0 added

Details

1# Chronicle

3Chronicle is in an **opt-in research preview**. It is only available for

4 ChatGPT Pro subscribers on macOS, and is not yet available in the EU, UK and

5 Switzerland. Please review the [Privacy and Security](#privacy-and-security)

6 section for details and to understand the current risks before enabling.

8Chronicle augments Codex memories with context from your screen. When you prompt

9Codex, those memories can help it understand what you’ve been working on with

10less need for you to restate context.

12Chronicle is available as an opt-in research preview in the Codex app on macOS.

13It requires macOS Screen Recording and Accessibility permissions. Before

14enabling, be aware that Chronicle uses rate limits quickly, increases risk of

15prompt injection, and stores memories unencrypted on your device.

17## How Chronicle helps

19We’ve designed Chronicle to reduce the amount of context you have to restate

20when you work with Codex. By using recent screen context to improve memory

21building, Chronicle can help Codex understand what you’re referring to, identify

22the right source to use, and pick up on the tools and workflows you rely on.

24### Use what’s on screen

26With Chronicle Codex can understand what you are currently looking at, saving

27you time and context switching.

29### Fill in missing context

31No need to carefully craft your context and start from zero. Chronicle lets

32Codex fill in the gaps in your context.

34### Remember tools and workflows

36No need to explain to Codex which tools to use to perform your work. Codex

37learns as you work to save you time in the long run.

39In these cases, Codex uses Chronicle to provide additional context. When another

40source is better for the job, such as reading the specific file, Slack thread,

41Google Doc, dashboard, or pull request, Codex uses Chronicle to identify the

42source and then use that source directly.

44## Enable Chronicle

461. Open Settings in the Codex app.

472. Go to **Personalization** and make sure **Memories** is enabled.

483. Turn on **Chronicle** below the Memories setting.

494. Review the consent dialog and choose **Continue**.

505. Grant macOS Screen Recording and Accessibility permissions when prompted.

516. When setup completes, choose **Try it out** or start a new thread.

53If macOS reports that Screen Recording or Accessibility permission is denied,

54open System Settings > Privacy & Security > Screen Recording or

55Accessibility and enable Codex. If a permission is restricted by macOS or your

56organization, Chronicle will start after the restriction is removed and Codex

57receives the required permission.

59## Pause or disable Chronicle at any time

61You control when Chronicle generates memories using screen context. Use the

62Codex menu bar icon to choose **Pause Chronicle** or **Resume Chronicle**. Pause

63Chronicle before meetings or when viewing sensitive content that you do not want

64Codex to use as context. To disable Chronicle, return to **Settings >

65Personalization > Memories** and turn off **Chronicle**.

67You can also control whether memories are used in a given thread. [Learn

68more](https://developers.openai.com/codex/memories#control-memories-per-thread).

70## Rate limits

72Chronicle works by running sandboxed agents in the background to generate

73memories from captured screen images. These agents currently consume rate limits

74quickly.

76## Privacy and security

78Chronicle uses screen captures, which can include sensitive information visible

79on your screen. It does not have access to your microphone or system audio.

80Don’t use Chronicle to record meetings or communications with others without

81their consent. Pause Chronicle when viewing content you do not want remembered

82in memories.

84### Where does Chronicle store my data?

86Screen captures are ephemeral and will only be saved temporarily on your

87computer. Temporary screen capture files may appear under

88`$TMPDIR/chronicle/screen_recording/` while Chronicle is running. Screen captures

89that are older than 6 hours will be deleted while Chronicle is running.

91The memories that Chronicle generates are just like other Codex memories:

92unencrypted markdown files that you can read and modify if needed. You can also

93ask Codex to search them. If you want to have Codex forget something you can

94delete the respective file inside the folder or selectively edit the markdown

95files to remove the information you’d like to remove. You should not manually

96add new information. The generated Chronicle memories are stored locally on your

97computer under `$CODEX_HOME/memories_extensions/chronicle/` (typically

98`~/.codex/memories_extensions/chronicle`).

100Both directories for your screen captures and memories might contain sensitive information. Make sure you do not share content with others, and be aware that other programs on your computer can also access these files.

101

102### What data gets shared with OpenAI?

103

104Chronicle captures screen context locally, then periodically uses Codex to

105summarize recent activity into memories. To generate those memories, Chronicle

106starts an ephemeral Codex session with access to this screen context. That

107session may process selected screenshot frames, OCR text extracted from

108screenshots, timing information, and local file paths for the relevant time

109window.

110

111Screen captures used for memory generation are stored temporarily on your device. They are processed on our

112servers to generate memories, which are then stored locally on device. We do not

113store the screenshots on our servers after processing unless required by law,

114and do not use them for training.

115

116The generated memories are Markdown files stored locally under

117`$CODEX_HOME/memories_extensions/chronicle/`. When Codex uses memories in a

118future session, relevant memory contents may be included as context for that

119session, and may be used to improve our models if allowed in your ChatGPT

120settings. [Learn more](https://help.openai.com/en/articles/7730893-data-controls-faq).

121

122## Prompt injection risk

123

124Using Chronicle increases risk to prompt injection attacks from screen content.

125For instance, if you browse a site with malicious agent instructions, Codex may

126follow those instructions.

127

128## Troubleshooting

129

130### How do I enable Chronicle?

131

132If you do not see the Chronicle setting, make sure you are using a Codex app

133build that includes Chronicle and that you have Memories enabled inside Settings

134> Personalization.

135

136Chronicle is currently only available for ChatGPT Pro subscribers on macOS.

137Chronicle is not available in the EU, UK and Switzerland.

138

139If setup does not complete:

140

1411. Confirm that Codex has Screen Recording and Accessibility permissions.

1422. Quit and reopen the Codex app.

1433. Open **Settings > Personalization** and check the Chronicle status.

144

145### Which model is used for generating the Chronicle memories?

146

147Chronicle uses the same model as your other [Memories](https://developers.openai.com/codex/memories). If you

148did not configure a specific model it uses your default Codex model. To choose a

149specific model, update the `consolidation_model` in your

150[configuration](https://developers.openai.com/codex/config-basic).

151

152```toml

153[memories]

154consolidation_model = "gpt-5.4-mini"

155```

plugins.md +4 −0

Details

43 43

44![Plugins list in Codex CLI](/images/codex/plugins/cli_light.png)44![Plugins list in Codex CLI](/images/codex/plugins/cli_light.png)

45 45

46The CLI plugin browser groups plugins by marketplace. Use the marketplace tabs

47to switch sources, open a plugin to inspect details, and press `Space`

48on an installed plugin to toggle its enabled state.

46### Install and use a plugin50### Install and use a plugin

47 51

48Once you open the plugin directory:52Once you open the plugin directory:

plugins/build.md +59 −5

Details

40 40

41![custom local marketplace in the plugin directory](/images/codex/plugins/codex-local-plugin-light.png)41![custom local marketplace in the plugin directory](/images/codex/plugins/codex-local-plugin-light.png)

42 42

43### Add a marketplace from the CLI

45Use `codex plugin marketplace add` when you want Codex to install and track a

46marketplace source for you instead of editing `config.toml` by hand.

48```bash

49codex plugin marketplace add owner/repo

50codex plugin marketplace add owner/repo --ref main

51codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins

52codex plugin marketplace add ./local-marketplace-root

53```

55Marketplace sources can be GitHub shorthand (`owner/repo` or

56`owner/repo@ref`), HTTP or HTTPS Git URLs, SSH Git URLs, or local marketplace root

57directories. Use `--ref` to pin a Git ref, and repeat `--sparse PATH` to use a

58sparse checkout for Git-backed marketplace repos. `--sparse` is valid only for

59Git marketplace sources.

61To refresh or remove configured marketplaces:

63```bash

64codex plugin marketplace upgrade

65codex plugin marketplace upgrade marketplace-name

66codex plugin marketplace remove marketplace-name

67```

43### Create a plugin manually69### Create a plugin manually

44 70

45Start with a minimal plugin that packages one skill.71Start with a minimal plugin that packages one skill.

211 personal installs, a common pattern is `./.codex/plugins/<plugin-name>`.237 personal installs, a common pattern is `./.codex/plugins/<plugin-name>`.

212- Keep `source.path` relative to the marketplace root, start it with `./`, and238- Keep `source.path` relative to the marketplace root, start it with `./`, and

213 keep it inside that root.239 keep it inside that root.

240- For local entries, `source` can also be a plain string path such as

241 `"./plugins/my-plugin"`.

214- Always include `policy.installation`, `policy.authentication`, and242- Always include `policy.installation`, `policy.authentication`, and

215 `category` on each plugin entry.243 `category` on each plugin entry.

216- Use `policy.installation` values such as `AVAILABLE`,244- Use `policy.installation` values such as `AVAILABLE`,

218- Use `policy.authentication` to decide whether auth happens on install or246- Use `policy.authentication` to decide whether auth happens on install or

219 first use.247 first use.

220 248

221The marketplace controls where Codex loads the plugin from. `source.path` can249The marketplace controls where Codex loads the plugin from. A local

222point somewhere else if your plugin lives outside those example directories. A250`source.path` can point somewhere else if your plugin lives outside those

223marketplace file can live in the repo where you are developing the plugin or in251example directories. A marketplace file can live in the repo where you are

224a separate marketplace repo, and one marketplace file can point to one plugin252developing the plugin or in a separate marketplace repo, and one marketplace

225or many.253file can point to one plugin or many.

254

255Marketplace entries can also point at Git-backed plugin sources. Use

256`"source": "url"` when the plugin lives at the repository root, or

257`"source": "git-subdir"` when the plugin lives in a subdirectory:

258

259```json

260{

261 "name": "remote-helper",

262 "source": {

263 "source": "git-subdir",

264 "url": "https://github.com/example/codex-plugins.git",

265 "path": "./plugins/remote-helper",

266 "ref": "main"

267 },

268 "policy": {

269 "installation": "AVAILABLE",

270 "authentication": "ON_INSTALL"

271 },

272 "category": "Productivity"

273}

274```

275

276Git-backed entries may use `ref` or `sha` selectors. If Codex can't resolve a

277marketplace entry's source, it skips that plugin entry instead of failing the

278whole marketplace.

226 279

227### How Codex uses marketplaces280### How Codex uses marketplaces

228 281

233 286

234- the curated marketplace that powers the official Plugin Directory287- the curated marketplace that powers the official Plugin Directory

235- a repo marketplace at `$REPO_ROOT/.agents/plugins/marketplace.json`288- a repo marketplace at `$REPO_ROOT/.agents/plugins/marketplace.json`

289- a Claude-style marketplace at `$REPO_ROOT/.claude-plugin/marketplace.json`

236- a personal marketplace at `~/.agents/plugins/marketplace.json`290- a personal marketplace at `~/.agents/plugins/marketplace.json`

237 291

238You can install any plugin exposed through a marketplace. Codex installs292You can install any plugin exposed through a marketplace. Codex installs

remote-connections.md +12 −3

Details

1# Remote connections1# Remote connections

2 2

~~3SSH remote connections are currently in alpha. We are gradually rolling out~~3SSH remote connections are currently in alpha. To enable them today, set

~~4access. Availability, setup flows, and supported environments may change as~~4`remote_control = true` in the `[features]` table in `~/.codex/config.toml`.

~~5the feature improves.~~5Availability, setup flows, and supported environments may change as the

6feature improves.

6 7

7Remote connections let Codex work with projects that live on another8Remote connections let Codex work with projects that live on another

8SSH-accessible machine. Use them when the codebase, credentials, services, or9SSH-accessible machine. Use them when the codebase, credentials, services, or

424. In the Codex app, open **Settings > Connections**, add or enable the SSH host,434. In the Codex app, open **Settings > Connections**, add or enable the SSH host,

43 then choose a remote project folder.44 then choose a remote project folder.

44 45

46If remote connections don't appear yet, enable the alpha feature flag in

47`~/.codex/config.toml`:

49```toml

50[features]

51remote_control = true

52```

45Remote project threads run commands, read files, and write changes on the54Remote project threads run commands, read files, and write changes on the

46remote host.55remote host.

47 56

OpenAI - Codex Docs Changes 2026-04-17 00:44 UTC → 2026-04-21 12:30 UTC