OpenAI - Codex Docs Changes

agent-approvals-security.md +16 −9

Details

121approvals_reviewer = "auto_review"121approvals_reviewer = "auto_review"

122```122```

123 123

124For the full reviewer lifecycle, trigger conditions, configuration precedence,

125and failure behavior, see

126[Auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review).

127

124The reviewer evaluates only actions that already need approval, such as sandbox128The reviewer evaluates only actions that already need approval, such as sandbox

125escalations, network requests, `request_permissions` prompts, or side-effecting129escalations, blocked network requests, `request_permissions` prompts, or

126app and MCP tool calls. Actions that stay inside the sandbox continue without an130side-effecting app and MCP tool calls. Actions that stay inside the sandbox

127extra review step.131continue without an extra review step.

128 132

129The reviewer policy checks for data exfiltration, credential probing, persistent133The reviewer policy checks for data exfiltration, credential probing, persistent

130security weakening, and destructive actions. Low-risk and medium-risk actions134security weakening, and destructive actions. Low-risk and medium-risk actions

131can proceed when policy allows them. The policy denies critical-risk actions.135can proceed when policy allows them. The policy denies critical-risk actions.

132High-risk actions require enough user authorization and no matching deny rule.136High-risk actions require enough user authorization and no matching deny rule.

133Timeouts, parse failures, and review errors fail closed.137Prompt-build, review-session, and parse failures fail closed. Timeouts are

138surfaced separately, but the action still does not run.

134 139

135The [default reviewer policy](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md)140The [default reviewer policy](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md)

136is in the open-source Codex repository. Enterprises can replace its141is in the open-source Codex repository. Enterprises can replace its

139take precedence. For setup details, see144take precedence. For setup details, see

140[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-automatic-review-policy).145[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-automatic-review-policy).

141 146

142In the Codex app, these reviews appear as automatic review items with a status such147In the Codex app, these reviews appear as automatic review items with a status

143as Reviewing, Approved, Denied, Stopped, or Timed out. They can also include a148such as Reviewing, Approved, Denied, Aborted, or Timed out. They can also

144risk level for the reviewed request.149include a risk level and user-authorization assessment for the reviewed

150request.

145 151

146Automatic review uses extra model calls, so it can add to Codex usage. Admins152Automatic review uses extra model calls, so it can add to Codex usage. Admins

147can constrain it with `allowed_approvals_reviewers`.153can constrain it with `allowed_approvals_reviewers`.

148 154

149### Common sandbox and approval combinations155### Common sandbox and approval combinations

150 156

152| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |158| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |

153| Auto (preset) | _no flags needed_ or `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |159| Auto (preset) | _no flags needed_ or `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |

154| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |160| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |

156| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |162| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |

163| Auto-review mode | `--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review` or `approvals_reviewer = "auto_review"` | Same sandbox boundary as standard on-request mode, but eligible approval requests are reviewed by Auto-review instead of surfacing to the user. |

158 165

159For non-interactive runs, use `codex exec --sandbox workspace-write`; Codex keeps older `codex exec --full-auto` invocations as a deprecated compatibility path and prints a warning.166For non-interactive runs, use `codex exec --sandbox workspace-write`; Codex keeps older `codex exec --full-auto` invocations as a deprecated compatibility path and prints a warning.

app.md +8 −0

Details

139 139

140Keep parallel code changes isolated with built-in Git worktree support.140Keep parallel code changes isolated with built-in Git worktree support.

141 141

142 </BentoContent>

143 <BentoContent href="/codex/remote-connections">

144

145### Remote connections

146

147Use the ChatGPT mobile app to start, steer, approve, and review Codex work on a

148connected host.

149

142 </BentoContent>150 </BentoContent>

143 <BentoContent href="/codex/app/computer-use">151 <BentoContent href="/codex/app/computer-use">

144 152

app/chrome-extension.md +3 −2

Details

28 28

291. Open Codex and go to **Plugins**.291. Open Codex and go to **Plugins**.

302. Add the **Chrome** plugin.302. Add the **Chrome** plugin.

