OpenAI - Codex Docs Changes

app.md +1 −0

Details

41- Find and fix bugs in my codebase with minimal, high-confidence changes.41- Find and fix bugs in my codebase with minimal, high-confidence changes.

42 42

43 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).43 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).

44 If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

44 45

45---46---

46 47

app/windows.md +12 −0

Details

28winget install Codex -s msstore28winget install Codex -s msstore

29```29```

30 30

31## Native sandbox

33The Codex app on Windows supports a native [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) when the agent runs in PowerShell, and uses Linux sandboxing when you run the agent in [Windows Subsystem for Linux (WSL)](#windows-subsystem-for-linux-wsl). To apply sandbox protections in either mode, set sandbox permissions to **Default permissions** in the Composer before sending messages to Codex.

35Running Codex in full access mode means Codex is not limited to your project

36 directory and might perform unintentional destructive actions that can lead to

37 data loss. Keep sandbox boundaries in place and use [rules](https://developers.openai.com/codex/rules) for

38 targeted exceptions, or set your [approval policy to

39 never](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) to have

40 Codex attempt to solve problems without asking for escalated permissions,

41 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).

31## Customize for your dev setup43## Customize for your dev setup

32 44

33### Preferred editor45### Preferred editor

auth.md +5 −1

Details

26 26

27OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the [API pricing page](https://openai.com/api/pricing/).27OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the [API pricing page](https://openai.com/api/pricing/).

28 28

~~29Recommendation is to use API key authentication for programmatic Codex CLI workflows (for example CI/CD jobs). Do not expose Codex execution in untrusted or publicly triggerable environments.~~29Features that rely on ChatGPT credits, such as [fast mode](https://developers.openai.com/codex/speed), are

30available only when you sign in with ChatGPT. If you sign in with an API key,

31Codex uses standard API pricing instead.

33Recommendation is to use API key authentication for programmatic Codex CLI workflows (for example CI/CD jobs). Don't expose Codex execution in untrusted or public environments.

30 34

31## Secure your Codex cloud account35## Secure your Codex cloud account

32 36

cli.md +2 −0

Details

47experimental. For the best Windows experience, use Codex in a WSL workspace47experimental. For the best Windows experience, use Codex in a WSL workspace

48and follow our [Windows setup guide](https://developers.openai.com/codex/windows).48and follow our [Windows setup guide](https://developers.openai.com/codex/windows).

49 49

50If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

50---52---

51 53

52## Work with the Codex CLI54## Work with the Codex CLI

config-basic.md +0 −1

Details

147 147

148| Key | Default | Maturity | Description |148| Key | Default | Maturity | Description |

149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

config-reference.md +630 −58

Details

12| --- | --- | --- |12| --- | --- | --- |

15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

18| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |

20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |

19| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |21| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |

39| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

~~41| `experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |~~

~~43| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |~~

45| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |46| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |

47| `features.artifact` | `boolean` | Enable native artifact tools such as slides and spreadsheets (under development). |

50| `features.default_mode_request_user_input` | `boolean` | Allow `request_user_input` in default collaboration mode (under development; off by default). |

51| `features.elevated_windows_sandbox` | `boolean` | Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it. |

52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

53| `features.experimental_windows_sandbox` | `boolean` | Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it. |

54| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |

56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |

48| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |57| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |

62| `features.request_rule` | `boolean` | Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset. |

63| `features.responses_websockets` | `boolean` | Prefer the Responses API WebSocket transport for supported providers (under development). |

64| `features.responses_websockets_v2` | `boolean` | Enable Responses API WebSocket v2 mode (under development). |

70| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

71| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |

72| `features.steer` | `boolean` | Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior. |

73| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

74| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |

~~69| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |~~

102| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |

104| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |

128| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |

158| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |

159| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

160| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

161| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

162| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

163| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

164| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |

165| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

166| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |

167| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |

168| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

169| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |

171| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |

172| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |

143| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

144| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |179| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |

180| `profiles.<name>.model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. |

185| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |

212| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

172| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |214| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

217| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

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

222| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

179| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |223| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |

206 250

207Key251Key

208 252

253`agents.<name>.nickname_candidates`

254

255Type / Values

256

257`array<string>`

258

259Details

260

261Optional pool of display nicknames for spawned agents in that role.

262

263Key

264

209`agents.job_max_runtime_seconds`265`agents.job_max_runtime_seconds`

210 266

211Type / Values267Type / Values

238 294

239Details295Details

240 296

241Maximum number of agent threads that can be open concurrently.297Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

242 298

243Key299Key

244 300

254 310

255Key311Key

256 312

313`analytics.enabled`

314

315Type / Values

316

317`boolean`

318

319Details

320

321Enable or disable analytics for this machine/profile. When unset, the client default applies.

322

323Key

324

257`approval_policy`325`approval_policy`

258 326

259Type / Values327Type / Values

470 538

471Key539Key

472 540

541`commit_attribution`

542

543Type / Values

544

545`string`

546

547Details

548

549Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

550

551Key

552

473`compact_prompt`553`compact_prompt`

474 554

475Type / Values555Type / Values

518 598

519Key599Key

520 600

521`experimental_use_freeform_apply_patch`601`experimental_use_unified_exec_tool`

522 602

523Type / Values603Type / Values

524 604

526 606

527Details607Details

528 608

529Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.609Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

530 610

531Key611Key

532 612

533`experimental_use_unified_exec_tool`613`features.apps`

534 614

535Type / Values615Type / Values

536 616

538 618

539Details619Details

540 620

541Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.621Enable ChatGPT Apps/connectors support (experimental).

542 622

543Key623Key

544 624

545`features.apply_patch_freeform`625`features.apps_mcp_gateway`

546 626

547Type / Values627Type / Values

548 628

550 630

551Details631Details

552 632

553Expose the freeform `apply_patch` tool (experimental).633Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).

554 634

555Key635Key

556 636

557`features.apps`637`features.artifact`

558 638

559Type / Values639Type / Values

560 640

562 642

563Details643Details

564 644

565Enable ChatGPT Apps/connectors support (experimental).645Enable native artifact tools such as slides and spreadsheets (under development).

566 646

567Key647Key

568 648

569`features.apps_mcp_gateway`649`features.child_agents_md`

570 650

571Type / Values651Type / Values

572 652

574 654

575Details655Details

576 656

577Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).657Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).

578 658

579Key659Key

580 660

581`features.child_agents_md`661`features.collaboration_modes`

582 662

583Type / Values663Type / Values

584 664

586 666

587Details667Details

588 668

589Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).669Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.

590 670

591Key671Key

592 672

593`features.collaboration_modes`673`features.default_mode_request_user_input`

674

675Type / Values

676

677`boolean`

678

679Details

680

681Allow `request_user_input` in default collaboration mode (under development; off by default).

682

683Key

684

685`features.elevated_windows_sandbox`

686

687Type / Values

688

689`boolean`

690

691Details

692

693Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.

694

695Key

696

697`features.enable_request_compression`

698

699Type / Values

700

701`boolean`

702

703Details

704

705Compress streaming request bodies with zstd when supported (stable; on by default).

706

707Key

708

709`features.experimental_windows_sandbox`

710

711Type / Values

712

713`boolean`

714

715Details

716

717Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.

718

719Key

720

721`features.fast_mode`

722

723Type / Values

724

725`boolean`

726

727Details

728

729Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

730

731Key

732

733`features.image_detail_original`

734

735Type / Values

736

737`boolean`

738

739Details

740

741Allow image outputs with `detail = "original"` on supported models (under development).

742

743Key

744

745`features.image_generation`

594 746

595Type / Values747Type / Values

596 748

598 750

599Details751Details

600 752

601Enable collaboration modes such as plan mode (stable; on by default).753Enable the built-in image generation tool (under development).

602 754

603Key755Key

604 756

634 786

635Details787Details

636 788

637Force PowerShell UTF-8 output (defaults to true).789Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.

790

791Key

792

793`features.prevent_idle_sleep`

794

795Type / Values

796

797`boolean`

798

799Details

800

801Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

638 802

639Key803Key

640 804

646 810

647Details811Details

648 812

649Refresh remote model list before showing readiness (experimental).813Legacy toggle for an older remote-model readiness flow. Current builds do not use it.

650 814

651Key815Key

652 816

658 822

659Details823Details

660 824

661Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).825Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.

826

827Key

828

829`features.responses_websockets`

830

831Type / Values

832

833`boolean`

834

835Details

836

837Prefer the Responses API WebSocket transport for supported providers (under development).

838

839Key

840

841`features.responses_websockets_v2`

842

843Type / Values

844

845`boolean`

846

847Details

848

849Enable Responses API WebSocket v2 mode (under development).

662 850

663Key851Key

664 852

682 870

683Details871Details

684 872

685Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).873Legacy toggle for an older Apps discovery flow. Current builds do not use it.

686 874

687Key875Key

688 876

694 882

695Details883Details

696 884

697Snapshot shell environment to speed up repeated commands (beta).885Snapshot shell environment to speed up repeated commands (stable; on by default).

698 886

699Key887Key

700 888

710 898

711Key899Key

712 900

901`features.skill_env_var_dependency_prompt`

902

903Type / Values

904

905`boolean`

906

907Details

908

909Prompt for missing skill environment-variable dependencies (under development).

910

911Key

912

913`features.skill_mcp_dependency_install`

914

915Type / Values

916

917`boolean`

918

919Details

920

921Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

922

923Key

924

925`features.sqlite`

926

927Type / Values

928

929`boolean`

930

931Details

932

933Enable SQLite-backed state persistence (stable; on by default).

934

935Key

936

937`features.steer`

938

939Type / Values

940

941`boolean`

942

943Details

944

945Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.

946

947Key

948

949`features.undo`

950

951Type / Values

952

953`boolean`

954

955Details

956

957Enable undo support (stable; off by default).

958

959Key

960

713`features.unified_exec`961`features.unified_exec`

714 962

715Type / Values963Type / Values

718 966

719Details967Details

720 968

721Use the unified PTY-backed exec tool (beta).969Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

722 970

723Key971Key

724 972

854 1102

855Key1103Key

856 1104

857`include_apply_patch_tool`

~~858~~

859Type / Values

~~860~~

861`boolean`

~~862~~

863Details

~~864~~

865Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.

~~866~~

867Key

~~868~~

869`instructions`1105`instructions`

870 1106

871Type / Values1107Type / Values

1058 1294

1059Key1295Key

1060 1296

1297`mcp_servers.<id>.oauth_resource`

1298

1299Type / Values

1300

1301`string`

1302

1303Details

1304

1305Optional RFC 8707 OAuth resource parameter to include during MCP login.

1306

1307Key

1308

1061`mcp_servers.<id>.required`1309`mcp_servers.<id>.required`

1062 1310

1063Type / Values1311Type / Values

1070 1318

1071Key1319Key

1072 1320

1321`mcp_servers.<id>.scopes`

1322

1323Type / Values

1324

1325`array<string>`

1326

1327Details

1328

1329OAuth scopes to request when authenticating to that MCP server.

1330

1331Key

1332

1073`mcp_servers.<id>.startup_timeout_ms`1333`mcp_servers.<id>.startup_timeout_ms`

1074 1334

1075Type / Values1335Type / Values

1334 1594

1335Key1595Key

1336 1596

1597`model_providers.<id>.supports_websockets`

1598

1599Type / Values

1600

1601`boolean`

1602

1603Details

1604

