OpenAI - Codex Docs Changes

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

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”

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

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

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 18:10 UTC → 2026-03-09 00:34 UTC