OpenAI - Codex Docs Changes 2026-03-31 00:39 UTC → 2026-04-08 00:40 UTC

1# Windows1# Windows

2 2 

3The [Codex app for Windows](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US) gives you one interface for3The [Codex app for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi) gives you one interface for

4working across projects, running parallel agent threads, and reviewing results.4working across projects, running parallel agent threads, and reviewing results.

5It runs natively on Windows using PowerShell and the5It runs natively on Windows using PowerShell and the

6[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to6[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to

11## Download and update the Codex app11## Download and update the Codex app

12 12 

13Download the Codex app from the13Download the Codex app from the

14[Microsoft Store](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US).14[Microsoft Store](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi).

15 15 

16Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.16Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.

17 17 

22| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |22| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |

23| `--full-auto` | `boolean` | Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`. |23| `--full-auto` | `boolean` | Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`. |

24| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |24| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |

25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5-codex`). |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` | Configuration profile name to load from `~/.codex/config.toml`. |

148 148 

149Details149Details

150 150 

151Override the model set in configuration (for example `gpt-5-codex`).151Override the model set in configuration (for example `gpt-5.4`).

152 152 

153Key153Key

154 154 

36inside enforced limits. That makes it easier to let Codex work independently36inside enforced limits. That makes it easier to let Codex work independently

37while still knowing when it will stop and ask for help.37while still knowing when it will stop and ask for help.

38 38 

39## Getting started

40 

41Codex applies sandboxing automatically when you use the default permissions

42mode.

43 

44### Prerequisites

45 

46On **macOS**, sandboxing works out of the box using the built-in Seatbelt

47framework.

48 

49On **Windows**, Codex uses the native [Windows

50sandbox](https://developers.openai.com/codex/windows#windows-sandbox) when you run in PowerShell and the

51Linux sandbox implementation when you run in WSL2.

52 

53On **Linux and WSL2**, install `bubblewrap` with your package manager first:

54 

55```bash

56sudo apt install bubblewrap

57```

58 

59```bash

60sudo dnf install bubblewrap

61```

62 

63Codex uses the system `bwrap` at `/usr/bin/bwrap` when it is available. If it

64is missing, Codex falls back to a bundled helper, but that helper requires

65unprivileged user namespaces. Installing your distro’s `bubblewrap` package is

66the most reliable setup.

67 

68Codex surfaces a startup warning when `bwrap` is missing or cannot create user

69namespaces. On distributions that restrict them with AppArmor, you can enable

70them with:

71 

72```bash

73sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

74```

75 

39## How you control it76## How you control it

40 77 

41Most people start with the permissions controls in the product.78Most people start with the permissions controls in the product.

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

16 16 

17```toml17```toml

18model = "gpt-5-codex"18model = "gpt-5.4"

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

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

21 21 

132Define additional providers and point `model_provider` at them:132Define additional providers and point `model_provider` at them:

133 133 

134```toml134```toml

135model = "gpt-5.1"135model = "gpt-5.4"

136model_provider = "proxy"136model_provider = "proxy"

137 137 

138[model_providers.proxy]138[model_providers.proxy]

91| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |91| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |

92| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |92| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |

93| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |93| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

94| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |94| `model` | `string` | Model to use (e.g., `gpt-5.4`). |

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

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

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

1194 1194 

1195Details1195Details

1196 1196 

1197Model to use (e.g., `gpt-5-codex`).1197Model to use (e.g., `gpt-5.4`).

1198 1198 

1199Key1199Key

1200 1200 

350# hide_rate_limit_model_nudge = true350# hide_rate_limit_model_nudge = true

351# hide_gpt5_1_migration_prompt = true351# hide_gpt5_1_migration_prompt = true

352# "hide_gpt-5.1-codex-max_migration_prompt" = true352# "hide_gpt-5.1-codex-max_migration_prompt" = true

353# model_migrations = { "gpt-4.1" = "gpt-5.1" }353# model_migrations = { "gpt-5.3-codex" = "gpt-5.4" }

354 354 

355################################################################################355################################################################################

356# Centralized Feature Flags (preferred)356# Centralized Feature Flags (preferred)

2 2 

3# Running Codex as an MCP server3# Running Codex as an MCP server

4 4 

5You can run Codex as an MCP server and connect it from other MCP clients (for example, an agent built with the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/guides/mcp/)).5You can run Codex as an MCP server and connect it from other MCP clients (for example, an agent built with the [OpenAI Agents SDK MCP integration](https://developers.openai.com/api/docs/guides/agents/integrations-observability#mcp)).

6 6 

7To start Codex as an MCP server, you can use the following command:7To start Codex as an MCP server, you can use the following command:

8 8 

20 20 

21## Adjust reasoning effort21## Adjust reasoning effort

22 22 

23You can adjust reasoning effort to control how long Codex thinks before responding. Higher effort can help on complex tasks, but responses take longer. Higher effort also uses more tokens and can consume your rate limits faster (especially with GPT-5-Codex).23You can adjust reasoning effort to control how long Codex thinks before responding. Higher effort can help on complex tasks, but responses take longer. Higher effort also uses more tokens and can consume your rate limits faster, especially with higher-capability models.

24 24 

25Use the same model switcher shown above, and choose `low`, `medium`, or `high` for each model. Start with `medium`, and only switch to `high` when you need more depth.25Use the same model switcher shown above, and choose `low`, `medium`, or `high` for each model. Start with `medium`, and only switch to `high` when you need more depth.

26 26 

107 107 

108## Alternative models108## Alternative models

109 109 

110![gpt-5.2-codex](/images/codex/gpt-5.2-codex.png)

111 

112gpt-5.2-codex

113 

114Advanced coding model for real-world engineering. Succeeded by GPT-5.3-Codex.

115 

116codex -m gpt-5.2-codex

117 

118Copy command

119 

120Show details

121 

122![gpt-5.2](/images/api/models/gpt-5.2.jpg)110![gpt-5.2](/images/api/models/gpt-5.2.jpg)

123 111 

124gpt-5.2112gpt-5.2

125 113 

126Previous general-purpose model for coding and agentic tasks across industries and domains. Succeeded by GPT-5.4.114Previous general-purpose model for coding and agentic tasks, including hard debugging tasks that benefit from deeper deliberation.

127 115 

128codex -m gpt-5.2116codex -m gpt-5.2

129 117 

131 119 

132Show details120Show details

133 121 

134![gpt-5.1-codex-max](/images/api/models/gpt-5.1-codex-max.jpg)

135 

136gpt-5.1-codex-max

137 

138Optimized for long-horizon, agentic coding tasks in Codex.

139 

140codex -m gpt-5.1-codex-max

141 

142Copy command

143 

144Show details

145 

146![gpt-5.1](/images/api/models/gpt-5.1.jpg)

147 

148gpt-5.1

149 

150Great for coding and agentic tasks across domains. Succeeded by GPT-5.2.

151 

152codex -m gpt-5.1

153 

154Copy command

155 

156Show details

157 

158![gpt-5.1-codex](/images/api/models/gpt-5.1-codex.jpg)

159 

160gpt-5.1-codex

161 

162Optimized for long-running, agentic coding tasks in Codex. Succeeded by GPT-5.1-Codex-Max.

163 

164codex -m gpt-5.1-codex

165 

166Copy command

167 

168Show details

169 

170![gpt-5-codex](/images/api/models/gpt-5-codex.jpg)

171 

172gpt-5-codex

173 

174Version of GPT-5 tuned for long-running, agentic coding tasks. Succeeded by GPT-5.1-Codex.

175 

176codex -m gpt-5-codex

177 

178Copy command

179 

180Show details

181 

182![gpt-5-codex-mini](/images/api/models/gpt-5-codex.jpg)

183 

184gpt-5-codex-mini

185 

186Smaller, more cost-effective version of GPT-5-Codex. Succeeded by GPT-5.1-Codex-Mini.

187 

188codex -m gpt-5-codex

189 

190Copy command

191 

192Show details

193 

194![gpt-5](/images/api/models/gpt-5.jpg)

195 

196gpt-5

197 

198Reasoning model for coding and agentic tasks across domains. Succeeded by GPT-5.1.

199 

200codex -m gpt-5

201 

202Copy command

203 

204Show details

205 

206## Other models122## Other models

207 123 

208Codex works best with the models listed above.124When you sign in with ChatGPT, Codex works best with the models listed above.

209 125 

210You can also point Codex at any model and provider that supports either the [Chat Completions](https://platform.openai.com/docs/api-reference/chat) or [Responses APIs](https://platform.openai.com/docs/api-reference/responses) to fit your specific use case.126You can also point Codex at any model and provider that supports either the [Chat Completions](https://platform.openai.com/docs/api-reference/chat) or [Responses APIs](https://platform.openai.com/docs/api-reference/responses) to fit your specific use case.

211 127 

1# Quickstart1# Quickstart

2 2 

3ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Using Codex with your ChatGPT subscription gives you access to the latest Codex models and features.3Every ChatGPT plan includes Codex.

4 4 

5You can also use Codex with API credits by signing in with an OpenAI API key.5You can also use Codex with API credits by signing in with an OpenAI API key.

6 6 

7For a limited time, **try Codex for free in ChatGPT Free and Go**, or enjoy

8**2x Codex rate limits** with Plus, Pro, Business and Enterprise

9subscriptions.

10 

11## Setup7## Setup

12 8 

13The Codex app is available on macOS (Apple Silicon).9The Codex app is available on macOS (Apple Silicon).