1605Whether that provider supports the Responses API WebSocket transport.

1606

1607Key

1608

1337`model_providers.<id>.wire_api`1609`model_providers.<id>.wire_api`

1338 1610

1339Type / Values1611Type / Values

1340 1612

1341`chat | responses`1613`responses`

1342 1614

1343Details1615Details

1344 1616

1345Protocol used by the provider (defaults to `chat` if omitted).1617Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.

1346 1618

1347Key1619Key

1348 1620

1390 1662

1391Details1663Details

1392 1664

1393Control GPT-5 Responses API verbosity (defaults to `medium`).1665Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

1394 1666

1395Key1667Key

1396 1668

1598 1870

1599Key1871Key

1600 1872

1873`otel.metrics_exporter`

1874

1875Type / Values

1876

1877`none | statsig | otlp-http | otlp-grpc`

1878

1879Details

1880

1881Select the OpenTelemetry metrics exporter (defaults to `statsig`).

1882

1883Key

1884

1601`otel.trace_exporter`1885`otel.trace_exporter`

1602 1886

1603Type / Values1887Type / Values

1682 1966

1683Key1967Key

1684 1968

1969`permissions.network.admin_url`

1970

1971Type / Values

1972

1973`string`

1974

1975Details

1976

1977Admin endpoint for the managed network proxy.

1978

1979Key

1980

1981`permissions.network.allow_local_binding`

1982

1983Type / Values

1984

1985`boolean`

1986

1987Details

1988

1989Permit local bind/listen operations through the managed proxy.

1990

1991Key

1992

1993`permissions.network.allow_unix_sockets`

1994

1995Type / Values

1996

1997`array<string>`

1998

1999Details

2000

2001Allowlist of Unix socket paths permitted through the managed proxy.

2002

2003Key

2004

2005`permissions.network.allow_upstream_proxy`

2006

2007Type / Values

2008

2009`boolean`

2010

2011Details

2012

2013Allow the managed proxy to chain to another upstream proxy.

2014

2015Key

2016

2017`permissions.network.allowed_domains`

2018

2019Type / Values

2020

2021`array<string>`

2022

2023Details

2024

2025Allowlist of domains permitted through the managed proxy.

2026

2027Key

2028

2029`permissions.network.dangerously_allow_all_unix_sockets`

2030

2031Type / Values

2032

2033`boolean`

2034

2035Details

2036

2037Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

2038

2039Key

2040

2041`permissions.network.dangerously_allow_non_loopback_admin`

2042

2043Type / Values

2044

2045`boolean`

2046

2047Details

2048

2049Permit non-loopback bind addresses for the managed proxy admin listener.

2050

2051Key

2052

2053`permissions.network.dangerously_allow_non_loopback_proxy`

2054

2055Type / Values

2056

2057`boolean`

2058

2059Details

2060

2061Permit non-loopback bind addresses for the managed proxy listener.

2062

2063Key

2064

2065`permissions.network.denied_domains`

2066

2067Type / Values

2068

2069`array<string>`

2070

2071Details

2072

2073Denylist of domains blocked by the managed proxy.

2074

2075Key

2076

2077`permissions.network.enable_socks5`

2078

2079Type / Values

2080

2081`boolean`

2082

2083Details

2084

2085Expose a SOCKS5 listener from the managed network proxy.

2086

2087Key

2088

2089`permissions.network.enable_socks5_udp`

2090

2091Type / Values

2092

2093`boolean`

2094

2095Details

2096

2097Allow UDP over the SOCKS5 listener when enabled.

2098

2099Key

2100

2101`permissions.network.enabled`

2102

2103Type / Values

2104

2105`boolean`

2106

2107Details

2108

2109Enable the managed network proxy configuration for subprocesses.

2110

2111Key

2112

2113`permissions.network.mode`

2114

2115Type / Values

2116

2117`limited | full`

2118

2119Details

2120

2121Network proxy mode used for subprocess traffic.

2122

2123Key

2124

2125`permissions.network.proxy_url`

2126

2127Type / Values

2128

2129`string`

2130

2131Details

2132

2133HTTP proxy endpoint used by the managed network proxy.

2134

2135Key

2136

2137`permissions.network.socks_url`

2138

2139Type / Values

2140

2141`string`

2142

2143Details

2144

2145SOCKS5 proxy endpoint used by the managed network proxy.

2146

2147Key

2148

1685`personality`2149`personality`

1686 2150

1687Type / Values2151Type / Values

1694 2158

1695Key2159Key

1696 2160

2161`plan_mode_reasoning_effort`

2162

2163Type / Values

2164

2166

2167Details

2168

2169Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.

2170

2171Key

2172

1697`profile`2173`profile`

1698 2174

1699Type / Values2175Type / Values

1718 2194

1719Key2195Key

1720 2196

1721`profiles.<name>.experimental_use_freeform_apply_patch`2197`profiles.<name>.analytics.enabled`

1722 2198

1723Type / Values2199Type / Values

1724 2200

1726 2202

1727Details2203Details

1728 2204

1729Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.2205Profile-scoped analytics enablement override.

1730 2206

1731Key2207Key

1732 2208

1742 2218

1743Key2219Key

1744 2220

1745`profiles.<name>.include_apply_patch_tool`2221`profiles.<name>.model_catalog_json`

1746 2222

1747Type / Values2223Type / Values

1748 2224

1749`boolean`2225`string (path)`

1750 2226

1751Details2227Details

1752 2228

1753Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.2229Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).

1754 2230

1755Key2231Key

1756 2232

1757`profiles.<name>.model_catalog_json`2233`profiles.<name>.model_instructions_file`

1758 2234

1759Type / Values2235Type / Values

1760 2236

1762 2238

1763Details2239Details

1764 2240

1765Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).2241Profile-scoped replacement for the built-in instruction file.

1766 2242

1767Key2243Key

1768 2244

1790 2266

1791Key2267Key

1792 2268

2269`profiles.<name>.plan_mode_reasoning_effort`

2270

2271Type / Values

2272

2274

2275Details

2276

2277Profile-scoped Plan-mode reasoning override.

2278

2279Key

2280

2281`profiles.<name>.service_tier`

2282

2283Type / Values

2284

2285`flex | fast`

2286

2287Details

2288

2289Profile-scoped service tier preference for new turns.

2290

2291Key

2292

2293`profiles.<name>.tools_view_image`

2294

2295Type / Values

2296

2297`boolean`

2298

2299Details

2300

2301Enable or disable the `view_image` tool in that profile.

2302

2303Key

2304

1793`profiles.<name>.web_search`2305`profiles.<name>.web_search`

1794 2306

1795Type / Values2307Type / Values

1802 2314

1803Key2315Key

1804 2316

2317`profiles.<name>.windows.sandbox`

2318

2319Type / Values

2320

2321`unelevated | elevated`

2322

2323Details

2324

2325Profile-scoped Windows sandbox mode override.

2326

2327Key

2328

1805`project_doc_fallback_filenames`2329`project_doc_fallback_filenames`

1806 2330

1807Type / Values2331Type / Values

1922 2446

1923Key2447Key

1924 2448

2449`service_tier`

2450

2451Type / Values

2452

2453`flex | fast`

2454

2455Details

2456

2457Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled.

2458

2459Key

2460

1925`shell_environment_policy.exclude`2461`shell_environment_policy.exclude`

1926 2462

1927Type / Values2463Type / Values

2078 2614

2079Key2615Key

2080 2616

2617`tools.view_image`

2618

2619Type / Values

2620

2621`boolean`

2622

2623Details

2624

2625Enable the local-image attachment tool `view_image`.

2626

2627Key

2628

2081`tools.web_search`2629`tools.web_search`

2082 2630

2083Type / Values2631Type / Values

2126 2674

2127Key2675Key

2128 2676

2677`tui.model_availability_nux.<model>`

2678

2679Type / Values

2680

2681`integer`

2682

2683Details

2684

2685Internal startup-tooltip state keyed by model slug.

2686

2687Key

2688

2129`tui.notification_method`2689`tui.notification_method`

2130 2690

2131Type / Values2691Type / Values

2174 2734

2175Key2735Key

2176 2736

2737`tui.theme`

2738

2739Type / Values

2740

2741`string`

2742

2743Details

2744

2745Syntax-highlighting theme override (kebab-case theme name).

2746

2747Key

2748

2177`web_search`2749`web_search`

2178 2750

2179Type / Values2751Type / Values

config-sample.md +131 −113

Details

15```toml15```toml

16# Codex example configuration (config.toml)16# Codex example configuration (config.toml)

17#17#

~~18# This file lists all keys Codex reads from config.toml, along with default~~18# This file lists the main keys Codex reads from config.toml, along with default

19# behaviors, recommended examples, and concise explanations. Adjust as needed.19# behaviors, recommended examples, and concise explanations. Adjust as needed.

20#20#

21# Notes21# Notes

30# Primary model used by Codex. Recommended example for most users: "gpt-5.4".30# Primary model used by Codex. Recommended example for most users: "gpt-5.4".

31model = "gpt-5.4"31model = "gpt-5.4"

32 32

~~33# Default communication style for supported models. Default: "friendly".~~33# Communication style for supported models. Allowed values: none | friendly | pragmatic

~~34# Allowed values: none | friendly | pragmatic~~34# personality = "pragmatic"

~~35# personality = "friendly"~~

36 35

37# Optional model override for /review. Default: unset (uses current session model).36# Optional model override for /review. Default: unset (uses current session model).

38# review_model = "gpt-5.4"37# review_model = "gpt-5.4"

43# Default OSS provider for --oss sessions. When unset, Codex prompts. Default: unset.42# Default OSS provider for --oss sessions. When unset, Codex prompts. Default: unset.

44# oss_provider = "ollama"43# oss_provider = "ollama"

45 44

~~46# Optional manual model metadata. When unset, Codex auto-detects from model.~~45# Preferred service tier. `fast` is honored only when enabled in [features].

~~47# Uncomment to force values.~~46# service_tier = "flex" # fast | flex

48# Optional manual model metadata. When unset, Codex uses model or preset defaults.

48# model_context_window = 128000 # tokens; default: auto for model49# model_context_window = 128000 # tokens; default: auto for model

~~49# model_auto_compact_token_limit = 0 # tokens; unset uses model defaults~~50# model_auto_compact_token_limit = 64000 # tokens; unset uses model defaults

~~50# tool_output_token_limit = 10000 # tokens stored per tool output~~51# tool_output_token_limit = 12000 # tokens stored per tool output

51# model_catalog_json = "/absolute/path/to/models.json" # optional startup-only model catalog override52# model_catalog_json = "/absolute/path/to/models.json" # optional startup-only model catalog override

52# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)53# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)

53# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"54# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"

57# Reasoning & Verbosity (Responses API capable models)58# Reasoning & Verbosity (Responses API capable models)

58################################################################################59################################################################################

59 60

~~61model_reasoning_effort = "medium"~~62# model_reasoning_effort = "medium"

65# plan_mode_reasoning_effort = "high"

62 66

64# model_reasoning_summary = "auto"68# model_reasoning_summary = "auto"

65 69

~~66# Text verbosity for GPT-5 family (Responses API): low | medium | high (default: medium)~~70# Text verbosity for GPT-5 family (Responses API): low | medium | high

67# model_verbosity = "medium"71# model_verbosity = "medium"

68 72

~~69# Force enable or disable reasoning summaries for current model~~73# Force enable or disable reasoning summaries for current model.

