Documentation 2026-05-23 00:54 UTC to 2026-05-26 18:54 UTC

278# } }278# } }

279```279```

280 280 

281You can also save presets as profiles, then select them with `codex --profile <name>`:281You can also save presets as [profile files](https://developers.openai.com/codex/config-advanced#profiles), then select them with `codex --profile profile-name`:

282 282 

283```283```

284[profiles.full_auto]284# ~/.codex/full_auto.config.toml

285approval_policy = "on-request"285approval_policy = "on-request"

286sandbox_mode = "workspace-write"286sandbox_mode = "workspace-write"

287```

287 288 

288[profiles.readonly_quiet]289```

290# ~/.codex/readonly_quiet.config.toml

289approval_policy = "never"291approval_policy = "never"

290sandbox_mode = "read-only"292sandbox_mode = "read-only"

291```293```

9| **General** | | |9| **General** | | |

10| | Command menu | `Cmd` + `Shift` + `P` or `Cmd` + `K` |10| | Command menu | `Cmd` + `Shift` + `P` or `Cmd` + `K` |

11| | Settings | `Cmd` + `,` |11| | Settings | `Cmd` + `,` |

12| | Keyboard shortcuts | `Cmd` + `/` |

12| | Open folder | `Cmd` + `O` |13| | Open folder | `Cmd` + `O` |

13| | Navigate back | `Cmd` + `[` |14| | Navigate back | `Cmd` + `[` |

14| | Navigate forward | `Cmd` + `]` |15| | Navigate forward | `Cmd` + `]` |

25| | Next thread | `Cmd` + `Shift` + `]` |26| | Next thread | `Cmd` + `Shift` + `]` |

26| | Dictation | `Ctrl` + `M` |27| | Dictation | `Ctrl` + `M` |

27 28 

29To find, customize, or reset shortcuts, open **Settings > Keyboard Shortcuts**.

30You can search by command name or switch the search field into keystroke mode

31and press the shortcut you want to find.

32 

28## Slash commands33## Slash commands

29 34 

30Slash commands let you control Codex without leaving the thread composer. Available commands vary based on your environment and access.35Slash commands let you control Codex without leaving the thread composer. Available commands vary based on your environment and access.

10require `Cmd`+`Enter` for multiline prompts or prevent sleep while a10require `Cmd`+`Enter` for multiline prompts or prevent sleep while a

11thread runs.11thread runs.

12 12 

13## Keyboard shortcuts

14 

15Open **Keyboard Shortcuts** to review commands, change bindings, or reset custom

16shortcuts to their defaults. Use the search field to find shortcuts by command

17name, or switch to keystroke search and press a key combination to find the

18command that uses it.

19 

13## Notifications20## Notifications

14 21 

15Choose when turn completion notifications appear, and whether the app should prompt for22Choose when turn completion notifications appear, and whether the app should prompt for

7 7 

8## CLI setup8## CLI setup

9 9 

10Choose your package manager10Choose your install option

11 11 

12npmHomebrew12macOS/LinuxWindowsnpmHomebrew

13 13 

141. 1141. 1

15 15 

16 ### Install16 ### Install

17 17 

18 Install the Codex CLI with npm.18 Install the Codex CLI with the standalone installer for macOS and Linux.

19 19 

20 npm install command20 macOS/Linux install command

21 21 

22 npm i -g @openai/codexCopy22 curl -fsSL https://chatgpt.com/codex/install.sh | shCopy

232. 2232. 2

24 24 

25 ### Run25 ### Run

37 37 

38 ### Upgrade38 ### Upgrade

39 39 

40 New versions of the Codex CLI are released regularly. See the [changelog](https://developers.openai.com/codex/changelog) for release notes. To upgrade with npm, run:40 New versions of the Codex CLI are released regularly. See the [changelog](https://developers.openai.com/codex/changelog) for release notes. To upgrade a standalone install, rerun the installer:

41 41 

42 npm upgrade command42 macOS/Linux upgrade command

43 43 

44 npm i -g @openai/codex@latestCopy44 curl -fsSL https://chatgpt.com/codex/install.sh | shCopy

45 45 

46The Codex CLI is available on macOS, Windows, and Linux. On Windows, run Codex46The Codex CLI is available on macOS, Windows, and Linux. On Windows, run Codex

47natively in PowerShell with the Windows sandbox, or use WSL2 when you need a47natively in PowerShell with the Windows sandbox, or use WSL2 when you need a

124codex features disable shell_snapshot124codex features disable shell_snapshot

125```125```

126 126 

127`codex features enable <feature>` and `codex features disable <feature>` write to `~/.codex/config.toml`. If you launch Codex with `--profile`, Codex stores the change in that profile rather than the root configuration.127`codex features enable <feature>` and `codex features disable <feature>` write to `~/.codex/config.toml`. If you launch Codex with `--profile profile-name`, Codex writes to `$CODEX_HOME/profile-name.config.toml` instead.

128 128 

129## Subagents129## Subagents

130 130 

25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |

26| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |26| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |

27| `--oss` | `boolean` | Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running. |27| `--oss` | `boolean` | Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running. |

28| `--profile, -p` | `string` | Configuration profile name to load from `~/.codex/config.toml`. |28| `--profile, -p` | `string` | Layer `$CODEX_HOME/profile-name.config.toml` on top of the base user config. |

29| `--remote` | `ws://host:port | wss://host:port` | Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode. |29| `--remote` | `ws://host:port | wss://host:port` | Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode. |

30| `--remote-auth-token-env` | `ENV_VAR` | Read a bearer token from this environment variable and send it when connecting with `--remote`. Requires `--remote`; tokens are only sent over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`. |30| `--remote-auth-token-env` | `ENV_VAR` | Read a bearer token from this environment variable and send it when connecting with `--remote`. Requires `--remote`; tokens are only sent over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`. |

31| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Select the sandbox policy for model-generated shell commands. |31| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Select the sandbox policy for model-generated shell commands. |

186 186 

187Details187Details

188 188 

189Configuration profile name to load from `~/.codex/config.toml`.189Layer `$CODEX_HOME/profile-name.config.toml` on top of the base user config.

190 190 

191Key191Key

192 192 

899 899 

900### `codex features`900### `codex features`

901 901 

902Manage feature flags stored in `~/.codex/config.toml`. The `enable` and `disable` commands persist changes so they apply to future sessions. When you launch with `--profile`, Codex writes to that profile instead of the root configuration.902Manage feature flags stored in `~/.codex/config.toml` or the selected profile file. The `enable` and `disable` commands persist changes so they apply to future sessions. When you launch with `--profile profile-name`, Codex writes to `$CODEX_HOME/profile-name.config.toml` instead of the base user config.

903 903 

904| Key | Type / Values | Details |904| Key | Type / Values | Details |

905| --- | --- | --- |905| --- | --- | --- |

906| `Disable subcommand` | `codex features disable <feature>` | Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided. |906| `Disable subcommand` | `codex features disable <feature>` | Persistently disable a feature flag in the active config file. With `--profile profile-name`, writes to `$CODEX_HOME/profile-name.config.toml`. |

907| `Enable subcommand` | `codex features enable <feature>` | Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided. |907| `Enable subcommand` | `codex features enable <feature>` | Persistently enable a feature flag in the active config file. With `--profile profile-name`, writes to `$CODEX_HOME/profile-name.config.toml`. |

908| `List subcommand` | `codex features list` | Show known feature flags, their maturity stage, and their effective state. |908| `List subcommand` | `codex features list` | Show known feature flags, their maturity stage, and their effective state. |

909 909 

910Key910Key

917 917 

918Details918Details

919 919 

920Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.920Persistently disable a feature flag in the active config file. With `--profile profile-name`, writes to `$CODEX_HOME/profile-name.config.toml`.

921 921 

922Key922Key

923 923 

929 929 

930Details930Details

931 931 

932Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.932Persistently enable a feature flag in the active config file. With `--profile profile-name`, writes to `$CODEX_HOME/profile-name.config.toml`.

933 933 

934Key934Key

935 935 

963| `--oss` | `boolean` | Use the local open source provider (requires a running Ollama instance). |963| `--oss` | `boolean` | Use the local open source provider (requires a running Ollama instance). |

964| `--output-last-message, -o` | `path` | Write the assistant’s final message to a file. Useful for downstream scripting. |964| `--output-last-message, -o` | `path` | Write the assistant’s final message to a file. Useful for downstream scripting. |

965| `--output-schema` | `path` | JSON Schema file describing the expected final response shape. Codex validates tool output against it. |965| `--output-schema` | `path` | JSON Schema file describing the expected final response shape. Codex validates tool output against it. |

966| `--profile, -p` | `string` | Select a configuration profile defined in config.toml. |966| `--profile, -p` | `string` | Layer `$CODEX_HOME/profile-name.config.toml` on top of the base user config. |

967| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Sandbox policy for model-generated commands. Defaults to configuration. |967| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Sandbox policy for model-generated commands. Defaults to configuration. |

968| `--skip-git-repo-check` | `boolean` | Allow running outside a Git repository (useful for one-off directories). |968| `--skip-git-repo-check` | `boolean` | Allow running outside a Git repository (useful for one-off directories). |

969| `-c, --config` | `key=value` | Inline configuration override for the non-interactive run (repeatable). |969| `-c, --config` | `key=value` | Inline configuration override for the non-interactive run (repeatable). |

1148 1148 

1149Details1149Details

1150 1150 

1151Select a configuration profile defined in config.toml.1151Layer `$CODEX_HOME/profile-name.config.toml` on top of the base user config.

1152 1152 

1153Key1153Key

1154 1154 

6 6 

7## Profiles7## Profiles

8 8 

9Profiles let you save named sets of configuration values and switch between them from the CLI.9Profiles let you save named configuration layers and switch between them from

10the CLI. When you pass `--profile profile-name`, Codex loads

11`~/.codex/config.toml`, then overlays `~/.codex/profile-name.config.toml`.

12Profile names can contain letters, numbers, hyphens, and underscores.

10 13 

11Profiles are experimental and may change or be removed in future releases.14Create a separate TOML file for each profile. Use top-level config keys in the

12 15profile file; don’t nest them under `[profiles.profile-name]`.

13Profiles are not currently supported in the Codex IDE extension.

14 

15Define profiles under `[profiles.<name>]` in `config.toml`, then run `codex --profile <name>`:

16 16 

17```17```

18model = "gpt-5.4"18# ~/.codex/deep-review.config.toml

19model = "gpt-5.5"

20model_reasoning_effort = "xhigh"

19approval_policy = "on-request"21approval_policy = "on-request"

20model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"

21 

22[profiles.deep-review]

23model = "gpt-5-pro"

24model_reasoning_effort = "high"

25approval_policy = "never"

26model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"22model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

23```

27 24 

28[profiles.lightweight]25```

29model = "gpt-4.1"26codex --profile deep-review

30approval_policy = "untrusted"27codex exec --profile deep-review "review this change"

31```28```

32 29 

33To make a profile the default, add `profile = "deep-review"` at the top level of `config.toml`. Codex loads that profile unless you override it on the command line.30Because the profile file is a layer above your base user config and below

31project and CLI config, it only needs the values that differ from your base

32config. Profile files can also override `model_catalog_json`; Codex uses the

33profile value when both files set it.

34 34 

35Profiles can also override `model_catalog_json`. When both the top level and the selected profile set `model_catalog_json`, Codex prefers the profile value.35In Codex 0.134.0 and later, `--profile` no longer reads `[profiles.profile-name]`

36from `config.toml`, and the top-level `profile = "profile-name"` selector is no

37longer supported. Move legacy profile settings into

38`~/.codex/profile-name.config.toml`, then remove the matching

39`[profiles.profile-name]` table and `profile = "profile-name"` selector from

40`config.toml`.

36 41 

37## One-off overrides from the CLI42## One-off overrides from the CLI

38 43 

88 93 

89Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.94Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.

90 95 

91Project config files can’t override settings that redirect credentials, change96Project config files can’t override settings that redirect credentials, alter

92provider auth, or run machine-local notification/telemetry commands.97host-owned app request metadata, change provider auth, select config profiles,

93Codex ignores the following keys in project-local `.codex/config.toml` and98or run machine-local notification/telemetry commands. Codex ignores the

94prints a startup warning when it sees them: `openai_base_url`,99following keys in project-local `.codex/config.toml` and prints a startup

95`chatgpt_base_url`, `model_provider`, `model_providers`, `notify`, `profile`,100warning when it sees them: `openai_base_url`, `chatgpt_base_url`,

96`profiles`, `experimental_realtime_ws_base_url`, and `otel`. Set those keys in101`apps_mcp_product_sku`, `model_provider`, `model_providers`, `notify`,

97your user-level `~/.codex/config.toml` instead.102`profile`, `profiles`, `experimental_realtime_ws_base_url`, and `otel`. Set

103provider, notification, and telemetry keys in your user-level

104`~/.codex/config.toml`; select config profiles with `--profile profile-name`

105and `~/.codex/profile-name.config.toml`.

98 106 

99## Hooks107## Hooks

100 108 

311For built-in profiles, custom profile syntax, and the full filesystem and319For built-in profiles, custom profile syntax, and the full filesystem and

312network configuration model, see [Permissions](https://developers.openai.com/codex/permissions).320network configuration model, see [Permissions](https://developers.openai.com/codex/permissions).

313 321 

314For the complete key list, including profile-scoped overrides and requirements322For the complete key list and requirements constraints, see

315constraints, see [Configuration Reference](https://developers.openai.com/codex/config-reference) and323[Configuration Reference](https://developers.openai.com/codex/config-reference) and

316[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).324[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).

317 325 

318In workspace-write mode, some environments keep `.git/` and `.codex/`326In workspace-write mode, some environments keep `.git/` and `.codex/`

19Codex resolves values in this order (highest precedence first):19Codex resolves values in this order (highest precedence first):

20 20 

211. CLI flags and `--config` overrides211. CLI flags and `--config` overrides

222. [Profile](https://developers.openai.com/codex/config-advanced#profiles) values (from `--profile <name>`)222. Project config files: `.codex/config.toml`, ordered from the project root down to your current working directory (closest wins; trusted projects only)

233. Project config files: `.codex/config.toml`, ordered from the project root down to your current working directory (closest wins; trusted projects only)233. [Profile](https://developers.openai.com/codex/config-advanced#profiles) files selected with `--profile profile-name` (`~/.codex/profile-name.config.toml`)

244. User config: `~/.codex/config.toml`244. User config: `~/.codex/config.toml`

255. System config (if present): `/etc/codex/config.toml` on Unix255. System config (if present): `/etc/codex/config.toml` on Unix

266. Built-in defaults266. Built-in defaults

27 27 

28Use that precedence to set shared defaults at the top level and keep profiles focused on the values that differ.28Use that precedence to set shared defaults in `config.toml` and keep [profile files](https://developers.openai.com/codex/config-advanced#profiles) focused on the values that differ.

29 29 

30If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers, including project-local config, hooks, and rules. User and system config still load, including user/global hooks and rules.30If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers, including project-local config, hooks, and rules. User and system config still load, including user/global hooks and rules.

31 31 

7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.

8 8 

9Project-scoped config can’t override machine-local provider, auth,9Project-scoped config can’t override machine-local provider, auth,

10notification, profile, or telemetry routing keys. Codex ignores10host-owned app request metadata, notification, configuration profile selection,

11`openai_base_url`, `chatgpt_base_url`, `model_provider`, `model_providers`,11or telemetry routing keys. Codex ignores `openai_base_url`,

12`notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and12`chatgpt_base_url`, `apps_mcp_product_sku`, `model_provider`,

13`otel` when they appear in a project-local `.codex/config.toml`; put those in13`model_providers`, `notify`, `profile`, `profiles`,

14user-level config instead.14`experimental_realtime_ws_base_url`, and `otel` when they appear in a

15project-local `.codex/config.toml`; put provider, notification, and telemetry

16keys in user-level config instead. Config [profile files](https://developers.openai.com/codex/config-advanced#profiles) live next to

17`config.toml` as `$CODEX_HOME/profile-name.config.toml`; select one with

18`--profile profile-name`.

15 19 

16For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access). For beta permission profiles, see [Permissions](https://developers.openai.com/codex/permissions).20For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access). For beta permission profiles, see [Permissions](https://developers.openai.com/codex/permissions).

17 21 

133| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |137| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |

134| `model` | `string` | Model to use (e.g., `gpt-5.5`). |138| `model` | `string` | Model to use (e.g., `gpt-5.5`). |

135| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |139| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

136| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |140| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. A selected `$CODEX_HOME/profile-name.config.toml` profile file can override this per profile. |

137| `model_context_window` | `number` | Context window tokens available to the active model. |141| `model_context_window` | `number` | Context window tokens available to the active model. |

138| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |142| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |

139| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |143| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

217| `plugins.<plugin>.mcp_servers.<server>.enabled` | `boolean` | Enable or disable an MCP server bundled by an installed plugin without changing the plugin manifest. |221| `plugins.<plugin>.mcp_servers.<server>.enabled` | `boolean` | Enable or disable an MCP server bundled by an installed plugin without changing the plugin manifest. |

218| `plugins.<plugin>.mcp_servers.<server>.enabled_tools` | `array<string>` | Allow list of tools exposed from a plugin-provided MCP server. |222| `plugins.<plugin>.mcp_servers.<server>.enabled_tools` | `array<string>` | Allow list of tools exposed from a plugin-provided MCP server. |

219| `plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a plugin-provided MCP tool. |223| `plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a plugin-provided MCP tool. |

220| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

221| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |

222| `profiles.<name>.analytics.enabled` | `boolean` | Profile-scoped analytics enablement override. |

223| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |

224| `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). |

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

226| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |

227| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |

228| `profiles.<name>.plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Profile-scoped Plan-mode reasoning override. |

229| `profiles.<name>.service_tier` | `string` | Profile-scoped service tier preference for new turns. |

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

231| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |

232| `profiles.<name>.windows.sandbox` | `unelevated | elevated` | Profile-scoped Windows sandbox mode override. |

233| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |224| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |

234| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |225| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

235| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |226| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |

1680 1671 

1681Details1672Details

1682 1673 

1683Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.1674Optional path to a JSON model catalog loaded on startup. A selected `$CODEX_HOME/profile-name.config.toml` profile file can override this per profile.

1684 1675 

1685Key1676Key

1686 1677 

2680 2671 

2681Key2672Key

2682 2673 

2683`profile`

2684 

2685Type / Values

2686 

2687`string`

2688 

2689Details

2690 

2691Default profile applied at startup (equivalent to `--profile`).

2692 

2693Key

2694 

2695`profiles.<name>.*`

2696 

2697Type / Values

2698 

2699`various`

2700 

2701Details

2702 

2703Profile-scoped overrides for any of the supported configuration keys.

2704 

2705Key

2706 

2707`profiles.<name>.analytics.enabled`

2708 

2709Type / Values

2710 

2711`boolean`

2712 

2713Details

2714 

2715Profile-scoped analytics enablement override.

2716 

2717Key

2718 

2719`profiles.<name>.experimental_use_unified_exec_tool`

2720 

2721Type / Values

2722 

2723`boolean`

2724 

2725Details

2726 

2727Legacy name for enabling unified exec; prefer `[features].unified_exec`.

2728 

2729Key

2730 

2731`profiles.<name>.model_catalog_json`

2732 

2733Type / Values

2734 

2735`string (path)`

2736 

2737Details

2738 

2739Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).

2740 

2741Key

2742 

2743`profiles.<name>.model_instructions_file`

2744 

2745Type / Values

2746 

2747`string (path)`

2748 

2749Details

2750 

2751Profile-scoped replacement for the built-in instruction file.

2752 

2753Key

2754 

2755`profiles.<name>.oss_provider`

2756 

2757Type / Values

2758 

2759`lmstudio | ollama`

2760 

2761Details

2762 

2763Profile-scoped OSS provider for `--oss` sessions.

2764 

2765Key

2766 

2767`profiles.<name>.personality`

2768 

2769Type / Values

2770 

2771`none | friendly | pragmatic`

2772 

2773Details

2774 

2775Profile-scoped communication style override for supported models.

2776 

2777Key

2778 

2779`profiles.<name>.plan_mode_reasoning_effort`

2780 

2781Type / Values

2782 

2783`none | minimal | low | medium | high | xhigh`

2784 

2785Details

2786 

2787Profile-scoped Plan-mode reasoning override.

2788 

2789Key

2790 

2791`profiles.<name>.service_tier`

2792 

2793Type / Values

2794 

2795`string`

2796 

2797Details

2798 

2799Profile-scoped service tier preference for new turns.

2800 

2801Key

2802 

2803`profiles.<name>.tools_view_image`

2804 

2805Type / Values

2806 

2807`boolean`

2808 

2809Details

2810 

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

2812 

2813Key

2814 

2815`profiles.<name>.web_search`

2816 

2817Type / Values

2818 

2819`disabled | cached | live`

2820 

2821Details

2822 

2823Profile-scoped web search mode override (default: `"cached"`).

2824 

2825Key

2826 

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

2828 

2829Type / Values

2830 

2831`unelevated | elevated`

2832 

2833Details

2834 

2835Profile-scoped Windows sandbox mode override.

2836 

2837Key

2838 

2839`project_doc_fallback_filenames`2674`project_doc_fallback_filenames`

2840 2675 

2841Type / Values2676Type / Values

1094# Notes1094# Notes

1095# - Root keys must appear before tables in TOML.1095# - Root keys must appear before tables in TOML.

1096# - Optional keys that default to "unset" are shown commented out with notes.1096# - Optional keys that default to "unset" are shown commented out with notes.

1097# - MCP servers, profiles, and model providers are examples; remove or edit.1097# - MCP servers, profile files, and model providers are examples; remove or edit.

1098 1098 

1099################################################################################1099################################################################################

1100 1100 

1382 1382 

1383web_search = "cached"1383web_search = "cached"

1384 1384 

1385# Active profile name. When unset, no profile is applied.1385# Config profiles are separate files under CODEX_HOME.

1386 1386 

1387# profile = "default"1387# Example: ~/.codex/ci.config.toml, selected with codex --profile ci.

1388 1388 

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

1390 1390 

2026 2026 

2027################################################################################2027################################################################################

2028 2028 

2029# Profiles (named presets)2029# Config Profiles (separate files)

2030 2030 

2031################################################################################2031################################################################################

2032 2032 

2033[profiles]2033# To create a config profile, put overrides in a separate profile file under $CODEX_HOME.

2034 2034 

2035# [profiles.default]2035# Select it with codex --profile ci.

2036 2036 

2037# model = "gpt-5.4"2037# For example, a CI profile could live at $CODEX_HOME/ci.config.toml:

2038 2038 

2039# model_provider = "openai"2039# model = "gpt-5.4"

2040 2040 

2041# approval_policy = "on-request"2041# approval_policy = "on-request"

2042 2042 

7 7 

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

9 9 

10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, web search mode, managed hooks, 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.10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, web search mode, managed hooks, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, [profile files](https://developers.openai.com/codex/config-advanced#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 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.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 

153computer_use = false153computer_use = false

154```154```

155 155 

156Use 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.156Use 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 file feature settings.

157 157 

158- `in_app_browser = false` disables the in-app browser pane.158- `in_app_browser = false` disables the in-app browser pane.

159- `browser_use = false` disables Browser Use and Browser Agent availability.159- `browser_use = false` disables Browser Use and Browser Agent availability.

33 runs-on: ubuntu-latest33 runs-on: ubuntu-latest

34 permissions:34 permissions:

35 contents: read35 contents: read

36 pull-requests: write

37 outputs:36 outputs:

38 final_message: ${{ steps.run_codex.outputs.final-message }}37 final_message: ${{ steps.run_codex.outputs.final-message }}

39 steps:38 steps:

40 - uses: actions/checkout@v539 - uses: actions/checkout@v5

41 with:40 with:

42 ref: refs/pull/${{ github.event.pull_request.number }}/merge41 ref: refs/pull/${{ github.event.pull_request.number }}/merge

42 persist-credentials: false

43 43 

44 - name: Pre-fetch base and head refs44 - name: Pre-fetch base and head refs

45 env:

46 PR_BASE_REF: ${{ github.event.pull_request.base.ref }}

47 PR_NUMBER: ${{ github.event.pull_request.number }}

45 run: |48 run: |

46 git fetch --no-tags origin \49 git fetch --no-tags origin \

47 ${{ github.event.pull_request.base.ref }} \50 "$PR_BASE_REF" \

48 +refs/pull/${{ github.event.pull_request.number }}/head51 "+refs/pull/$PR_NUMBER/head"

49 52 

50 - name: Run Codex53 - name: Run Codex

51 id: run_codex54 id: run_codex

54 openai-api-key: ${{ secrets.OPENAI_API_KEY }}57 openai-api-key: ${{ secrets.OPENAI_API_KEY }}

55 prompt-file: .github/codex/prompts/review.md58 prompt-file: .github/codex/prompts/review.md

56 output-file: codex-output.md59 output-file: codex-output.md

57 safety-strategy: drop-sudo

58 sandbox: workspace-write

59 60 

60 post_feedback:61 post_feedback:

61 runs-on: ubuntu-latest62 runs-on: ubuntu-latest

62 needs: codex63 needs: codex

63 if: needs.codex.outputs.final_message != ''64 if: needs.codex.outputs.final_message != ''

65 permissions:

66 issues: write

67 pull-requests: write

64 steps:68 steps:

65 - name: Post Codex feedback69 - name: Post Codex feedback

66 uses: actions/github-script@v770 uses: actions/github-script@v7

84Fine-tune how Codex runs by setting the action inputs that map to `codex exec` options:88Fine-tune how Codex runs by setting the action inputs that map to `codex exec` options:

85 89 

86- `prompt` or `prompt-file` (choose one): Inline instructions or a repository path to Markdown or text with your task. Consider storing prompts in `.github/codex/prompts/`.90- `prompt` or `prompt-file` (choose one): Inline instructions or a repository path to Markdown or text with your task. Consider storing prompts in `.github/codex/prompts/`.

87- `codex-args`: Extra CLI flags. Provide a JSON array (for example `["--json"]`) or a shell string (`--sandbox workspace-write --json`) to allow edits, streaming, or MCP configuration.91- `codex-args`: Extra CLI flags. Provide a JSON array (for example `["--ephemeral"]`) or a shell string (`--profile ci`) to configure sessions, profiles, or MCP settings.

88- `model` and `effort`: Pick the Codex agent configuration you want; leave empty for defaults.92- `model` and `effort`: Pick the Codex agent configuration you want; leave empty for defaults.

89- `sandbox`: Match the sandbox mode (`workspace-write`, `read-only`, `danger-full-access`) to the permissions Codex needs during the run.93- `sandbox`: Match the sandbox mode (`workspace-write`, `read-only`, `danger-full-access`) to the permissions Codex needs during the run.

90- `output-file`: Save the final Codex message to disk so later steps can upload or diff it.94- `output-file`: Save the final Codex message to disk so later steps can upload or diff it.

96Codex has broad access on GitHub-hosted runners unless you restrict it. Use these inputs to control exposure:100Codex has broad access on GitHub-hosted runners unless you restrict it. Use these inputs to control exposure:

97 101 

98- `safety-strategy` (default `drop-sudo`) removes `sudo` before running Codex. This is irreversible for the job and protects secrets in memory. On Windows you must set `safety-strategy: unsafe`.102- `safety-strategy` (default `drop-sudo`) removes `sudo` before running Codex. This is irreversible for the job and protects secrets in memory. On Windows you must set `safety-strategy: unsafe`.

99- `unprivileged-user` pairs `safety-strategy: unprivileged-user` with `codex-user` to run Codex as a specific account. Ensure the user can read and write the repository checkout (see `.cache/codex-action/examples/unprivileged-user.yml` for an ownership fix).103- `unprivileged-user` pairs `safety-strategy: unprivileged-user` with `codex-user` to run Codex as a specific account. Ensure the user can read and write the repository checkout (see the [`unprivileged-user` example](https://github.com/openai/codex-action/blob/main/examples/unprivileged-user.yml) for an ownership fix).

100- `read-only` keeps Codex from changing files or using the network, but it still runs with elevated privileges. Don’t rely on `read-only` alone to protect secrets.104- `read-only` keeps Codex from changing files or using the network, but it still runs with elevated privileges. Don’t rely on `read-only` alone to protect secrets.

101- `sandbox` limits filesystem and network access within Codex itself. Choose the narrowest option that still lets the task complete.105- `sandbox` limits filesystem and network access within Codex itself. Choose the narrowest option that still lets the task complete.

102- `allow-users` and `allow-bots` restrict who can trigger the workflow. By default only users with write access can run the action; list extra trusted accounts explicitly or leave the field empty for the default behavior.106- `allow-users` and `allow-bots` restrict who can trigger the workflow. By default only users with write access can run the action; list extra trusted accounts explicitly or leave the field empty for the default behavior.

29| `cwd` | `string` | Working directory for the session. If relative, resolved against the server process’s current directory. |29| `cwd` | `string` | Working directory for the session. If relative, resolved against the server process’s current directory. |

30| `include-plan-tool` | `boolean` | Whether to include the plan tool in the conversation. |30| `include-plan-tool` | `boolean` | Whether to include the plan tool in the conversation. |

31| `model` | `string` | Optional override for the model name (for example, `o3`, `o4-mini`). |31| `model` | `string` | Optional override for the model name (for example, `o3`, `o4-mini`). |

32| `profile` | `string` | Configuration profile from `config.toml` to specify default options. |32| `profile` | `string` | Configuration profile name; Codex loads `$CODEX_HOME/profile-name.config.toml` to specify default options. |

33| `sandbox` | `string` | Sandbox mode: `read-only`, `workspace-write`, or `danger-full-access`. |33| `sandbox` | `string` | Sandbox mode: `read-only`, `workspace-write`, or `danger-full-access`. |

34 34 

35**`codex-reply`**: Continue a Codex session by providing the thread ID and prompt. The `codex-reply` tool takes these properties:35**`codex-reply`**: Continue a Codex session by providing the thread ID and prompt. The `codex-reply` tool takes these properties:

73 73 

74Before starting, make sure you have:74Before starting, make sure you have:

75 75 

76- [Codex CLI](https://developers.openai.com/codex/cli) installed locally so `npx codex` can run.76- [Codex CLI](https://developers.openai.com/codex/cli) installed locally so the `codex` command is available.

77- Python 3.10+ with `pip`.77- Python 3.10+ with `pip`.

78- Node.js 18+ (required for `npx`).78- Node.js 18+ if you want to run the MCP Inspector example above.

79- An OpenAI API key stored locally. You can create or manage keys in the [OpenAI dashboard](https://platform.openai.com/account/api-keys).79- An OpenAI API key stored locally. You can create or manage keys in the [OpenAI dashboard](https://platform.openai.com/account/api-keys).

80 80 

81Create a working directory for the guide and add your API key to a `.env` file:81Create a working directory for the guide and add your API key to a `.env` file:

115 async with MCPServerStdio(115 async with MCPServerStdio(

116 name="Codex CLI",116 name="Codex CLI",

117 params={117 params={

118 "command": "npx",118 "command": "codex",

119 "args": ["-y", "codex", "mcp-server"],119 "args": ["mcp-server"],

120 },120 },

121 client_session_timeout_seconds=360000,121 client_session_timeout_seconds=360000,

122 ) as codex_mcp_server:122 ) as codex_mcp_server:

161 async with MCPServerStdio(161 async with MCPServerStdio(

162 name="Codex CLI",162 name="Codex CLI",

163 params={163 params={

164 "command": "npx",164 "command": "codex",

165 "args": ["-y", "codex", "mcp-server"],165 "args": ["mcp-server"],

166 },166 },

167 client_session_timeout_seconds=360000,167 client_session_timeout_seconds=360000,

168 ) as codex_mcp_server:168 ) as codex_mcp_server:

232async def main() -> None:232async def main() -> None:

233 async with MCPServerStdio(233 async with MCPServerStdio(

234 name="Codex CLI",234 name="Codex CLI",

235 params={"command": "npx", "args": ["-y", "codex", "mcp"]},235 params={"command": "codex", "args": ["mcp"]},

236 client_session_timeout_seconds=360000,236 client_session_timeout_seconds=360000,

237 ) as codex_mcp_server:237 ) as codex_mcp_server:

238 designer_agent = Agent(238 designer_agent = Agent(

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

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

80 80 

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 feature flags. You can edit it directly or ask Codex to update it for you.81[`config.toml`](https://developers.openai.com/codex/config-basic) is where you define durable preferences such as MCP servers, multi-agent setup, and feature flags. Profile-specific overrides live in separate `$CODEX_HOME/profile-name.config.toml` files.

82 82 

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.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.

84 84 

124}124}

125```125```

126 126 

127## Authenticate in CI127## Authenticate in automation

128 128 

129`codex exec` reuses saved CLI authentication by default. In CI, it’s common to provide credentials explicitly:129`codex exec` reuses saved CLI authentication by default. In CI, it’s common to provide credentials explicitly:

130 130 

131### Use API key auth (recommended)131### Use API key auth

132 132 

133- Set `CODEX_API_KEY` as a secret environment variable for the job.133For GitHub Actions, use the [Codex GitHub Action](https://developers.openai.com/codex/github-action) instead of installing and authenticating the CLI yourself. The action is designed to reduce API key exposure by installing Codex, starting a Responses API proxy, and running Codex with a configurable safety strategy.

134- Keep prompts and tool output in mind: they can include sensitive code or data.134 

135Do not set `OPENAI_API_KEY` or `CODEX_API_KEY` as a job-level environment variable in workflows that check out or run repository-controlled code. Build scripts, tests, dependency lifecycle hooks, or a compromised action in the same job can read those environment variables.

136 

137For other automation environments, set `CODEX_API_KEY` only for the single `codex exec` invocation and make sure no untrusted code runs in the same process environment.

135 138 

136To use a different API key for a single run, set `CODEX_API_KEY` inline:139To use a different API key for a single run, set `CODEX_API_KEY` inline:

137 140 

180 183 

181### Example: Autofix CI failures in GitHub Actions184### Example: Autofix CI failures in GitHub Actions

182 185 

183You can use `codex exec` to automatically propose fixes when a CI workflow fails. The typical pattern is:186For GitHub Actions workflows, use [`openai/codex-action`](https://github.com/openai/codex-action) instead of installing Codex and passing the API key to a shell step. The action starts a secure proxy for the OpenAI API key.

187 

188You can use Codex to automatically propose fixes when a CI workflow fails. The pattern is:

184 189 

1851. Trigger a follow-up workflow when your main CI workflow completes with an error.1901. Trigger a follow-up workflow when your main CI workflow completes with an error.

1862. Check out the failing commit SHA.1912. Check out the failing commit with repository read permissions only.

1873. Install dependencies and run Codex with a narrow prompt and minimal permissions.1923. Run setup commands before Codex, without exposing your OpenAI API key to those steps.

1884. Re-run the test command.1934. Run the Codex GitHub Action.

1895. Open a pull request with the resulting patch.1945. Save Codex’s local changes as a patch artifact.

1956. In a separate job, apply the patch and open a pull request.

196 

197The Codex job below has only `contents: read`. After Codex runs, it only serializes the diff as an artifact. The `open_pr` job receives repository write permissions, but it does not receive `OPENAI_API_KEY`.

190 198 

191#### Minimal workflow using the Codex CLI199The example assumes a Node.js project. Adjust the setup and test commands to match your stack.

192 200 

193The example below shows the core steps. Adjust the install and test commands to match your stack.201For a deeper security checklist, see the [Codex GitHub Action security guidance](https://github.com/openai/codex-action/blob/main/docs/security.md).

194 202 

195```203```

196name: Codex auto-fix on CI failure204name: Codex auto-fix on CI failure

200 workflows: ["CI"]208 workflows: ["CI"]

201 types: [completed]209 types: [completed]

202 210 

203 permissions:

204 contents: write

205 pull-requests: write

206 

207jobs:211jobs:

208 auto-fix:212 generate_fix:

209 if: ${{ github.event.workflow_run.conclusion == 'failure' }}213 if: ${{ github.event.workflow_run.conclusion == 'failure' }}

210 runs-on: ubuntu-latest214 runs-on: ubuntu-latest

211 env:215 permissions:

212 OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}216 contents: read

213 FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}217 outputs:

214 FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}218 has_patch: ${{ steps.diff.outputs.has_patch }}

215 steps:219 steps:

216 - uses: actions/checkout@v4220 - uses: actions/checkout@v5

217 with:221 with:

218 ref: ${{ env.FAILED_HEAD_SHA }}222 ref: ${{ github.event.workflow_run.head_sha }}

219 fetch-depth: 0223 fetch-depth: 0

224 persist-credentials: false

220 225 

221 - uses: actions/setup-node@v4226 - uses: actions/setup-node@v4

222 with:227 with:

224 229 

225 - name: Install dependencies230 - name: Install dependencies

226 run: |231 run: |

227 if [ -f package-lock.json ]; then npm ci; else npm i; fi232 if [ -f package-lock.json ]; then npm ci; fi

228 233 

229 - name: Install Codex234 - name: Run Codex

230 run: npm i -g @openai/codex235 uses: openai/codex-action@v1

236 with:

237 openai-api-key: ${{ secrets.OPENAI_API_KEY }}

238 prompt: |

239 The CI workflow "${{ github.event.workflow_run.name }}" failed for commit

240 ${{ github.event.workflow_run.head_sha }}.

231 241 

232 - name: Authenticate Codex242 Run `npm test --silent` to reproduce the failure. Identify the minimal

233 run: codex login --api-key "$OPENAI_API_KEY"243 change needed to make the tests pass, implement only that change, and

244 run `npm test --silent` again.

234 245 

235 - name: Run Codex246 Do not refactor unrelated files.

247 

248 - name: Create patch artifact

249 id: diff

236 run: |250 run: |

237 codex exec --sandbox workspace-write \251 git add -N .

238 "Read the repository, run the test suite, identify the minimal change needed to make all tests pass, implement only that change, and stop. Do not refactor unrelated files."252 git diff --binary HEAD > codex.patch

253 if [ -s codex.patch ]; then

254 echo "has_patch=true" >> "$GITHUB_OUTPUT"

255 else

256 echo "has_patch=false" >> "$GITHUB_OUTPUT"

257 fi

258 

259 - name: Upload patch artifact

260 if: steps.diff.outputs.has_patch == 'true'

261 uses: actions/upload-artifact@v4

262 with:

263 name: codex-fix-patch

264 path: codex.patch

265 if-no-files-found: error

239 266 

240 - name: Verify tests267 open_pr:

241 run: npm test --silent268 runs-on: ubuntu-latest

269 needs: generate_fix

270 if: needs.generate_fix.outputs.has_patch == 'true'

271 permissions:

272 contents: write

273 pull-requests: write

274 steps:

275 - uses: actions/checkout@v5

276 with:

277 ref: ${{ github.event.workflow_run.head_sha }}

278 fetch-depth: 0

242 279 

243 - name: Create pull request280 - uses: actions/download-artifact@v4

244 if: success()

245 uses: peter-evans/create-pull-request@v6

246 with:281 with:

247 branch: codex/auto-fix-${{ github.event.workflow_run.run_id }}282 name: codex-fix-patch

248 base: ${{ env.FAILED_HEAD_BRANCH }}

249 title: "Auto-fix failing CI via Codex"

250```

251 283 

252#### Alternative: Use the Codex GitHub Action284 - name: Apply Codex patch

285 run: git apply --index codex.patch

253 286 

254If you want to avoid installing the CLI yourself, you can run `codex exec` through the [Codex GitHub Action](https://developers.openai.com/codex/github-action) and pass the prompt as an input.287 - name: Open pull request

288 env:

289 GH_TOKEN: ${{ github.token }}

290 FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}

291 FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}

292 RUN_ID: ${{ github.event.workflow_run.run_id }}

293 run: |

294 branch="codex/auto-fix-$RUN_ID"

295 

296 git config user.name "github-actions[bot]"

297 git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

298 git switch -c "$branch"

299 git commit -m "Auto-fix failing CI via Codex"

300 git push origin "$branch"

301 

302 {

303 echo "Codex generated this patch after CI failed for \`$FAILED_HEAD_SHA\`."

304 echo

305 echo "Review the changes before merging."

306 } > pr-body.md

307 

308 gh pr create \

309 --base "$FAILED_HEAD_BRANCH" \

310 --head "$branch" \

311 --title "Auto-fix failing CI via Codex" \

312 --body-file pr-body.md

313```

255 314 

256## Advanced stdin piping315## Advanced stdin piping

257 316 

78 78 

791. Install the Codex CLI791. Install the Codex CLI

80 80 

81 Install with npm:81 On macOS or Linux, use the standalone installer:

82 82 

83 ```83 ```

84 npm install -g @openai/codex84 curl -fsSL https://chatgpt.com/codex/install.sh | sh

85 ```

86 

87 On Windows, run:

88 

89 ```

90 powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

85 ```91 ```

86 92 

87 Install with Homebrew:93 You can also install Codex CLI with npm or Homebrew:

94 

95 ```

96 npm install -g @openai/codex

97 ```

88 98 

89 ```99 ```

90 brew install codex100 brew install --cask codex

91 ```101 ```

922. Run `codex` and sign in1022. Run `codex` and sign in

93 103 

157Then run these commands from your WSL shell:157Then run these commands from your WSL shell:

158 158 

159```159```

160# https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl

161# Install Node.js in WSL (via nvm)

162curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

163 

164# In a new tab or after exiting and running `wsl` again to install Node.js

165nvm install 22

166 

167# Install and run Codex in WSL160# Install and run Codex in WSL

168npm i -g @openai/codex161curl -fsSL https://chatgpt.com/codex/install.sh | sh

169codex162codex

170```163```

171 164