~~313. Follow the setup flow. It guides you through installing or connecting the~~313. Follow the setup flow. It guides you through installing the [Codex Chrome

~~32 Chrome extension and approving Chrome's permission prompts.~~32 extension](https://chromewebstore.google.com/detail/codex/hehggadaopoacecdllhhajmbjkdcmajg)

33 and approving Chrome's permission prompts.

334. Open Chrome and confirm the Codex extension shows **Connected**.344. Open Chrome and confirm the Codex extension shows **Connected**.

34 35

35After the plugin setup is complete, start a new Codex thread. Codex can suggest36After the plugin setup is complete, start a new Codex thread. Codex can suggest

auth.md +15 −1

Details

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

31Codex uses standard API pricing instead.31Codex uses standard API pricing instead.

32 32

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

34as CI/CD jobs. Don't expose Codex execution in untrusted or public environments.

36### Use Codex access tokens for enterprise automation

38In ChatGPT Enterprise workspaces, admins can allow permitted members to create

39Codex access tokens for trusted, non-interactive Codex local workflows. Use an

40access token when automation needs ChatGPT workspace access, ChatGPT-managed

41Codex entitlements, or enterprise workspace controls without a browser sign-in.

43Access tokens are intended for trusted scripts, schedulers, and private CI

44runners. For general OpenAI API calls, continue to use Platform API keys.

46For setup steps, permissions, rotation, and revocation guidance, see

47[Access tokens](https://developers.openai.com/codex/enterprise/access-tokens).

34 48

35## Secure your Codex cloud account49## Secure your Codex cloud account

36 50

concepts/sandboxing.md +21 −15

Details

126the composer or chat input. That selector lets you rely on Codex's default126the composer or chat input. That selector lets you rely on Codex's default

127permissions, switch to full access, or use your custom configuration.127permissions, switch to full access, or use your custom configuration.

128 128

129<div class="not-prose max-w-[22rem] mr-auto mb-6">129<PermissionModeSelectorDemo client:load />

130 <img src="https://developers.openai.com/images/codex/app/permissions-selector-light.webp"

131 alt="Codex app permissions selector showing Default permissions, Full access, and Custom (config.toml)"

132 class="block h-auto w-full mx-0!"

133 />

134</div>

135 130

136In the CLI, use [`/permissions`](https://developers.openai.com/codex/cli/slash-commands#update-permissions-with-permissions)131In the CLI, use [`/permissions`](https://developers.openai.com/codex/cli/slash-commands#update-permissions-with-permissions)

137to switch modes during a session.132to switch modes during a session.

142configuration. Codex stores those defaults in `config.toml`, its local settings137configuration. Codex stores those defaults in `config.toml`, its local settings

143file. [Config basics](https://developers.openai.com/codex/config-basic) explains how it works, and the138file. [Config basics](https://developers.openai.com/codex/config-basic) explains how it works, and the

144[Configuration reference](https://developers.openai.com/codex/config-reference) documents the exact keys for139[Configuration reference](https://developers.openai.com/codex/config-reference) documents the exact keys for

145`sandbox_mode`, `approval_policy`, and140`sandbox_mode`, `approval_policy`, `approvals_reviewer`, and

146`sandbox_workspace_write.writable_roots`. Use those settings to decide how much141`sandbox_workspace_write.writable_roots`. Use those settings to decide how much

147autonomy Codex gets by default, which directories it can write to, and when it142autonomy Codex gets by default, which directories it can write to, when it

148should pause for approval.143should pause for approval, and who reviews eligible approval requests.

149 144

150At a high level, the common sandbox modes are:145At a high level, the common sandbox modes are:

151 146

166 needs to go beyond that boundary.161 needs to go beyond that boundary.

167- `never`: Codex doesn't stop for approval prompts.162- `never`: Codex doesn't stop for approval prompts.

168 163

164When approvals are interactive, you can also choose who reviews them with

165`approvals_reviewer`:

166

167- `user`: approval prompts surface to the user. This is the default.

168- `auto_review`: eligible approval prompts go to a reviewer agent (see

169 [Auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review)).

170

169Full access means using `sandbox_mode = "danger-full-access"` together with171Full access means using `sandbox_mode = "danger-full-access"` together with

170`approval_policy = "never"`. By contrast, the lower-risk local automation172`approval_policy = "never"`. By contrast, the lower-risk local automation

171preset is `sandbox_mode = "workspace-write"` together with173preset is `sandbox_mode = "workspace-write"` together with

172`approval_policy = "on-request"`, or the matching CLI flags174`approval_policy = "on-request"`, or the matching CLI flags

173`--sandbox workspace-write --ask-for-approval on-request`.175`--sandbox workspace-write --ask-for-approval on-request`. You can then keep

176`approvals_reviewer = "user"` for manual approvals or set

177`approvals_reviewer = "auto_review"` for automatic approval review.

174 178

175If you need Codex to work across more than one directory, writable roots let179If you need Codex to work across more than one directory, writable roots let

176you extend the places it can modify without removing the sandbox entirely. If180you extend the places it can modify without removing the sandbox entirely. If

193[Codex app features](https://developers.openai.com/codex/app/features#approvals-and-sandboxing), and for the197[Codex app features](https://developers.openai.com/codex/app/features#approvals-and-sandboxing), and for the

194IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).198IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).

195 199

196Automatic review, when available, doesn't change the sandbox boundary. It200Automatic review, when available, does not change the sandbox boundary. It is

197reviews approval requests, such as sandbox escalations or network access, while201one possible `approvals_reviewer` for approval requests at that boundary, such

198actions already allowed inside the sandbox run without extra review. See202as sandbox escalations, blocked network access, or side-effecting tool calls

199[Automatic approval reviews](https://developers.openai.com/codex/agent-approvals-security#automatic-approval-reviews)203that still need approval. Actions already allowed inside the sandbox run

200for the policy behavior.204without extra review. For the reviewer lifecycle, trigger types, denial

205semantics, and configuration details, see

206[Auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review).

201 207

202Platform details live in the platform-specific docs. For native Windows setup,208Platform details live in the platform-specific docs. For native Windows setup,

203behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin209behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin

concepts/sandboxing/auto-review.md +165 −0 added

Details

1# Auto-review

3Auto-review replaces manual approval at the sandbox boundary with a separate

4reviewer agent. The main Codex agent still runs inside the same sandbox, with

5the same approval policy and the same network and filesystem limits. The

6difference is who reviews eligible escalation requests.

8Auto-review only applies when approvals are interactive. In practice, that

9 means `approval_policy = "on-request"` or a granular approval policy that

10 still surfaces the relevant prompt category. With `approval_policy = "never"`,

11 there is nothing to review.

13## How auto-review works

15At a high level, the flow is:

171. The main agent works inside `read-only` or `workspace-write`.

182. When it needs to cross the sandbox boundary, it requests approval.

193. If `approvals_reviewer = "auto_review"`, Codex routes that approval request

20 to a separate reviewer agent instead of stopping for a person.

214. The reviewer decides whether the action should run and returns a rationale.

225. If the action is approved, execution continues. If it is denied, the main

23 agent is instructed to find a materially safer path or stop and ask the

24 user.

26Auto-review is a reviewer swap, not a permission grant. It does not expand

27`writable_roots`, enable network access, or weaken protected paths. It only

28changes how Codex handles actions that already need approval.

30## When it triggers

32Auto-review evaluates approval requests that would otherwise pause for a human.

33These include:

35- Shell or exec tool calls that request escalated sandbox permissions.

36- Network requests blocked by the current sandbox or policy.

37- File edits outside the allowed writable roots.

38- MCP or app tool calls that require approval based on their tool annotations

39 or configured approval mode.

40- Browser Use access to a new website or domain.

42Auto-review does not run for routine actions already allowed inside the

43sandbox. If a command can run under the active `sandbox_mode`, or a tool call

44stays within the allowed policy, the main agent continues without review.

46Computer Use is a separate case. App approvals for Computer Use still surface

47directly to the user, so Auto-review does not replace those app-level prompts.

49## What auto-review blocks

51At a high level, Auto-review is designed to block actions such as:

53- sending private data, secrets, or credentials to untrusted destinations

54- probing for credentials, tokens, cookies, or session material

55- broad or persistent security weakening

56- destructive actions with significant risk of irreversible damage

58The exact policy lives in the open-source Codex repository:

59[policy_template.md](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy_template.md)

60and

61[policy.md](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md).

62That policy can be customized per enterprise with `guardian_policy_config` or

63per user with local [`[auto_review].policy`](/codex/config-advanced#approval-policies-and-sandbox-modes).

65## What the reviewer sees

67The reviewer is itself a Codex agent with a narrower job than the main agent:

68decide whether a specific boundary-crossing action should run.

70The reviewer sees a compact transcript plus the exact approval request. That

71typically includes user messages, surfaced assistant updates, relevant tool

72calls and tool outputs, and the action now being proposed for approval. It can

73also perform read-only checks to gather missing context, but it does so rarely.

75Hidden assistant reasoning is not included. Auto-review sees retained

76conversation items and tool evidence, not private chain-of-thought.

78## Denials and failure behavior

80An explicit denial is not treated like an ordinary sandbox error. Codex returns

81the review rationale to the main agent and adds a stronger instruction:

83- Do not pursue the same outcome via workaround, indirect execution, or policy

84 circumvention.

85- Continue only with a materially safer alternative.

86- Otherwise, stop and ask the user.

88Codex also applies a rejection circuit breaker per turn. In the current

89open-source implementation, Auto-review interrupts the turn after `3`

90consecutive denials or `10` denials within a rolling window of the last `50`

91reviews in the same turn.

93Any non-denial resets the consecutive-denial counter. When the breaker trips,

94Codex emits a warning and aborts the current turn with an interrupt rather than

95letting the agent loop on more escalation attempts.

97Timeouts are surfaced separately from explicit denials, and the main agent is

98informed that a timeout alone is not proof that the action is unsafe.

100There is also an explicit override path for denied actions. In the current

101open-source TUI, run `/approve` to open the **Auto-review Denials** picker, then

102select one recent denied action to approve for one retry. Codex records up to 10

103recent denials per thread. That approval is narrow: it applies to the exact

104denied action, not similar future actions; it is recorded for one retry in the

105same context; and the retry still goes through Auto-review. Under the hood,

106Codex injects a developer-scoped approval marker for that exact action. The

107reviewer then sees that explicit user override as context, but it still follows

108policy and can deny again if policy says the user cannot overwrite that class of

109denial.

110

111## Configuration

112

113For setup details, see

114[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-automatic-review-policy).

115

116The default reviewer policy is in the open-source Codex repository:

117[core/src/guardian/policy.md](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md).

118Enterprises can replace its tenant-specific section with

119`guardian_policy_config` in managed requirements. Individual users can also set

120a local

121[`[auto_review].policy`](/codex/config-advanced#approval-policies-and-sandbox-modes)

122in their `config.toml`, but managed requirements take precedence:

123

124```toml

125[auto_review]

126policy = """

127YOUR POLICY GOES HERE

128"""

129```

130

131To customize the policy, copy the whole default policy wording first, then

132iterate based on your individual risk profile.

133

134## Reduce review volume without weakening security

135

136Auto-review works best when the sandbox already covers your common safe

137workflows. If too many mundane actions need review, fix the boundary first

138instead of teaching the reviewer to approve noisy escalations forever.

139

140In practice, the highest-leverage changes are:

141

142- Add narrow

143 [`writable_roots`](https://developers.openai.com/codex/config-advanced#approval-policies-and-sandbox-modes)

144 for scratch directories or neighboring repos you intentionally use.

145- Add narrowly scoped [prefix rules](https://developers.openai.com/codex/rules). Prefer precise command

146 prefixes such as `["cargo", "test"]` or `["pnpm", "run", "lint"]` over broad

147 patterns such as `["python"]` or `["curl"]`. Broad rules often erase the very

148 boundary Auto-review is meant to guard.

149

150Auto-review session transcripts are retained under `~/.codex/sessions` by

151default, so you can ask Codex to analyze past traffic there before changing

152policy or permissions.

153

154## Limits

155

156Auto-review improves the default operating point for long-running agentic work,

157but it is not a deterministic security guarantee.

158

159- It only evaluates actions that ask to cross a boundary.

160- It can still make mistakes, especially in adversarial or unusual contexts.

161- It should complement, not replace, good sandbox design, monitoring, and

162 organization-specific policy.

163

164For the research rationale and published evaluation results, see the

165[Alignment Research post on Auto-review](https://alignment.openai.com/auto-review/).

concepts/subagents.md +8 −9

Details

66If you don't pin a model or `model_reasoning_effort`, Codex can choose a setup66If you don't pin a model or `model_reasoning_effort`, Codex can choose a setup

67that balances intelligence, speed, and price for the task. It may favor67that balances intelligence, speed, and price for the task. It may favor

68`gpt-5.4-mini` for fast scans or a higher-effort `gpt-5.5` configuration for68`gpt-5.4-mini` for fast scans or a higher-effort `gpt-5.5` configuration for

~~69more demanding reasoning when that model is available. When you want finer~~69more demanding reasoning. When you want finer control, steer that choice in

~~70control, steer that choice in your prompt or set `model` and~~70your prompt or set `model` and

71`model_reasoning_effort` directly in the agent file.71`model_reasoning_effort` directly in the agent file.

72 72

~~73For most tasks in Codex, start with `gpt-5.5` when it is available. Continue~~73For most tasks in Codex, start with `gpt-5.5`. Use `gpt-5.4-mini` when you

~~74 using `gpt-5.4` during the rollout if `gpt-5.5` is not yet available. Use~~74 want a faster, lower-cost option for lighter subagent work. If you have

~~75 `gpt-5.4-mini` when you want a faster, lower-cost option for lighter subagent~~75 ChatGPT Pro and want near-instant text-only iteration, `gpt-5.3-codex-spark`

~~76 work. If you have ChatGPT Pro and want near-instant text-only iteration,~~76 remains available in research preview.

~~77 `gpt-5.3-codex-spark` remains available in research preview.~~

78 77

79### Model choice78### Model choice

80 79

81- **`gpt-5.5`**: Start here for demanding agents when it is available. It is strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.80- **`gpt-5.5`**: Start here for demanding agents. It is strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.

~~82- **`gpt-5.4`**: Use this when `gpt-5.5` is not yet available or when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.~~81- **`gpt-5.4`**: Use this when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.

83- **`gpt-5.4-mini`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.82- **`gpt-5.4-mini`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.

84- **`gpt-5.3-codex-spark`**: If you have ChatGPT Pro, use this research preview model for near-instant, text-only iteration when latency matters more than broader capability.83- **`gpt-5.3-codex-spark`**: If you have ChatGPT Pro, use this research preview model for near-instant, text-only iteration when latency matters more than broader capability.

85 84

config-basic.md +1 −0

Details

170| Key | Default | Maturity | Description |170| Key | Default | Maturity | Description |

171| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |171| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

config-reference.md +7 −1

Details

208 key: "commit_attribution",208 key: "commit_attribution",

209 type: "string",209 type: "string",

210 description:210 description:

211 "Override the commit co-author trailer text. Set an empty string to disable automatic attribution.",211 'Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex <noreply@openai.com>`; set `""` to disable.',

212 },212 },

213 {213 {

214 key: "model_instructions_file",214 key: "model_instructions_file",

330 description:330 description:

331 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.",331 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.",

332 },332 },

333 {

334 key: "features.codex_git_commit",

335 type: "boolean",

336 description:

337 "Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages.",

338 },

333 {339 {

334 key: "hooks",340 key: "hooks",

335 type: "table",341 type: "table",

config-sample.md +4 −1

Details

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

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

85 85

~~86# Override the default commit co-author trailer. Set to "" to disable it.~~86# Override the default commit co-author trailer. This only takes effect when

87# [features].codex_git_commit is enabled. When enabled and unset, Codex uses

88# "Codex <noreply@openai.com>". Set to "" to disable it.

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

88 90

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

398# Leave this table empty to accept defaults. Set explicit booleans to opt in/out.400# Leave this table empty to accept defaults. Set explicit booleans to opt in/out.

399# shell_tool = true401# shell_tool = true

400# apps = false402# apps = false

403# codex_git_commit = false

401# codex_hooks = false404# codex_hooks = false

402# unified_exec = true405# unified_exec = true

403# shell_snapshot = true406# shell_snapshot = true

enterprise/access-tokens.md +144 −0 added

Details

1# Access tokens

3Codex access tokens let trusted automation run Codex local with a ChatGPT workspace identity. Use them when a script, scheduled job, or CI runner needs repeatable, non-interactive Codex access.

5Codex access tokens are currently supported for ChatGPT Business and

6 Enterprise workspaces.

8Access tokens are created in the ChatGPT admin console at [Access tokens](https://chatgpt.com/admin/access-tokens). They are tied to the ChatGPT user and workspace that create them, and Codex uses them as agent identities for programmatic local workflows.

10If a Platform API key works for your automation, keep using API key auth. Use

11 Codex access tokens when the workflow specifically needs ChatGPT workspace

12 access, ChatGPT-managed Codex entitlements, or enterprise workspace controls.

14## How access tokens work

16Use an access token when Codex needs to run without a user completing a browser sign-in. The token represents the ChatGPT workspace user who created it, so runs can use that user's Codex access and appear in workspace governance data.

18Codex checks the token when a run starts and ties the run to that workspace identity. Treat the token like any other automation secret: store it in a secret manager, keep it out of logs, and rotate it regularly.

20Use access tokens for:

22- `codex exec` jobs that run from trusted automation.

23- Local scripts that need repeatable, non-interactive Codex runs.

24- Enterprise workflows where usage should be associated with a ChatGPT workspace user instead of an API organization key.

26Main risks to avoid:

28- **Leaked secrets:** anyone with the token can start Codex runs as the token creator. Store tokens in a secret manager, keep them out of logs, and rotate them regularly.

29- **Untrusted runners:** public CI, forked pull requests, or shared machines can expose tokens to people outside your workspace. Use access tokens only on trusted runners.

30- **Shared identities:** one person's token reused across unrelated teams makes ownership and audit trails harder to interpret. Create tokens for a specific workflow owner.

31- **Stale credentials:** long-lived tokens can remain active after the workflow changes. Prefer finite expirations and revoke tokens that are no longer used.

32- **Wrong credential type:** access tokens are for Codex local workflows. Use Platform API keys for general OpenAI API calls.

34## Enable access token creation

36Use the Codex Local controls in workspace settings to turn on access token creation for allowed members.

38<CodexScreenshot

39 alt="Access token access permission in ChatGPT workspace RBAC settings"

40 lightSrc="/images/codex/enterprise/rbac_access_token_access_permission.png"

41 darkSrc="/images/codex/enterprise/rbac_access_token_access_permission_dark.png"

42 maxWidth={847}

43 variant="no-wallpaper"

44/>

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

472. In the Codex Local section, make sure **Allow members to use Codex Local** is turned on.

483. Turn on **Allow members to use Codex access tokens** if all allowed members should be able to create access tokens.

494. If you use custom roles for a narrower rollout, assign the access token permission only to groups that need to create tokens.

51Keep access token creation limited to people or service owners who understand where the token will be stored, which automation will use it, and how it will be rotated.

53## Create an access token

55Use the Access tokens page to name the token and choose when it expires.

571. Go to [Access tokens](https://chatgpt.com/admin/access-tokens).

582. Select **Create**.

60<CodexScreenshot

61 alt="Access tokens page with the Create button"

62 lightSrc="/images/codex/enterprise/access_token_create_header.png"

63 darkSrc="/images/codex/enterprise/access_token_create_header_dark.png"

64 maxWidth={942}

65 variant="no-wallpaper"

66/>

683. Enter a descriptive name, such as `release-ci` or `nightly-docs-check`.

70<CodexScreenshot

71 alt="Create access token modal with fields for name and expiration"

72 lightSrc="/images/codex/enterprise/access_token_creation_modal.png"

73 darkSrc="/images/codex/enterprise/access_token_creation_modal_dark.png"

74 maxWidth={544}

75 variant="no-wallpaper"

76/>

784. Choose an expiration. Prefer a finite expiration such as 7, 30, 60, or 90 days. If you choose **No expiration**, rotate the token on a regular schedule.

795. Select **Create**.

806. Copy the generated access token immediately. You cannot view it again after you close the modal.

817. Store the token in your secret manager or CI secret store.

83The shortest custom expiration is one day. Revoked and expired tokens cannot be used to start new Codex runs.

85## Use an access token with Codex CLI

87For ephemeral automation, store the token in `CODEX_ACCESS_TOKEN` and run Codex normally:

89```bash

90export CODEX_ACCESS_TOKEN="<access-token>"

91codex exec --json "review this repository and summarize the top risks"

92```

94For a persistent local login, pipe the token to `codex login --with-access-token`:

96```bash

97printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token

98codex exec "summarize the last release diff"

99```

100

101`codex login --with-access-token` stores an agent identity credential in Codex auth storage. If you prefer not to persist credentials on the machine, use the `CODEX_ACCESS_TOKEN` environment variable instead.

102

103## Rotate or revoke a token

104

105Rotate access tokens the same way you rotate other automation secrets:

106

1071. Create a replacement token.

1082. Update the secret in the runner, scheduler, or secret manager.

1093. Run a smoke test with the new token.

1104. Revoke the old token from [Access tokens](https://chatgpt.com/admin/access-tokens).

111

112From the Access tokens page, workspace owners and admins can revoke any workspace token. Members with access token permission can revoke only the tokens they created.

113

114## Permission model

115

116Access token permissions are separate from the general Codex local permission. A member can have access to the Codex app, CLI, or IDE extension without being allowed to create access tokens.

117

119| ------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------- | -------------------------------------- |

120| Open [Access tokens](https://chatgpt.com/admin/access-tokens) | Yes | Yes | No |

121| Create access tokens | Yes, for their own ChatGPT workspace identity | Yes, for their own ChatGPT workspace identity | No |

122| List access tokens | Workspace list, including who created each token | Only tokens they created | No |

124| Grant or remove access token permission | Yes | No | No |

125| Manage other Codex enterprise settings | Yes, based on admin role and Codex admin permissions | No, unless separately granted | No |

126

127In short: workspace owners and admins manage access at the workspace level. Members need the access token permission to create and manage their own tokens, but the permission does not grant admin rights or access to other members' tokens.

128

129## Troubleshooting

130

131### The access tokens page returns 404 or forbidden

132

133Ask a workspace owner or admin to confirm that Codex access tokens are enabled and that your role includes the access token permission.

134

135### `codex login --with-access-token` fails

136

137Confirm that you copied the generated access token, not a browser session token or Platform API key. Also confirm that the token has not expired or been revoked.

138

139## Related docs

140

141- [Authentication](https://developers.openai.com/codex/auth)

142- [Non-interactive mode](https://developers.openai.com/codex/noninteractive)

143- [Admin setup](https://developers.openai.com/codex/enterprise/admin-setup)

144- [Governance](https://developers.openai.com/codex/enterprise/governance)

enterprise/admin-setup.md +4 −2

Details

11 11

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

13 13

14Use this page as the step-by-step rollout guide. For detailed policy, configuration, and monitoring details, use the linked pages: [Authentication](https://developers.openai.com/codex/auth), [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security), [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), and [Governance](https://developers.openai.com/codex/enterprise/governance).14Use this page as the step-by-step rollout guide. For detailed policy, configuration, automation, and monitoring details, use the linked pages: [Authentication](https://developers.openai.com/codex/auth), [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security), [Access tokens](https://developers.openai.com/codex/enterprise/access-tokens), [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), and [Governance](https://developers.openai.com/codex/enterprise/governance).

15 15

16## Enterprise-grade security and privacy16## Enterprise-grade security and privacy

17 17

59 59

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

61 61

~~62If this toggle is off, users who attempt to use the Codex app, CLI, or IDE will see the following error: “403 - Unauthorized. Contact your ChatGPT administrator for access.”~~62If members need programmatic Codex local workflows, also turn on **Allow members to use Codex access tokens** or grant the access token permission through a custom role. For setup and permission details, see [Access tokens](https://developers.openai.com/codex/enterprise/access-tokens).

64If the Codex Local toggle is off, users who attempt to use the Codex app, CLI, or IDE will see the following error: “403 - Unauthorized. Contact your ChatGPT administrator for access.”

63 65

64#### Enable device code authentication for Codex CLI66#### Enable device code authentication for Codex CLI

65 67

enterprise/governance.md +39 −32

Details

15## Analytics Dashboard15## Analytics Dashboard

16 16

17<div class="max-w-1xl mx-auto">17<div class="max-w-1xl mx-auto">

~~18 <img src="https://developers.openai.com/images/codex/enterprise/analytics.png"~~18 <img src="https://developers.openai.com/images/codex/enterprise/analytics-dashboard.png"

19 alt="Codex analytics dashboard"19 alt="Codex analytics dashboard"

~~20 class="block w-full mx-auto rounded-lg"~~20 class="block w-full mx-auto rounded-lg !border-0"

21 />21 />

22</div>22</div>

23 23

~~24### Dashboards~~24### Dashboard views

25 25

~~26The [analytics dashboard](https://chatgpt.com/codex/settings/analytics) allows ChatGPT workspace administrators to track feature adoption.~~26The [analytics dashboard](https://chatgpt.com/codex/cloud/settings/analytics#usage) allows ChatGPT workspace administrators and analytics viewers to track Codex adoption, usage, and Code Review feedback. Usage data can lag by up to 12 hours.

27 27

~~28Codex provides the following dashboards:~~28Codex provides date-range controls for daily and weekly views. Key charts include:

29 29

~~30- Daily users by product (CLI, IDE, cloud, Code Review)~~30- Active users by product surface, including CLI, IDE extension, cloud, desktop, and Code Review

~~31- Daily code review users~~31- Workspace and personal usage breakdowns, including credit and token usage by product surface

~~32- Daily code reviews~~32- Product activity for threads and turns by client

~~33- Code reviews by priority level~~33- User ranking table, with filters for client and sort options such as credits, threads, turns, text tokens, and current streak

~~34- Daily code reviews by feedback sentiment~~34- Code Review activity, including PRs reviewed, issues by priority, comments, replies, reactions, and feedback sentiment

~~35- Daily cloud tasks~~35- Skill invocations, agent identity usage, and access token usage when your workspace has those features

~~36- Daily cloud users~~

~~37- Daily VS Code extension users~~

~~38- Daily CLI users~~

39 36

40### Data export37### Data export

41 38

42Administrators can also export Codex analytics data in CSV or JSON format. Codex provides the following export options:39Administrators can also export Codex analytics data in CSV or JSON format. Codex provides the following export options:

43 40

~~44- Code review users and reviews (Daily unique users and total reviews completed in Code Review)~~41- Workspace usage, including daily active users, threads, turns, and credits by surface

~~45- Code review findings and feedback (Daily counts of comments, reactions, replies, and priority-level findings)~~42- Usage per user, including daily threads, turns, and credits across surfaces, with optional email addresses when allowed

~~46- cloud users and tasks (daily unique cloud users and tasks completed)~~43- Code Review details, including daily comments, reactions, replies, and priority-level findings

~~47- CLI and VS Code users (Daily unique users for the Codex CLI and VS Code extension)~~

~~48- Sessions and messages per user (Daily session starts and user message counts for each Codex user across surfaces)~~

49 44

50## Analytics API45## Analytics API

51 46

~~52Use the [Analytics API](https://chatgpt.com/codex/settings/apireference) when you want to automate reporting, build internal dashboards, or join Codex metrics with your existing engineering data.~~47Use the [Analytics API](https://chatgpt.com/codex/cloud/settings/apireference) when you want to automate reporting, build internal dashboards, or join Codex metrics with your existing engineering data.

53 48

54### What it measures49### What it measures

55 50

~~56The Analytics API provides daily, time-series metrics for a workspace, with optional per-user breakdowns and per-client usage.~~51The enterprise Analytics API returns daily or weekly UTC buckets for a workspace. It supports workspace-level and per-user usage, per-client breakdowns, Code Review throughput, Code Review comment priority, and user engagement with Code Review comments.

57 52

58### Endpoints53### Endpoints

59 54

~~60#### Daily usage and adoption~~55The base URL is `https://api.chatgpt.com/v1/analytics/codex`. All endpoints return paginated `page` objects with `has_more` and `next_page`.

61 56

~~62- Daily totals for threads, turns, and credits~~57Use `start_time` for the inclusive Unix timestamp at the beginning of the reporting window, `end_time` for the exclusive Unix timestamp at the end of the reporting window, `group_by` for `day` or `week` buckets, `limit` for page size, and `page` to continue from a previous response. Requests can look back up to 90 days.

~~63- Breakdown by client surface~~58

~~64- Optional per-user reporting for adoption and power-user analysis~~59#### Usage

61`GET /workspaces/{workspace_id}/usage`

63- Returns totals for threads, turns, credits, and per-client usage in daily or weekly buckets.

64- Omit `group` to return per-user rows.

65- Set `group=workspace` to return workspace-wide rows.

66- Includes text input, cached input, and output token fields.

65 67

66#### Code review activity68#### Code review activity

67 69

~~68- Pull request reviews completed by Codex~~70`GET /workspaces/{workspace_id}/code_reviews`

~~69- Total comments generated by Codex~~71

~~70- Severity breakdown of comments~~72- Returns pull request reviews completed by Codex.

73- Returns total comments generated by Codex.

74- Breaks comments down by P0, P1, and P2 priority.

71 75

72#### User engagement with code review76#### User engagement with code review

73 77

~~74- Replies to Codex comments~~78`GET /workspaces/{workspace_id}/code_review_responses`

~~75- Reactions, including upvotes and downvotes~~79

~~76- Engagement breakdowns for how teams respond to Codex feedback~~80- Returns replies and reactions to Codex comments.

81- Breaks reactions down into positive, negative, and other reactions.

82- Counts comments that received reactions, replies, or either form of engagement.

77 83

78### How it works84### How it works

79 85

80Analytics is daily and time-windowed. Results are time-ordered and returned in pages with cursor-based pagination. You can query by workspace and optionally group by user or aggregate at the workspace level.86Analytics uses time windows and supports day or week grouping. Results are time-ordered and returned in pages with cursor-based pagination. Use an API key scoped to `codex.enterprise.analytics.read`.

81 87

82### Common use cases88### Common use cases

83 89

109Use record metadata to answer questions like:115Use record metadata to answer questions like:

110 116

111- Who ran a task117- Who ran a task

118- Who created or revoked an access token

112- When it ran119- When it ran

113- Which model was used120- Which model was used

114- How much content was processed121- How much content was processed

models.md +5 −7

Details

37 value: false,37 value: false,

38 },38 },

39 { title: "ChatGPT Credits", value: true },39 { title: "ChatGPT Credits", value: true },

~~40 { title: "API Access", value: false },~~40 { title: "API Access", value: true },

41 ],41 ],

42 }}42 }}

43 />43 />

205For most tasks in Codex, start with `gpt-5.5` when it appears in your model205For most tasks in Codex, start with `gpt-5.5` when it appears in your model

206 picker. It is strongest for complex coding, computer use, knowledge work, and206 picker. It is strongest for complex coding, computer use, knowledge work, and

207 research workflows. GPT-5.5 is currently available in Codex when you sign in207 research workflows. GPT-5.5 is currently available in Codex when you sign in

208 with ChatGPT; it isn't available with API-key authentication. During the208 with ChatGPT or API-key authentication. Use `gpt-5.4-mini` when you want a

209 rollout, continue using `gpt-5.4` if `gpt-5.5` is not yet available. Use209 faster, lower-cost option for lighter coding tasks or subagents. The

210 `gpt-5.4-mini` when you want a faster, lower-cost option for lighter coding210 `gpt-5.3-codex-spark` model is available in research preview for ChatGPT Pro

211 tasks or subagents. The `gpt-5.3-codex-spark` model is available in research211 subscribers and is optimized for near-instant, real-time coding iteration.

212 preview for ChatGPT Pro subscribers and is optimized for near-instant,

213 real-time coding iteration.

214 212

215## Alternative models213## Alternative models

216 214

remote-connections.md +215 −21

Details

1# Remote connections1# Remote connections

2 2

~~3SSH remote connections are currently in alpha. To enable them today, set~~3import {

~~4 `remote_connections = true` in the `[features]` table in~~4 Desktop,

~~5 `~/.codex/config.toml`. Availability, setup flows, and supported environments~~5 Storage,

~~6 may change as the feature improves.~~6 Terminal,

7} from "@components/react/oai/platform/ui/Icon.react";

7 8

~~8Remote connections let Codex work with projects that live on another~~9Remote connections let you use Codex when you are away from the machine that

~~9SSH-accessible machine. Use them when the codebase, credentials, services, or~~10runs it, or when your project lives on another machine. Connect the ChatGPT

~~10build environment you need are available on that host instead of your local~~11mobile app to a Codex App host, pick up work from another device, or configure

~~11machine.~~12Codex to work on an SSH host.

14Remote access uses the connected host's projects, threads, files, credentials,

15permissions, plugins, Computer Use, browser setup, and local tools.

17## What you can do remotely

19- Start new threads in projects on the host, or continue existing ones.

20- Send follow-up instructions, answer questions, and steer active work.

21- Approve commands and other actions.

22- Review outputs, diffs, test results, terminal output, and screenshots.

23- Get notified when Codex completes a task or needs your attention.

24- Switch between connected hosts and threads.

26The next sections cover using the ChatGPT mobile app to control a Codex App

27host. To connect Codex to a project on an SSH host, see

28[connect to an SSH host](#connect-to-an-ssh-host).

30<div class="not-prose my-6 max-w-4xl rounded-xl bg-[url('/images/codex/codex-wallpaper-1.webp')] bg-cover bg-center p-4 md:p-8">

31 <CodexScreenshot

32 alt="Codex mobile setup screen alongside the ChatGPT mobile Codex project list"

33 lightSrc="/images/codex/app/mobile-setup-light.webp"

34 darkSrc="/images/codex/app/mobile-setup-dark.webp"

35 variant="no-wallpaper"

36 maxHeight="none"

37 maxWidth="420px"

38 />

39</div>

41## Before you set up mobile access

43Make sure you have:

45- Codex access in the ChatGPT account and workspace you want to use.

46- The latest ChatGPT mobile app on an iOS or Android device. If you do not see

47 Codex in the app, update ChatGPT first.

48- A Mac host that is awake, online, running the Codex App, and signed in to the

49 same account and workspace. Mobile setup and device control currently require

50 the Codex App for macOS on the host; the setup flow isn't available from the

51 Codex CLI or IDE Extension.

52- Any required multi-factor authentication, SSO, or passkey configuration for

53 that account or workspace.

55If you use Codex through a ChatGPT workspace, your admin may need to enable

56Remote Control access before you can connect from your phone.

58## Set up mobile access

60Start in the Codex App on the host you want to connect. The setup flow enables

61remote access for that host, then shows a QR code you can scan from your phone.

63<WorkflowSteps variant="headings">

651. Start Codex mobile setup.

67 Open Codex on the host and select **Set up Codex mobile** in the

68 sidebar.

702. Scan the QR code.

72 Use your phone to scan the QR code shown by Codex. The code opens ChatGPT so

73 you can finish connecting the mobile app to the host.

753. Finish setup in ChatGPT.

77 ChatGPT opens the Codex mobile setup flow. Confirm the same ChatGPT account

78 and workspace, then complete any required multi-factor authentication, SSO,

79 or passkey steps. After setup succeeds, the host appears in Codex on your

80 phone.

824. Review host settings.

84 In Codex on the host, use **Settings > Connections** to manage connected

85 devices. You can also choose whether to keep the computer awake, enable

86 Computer Use, or install the Chrome extension.

88</WorkflowSteps>

90<div class="not-prose my-6 max-w-4xl">

91 <CodexScreenshot

92 alt="Connections settings showing devices that can control this Mac and remote access settings"

93 lightSrc="/images/codex/app/mobile-control-this-mac-framed-light.webp"

94 darkSrc="/images/codex/app/mobile-control-this-mac-framed-dark.webp"

95 maxHeight="480px"

96 class="p-3 sm:p-4"

97 imageClass="rounded-xl"

98 />

99</div>

100

101## Choose what to connect

102

103Start with the Mac laptop or desktop where you already use Codex. Add an

104always-on Mac or SSH host when you need continuous access or a different

105environment.

106

107### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Desktop width={17} height={17} /></span><span>Your Mac laptop or desktop</span></span>

108

109Connect the Mac where you already run Codex day to day. This gives remote access

110to the same projects, threads, credentials, plugins, and local setup you already

111use.

112

113If that Mac sleeps, loses network access, or closes Codex, remote access stops

114until it is available again. If you use this computer as your host device, keep

115it plugged in and turn on **Keep this Mac awake** in the host's connection

116settings.

117

118### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Storage width={17} height={17} /></span><span>A dedicated always-on Mac</span></span>

119

120Use a dedicated always-on Mac when you want Codex to stay reachable for

121longer-running work.

122

123Install the projects, credentials, plugins, MCP servers, and tools Codex should

124use on that machine.

125

126### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Terminal width={17} height={17} /></span><span>A remote development environment</span></span>

127

128Use an SSH host or managed devbox when the project already lives in a remote

129environment. Connect the Codex App host to that environment first; your phone

130still connects to the Codex App host, and Codex works in the remote environment

131with its dependencies, security policies, and compute resources.

132

133For SSH setup details, see [connect to an SSH host](#connect-to-an-ssh-host).

134

135## What comes from the connected host

136

137Your phone sends prompts, approvals, and follow-up messages to Codex. The

138connected host provides the environment Codex uses.

139

140That means:

141

142- Repository files and local documents come from the connected host.

143- Shell commands run on that host or remote environment.

144- Any plugin installed on that host is available when you use Codex remotely.

145- MCP servers, skills, browser access, and Computer Use come from that host's

146 configuration.

147- Signed-in websites and desktop apps are available only when the host can

148 access them.

149- Sandboxing, security controls, and action approvals still apply to the

150 connected session.

151

152Codex uses a secure relay layer to keep trusted machines reachable across your

153authorized ChatGPT devices without exposing them directly to the public

154internet.

155

156## Pick up work from another device

157

158You can also connect one Codex App host to another. For example, if your laptop

159is unavailable, you can start a thread from your phone on an always-on host,

160then later open Codex on your laptop and continue that thread from there.

161

162In Codex on the laptop, use **Settings > Connections > Control other devices**

163to add the other host. A device can allow remote access and control another

164device at the same time.

165

166<div class="not-prose my-6 max-w-4xl">

167 <CodexScreenshot

168 alt="Connections settings showing another device available under Control other devices"

169 lightSrc="/images/codex/app/mobile-control-other-devices-framed-light.webp"

170 darkSrc="/images/codex/app/mobile-control-other-devices-framed-dark.webp"

171 maxHeight="360px"

172 class="p-3 sm:p-4"

173 imageClass="rounded-xl"

174 />

175</div>

176

177## Connect to an SSH host

178

179In the Codex App, add remote projects from an SSH host and run threads against

180the remote filesystem and shell. Remote project threads run commands, read

181files, and write changes on the remote host.

12 182

13Keep the remote host configured with the same security expectations you use for183Keep the remote host configured with the same security expectations you use for

14normal SSH access: trusted keys, least-privilege accounts, and no184normal SSH access: trusted keys, least-privilege accounts, and no

15unauthenticated public listeners.185unauthenticated public listeners.

16 186

~~17## Codex app~~

~~19In the Codex app, add remote projects from an SSH host and run threads against~~

~~20the remote filesystem and shell.~~

22<WorkflowSteps variant="headings">187<WorkflowSteps variant="headings">

23 188

241. Add the host to your SSH config so Codex can auto-discover it.1891. Add the host to your SSH config so Codex can auto-discover it.

33 Codex reads concrete host aliases from `~/.ssh/config`, resolves them with198 Codex reads concrete host aliases from `~/.ssh/config`, resolves them with

34 OpenSSH, and ignores pattern-only hosts.199 OpenSSH, and ignores pattern-only hosts.

35 200

~~362. Confirm you can SSH to the host from the machine running the Codex app.~~2012. Confirm you can SSH to the host from the machine running the Codex App.

37 202

38 ```bash203 ```bash

39 ssh devbox204 ssh devbox

45 user's login shell. Make sure the `codex` command is available on the210 user's login shell. Make sure the `codex` command is available on the

46 remote host's `PATH` in that shell.211 remote host's `PATH` in that shell.

47 212

~~484. In the Codex app, open **Settings > Connections**, add or enable the SSH host,~~2134. In the Codex App, open **Settings > Connections**, add or enable the SSH

~~49 then choose a remote project folder.~~214 host, then choose a remote project folder.

50 215

51</WorkflowSteps>216</WorkflowSteps>

52 217

58remote_connections = true223remote_connections = true

59```224```

60 225

~~61Remote project threads run commands, read files, and write changes on the~~

~~62remote host.~~

64<CodexScreenshot226<CodexScreenshot

65 alt="Codex app settings showing SSH remote connections"227 alt="Codex app settings showing SSH remote connections"

66 lightSrc="/images/codex/app/remote-connections-light.webp"228 lightSrc="/images/codex/app/remote-connections-light.webp"

67 darkSrc="/images/codex/app/remote-connections-dark.webp"229 darkSrc="/images/codex/app/remote-connections-dark.webp"

68 maxHeight="420px"230 maxHeight="420px"

~~69 variant="no-wallpaper"~~231 class="p-3 sm:p-4"

232 imageClass="rounded-xl"

70/>233/>

71 234

72## Authentication and network exposure235## Authentication and network exposure

78mesh networking tool such as Tailscale instead of exposing the app server241mesh networking tool such as Tailscale instead of exposing the app server

79directly to the internet.242directly to the internet.

80 243

244## Troubleshooting

245

246### You do not see the host on your phone

247

248Confirm that the Codex App is running on the host, **Allow other devices to

249connect** is enabled, and the same ChatGPT account and workspace are selected on

250both devices.

251

252### The approval request does not appear

253

254Open the ChatGPT mobile app and go to Codex. Confirm that the phone and host use

255the same ChatGPT account and workspace, then scan the QR code again or restart

256setup from the host. If you use a ChatGPT workspace, ask your admin to confirm

257that Remote Control access is enabled.

258

259### The remote session disconnects

260

261Check whether the host went to sleep, lost network access, or closed Codex.

262Keep the host awake and connected while Codex works.

263

264### Authentication blocks setup

265

266Complete the account or workspace authentication prompt shown during setup. If

267your organization requires SSO, multi-factor authentication, or a passkey,

268finish that flow before trying again. If setup still fails, ask your workspace

269admin to confirm that Remote Control access is enabled.

270

81## See also271## See also

82 272

~~83- [Codex app settings](https://developers.openai.com/codex/app/settings)~~273- [Codex App](https://developers.openai.com/codex/app)

274- [Codex App features](https://developers.openai.com/codex/app/features)

275- [Codex App settings](https://developers.openai.com/codex/app/settings)

276- [Computer Use](https://developers.openai.com/codex/app/computer-use)

277- [Chrome extension](https://developers.openai.com/codex/app/chrome-extension)

84- [Command line options](https://developers.openai.com/codex/cli/reference)278- [Command line options](https://developers.openai.com/codex/cli/reference)

85- [Authentication](https://developers.openai.com/codex/auth)279- [Authentication](https://developers.openai.com/codex/auth)

OpenAI - Codex Docs Changes 2026-05-07 20:02 UTC → 2026-05-14 21:00 UTC