70# model_supports_reasoning_summaries = true74# model_supports_reasoning_summaries = true

71 75

72################################################################################76################################################################################

76# Additional user instructions are injected before AGENTS.md. Default: unset.80# Additional user instructions are injected before AGENTS.md. Default: unset.

77# developer_instructions = ""81# developer_instructions = ""

78 82

~~79# (Ignored) Optional legacy base instructions override (prefer AGENTS.md). Default: unset.~~

~~80# instructions = ""~~

82# Inline override for the history compaction prompt. Default: unset.83# Inline override for the history compaction prompt. Default: unset.

83# compact_prompt = ""84# compact_prompt = ""

84 85

86# Override the default commit co-author trailer. Set to "" to disable it.

87# commit_attribution = "Jane Doe <jane@example.com>"

85# Override built-in base instructions with a file path. Default: unset.89# Override built-in base instructions with a file path. Default: unset.

86# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"90# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"

87 91

~~88# Migration note: experimental_instructions_file was renamed to model_instructions_file (deprecated).~~

90# Load the compact prompt override from a file. Default: unset.92# Load the compact prompt override from a file. Default: unset.

91# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"93# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"

92 94

~~93# Legacy name for apply_patch_freeform. Default: false~~

~~94include_apply_patch_tool = false~~

96################################################################################95################################################################################

97# Notifications96# Notifications

98################################################################################97################################################################################

99 98

100# External notifier program (argv array). When unset: disabled.99# External notifier program (argv array). When unset: disabled.

101# Example: notify = ["notify-send", "Codex"]100# notify = ["notify-send", "Codex"]

102notify = [ ]

103 101

104################################################################################102################################################################################

105# Approval & Sandbox103# Approval & Sandbox

124# - danger-full-access (no sandbox; extremely risky)122# - danger-full-access (no sandbox; extremely risky)

125sandbox_mode = "read-only"123sandbox_mode = "read-only"

126 124

127[windows]

128# Native Windows sandbox mode (Windows only): unelevated | elevated

129sandbox = "unelevated"

~~130~~

131################################################################################125################################################################################

132# Authentication & Login126# Authentication & Login

133################################################################################127################################################################################

135# Where to persist CLI login credentials: file (default) | keyring | auto129# Where to persist CLI login credentials: file (default) | keyring | auto

136cli_auth_credentials_store = "file"130cli_auth_credentials_store = "file"

137 131

138# Base URL for ChatGPT auth flow (not OpenAI API). Default:132# Base URL for ChatGPT auth flow (not OpenAI API).

139chatgpt_base_url = "https://chatgpt.com/backend-api/"133chatgpt_base_url = "https://chatgpt.com/backend-api/"

140 134

141# Restrict ChatGPT login to a specific workspace id. Default: unset.135# Restrict ChatGPT login to a specific workspace id. Default: unset.

142# forced_chatgpt_workspace_id = ""136# forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

143 137

144# Force login mechanism when Codex would normally auto-select. Default: unset.138# Force login mechanism when Codex would normally auto-select. Default: unset.

145# Allowed values: chatgpt | api139# Allowed values: chatgpt | api

204# If you use --yolo or another full access sandbox setting, web search defaults to live.196# If you use --yolo or another full access sandbox setting, web search defaults to live.

205web_search = "cached"197web_search = "cached"

206 198

207################################################################################

208# Profiles (named presets)

209################################################################################

~~210~~

211# Active profile name. When unset, no profile is applied.199# Active profile name. When unset, no profile is applied.

212# profile = "default"200# profile = "default"

213 201

202# Suppress the warning shown when under-development feature flags are enabled.

203# suppress_unstable_features_warning = true

204

214################################################################################205################################################################################

215# Agents (multi-agent roles and limits)206# Agents (multi-agent roles and limits)

216################################################################################207################################################################################

217 208

218# [agents]209[agents]

219# Maximum concurrently open agent threads. Default: 6210# Maximum concurrently open agent threads. Default: 6

220# max_threads = 6211# max_threads = 6

221# Maximum nested spawn depth. Root session starts at depth 0. Default: 1212# Maximum nested spawn depth. Root session starts at depth 0. Default: 1

224# job_max_runtime_seconds = 1800215# job_max_runtime_seconds = 1800

225 216

226# [agents.reviewer]217# [agents.reviewer]

227# description = "Find security, correctness, and test risks in code."218# description = "Find correctness, security, and test risks in code."

228# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it219# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it

220# nickname_candidates = ["Athena", "Ada"]

229 221

230################################################################################222################################################################################

231# Skills (per-skill overrides)223# Skills (per-skill overrides)

236# path = "/path/to/skill/SKILL.md"228# path = "/path/to/skill/SKILL.md"

237# enabled = false229# enabled = false

238 230

239################################################################################

240# Experimental toggles (legacy; prefer [features])

241################################################################################

~~242~~

243experimental_use_unified_exec_tool = false

~~244~~

245# Include apply_patch via freeform editing path (affects default tool set). Default: false

246experimental_use_freeform_apply_patch = false

~~247~~

248################################################################################231################################################################################

249# Sandbox settings (tables)232# Sandbox settings (tables)

250################################################################################233################################################################################

267[shell_environment_policy]250[shell_environment_policy]

268# inherit: all (default) | core | none251# inherit: all (default) | core | none

269inherit = "all"252inherit = "all"

270# Skip default excludes for names containing KEY/SECRET/TOKEN (case-insensitive). Default: true253# Skip default excludes for names containing KEY/SECRET/TOKEN (case-insensitive). Default: false

271ignore_default_excludes = true254ignore_default_excludes = false

272# Case-insensitive glob patterns to remove (e.g., "AWS_*", "AZURE_*"). Default: []255# Case-insensitive glob patterns to remove (e.g., "AWS_*", "AZURE_*"). Default: []

273exclude = []256exclude = []

274# Explicit key/value overrides (always win). Default: {}257# Explicit key/value overrides (always win). Default: {}

278# Experimental: run via user shell profile. Default: false261# Experimental: run via user shell profile. Default: false

279experimental_use_profile = false262experimental_use_profile = false

280 263

264################################################################################

265# Managed network proxy settings

266################################################################################

267

268[permissions.network]

269# enabled = true

270# proxy_url = "http://127.0.0.1:43128"

271# admin_url = "http://127.0.0.1:43129"

272# enable_socks5 = false

273# socks_url = "http://127.0.0.1:43130"

274# enable_socks5_udp = false

275# allow_upstream_proxy = false

276# dangerously_allow_non_loopback_proxy = false

277# dangerously_allow_non_loopback_admin = false

278# dangerously_allow_all_unix_sockets = false

279# mode = "limited" # limited | full

280# allowed_domains = ["api.openai.com"]

281# denied_domains = ["example.com"]

282# allow_unix_sockets = ["/var/run/docker.sock"]

283# allow_local_binding = false

284

281################################################################################285################################################################################

282# History (table)286# History (table)

283################################################################################287################################################################################

286# save-all (default) | none290# save-all (default) | none

287persistence = "save-all"291persistence = "save-all"

288# Maximum bytes for history file; oldest entries are trimmed when exceeded. Example: 5242880292# Maximum bytes for history file; oldest entries are trimmed when exceeded. Example: 5242880

289# max_bytes = 0293# max_bytes = 5242880

290 294

291################################################################################295################################################################################

292# UI, Notifications, and Misc (tables)296# UI, Notifications, and Misc (tables)

318# You can also add custom .tmTheme files under $CODEX_HOME/themes.322# You can also add custom .tmTheme files under $CODEX_HOME/themes.

319# theme = "catppuccin-mocha"323# theme = "catppuccin-mocha"

320 324

325# Internal tooltip state keyed by model slug. Usually managed by Codex.

326# [tui.model_availability_nux]

327# "gpt-5.4" = 1

328

329# Enable or disable analytics for this machine. When unset, Codex uses its default behavior.

330[analytics]

331enabled = true

332

321# Control whether users can submit feedback from `/feedback`. Default: true333# Control whether users can submit feedback from `/feedback`. Default: true

322[feedback]334[feedback]

323enabled = true335enabled = true

331# "hide_gpt-5.1-codex-max_migration_prompt" = true343# "hide_gpt-5.1-codex-max_migration_prompt" = true

332# model_migrations = { "gpt-4.1" = "gpt-5.1" }344# model_migrations = { "gpt-4.1" = "gpt-5.1" }

333 345

334# Suppress the warning shown when under-development feature flags are enabled.

335# suppress_unstable_features_warning = true

~~336~~

337################################################################################346################################################################################

338# Centralized Feature Flags (preferred)347# Centralized Feature Flags (preferred)

339################################################################################348################################################################################

343# shell_tool = true352# shell_tool = true

344# apps = false353# apps = false

345# apps_mcp_gateway = false354# apps_mcp_gateway = false

346# web_search_cached = false

347# web_search_request = false

348# unified_exec = false355# unified_exec = false

349# shell_snapshot = false356# shell_snapshot = false

350# apply_patch_freeform = false

351# multi_agent = false357# multi_agent = false

352# search_tool = false

353# personality = true358# personality = true

354# request_rule = true

355# collaboration_modes = true

356# use_linux_sandbox_bwrap = false359# use_linux_sandbox_bwrap = false

357# remote_models = false360# runtime_metrics = true

358# runtime_metrics = false

359# powershell_utf8 = true361# powershell_utf8 = true

360# child_agents_md = false362# child_agents_md = false

363# sqlite = true

364# fast_mode = true

365# enable_request_compression = true

366# image_generation = false

367# skill_mcp_dependency_install = true

368# skill_env_var_dependency_prompt = false

369# default_mode_request_user_input = false

370# artifact = false

371# prevent_idle_sleep = false

372# responses_websockets = false

373# responses_websockets_v2 = false

374# image_detail_original = false

361 375

362################################################################################376################################################################################

363# Define MCP servers under this table. Leave empty to disable.377# Define MCP servers under this table. Leave empty to disable.

379# tool_timeout_sec = 60.0 # optional; default 60.0 seconds393# tool_timeout_sec = 60.0 # optional; default 60.0 seconds

380# enabled_tools = ["search", "summarize"] # optional allow-list394# enabled_tools = ["search", "summarize"] # optional allow-list

381# disabled_tools = ["slow-tool"] # optional deny-list (applied after allow-list)395# disabled_tools = ["slow-tool"] # optional deny-list (applied after allow-list)

396# scopes = ["read:docs"] # optional OAuth scopes

397# oauth_resource = "https://docs.example.com/" # optional OAuth resource

382 398

383# --- Example: Streamable HTTP transport ---399# --- Example: Streamable HTTP transport ---

384# [mcp_servers.github]400# [mcp_servers.github]

391# startup_timeout_sec = 10.0 # optional407# startup_timeout_sec = 10.0 # optional

392# tool_timeout_sec = 60.0 # optional408# tool_timeout_sec = 60.0 # optional

393# enabled_tools = ["list_issues"] # optional allow-list409# enabled_tools = ["list_issues"] # optional allow-list

410# disabled_tools = ["delete_issue"] # optional deny-list

411# scopes = ["repo"] # optional OAuth scopes

394 412

395################################################################################413################################################################################

396# Model Providers414# Model Providers

397################################################################################415################################################################################

398 416

399# Built-ins include:417# Built-ins include:

400# - openai (Responses API; requires login or OPENAI_API_KEY via auth flow)418# - openai

401# - oss (Chat Completions API; defaults to http://localhost:11434/v1)419# - ollama

420# - lmstudio

402 421

403[model_providers]422[model_providers]

404 423

406# [model_providers.openaidr]425# [model_providers.openaidr]

407# name = "OpenAI Data Residency"426# name = "OpenAI Data Residency"

408# base_url = "https://us.api.openai.com/v1" # example with 'us' domain prefix427# base_url = "https://us.api.openai.com/v1" # example with 'us' domain prefix

409# wire_api = "responses" # "responses" | "chat" (default varies)428# wire_api = "responses" # only supported value

410# # requires_openai_auth = true # built-in OpenAI defaults to true429# # requires_openai_auth = true # built-in OpenAI defaults to true

411# # request_max_retries = 4 # default 4; max 100430# # request_max_retries = 4 # default 4; max 100

412# # stream_max_retries = 5 # default 5; max 100431# # stream_max_retries = 5 # default 5; max 100

413# # stream_idle_timeout_ms = 300000 # default 300_000 (5m)432# # stream_idle_timeout_ms = 300000 # default 300_000 (5m)

433# # supports_websockets = true # optional

414# # experimental_bearer_token = "sk-example" # optional dev-only direct bearer token434# # experimental_bearer_token = "sk-example" # optional dev-only direct bearer token

415# # http_headers = { "X-Example" = "value" }435# # http_headers = { "X-Example" = "value" }

416# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }436# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }

417 437

418# --- Example: Azure (Chat/Responses depending on endpoint) ---438# --- Example: Azure/OpenAI-compatible provider ---

419# [model_providers.azure]439# [model_providers.azure]

420# name = "Azure"440# name = "Azure"

421# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"441# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"

422# wire_api = "responses" # or "chat" per endpoint442# wire_api = "responses"

423# query_params = { api-version = "2025-04-01-preview" }443# query_params = { api-version = "2025-04-01-preview" }

424# env_key = "AZURE_OPENAI_API_KEY"444# env_key = "AZURE_OPENAI_API_KEY"

425# # env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"445# env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"

446# # supports_websockets = false

426 447

427# --- Example: Local OSS (e.g., Ollama-compatible) ---448# --- Example: Local OSS (e.g., Ollama-compatible) ---

428# [model_providers.ollama]449# [model_providers.ollama]

429# name = "Ollama"450# name = "Ollama"

430# base_url = "http://localhost:11434/v1"451# base_url = "http://localhost:11434/v1"

431# wire_api = "chat"452# wire_api = "responses"

~~432~~

433################################################################################

434# Profiles (named presets)

435################################################################################

~~436~~

437[profiles]

~~438~~

439# [profiles.default]

440# model = "gpt-5.4"

441# model_provider = "openai"

442# approval_policy = "on-request"

443# sandbox_mode = "read-only"

444# oss_provider = "ollama"

445# model_reasoning_effort = "medium"

446# model_reasoning_summary = "auto"

447# model_verbosity = "medium"

448# personality = "friendly" # or "pragmatic" or "none"

449# chatgpt_base_url = "https://chatgpt.com/backend-api/"

450# model_catalog_json = "./models.json"

451# experimental_compact_prompt_file = "./compact_prompt.txt"

452# include_apply_patch_tool = false

453# experimental_use_unified_exec_tool = false

454# experimental_use_freeform_apply_patch = false

455# tools.web_search = false # deprecated legacy alias; prefer top-level `web_search`

456# features = { unified_exec = false }

457 453

458################################################################################454################################################################################

459# Apps / Connectors455# Apps / Connectors

477# enabled = false473# enabled = false

478# approval_mode = "approve"474# approval_mode = "approve"

479 475

476################################################################################

477# Profiles (named presets)

478################################################################################

479

480[profiles]

481

482# [profiles.default]

483# model = "gpt-5.4"

484# model_provider = "openai"

485# approval_policy = "on-request"

486# sandbox_mode = "read-only"

487# service_tier = "flex"

488# oss_provider = "ollama"

489# model_reasoning_effort = "medium"

490# plan_mode_reasoning_effort = "high"

491# model_reasoning_summary = "auto"

492# model_verbosity = "medium"

493# personality = "pragmatic" # or "friendly" or "none"

494# chatgpt_base_url = "https://chatgpt.com/backend-api/"

495# model_catalog_json = "./models.json"

496# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"

497# experimental_compact_prompt_file = "./compact_prompt.txt"

498# tools_view_image = true

499# features = { unified_exec = false }

500

480################################################################################501################################################################################

481# Projects (trust levels)502# Projects (trust levels)

482################################################################################503################################################################################

483 504

484# Mark specific worktrees as trusted or untrusted.

485[projects]505[projects]

506# Mark specific worktrees as trusted or untrusted.

486# [projects."/absolute/path/to/project"]507# [projects."/absolute/path/to/project"]

487# trust_level = "trusted" # or "untrusted"508# trust_level = "trusted" # or "untrusted"

488 509

510################################################################################

511# Tools

512################################################################################

513

514[tools]

515# view_image = true

516

489################################################################################517################################################################################

490# OpenTelemetry (OTEL) - disabled by default518# OpenTelemetry (OTEL) - disabled by default

491################################################################################519################################################################################

499exporter = "none"527exporter = "none"

500# Trace exporter: none (default) | otlp-http | otlp-grpc528# Trace exporter: none (default) | otlp-http | otlp-grpc

501trace_exporter = "none"529trace_exporter = "none"

530# Metrics exporter: none | statsig | otlp-http | otlp-grpc

531metrics_exporter = "statsig"

502 532

503# Example OTLP/HTTP exporter configuration533# Example OTLP/HTTP exporter configuration

504# [otel.exporter."otlp-http"]534# [otel.exporter."otlp-http"]

508# [otel.exporter."otlp-http".headers]538# [otel.exporter."otlp-http".headers]

509# "x-otlp-api-key" = "${OTLP_TOKEN}"539# "x-otlp-api-key" = "${OTLP_TOKEN}"

510 540

511# Example OTLP/gRPC exporter configuration

512# [otel.exporter."otlp-grpc"]

513# endpoint = "https://otel.example.com:4317",

514# headers = { "x-otlp-meta" = "abc123" }

~~515~~

516# Example OTLP exporter with mutual TLS

517# [otel.exporter."otlp-http"]

518# endpoint = "https://otel.example.com/v1/logs"

519# protocol = "binary"

~~520~~

521# [otel.exporter."otlp-http".headers]

522# "x-otlp-api-key" = "${OTLP_TOKEN}"

~~523~~

524# [otel.exporter."otlp-http".tls]541# [otel.exporter."otlp-http".tls]

525# ca-certificate = "certs/otel-ca.pem"542# ca-certificate = "certs/otel-ca.pem"

526# client-certificate = "/etc/codex/certs/client.pem"543# client-certificate = "/etc/codex/certs/client.pem"

527# client-private-key = "/etc/codex/certs/client-key.pem"544# client-private-key = "/etc/codex/certs/client-key.pem"

528```

529 545

530################################################################################546# Example OTLP/gRPC trace exporter configuration

547# [otel.trace_exporter."otlp-grpc"]

548# endpoint = "https://otel.example.com:4317"

549# headers = { "x-otlp-meta" = "abc123" }

531 550

551################################################################################

532# Windows552# Windows

~~533~~

534################################################################################553################################################################################

535 554

536[windows]555[windows]

~~537~~ 556# Native Windows sandbox mode (Windows only): unelevated | elevated

538# Native Windows sandbox mode (Windows only). The example below uses the557sandbox = "unelevated"

~~539~~ 558```

540# recommended elevated mode.

~~541~~

542sandbox = “elevated”

enterprise/admin-setup.md +229 −77

Details

1# Admin Setup1# Admin Setup

2 2

3![Codex enterprise admin toggle](/images/codex/codex_enterprise_admin.png)

3This guide is for ChatGPT Enterprise admins who want to set up Codex for their workspace.5This guide is for ChatGPT Enterprise admins who want to set up Codex for their workspace.

4 6

5Use this page as the step-by-step rollout guide. It focuses on setup order and decision points. For detailed policy, configuration, and monitoring details, use the linked pages: [Authentication](https://developers.openai.com/codex/auth), [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security), [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), and [Governance](https://developers.openai.com/codex/enterprise/governance).7Use this page as the step-by-step rollout guide. For detailed policy, configuration, and monitoring details, use the linked pages: [Authentication](https://developers.openai.com/codex/auth), [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security), [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), and [Governance](https://developers.openai.com/codex/enterprise/governance).

6 8

7## Enterprise-grade security and privacy9## Enterprise-grade security and privacy

8 10

9Codex supports ChatGPT Enterprise security features, including:11Codex supports ChatGPT Enterprise security features, including:

10 12

11- No training on enterprise data13- No training on enterprise data

~~12- Zero data retention for the App, CLI, and IDE (code remains in developer environment)~~14- Zero data retention for the App, CLI, and IDE (code stays in the developer environment)

13- Residency and retention that follow ChatGPT Enterprise policies15- Residency and retention that follow ChatGPT Enterprise policies

14- Granular user access controls16- Granular user access controls

15- Data encryption at rest (AES-256) and in transit (TLS 1.2+)17- Data encryption at rest (AES-256) and in transit (TLS 1.2+)

18- Audit logging via the ChatGPT Compliance API

16 19

17For security controls and runtime protections, see [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security). Refer to [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) for more details.20For security controls and runtime protections, see [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security). Refer to [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) for more details.

18 21

~~19## Local vs. cloud setup~~22## Pre-requisites: Determine owners and rollout strategy

~~21Codex operates in two environments: local and cloud.~~

~~231. **Codex local** includes the Codex app, CLI, and IDE extension. The agent runs on the developer’s computer in a sandbox.~~

242. **Codex cloud** includes hosted Codex features (including Codex cloud, iOS, Code Review, and tasks created by the [Slack integration](https://developers.openai.com/codex/integrations/slack) or [Linear integration](https://developers.openai.com/codex/integrations/linear)). The agent runs remotely in a hosted container with your codebase.

~~26You can enable local, cloud, or both, and control access with workspace settings and role-based access control (RBAC).~~

~~28## Step 0: Owners and rollout decision~~

~~30Ensure you have the following owners:~~

31 23

~~32- Workspace owner with access to ChatGPT Enterprise~~24During your rollout, team members may support different aspects of integrating Codex into your organization. Ensure you have the following owners:

~~33- IT management owner for managed configuration~~

~~34- Governance owner for analytics / compliance review~~

35 25

~~36A rollout decision:~~26- **ChatGPT Enterprise workspace owner:** required to configure Codex settings in your workspace.

27- **Security owner:** determines agent permissions settings for Codex.

28- **Analytics owner:** integrates analytics and compliance APIs into your data pipelines.

37 29

~~38- Codex local only (Codex app, CLI, and IDE extension)~~30Decide which Codex surfaces you will use:

~~39- Codex cloud only (Codex web, GitHub code review)~~

~~40- Both local + cloud~~

41 31

~~42Review [authentication](https://developers.openai.com/codex/auth) before rollout:~~32- **Codex local:** includes the Codex app, CLI, and IDE extension. The agent runs on the developer's computer in a sandbox.

33- **Codex cloud:** includes hosted Codex features (including Codex cloud, iOS, Code Review, and tasks created by the [Slack integration](https://developers.openai.com/codex/integrations/slack) or [Linear integration](https://developers.openai.com/codex/integrations/linear)). The agent runs remotely in a hosted container with your codebase.

34- **Both:** use local + cloud together.

43 35

~~44- Codex local supports ChatGPT sign-in or API keys. Confirm MFA/SSO requirements and any managed login restrictions in authentication~~36You can enable local, cloud, or both, and control access with workspace settings and role-based access control (RBAC).

~~45- Codex cloud requires ChatGPT sign-in~~

46 37

~~47## Step 1: Enable workspace toggles~~38## Step 1: Enable Codex in your workspace

48 39

~~49Turn on only the Codex features you plan to roll out in this phase.~~40You configure access to Codex in ChatGPT Enterprise workspace settings.

50 41

51Go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).42Go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).

52 43

53### Codex local44### Codex local

54 45

46Codex local is enabled by default for new ChatGPT Enterprise workspaces. If

47 you are not a ChatGPT workspace owner, you can test whether you have access by

48 [installing Codex](https://developers.openai.com/codex/quickstart) and logging in with your work email.

55Turn on **Allow members to use Codex Local**.50Turn on **Allow members to use Codex Local**.

56 51

57This enables use of the Codex app, CLI, and IDE extension for allowed users.52This enables use of the Codex app, CLI, and IDE extension for allowed users.

60 55

61#### Enable device code authentication for Codex CLI56#### Enable device code authentication for Codex CLI

62 57

~~63Allow developers to sign in with device codes when using Codex CLI in a non-interactive environment. More details in [authentication](https://developers.openai.com/codex/auth/).~~58Allow developers to sign in with a device code when using Codex CLI in a non-interactive environment (for example, a remote development box). More details are in [authentication](https://developers.openai.com/codex/auth/).

64 59

65![Codex local toggle](/images/codex/enterprise/local-toggle-config.png)60![Codex local toggle](/images/codex/enterprise/local-toggle-config.png)

66 61

82 77

83Note that it may take up to 10 minutes for Codex to appear in ChatGPT.78Note that it may take up to 10 minutes for Codex to appear in ChatGPT.

84 79

~~85#### Allow members to administer Codex~~

87Allows users to view overall Codex [workspace analytics](https://chatgpt.com/codex/settings/analytics), access [cloud-managed requirements](https://chatgpt.com/codex/settings/managed-configs), and manage Cloud environments (edit and delete).

~~89Codex cloud not required.~~

91#### Enable Codex Slack app to post answers on task completion80#### Enable Codex Slack app to post answers on task completion

92 81

93Codex posts its full answer back to Slack when the task completes. Otherwise, Codex posts only a link to the task.82Codex posts its full answer back to Slack when the task completes. Otherwise, Codex posts only a link to the task.

98 87

99By default, Codex cloud agents have no internet access during runtime to help protect against security and safety risks like prompt injection.88By default, Codex cloud agents have no internet access during runtime to help protect against security and safety risks like prompt injection.

100 89

101This setting enables users to use an allowlist for common software dependency domains, add more domains and trusted sites, and specify allowed HTTP methods.90This setting lets users use an allowlist for common software dependency domains, add domains and trusted sites, and specify allowed HTTP methods.

102 91

103For security implications of internet access and runtime controls, see [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).92For security implications of internet access and runtime controls, see [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).

104 93

106 95

107## Step 2: Set up custom roles (RBAC)96## Step 2: Set up custom roles (RBAC)

108 97

109Use RBAC to control which users or groups can access Codex local and Codex cloud.98Use RBAC to control granular permissions for access Codex local and Codex cloud.

100![Codex cloud toggle](/images/codex/enterprise/rbac_custom_roles.png)

110 101

111### What RBAC lets you do102### What RBAC lets you do

112 103

113Workspace Owners can use RBAC in ChatGPT admin settings to:104Workspace Owners can use RBAC in ChatGPT admin settings to:

114 105

115- Set a default role for users who are not assigned any custom role106- Set a default role for users who aren't assigned any custom role

116- Create custom roles with granular permissions107- Create custom roles with granular permissions

117- Assign one or more custom roles to Groups (including SCIM-synced groups)108- Assign one or more custom roles to Groups

109- Automatically sync users into Groups via SCIM

118- Manage roles centrally from the Custom Roles tab110- Manage roles centrally from the Custom Roles tab

119 111

120Users can inherit multiple roles, and permissions resolve to the maximum allowed across those roles.112Users can inherit more than one role, and permissions resolve to the most permissive (least restrictive) access across those roles.

113

114### Create a Codex Admin group

115

116Set up a dedicated "Codex Admin" group rather than granting Codex administration to a broad audience.

117

118The **Allow members to administer Codex** toggle grants the Codex Admin role. Codex Admins can:

119

120- View Codex [workspace analytics](https://chatgpt.com/codex/settings/analytics)

121- Open the Codex [Policies page](https://chatgpt.com/codex/settings/policies) to manage cloud-managed `requirements.toml` policies

122- Assign those managed policies to user groups or configure a default fallback policy

123- Manage Codex cloud environments, including editing and deleting environments

124

125Use this role for the small set of admins who own Codex rollout, policy management, and governance. It's not required for general Codex users. You don't need Codex cloud to enable this toggle.

126

127Recommended rollout pattern:

128

129- Create a "Codex Users" group for people who should use Codex

130- Create a separate "Codex Admin" group for the smaller set of people who should manage Codex settings and policies

131- Assign the custom role with **Allow members to administer Codex** enabled only to the "Codex Admin" group

132- Keep membership in the "Codex Admin" group limited to workspace owners or designated platform, IT, and governance operators

133- If you use SCIM, back the "Codex Admin" group with your identity provider so membership changes are auditable and centrally managed

121 134

122### Important behavior to plan for135This separation makes it easier to roll out Codex while keeping analytics, environment management, and policy deployment limited to trusted admins. For RBAC setup details and the full permission model, see the [OpenAI RBAC Help Center article](https://help.openai.com/en/articles/11750701-rbac).

123 136

124Users in any custom role group do not use the workspace default permissions.137## Step 3: Configure Codex local requirements

125 138

126If you are gradually rolling out Codex, one suggestion is to have a “Codex Users” group and a second “Codex Admin” group that has the “Allow members to administer Codex” toggle enabled.139Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).

127 140

128For RBAC setup details and the full permission model, see the [OpenAI RBAC Help Center article](https://help.openai.com/en/articles/11750701-rbac).141Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules.

129 142

130## Step 3: Configure Codex local managed settings143![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)

131 144

132For Codex local, set an admin-approved baseline for local behavior before broader rollout.145Recommended setup:

133 146

134### Use managed configuration for two different goals1471. Create a baseline policy for most users, then create stricter or more permissive variants only where needed.

1482. Assign each managed policy to a specific user group, and configure a default fallback policy for everyone else.

1493. Order group rules with care. If a user matches more than one group-specific rule, the first matching rule applies.

1504. Treat each policy as a complete profile for that group. Codex doesn't fill missing fields from later matching group rules.

135 151

136- **Requirements** (`requirements.toml`): Admin-enforced constraints users cannot override152These cloud-managed policies apply across Codex local surfaces when users sign in with ChatGPT, including the Codex app, CLI, and IDE extension.

137- **Managed defaults** (`managed_config.toml`): Starting values applied when Codex launches

138 153

139### Team Config154### Example requirements.toml policies

155

156Use cloud-managed `requirements.toml` policies to enforce the guardrails you want for each group. The snippets below are examples you can adapt, not required settings.

157

158![Example managed requirements policy](/images/codex/enterprise/example_policy.png)

159

160Example: limit web search, sandbox mode, and approvals for a standard local rollout:

161

162```toml

163allowed_web_search_modes = ["disabled", "cached"]

164allowed_sandbox_modes = ["workspace-write"]

165allowed_approval_policies = ["on-request"]

166```

167

168Example: add a restrictive command rule when you want admins to block or gate specific commands:

169

170```toml

171[rules]

172prefix_rules = [

173 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating remote history." },

174]

175```

176

177You can use either example on its own or combine them in a single managed policy for a group. For exact keys, precedence, and more examples, see [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) and [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).

178

179### Checking user policies

180

181Use the policy lookup tools at the end of the workflow to confirm which managed policy applies to a user. You can check policy assignment by group or by entering a user email.

182

183![Policy lookup by group or user email](/images/codex/enterprise/policy_lookup.png)

184

185If you plan to restrict login method or workspace for local clients, see the admin-managed authentication restrictions in [Authentication](https://developers.openai.com/codex/auth).

186

187## Step 4: Standardize local configuration with Team Config

140 188

141Teams who want to standardize Codex across an organization can use Team Config to share defaults, rules, and skills without duplicating setup on every local configuration.189Teams who want to standardize Codex across an organization can use Team Config to share defaults, rules, and skills without duplicating setup on every local configuration.

142 190

191You can check Team Config settings into the repository under the `.codex` directory. Codex automatically picks up Team Config settings when a user opens that repository.

192

193Start with Team Config for your highest-traffic repositories so teams get consistent behavior in the places they use Codex most.

194

144| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |196| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |

148 200

149For locations and precedence, see [Config basics](https://developers.openai.com/codex/config-basic#configuration-precedence).201For locations and precedence, see [Config basics](https://developers.openai.com/codex/config-basic#configuration-precedence).

150 202

151### Recommended first decisions for local rollout203## Step 5: Configure Codex cloud usage (if enabled)

152 204

153Define a baseline for your pilot:205This step covers repository and environment setup after you enable the Codex cloud workspace toggle.

~~154~~

155- Approval policy posture

156- Sandbox mode posture

157- Web search posture

158- MCP / connectors policy

159- Local logging and telemetry posture

~~160~~

161For exact keys, precedence, MDM deployment, and examples, see [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) and [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).

~~162~~

163If you plan to restrict login method or workspace for local clients, see the admin-managed authentication restrictions in [Authentication](https://developers.openai.com/codex/auth).

~~164~~

165## Step 4: Configure Codex cloud usage (if enabled)

~~166~~

167This step covers repository and environment setup after the Codex cloud workspace toggle is enabled.

168 206

169### Connect Codex cloud to repositories207### Connect Codex cloud to repositories

170 208

1711. Navigate to [Codex](https://chatgpt.com/codex) and select **Get started**2091. Navigate to [Codex](https://chatgpt.com/codex) and select **Get started**

1722. Select **Connect to GitHub** to install the ChatGPT GitHub Connector if you haven't already connected GitHub to ChatGPT2102. Select **Connect to GitHub** to install the ChatGPT GitHub Connector if you haven't already connected GitHub to ChatGPT

1733. Install or authorize the ChatGPT GitHub Connector2113. Install or connect the ChatGPT GitHub Connector

1744. Choose an installation target for the ChatGPT Connector (typically your main organization)2124. Choose an installation target for the ChatGPT Connector (typically your main organization)

1755. Allow the repositories you want to connect to Codex2135. Allow the repositories you want to connect to Codex

176 214

215For GitHub Enterprise Managed Users (EMU), an organization owner must install

216 the Codex GitHub App for the organization before users can connect

217 repositories in Codex cloud.

218

177For more, see [Cloud environments](https://developers.openai.com/codex/cloud/environments).219For more, see [Cloud environments](https://developers.openai.com/codex/cloud/environments).

178 220

179Codex uses short-lived, least-privilege GitHub App installation tokens for each operation and respects the user's existing GitHub repository permissions and branch protection rules.221Codex uses short-lived, least-privilege GitHub App installation tokens for each operation and respects the user's existing GitHub repository permissions and branch protection rules.

180 222

181### Configure IP addresses (as needed)223### Configure IP addresses

182 224

183Configure connector / IP allow lists if required by your network policy with these [egress IP ranges](https://openai.com/chatgpt-agents.json).225If your GitHub organization controls the IP addresses that apps use to connect, make sure to include these [egress IP ranges](https://openai.com/chatgpt-agents.json).

184 226

185These IP ranges can change. Consider checking them automatically and updating your allow list based on the latest values.227These IP ranges can change. Consider checking them automatically and updating your allow list based on the latest values.

186 228

188 230

189To allow Codex to perform code reviews on GitHub, go to [Settings → Code review](https://chatgpt.com/codex/settings/code-review).231To allow Codex to perform code reviews on GitHub, go to [Settings → Code review](https://chatgpt.com/codex/settings/code-review).

190 232

191Code review can be configured at the repository level. Users can also enable auto review for their PRs and choose when Codex automatically triggers a review. More details on [GitHub](https://developers.openai.com/codex/integrations/github) integration page.233You can configure code review at the repository level. Users can also enable auto review for their PRs and choose when Codex automatically triggers a review. More details are on the [GitHub integration page](https://developers.openai.com/codex/integrations/github).

234

235Use the overview page to confirm your workspace has code review turned on and to see the available review controls.

236

237![Code review settings overview](/images/codex/enterprise/code_review_settings_overview.png)

238

239 Use the auto review settings to decide whether Codex should review pull

240 requests automatically for connected repositories.

241

242![Automatic code review settings](/images/codex/enterprise/auto_code_review_settings.png)

243

244 Use review triggers to control which pull request events should start a

245 Codex review.

246

247![Code review trigger settings](/images/codex/enterprise/review_triggers.png)

248

249### Configure Codex security

192 250

193Additional integration docs for [Slack](https://developers.openai.com/codex/integrations/slack), [GitHub](https://developers.openai.com/codex/integrations/github), and [Linear](https://developers.openai.com/codex/integrations/linear).251Codex Security helps engineering and security teams find, confirm, and remediate likely vulnerabilities in connected GitHub repositories.

194 252

195## Step 5: Set up governance and observability253At a high level, Codex Security:

196 254

197Codex gives enterprise teams several options for visibility into adoption and impact. Set up governance early so your team can monitor adoption, investigate issues, and support compliance workflows.255- scans connected repositories commit by commit

256- ranks likely findings and confirms them when possible

257- shows structured findings with evidence, criticality, and suggested remediation

258- lets teams refine a repository threat model to improve prioritization and review quality

259

260For setup, scan creation, findings review, and threat model guidance, see [Codex Security setup](https://developers.openai.com/codex/security/setup). For a product overview, see [Codex Security](https://developers.openai.com/codex/security).

261

262Integration docs are also available for [Slack](https://developers.openai.com/codex/integrations/slack), [GitHub](https://developers.openai.com/codex/integrations/github), and [Linear](https://developers.openai.com/codex/integrations/linear).

263

264## Step 6: Set up governance and observability

265

266Codex gives enterprise teams options for visibility into adoption and impact. Set up governance early so your team can track adoption, investigate issues, and support compliance workflows.

198 267

199### Codex governance typically uses268### Codex governance typically uses

200 269

201- Analytics Dashboard for quick, self-serve visibility270- Analytics Dashboard for quick, self-serve visibility

202- Analytics API for programmatic reporting and BI integration271- Analytics API for programmatic reporting and business intelligence integration

203- Compliance API for audit and investigation workflows272- Compliance API for audit and investigation workflows

204 273

205### Recommended minimum setup274### Recommended baseline setup

206 275

207- Assign an owner for adoption reporting276- Assign an owner for adoption reporting

208- Assign an owner for audit and compliance review277- Assign an owner for audit and compliance review

209- Define a review cadence278- Define a review cadence

210- Decide what success looks like279- Decide what success looks like

211 280

212For details and examples, see [Governance](https://developers.openai.com/codex/enterprise/governance).281### Analytics API setup steps

282

283To set up the Analytics API key:

284

2851. Sign in to the [OpenAI API Platform Portal](https://platform.openai.com) as an owner or admin, and select the correct organization.

2862. Go to the [API keys page](https://platform.openai.com/settings/organization/api-keys).

2873. Create a new secret key dedicated to Codex Analytics, and give it a descriptive name such as Codex Analytics API.

2884. Select the appropriate project for your organization. If you only have one project, the default project is fine.

2895. Set the key permissions to Read only, since this API only retrieves analytics data.

2906. Copy the key value and store it securely, because you can only view it once.

2917. Email [support@openai.com](mailto:support@openai.com) to have that key scoped to `codex.enterprise.analytics.read` only. Wait for OpenAI to confirm your API key has Codex Analytics API access.

292

293![Codex analytics key creation](/images/codex/codex_analytics_key.png)

294

295To use the Analytics API key:

296

2971. Find your `workspace_id` in the [ChatGPT Admin console](https://chatgpt.com/admin) under Workspace details.

2982. Call the Analytics API at `https://api.chatgpt.com/v1/analytics/codex` using your Platform API key, and include your `workspace_id` in the path.

2993. Choose the endpoint you want to query:

300

301- /workspaces/`{workspace_id}`/usage

302- /workspaces/`{workspace_id}`/code_reviews

303- /workspaces/`{workspace_id}`/code_review_responses

304

3054. Set a reporting date range with `start_time` and `end_time` if needed.

3065. Retrieve the next page of results with `next_page` if the response spans more than one page.

307

308Example curl command to retrieve workspace usage:

309

310```bash

311curl -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \

312 "https://api.chatgpt.com/v1/analytics/codex/workspaces/WORKSPACE_ID/usage"

313```

314

315For more details on the Analytics API, see [Analytics API](https://developers.openai.com/codex/enterprise/governance#analytics-api).

316

317### Compliance API setup steps

318

319To set up the Compliance API key:

320

3211. Sign in to the [OpenAI API Platform Portal](https://platform.openai.com) as an owner or admin, and select the correct organization.

3222. Go to the [API keys page](https://platform.openai.com/settings/organization/api-keys).

3233. Create a new secret key dedicated to Compliance API and select the appropriate project for your organization. If you only have one project, the default project is fine.

3244. Choose All permissions.

3255. Copy the key value and store it securely, because you can only view it once.

3266. Send an email to [support@openai.com](mailto:support@openai.com) with:

327

328- the last 4 digits of the API key

329- the key name

330- the created-by name

331- the scope needed: `read`, `delete`, or both

332

3337. Wait for OpenAI to confirm your API key has Compliance API access.

334

335To use the Compliance API key:

336

3371. Find your `workspace_id` in the [ChatGPT Admin console](https://chatgpt.com/admin) under Workspace details.

3382. Use the Compliance API at `https://api.chatgpt.com/v1/`

3393. Pass your Compliance API key in the Authorization header as a Bearer token.

3404. For Codex-related compliance data, use these endpoints:

341

342- /compliance/workspaces/`{workspace_id}`/logs

343- /compliance/workspaces/`{workspace_id}`/logs/`{log_file_id}`

344- /compliance/workspaces/`{workspace_id}`/codex_tasks

345- /compliance/workspaces/`{workspace_id}`/codex_environments

346

3475. For most Codex compliance integrations, start with the logs endpoint and request Codex event types such as CODEX_LOG or CODEX_SECURITY_LOG.

3486. Use /logs to list available Codex compliance log files, then /logs/`{log_file_id}` to download a specific file.

349

350Example curl command to list compliance log files:

351

352```bash

353curl -L -H "Authorization: Bearer YOUR_COMPLIANCE_API_KEY" \

354 "https://api.chatgpt.com/v1/compliance/workspaces/WORKSPACE_ID/logs?event_type=CODEX_LOG&after=2026-03-01T00:00:00Z"

355```

356

357Example curl command to list Codex tasks:

358

359```bash

360curl -H "Authorization: Bearer YOUR_COMPLIANCE_API_KEY" \

361 "https://api.chatgpt.com/v1/compliance/workspaces/WORKSPACE_ID/codex_tasks"

362```

363

364For more details on the Compliance API, see [Compliance API](https://developers.openai.com/codex/enterprise/governance#compliance-api).

213 365

214## Step 6: Confirm and validate setup366## Step 7: Confirm and verify setup

215 367

216### What to verify368### What to verify

217 369

219- (If enabled) Users can sign in to Codex cloud (ChatGPT sign-in required)371- (If enabled) Users can sign in to Codex cloud (ChatGPT sign-in required)

220- MFA and SSO requirements match your enterprise security policy372- MFA and SSO requirements match your enterprise security policy

221- RBAC and workspace toggles produce the expected access behavior373- RBAC and workspace toggles produce the expected access behavior

222- Managed configuration is applied for users374- Managed configuration applies for users

223- Governance data is visible for admins375- Governance data is visible for admins

224 376

225For authentication options and enterprise login restrictions, see [Authentication](https://developers.openai.com/codex/auth).377For authentication options and enterprise login restrictions, see [Authentication](https://developers.openai.com/codex/auth).

226 378

227Once your team is confident with setup, you can confidently roll Codex out to additional teams and organizations.379Once your team is confident with setup, you can roll Codex out to more teams and organizations.

enterprise/managed-configuration.md +10 −10

Details

7 7

8## Admin-enforced requirements (requirements.toml)8## Admin-enforced requirements (requirements.toml)

9 9

10Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers can be enabled). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced requirement, Codex falls back to a requirements-compatible value and notifies the user. If an `mcp_servers` allowlist is configured, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.10Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.

11 11

12Requirements can also be used to constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note features are generally not security-sensitive, but enterprises have the option of pinning values, if desired. Omitted keys remain unconstrained.12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.

13 13

14For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml).14For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml).

15 15

16### Locations and precedence16### Locations and precedence

17 17

~~18Requirements layers are applied in this order (earlier wins per field):~~18Codex applies requirements layers in this order (earlier wins per field):

19 19

201. Cloud-managed requirements (ChatGPT Business or Enterprise)201. Cloud-managed requirements (ChatGPT Business or Enterprise)

212. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`212. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`

223. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS)223. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS)

23 23

24Across layers, requirements are merged per field: if an earlier layer sets a field (including an empty list), later layers do not override that field, but lower layers can still fill fields that remain unset.24Across layers, Codex merges requirements per field: if an earlier layer sets a field (including an empty list), later layers don't override that field, but lower layers can still fill fields that remain unset.

25 25

26For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).26For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).

27 27

53 53

54Admins can configure different managed requirements for different user groups, and also set a default fallback requirements policy.54Admins can configure different managed requirements for different user groups, and also set a default fallback requirements policy.

55 55

~~56If a user matches multiple group-specific rules, the first matching rule applies. Codex does not fill unset requirement fields from later matching group rules.~~56If a user matches more than one group-specific rule, the first matching rule applies. Codex doesn't fill unset fields from later matching group rules.

57 57

58For example, if the first matching group rule sets only `allowed_sandbox_modes = ["read-only"]` and a later matching group rule sets `allowed_approval_policies = ["on-request"]`, Codex applies only the first matching group rule and does not fill `allowed_approval_policies` from the later rule.58For example, if the first matching group rule sets only `allowed_sandbox_modes = ["read-only"]` and a later matching group rule sets `allowed_approval_policies = ["on-request"]`, Codex applies only the first matching group rule and doesn't fill `allowed_approval_policies` from the later rule.

59 59

60#### How Codex applies cloud-managed requirements locally60#### How Codex applies cloud-managed requirements locally

61 61

62When a user starts Codex and signs in with ChatGPT on a Business or Enterprise plan, Codex applies managed requirements on a best-effort basis. Codex first checks for a valid, unexpired local managed requirements cache entry and uses it if available. If the cache is missing, expired, invalid, or does not match the current auth identity, Codex attempts to fetch managed requirements from the service (with retries) and writes a new signed cache entry on success. If no valid cached entry is available and the fetch fails or times out, Codex continues without the managed requirements layer.62When a user starts Codex and signs in with ChatGPT on a Business or Enterprise plan, Codex applies managed requirements on a best-effort basis. Codex first checks for a valid, unexpired local managed requirements cache entry and uses it if available. If the cache is missing, expired, corrupted, or doesn't match the current auth identity, Codex attempts to fetch managed requirements from the service (with retries) and writes a new signed cache entry on success. If no valid cached entry is available and the fetch fails or times out, Codex continues without the managed requirements layer.

63 63

~~64After cache resolution, managed requirements are enforced as part of the normal requirements layering described above.~~64After cache resolution, Codex enforces managed requirements as part of the normal requirements layering described above.

65 65

66### Example requirements.toml66### Example requirements.toml

67 67

78allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed78allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

79```79```

80 80

~~81`allowed_web_search_modes = []` effectively allows only `"disabled"`.~~81`allowed_web_search_modes = []` allows only `"disabled"`.

82For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.82For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.

83 83

84You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags):84You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags):

89unified_exec = false89unified_exec = false

90```90```

91 91

92Use the canonical feature keys from `config.toml`’s `[features]` table. Codex normalizes the effective feature set to satisfy 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 command rules from requirements94### Enforce command rules from requirements

95 95

ide.md +1 −0

Details

64To see all available commands and bind them as keyboard shortcuts, select the settings icon in the Codex chat and select **Keyboard shortcuts**.64To see all available commands and bind them as keyboard shortcuts, select the settings icon in the Codex chat and select **Keyboard shortcuts**.

65You can also refer to the [Codex IDE extension commands](https://developers.openai.com/codex/ide/commands) page.65You can also refer to the [Codex IDE extension commands](https://developers.openai.com/codex/ide/commands) page.

66For a list of supported slash commands, see [Codex IDE extension slash commands](https://developers.openai.com/codex/ide/slash-commands).66For a list of supported slash commands, see [Codex IDE extension slash commands](https://developers.openai.com/codex/ide/slash-commands).

67If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

67 68

68---69---

69 70

learn/best-practices.md +223 −0 added

Details

1# Best practices

3If you’re new to Codex or coding agents in general, this guide will help you get better results faster. It covers the core habits that make Codex more effective across the [CLI](https://developers.openai.com/codex/cli), [IDE extension](https://developers.openai.com/codex/ide), and the [Codex app](https://developers.openai.com/codex/app), from prompting and planning to validation, MCP, skills, and automations.

5Codex works best when you treat it less like a one-off assistant and more like a teammate you configure and improve over time.

7A useful way to think about this: start with the right task context, use `AGENTS.md` for durable guidance, configure Codex to match your workflow, connect external systems with MCP, turn repeated work into skills, and automate stable workflows.

9## Strong first use: Context and prompts

11Codex is already strong enough to be useful even when your prompt isn't perfect. You can often hand it a hard problem with minimal setup and still get a strong result. Clear [prompting](https://developers.openai.com/codex/prompting) isn't required to get value, but it does make results more reliable, especially in larger codebases or higher-stakes tasks.

13If you work in a large or complex repository, the biggest unlock is giving Codex the right task context and a clear structure for what you want done.

15A good default is to include four things in your prompt:

17- **Goal:** What are you trying to change or build?

18- **Context:** Which files, folders, docs, examples, or errors matter for this task? You can @ mention certain files as context.

19- **Constraints:** What standards, architecture, safety requirements, or conventions should Codex follow?

20- **Done when:** What should be true before the task is complete, such as tests passing, behavior changing, or a bug no longer reproducing?

22This helps Codex stay scoped, make fewer assumptions, and produce work that's easier to review.

24Choose a reasoning level based on how hard the task is and test what works best for your workflow. Different users and tasks work best with different settings.

26- Low for faster, well-scoped tasks

27- Medium or High for more complex changes or debugging

28- Extra High for long, agentic, reasoning-heavy tasks

30To provide context faster, try using speech dictation inside the Codex app to

31 dictate what you want Codex to do rather than typing it.

33## Plan first for difficult tasks

35If the task is complex, ambiguous, or hard to describe well, ask Codex to plan before it starts coding.

37A few approaches work well:

39**Use Plan mode:** For most users, this is the easiest and most effective option. Plan mode lets Codex gather context, ask clarifying questions, and build a stronger plan before implementation. Toggle with `/plan` or <kbd>Shift</kbd>+<kbd>Tab</kbd>.

41**Ask Codex to interview you:** If you have a rough idea of what you want but aren't sure how to describe it well, ask Codex to question you first. Tell it to challenge your assumptions and turn the fuzzy idea into something concrete before writing code.

43**Use a PLANS.md template:** For more advanced workflows, you can configure Codex to follow a `PLANS.md` or execution-plan template for longer-running or multi-step work. For more detail, see the [execution plans guide](https://developers.openai.com/cookbook/articles/codex_exec_plans).

45## Make guidance reusable with `AGENTS.md`

47Once a prompting pattern works, the next step is to stop repeating it manually. That's where [AGENTS.md](https://developers.openai.com/codex/guides/agents-md) comes in.

49Think of `AGENTS.md` as an open-format README for agents. It loads into context automatically and is the best place to encode how you and your team want Codex to work in a repository.

51A good `AGENTS.md` covers:

53- repo layout and important directories

54- How to run the project

55- Build, test, and lint commands

56- Engineering conventions and PR expectations

57- Constraints and do-not rules

58- What done means and how to verify work

60The `/init` slash command in the CLI is the quick-start command to scaffold a starter `AGENTS.md` in the current directory. It's a great starting point, but you should edit the result to match how your team actually builds, tests, reviews, and ships code.

62You can create `AGENTS.md` files at different levels: a global `AGENTS.md` for personal defaults that sits in `~/.codex`, a repo-level file for shared standards, and more specific files in subdirectories for local rules. If there’s a more specific file closer to your current directory, that guidance wins.

64Keep it practical. A short, accurate `AGENTS.md` is more useful than a long file full of vague rules. Start with the basics, then add new rules only after you notice repeated mistakes.

66If `AGENTS.md` starts getting too large, keep the main file concise and reference task-specific markdown files for things like planning, code review, or architecture.

68When Codex makes the same mistake twice, ask it for a retrospective and update

69 `AGENTS.md`. Guidance stays practical and based on real friction.

71## Configure Codex for consistency

73Configuration is one of the main ways to make Codex behave more consistently across sessions and surfaces. For example, you can set defaults for model choice, reasoning effort, sandbox mode, approval policy, profiles, and MCP setup.

75A good starting pattern is:

77- Keep personal defaults in `~/.codex/config.toml` (Settings → Configuration → Open config.toml from the Codex app)

78- Keep repo-specific behavior in `.codex/config.toml`

79- Use command-line overrides only for one-off situations (if you use the CLI)

81[`config.toml`](https://developers.openai.com/codex/config-basic) is where you define durable preferences such as MCP servers, profiles, multi-agent setup, and experimental features. You can edit it directly or ask Codex to update it for you.

83Codex ships with operating level sandboxing and has two key knobs that you can control. Approval mode determines when Codex asks for your permission to run a command and sandbox mode determines if Codex can read or write in the directory and what files the agent can access.

85If you're new to coding agents, start with the default permissions. Keep approval and sandboxing tight by default, then loosen permissions only for trusted repos or specific workflows once the need is clear.

87Note that the CLI, IDE, and Codex app all share the same configuration layers. Learn more on the [sample configuration](https://developers.openai.com/codex/config-sample) page.

89Configure Codex for your real environment early. Many quality issues are

90 really setup issues, like the wrong working directory, missing write access,

91 wrong model defaults, or missing tools and connectors.

93## Improve reliability with testing and review

95Don't stop at asking Codex to make a change. Ask it to create tests when needed, run the relevant checks, confirm the result, and review the work before you accept it.

97Codex can do this loop for you, but only if it knows what “good” looks like. That guidance can come from either the prompt or `AGENTS.md`.

99That can include:

100

101- Writing or updating tests for the change

102- Running the right test suites

103- Checking lint, formatting, or type checks

104- Confirming the final behavior matches the request

105- Reviewing the diff for bugs, regressions, or risky patterns

106

107Toggle the diff panel in the Codex app to directly [review

108 changes](https://developers.openai.com/codex/app/review) locally. Click on a specific row to provide

109 feedback that gets fed as context to the next Codex turn.

110

111A useful option here is the slash command `/review`, which gives you a few ways to review code:

112

113- Review against a base branch for PR-style review

114- Review uncommitted changes

115- Review a commit

116- Use custom review instructions

117

118If you and your team have a `code_review.md` file and reference it from `AGENTS.md`, Codex can follow that guidance during review as well. This is a strong pattern for teams that want review behavior to stay consistent across repositories and contributors.

119

120Codex shouldn't just generate code. With the right instructions, it can also help **test it, check it, and review it**.

121

122If you use GitHub Cloud, you can set up Codex to run [code reviews for your PRs](https://developers.openai.com/codex/integrations/github). At OpenAI, Codex reviews 100% of PRs. You can enable automatic reviews or have Codex reactively review when you @Codex.

123

124## Use MCPs for external context

125

126Use MCPs when the context Codex needs lives outside the repo. It lets Codex connect to the tools and systems you already use, so you don't have to keep copying and pasting live information into prompts.

127

128[Model Context Protocol](https://developers.openai.com/codex/mcp), or MCP, is an open standard for connecting Codex to external tools and systems.

129

130Use MCP when:

131

132- The needed context lives outside the repo

133- The data changes frequently

134- You want Codex to use a tool rather than rely on pasted instructions

135- You need a repeatable integration across users or projects

136

137Codex supports both STDIO and Streamable HTTP servers with OAuth.

138

139In the Codex App, head to Settings → MCP servers to see custom and recommended servers. Often, Codex can help you install the needed servers. All you need to do is ask. You can also use the `codex mcp add` command in the CLI to add your custom servers with a name, URL, and other details.

140

141Add tools only when they unlock a real workflow. Do not start by wiring in

142 every tool you use. Start with one or two tools that clearly remove a manual

143 loop you already do often, then expand from there.

144

145## Turn repeatable work into skills

146

147Once a workflow becomes repeatable, stop relying on long prompts or repeated back-and-forth. Use a [Skill](https://developers.openai.com/codex/skills) to package the instructions in a SKILL.md file, context, and supporting logic Codex should apply consistently. Skills work across the CLI, IDE extension, and Codex app.

148

149Keep each skill scoped to one job. Start with 2 to 3 concrete use cases, define clear inputs and outputs, and write the description so it says what the skill does and when to use it. Include the kinds of trigger phrases a user would actually say.

150

151Don't try to cover every edge case up front. Start with one representative task, get it working well, then turn that workflow into a skill and improve from there. Include scripts or extra assets only when they improve reliability.

152

153A good rule of thumb: if you keep reusing the same prompt or correcting the same workflow, it should probably become a skill.

154

155Skills are especially useful for recurring jobs like:

156

157- Log triage

158- Release note drafting

159- PR review against a checklist

160- Migration planning

161- Telemetry or incident summaries

162- Standard debugging flows

163

164The `$skill-creator` skill is the best place to start to scaffold the first version of a skill and to use the `$skill-installer` skill to install it locally. One of the most important parts of a skill is the description. It should say what the skill does and when to use it.

165

166Personal skills are stored in `$HOME/.agents/skills`, and shared team skills

167 can be checked into `.agents/skills` inside a repository. This is especially

168 helpful for onboarding new teammates.

169

170## Use automations for repeated work

171

172Once a workflow is stable, you can schedule Codex to run it in the background for you. In the Codex app, [automations](https://developers.openai.com/codex/app/automations) let you choose the project, prompt, cadence, and execution environment for a recurring task.

173

174Once a task becomes repetitive for you, you can create an automation in the Automations tab on the Codex app. You can choose which project it runs in, the prompt it runs (you can invoke skills), and the cadence it will run. You can also choose whether the automation runs in a dedicated git worktree or in your local environment. Learn more about [git worktrees](https://developers.openai.com/codex/app/worktrees).

175

176Good candidates include:

177

178- Summarizing recent commits

179- Scanning for likely bugs

180- Drafting release notes

181- Checking CI failures

182- Producing standup summaries

183- Running repeatable analysis workflows on a schedule

184

185A useful rule is that skills define the method, automations define the schedule. If a workflow still needs a lot of steering, turn it into a skill first. Once it's predictable, automation becomes a force multiplier.

186

187Use automations for reflection and maintenance, not just execution. Review

188 recent sessions, summarize repeated friction, and improve prompts,

189 instructions, or workflow setup over time.

190

191## Organize long-running work with session controls

192

193Codex sessions aren't just chat history. They're working threads that accumulate context, decisions, and actions over time, so managing them well has a big impact on quality.

194

195The Codex app UI makes thread management easiest because you can pin threads and create worktrees. If you are using the CLI, these [slash commands](https://developers.openai.com/codex/cli/slash-commands) are especially useful:

196

197- `/experimental` to toggle experimental features and add to your `config.toml`

198- `/resume` to resume a saved conversation

199- `/fork` to create a new thread while preserving the original transcript

200- `/compact` when the thread is getting long and you want a summarized version of earlier context. Note that Codex does automatically compact conversations for you

201- `/agent` when you are running parallel agents and want to switch between the active agent thread

202- `/theme` to choose a syntax highlighting theme

203- `/apps` to use ChatGPT apps directly in Codex

204- `/status` to inspect the current session state

205

206Keep one thread per coherent unit of work. If the work is still part of the same problem, staying in the same thread is often better because it preserves the reasoning trail. Fork only when the work truly branches.

207

208Use Codex’s [multi-agent](https://developers.openai.com/codex/concepts/multi-agents) workflows to offload

209bounded work from the main thread. Keep the main agent focused on the core

210problem, and use subagents for tasks like exploration, tests, or triage.

211

212## Common mistakes

213

214A few common mistakes to avoid when first using Codex:

215

216- Overloading the prompt with durable rules instead of moving them into `AGENTS.md` or a skill

217- Not letting the agent see its work by not giving details on how to best run build and test commands

218- Skipping planning on multi-step and complex tasks

219- Giving Codex full permission to your computer before you understand the workflow

220- Running live threads on the same files without using git worktrees

221- Turning a recurring task into an automation before it's reliable manually

222- Treating Codex like something you have to watch step by step instead of using it in parallel with your own work

223- Using one thread per project instead of one thread per task. This leads to bloated context and worse results over time

multi-agent.md +16 −15

Details

31 31

32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.

33 33

~~34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, which is tuned for waiting and repeated status checks.~~34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, tuned for waiting and repeated status checks.

35 35

36To see it in action, try the following prompt on your project:36To see it in action, try the following prompt on your project:

37 37

53 53

54## Process CSV batches with sub-agents54## Process CSV batches with sub-agents

55 55

56Use `spawn_agents_on_csv` when you have many similar tasks that can be expressed as one row per work item. Codex reads the CSV, spawns one worker sub-agent per row, waits for the full batch to finish, and exports the combined results to CSV.56Use `spawn_agents_on_csv` when you have many similar tasks that map to one row per work item. Codex reads the CSV, spawns one worker sub-agent per row, waits for the full batch to finish, and exports the combined results to CSV.

57 57

58This works well for repeated audits such as:58This works well for repeated audits such as:

59 59

69- `output_schema` when each worker should return a JSON object with a fixed shape69- `output_schema` when each worker should return a JSON object with a fixed shape

70- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control70- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control

71 71

~~72Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting a result, that row is marked as failed in the exported CSV.~~72Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting a result, Codex marks that row with an error in the exported CSV.

73 73

74Example prompt:74Example prompt:

75 75

101shows the source thread label, and you can press `o` to open that thread before101shows the source thread label, and you can press `o` to open that thread before

102you approve, reject, or answer the request.102you approve, reject, or answer the request.

103 103

104In non-interactive flows, or whenever a run cannot surface a fresh approval,104In non-interactive flows, or whenever a run can’t surface a fresh approval,

105an action that needs new approval fails and the error is surfaced back to the105an action that needs new approval fails and Codex surfaces the error back to the

106parent workflow.106parent workflow.

107 107

108Codex also reapplies the parent turn’s live runtime overrides when it spawns a108Codex also reapplies the parent turn’s live runtime overrides when it spawns a

116 116

117You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).117You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).

118 118

119Agent roles can be defined either in your local configuration (typically `~/.codex/config.toml`) or shared in a project-specific `.codex/config.toml`.119Define agent roles either in your local configuration (typically `~/.codex/config.toml`) or in a project-specific `.codex/config.toml`.

120 120

121Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a121Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a

122role-specific config file (`config_file`) when Codex spawns an agent with that role.122role-specific config file (`config_file`) when Codex spawns an agent with that role.

132 132

133- `model` and `model_reasoning_effort` to select a specific model for your agent role133- `model` and `model_reasoning_effort` to select a specific model for your agent role

134- `sandbox_mode` to mark an agent as `read-only`134- `sandbox_mode` to mark an agent as `read-only`

135- `developer_instructions` to give the agent role additional instructions without relying on the parent agent for passing them135- `developer_instructions` to give the agent role extra instructions without relying on the parent agent to pass them

136 136

137### Schema137### Schema

138 138

140| --- | --- | --- | --- |140| --- | --- | --- | --- |

147 147

148**Notes:**148**Notes:**

149 149

150- Unknown fields in `[agents.<name>]` are rejected.150- Codex rejects unknown fields in `[agents.<name>]`.

151- `agents.max_threads` defaults to `6` when you leave it unset.

151- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.152- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.

152- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.153- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.

153- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.154- Codex resolves relative `config_file` paths relative to the `config.toml` file that defines the role.

154- `agents.<name>.config_file` is validated at config load time and must point to an existing file.155- Codex validates `agents.<name>.config_file` at config load time, and it must point to an existing file.

155- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.156- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.

156- If Codex can’t load a role config file, agent spawns can fail until you fix the file.157- If Codex can’t load a role config file, agent spawns can fail until you fix the file.

157- Any configuration not set by the agent role will be inherited from the parent session.158- The agent inherits any configuration that the role doesn’t set from the parent session.

158 159

159### Example agent roles160### Example agent roles

160 161

236Review this branch against main. Have explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.237Review this branch against main. Have explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

237```238```

238 239

239#### Example 2: frontend integration debugging team240#### Example 2: Frontend integration debugging team

240 241

241This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.242This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.

242 243

quickstart.md +3 −0

Details

41- Find and fix bugs in my codebase with minimal, high-confidence changes.40- Find and fix bugs in my codebase with minimal, high-confidence changes.

42 41

43 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).42 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).

43 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

44 44

45 [Learn more about the Codex app](https://developers.openai.com/codex/app)45 [Learn more about the Codex app](https://developers.openai.com/codex/app)

46 46

694. Use Git checkpoints694. Use Git checkpoints

70 70

71 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.71 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.

72 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

72 73

73 [Learn more about the Codex IDE extension](https://developers.openai.com/codex/ide)74 [Learn more about the Codex IDE extension](https://developers.openai.com/codex/ide)

74 75

1004. Use Git checkpoints1014. Use Git checkpoints

101 102

102 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.103 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.

104 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

103 105

104[Learn more about the Codex CLI](https://developers.openai.com/codex/cli)106[Learn more about the Codex CLI](https://developers.openai.com/codex/cli)

105 107

security.md +1 −1

Details

26 26

27## Access and prerequisites27## Access and prerequisites

28 28

29Codex Security works with connected GitHub repositories through Codex cloud. OpenAI manages access. If you need access or a repository isn’t visible, contact your OpenAI account team and confirm the repository is available through your Codex cloud workspace.29Codex Security works with connected GitHub repositories through Codex Web. OpenAI manages access. If you need access or a repository isn't visible, contact your OpenAI account team and confirm the repository is available through your Codex Web workspace.

30 30

31## Related docs31## Related docs

32 32

speed.md +3 −2

Details

8Fast mode is currently supported on GPT-5.4. When enabled, speed is increased8Fast mode is currently supported on GPT-5.4. When enabled, speed is increased

9by 1.5x and credits are consumed at a 2x rate.9by 1.5x and credits are consumed at a 2x rate.

10 10

~~11Enable it by typing `/fast`. It is available in Codex IDE Extensions, Codex~~11Enable it by typing `/fast`. It’s available in Codex IDE Extensions, Codex

~~12CLI, and the Codex app.~~12CLI, and the Codex app when you sign in with ChatGPT. With an API key, Codex

13uses standard API pricing instead and you can’t use `/fast`.

13 14

14[15[

15Your browser does not support the video tag.16Your browser does not support the video tag.

windows.md +10 −0

Details

27- Runs commands as a dedicated Windows Sandbox User.27- Runs commands as a dedicated Windows Sandbox User.

28- Limits network access by installing Windows Firewall rules.28- Limits network access by installing Windows Firewall rules.

29 29

30### Sandbox permissions

32Running Codex in full access mode means Codex is not limited to your project

33 directory and might perform unintentional destructive actions that can lead to

34 data loss. For safer automation, keep sandbox boundaries in place and use

35 [rules](https://developers.openai.com/codex/rules) for specific exceptions, or set your [approval policy to

36 never](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) to have

37 Codex attempt to solve problems without asking for escalated permissions,

38 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).

30### Grant sandbox read access40### Grant sandbox read access

31 41

32When a command fails because the Windows sandbox can't read a directory, use:42When a command fails because the Windows sandbox can't read a directory, use:

OpenAI - Codex Docs Changes 2026-03-07 06:14 UTC → 2026-03-11 00:31 UTC