Documentation 2026-05-20 00:58 UTC to 2026-05-21 18:44 UTC

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

64connected host.](https://developers.openai.com/codex/remote-connections)[### Computer use64connected host.](https://developers.openai.com/codex/remote-connections)[### Computer use

65 65 

66Let Codex use macOS apps for GUI tasks, browser flows, and native app testing.](https://developers.openai.com/codex/app/computer-use)[### Review and ship changes66Let Codex use macOS apps for GUI tasks, browser flows, and native app testing.](https://developers.openai.com/codex/app/computer-use)[### Appshots

67 

68Send the frontmost Mac app window to Codex with a screenshot and available text.](https://developers.openai.com/codex/appshots)[### Review and ship changes

67 69 

68Inspect diffs, address PR feedback, stage files, commit, and push.](https://developers.openai.com/codex/app/review)[### Terminal and actions70Inspect diffs, address PR feedback, stage files, commit, and push.](https://developers.openai.com/codex/app/review)[### Terminal and actions

69 71 

244- `thread/turns/items/list` - reserved for paged turn-item loading; currently returns unsupported.244- `thread/turns/items/list` - reserved for paged turn-item loading; currently returns unsupported.

245- `thread/loaded/list` - list the thread ids currently loaded in memory.245- `thread/loaded/list` - list the thread ids currently loaded in memory.

246- `thread/name/set` - set or update a thread’s user-facing name for a loaded thread or a persisted rollout; emits `thread/name/updated`.246- `thread/name/set` - set or update a thread’s user-facing name for a loaded thread or a persisted rollout; emits `thread/name/updated`.

247- `thread/goal/set` - set the goal for a loaded thread (experimental; requires `capabilities.experimentalApi`); emits `thread/goal/updated`.247- `thread/goal/set` - set the goal for a thread; emits `thread/goal/updated`.

248- `thread/goal/get` - read the current goal for a loaded thread (experimental; requires `capabilities.experimentalApi`).248- `thread/goal/get` - read the current goal for a thread.

249- `thread/goal/clear` - clear the goal for a loaded thread (experimental; requires `capabilities.experimentalApi`); emits `thread/goal/cleared`.249- `thread/goal/clear` - clear the goal for a thread; emits `thread/goal/cleared`.

250- `thread/metadata/update` - patch SQLite-backed stored thread metadata; currently supports persisted `gitInfo`.250- `thread/metadata/update` - patch SQLite-backed stored thread metadata; currently supports persisted `gitInfo`.

251- `thread/archive` - move a thread’s log file into the archived directory; returns `{}` on success and emits `thread/archived`.251- `thread/archive` - move a thread’s log file into the archived directory; returns `{}` on success and emits `thread/archived`.

252- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread after a no-subscriber inactivity grace period and emits `thread/closed`.252- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread after a no-subscriber inactivity grace period and emits `thread/closed`.

444 444 

445### Manage a thread goal445### Manage a thread goal

446 446 

447`thread/goal/set`, `thread/goal/get`, and `thread/goal/clear` are experimental447Use `thread/goal/set`, `thread/goal/get`, and `thread/goal/clear` to manage the

448and require `capabilities.experimentalApi = true` plus the `goals` feature. Use448same persisted goal state surfaced by `/goal` in the TUI.

449them for the same persisted goal state surfaced by `/goal` in the TUI.

450 449 

451```450```

452{ "method": "thread/goal/set", "id": 13, "params": {451{ "method": "thread/goal/set", "id": 13, "params": {

25 25 

26Browser use lets Codex operate the in-app browser directly. Use it for local26Browser use lets Codex operate the in-app browser directly. Use it for local

27development servers and file-backed previews when Codex needs to click, type,27development servers and file-backed previews when Codex needs to click, type,

28inspect rendered state, take screenshots, or verify a fix in the page.28inspect rendered state, take screenshots, download page assets, run read-only

29page inspection JavaScript, or verify a fix in the page.

29 30 

30To use it, install and enable the Browser plugin. Then ask Codex to use the31To use it, install and enable the Browser plugin. Then ask Codex to use the

31browser in your task, or reference it directly with `@Browser`. The app keeps32browser in your task, or reference it directly with `@Browser`. The app keeps

67When a bug is visible only in the rendered page, use browser comments to give68When a bug is visible only in the rendered page, use browser comments to give

68Codex precise feedback on the page.69Codex precise feedback on the page.

69 70 

70- Turn on comment mode, select an element or area, and submit a comment.71- Turn on Annotation mode, select an element or area, and submit a comment.

71- In comment mode, hold `Shift` and click to select an area.72- In Annotation mode, hold `Shift` and click to select an area.

72- Hold `Cmd` while clicking to send a comment immediately.73- Hold `Cmd` while clicking to send a comment immediately.

73 74 

74After you leave comments, send a message in the thread asking Codex to address75After you leave comments, send a message in the thread asking Codex to address

86it stays inside the chart bounds.87it stays inside the chart bounds.

87```88```

88 89 

90### Styling feedback

91 

92When you add an annotation to a section on the page, press the config icon next

93to the text input to give Codex more granular style feedback. You can change

94values like font, text, spacing, and color, preview the result directly on the

95page, and then send the annotation so Codex has a clearer target for the change.

96 

97![Codex app showing in-app browser annotation style controls](/images/codex/app/iab-annotations-light.webp)

98 

89## Keep browser tasks scoped99## Keep browser tasks scoped

90 100 

91The in-app browser is for review and iteration. Keep each browser task small101The in-app browser is for review and iteration. Keep each browser task small

43| Slash command | Description |43| Slash command | Description |

44| --- | --- |44| --- | --- |

45| `/feedback` | Open the feedback dialog to submit feedback and optionally include logs. |45| `/feedback` | Open the feedback dialog to submit feedback and optionally include logs. |

46| `/goal` | Set a persistent goal for Codex to work toward; use `/plan` first to shape it. |

46| `/mcp` | Open MCP status to view connected servers. |47| `/mcp` | Open MCP status to view connected servers. |

47| `/plan-mode` | Toggle plan mode for multi-step planning. |48| `/plan` | Toggle plan mode for multi-step planning. |

48| `/review` | Start code review mode to review uncommitted changes or compare against a base branch. |49| `/review` | Start code review mode to review uncommitted changes or compare against a base branch. |

49| `/status` | Show the thread ID, context usage, and rate limits. |50| `/status` | Show the thread ID, context usage, and rate limits. |

50 51 

52### Set or manage a goal with `/goal`

53 

54Use `/goal` in the app composer to start Goal mode. A goal is a persistent

55objective that Codex works toward until it finishes the task, pauses, or needs

56more input. To define the goal with Codex first, start with `/plan`, then set

57the refined goal with `/goal`.

58 

59![Codex app goal progress controls above the composer](/images/codex/app/goal-dialog-light.webp)

60 

61When a goal is active, the app shows its progress above the composer. Use the

62buttons in that progress row to pause or resume the goal, edit the goal text, or

63clear the goal instead of typing another slash command. You can keep steering

64Codex with follow-up messages while the goal runs.

65 

66For guidance on writing effective goals, see [Goal mode](https://developers.openai.com/codex/prompting#goal-mode).

67 

51## Deeplinks68## Deeplinks

52 69 

53The Codex app registers the `codex://` URL scheme so links can open specific parts of the app directly.70The Codex app registers the `codex://` URL scheme so links can open specific parts of the app directly.

87Security** and check **Screen Recording** and **Accessibility** for the Codex87Security** and check **Screen Recording** and **Accessibility** for the Codex

88app.88app.

89 89 

90## Locked use

91 

92Locked computer use lets Codex use Computer Use after your Mac locks, but only

93after you enable it. Use it when a Codex task needs to use desktop apps from a

94connected device after the Mac locks.

95 

96When you enable locked computer use, Codex installs an Apple

97[authorization plug-in](https://developer.apple.com/documentation/security/authorization-plug-ins)

98that participates in the macOS unlock flow.

99 

100Locked use is intentionally narrow. It’s not a general-purpose remote-unlock

101path for your Mac, and it doesn’t let other apps or local processes unlock the

102computer.

103 

104To use locked computer use:

105 

1061. Open **Codex settings > Computer Use**.

1072. Enable locked computer use.

1083. Start a task that uses computer use from a connected device after your Mac’s

109 screen has locked.

110 

111When a Codex task accesses an app via Computer Use after your Mac locks, Codex

112temporarily unlocks the Mac while blocking local use and preserving the locked

113screen protections. Before unlocking, Codex checks whether the unlock attempt is

114for an active, trusted computer use turn. Outside that short-lived window, Codex

115denies the unlock and asks you to unlock manually if needed.

116 

117Locked use includes safeguards:

118 

119- The authorization window is short-lived and scoped to the current unlock

120 attempt.

121- Automatic unlock is available only to Codex during active computer use turns.

122- Codex covers every display while the desktop is temporarily unlocked.

123- If Codex detects local keyboard or pointer input, it relocks the Mac and

124 pauses automatic unlock until you unlock it manually.

125 

90## Safety guidance126## Safety guidance

91 127 

92With computer use, Codex can view screen content, take screenshots, and interact128With computer use, Codex can view screen content, take screenshots, and interact

1# Appshots – Codex

2 

3Appshots let you send the frontmost app window to a Codex thread. Use them when

4you’re actively working in another app on your computer and want to provide

5Codex with your current context so it can help you with the task.

6 

7Appshots are available in the Codex app on macOS. Press both Command keys, or

8your custom Appshots hotkey, to take one.

9 

10## What appshots capture

11 

12An appshot captures the frontmost window only. It can include:

13 

14- An image of the visible window.

15- Available text from that window, including visible text and text the app makes

16 available outside the visible scroll area.

17 

18After you add an appshot to a thread, it behaves like a Codex attachment. Codex

19stores appshots locally in the session file, like files or images you attach

20manually.

21 

22## When to use appshots

23 

24Use appshots when Codex needs context from a Mac app before it can act.

25 

26Examples:

27 

28- Share an API reference page and ask Codex to write a script that uses it.

29- Share an email or calendar view and ask Codex to draft the next step.

30- Share an image editor, design, or preview window and ask Codex to revise the

31 related assets or code.

32- Share an error, settings panel, or app state that’s easier to show than

33 describe.

34 

35## Take an appshot

36 

371. Open the Codex app on your Mac.

382. Open the app and window you want to share.

393. Press both Command keys, or the custom hotkey you configured in Codex

40 settings.

414. Allow macOS permissions if Codex asks.

425. Ask Codex to perform a task with the appshot.

43 

44By default, Codex starts a new thread for the appshot. If you interacted with a

45Codex thread in the last 60 seconds, Codex adds the appshot to that recent

46thread instead. Taking consecutive appshots adds them to the same thread.

47 

48You can change the Appshots hotkey in Codex settings.

49 

50## Permissions and safety

51 

52Codex may ask for permissions before it can take appshots:

53 

54- **Screen & System Audio Recording** lets Codex capture an image of the

55 frontmost window.

56- **Accessibility** lets Codex read available text from the frontmost window.

57 

58Taking an appshot shares the captured image and available text with Codex.

59Avoid taking appshots of sensitive content unless the task requires that

60content.

61 

62Review appshots the same way you would review sharing screenshots and documents

63with Codex.

64 

65## Limits and troubleshooting

66 

67Appshots are a Codex app feature. Create them from the Codex app on macOS. If

68you resume a thread in the CLI that already contains an appshot, the attachment

69is part of the thread history, but the CLI can’t create a new appshot.

70 

71For some apps and websites, including Google Docs, Gmail, Google Sheets, and

72Google Slides, Codex may receive only the visible screenshot and may not receive

73the full document or off-screen text. If you have the matching plugin installed,

74Codex can use that plugin to access the relevant app content and help with your

75request.

76 

77If appshots don’t work:

78 

791. Open **System Settings > Privacy & Security**.

802. Check **Screen & System Audio Recording** and **Accessibility** for Codex

81 Computer Use.

823. Restart Codex and try again.

83 

101 101 

102## Models and reasoning102## Models and reasoning

103 103 

104For most tasks in Codex, `gpt-5.5` is the recommended model when it’s104For most tasks in Codex, `gpt-5.5` is the recommended model. It is OpenAI’s newest frontier model for complex coding, computer

105available. It’s OpenAI’s newest frontier model for complex coding, computer

106use, knowledge work, and research workflows, with stronger planning, tool use,105use, knowledge work, and research workflows, with stronger planning, tool use,

107and follow-through on multi-step tasks. If `gpt-5.5` isn’t yet available,106and follow-through on multi-step tasks. For extra fast tasks, ChatGPT Pro subscribers have

108continue using `gpt-5.4`. For extra fast tasks, ChatGPT Pro subscribers have

109access to the GPT-5.3-Codex-Spark model in research preview.107access to the GPT-5.3-Codex-Spark model in research preview.

110 108 

111Switch models mid-session with the `/model` command, or specify one when launching the CLI.109Switch models mid-session with the `/model` command, or specify one when launching the CLI.

50| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between general-purpose models (`gpt-4.1-mini`) and deeper reasoning models before running a task. |50| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between general-purpose models (`gpt-4.1-mini`) and deeper reasoning models before running a task. |

51| [`/fast`](#toggle-fast-mode-with-fast) | Toggle a Fast service tier when the model catalog exposes one. | Turn the current model’s Fast tier on or off, or check whether the thread is using it. |51| [`/fast`](#toggle-fast-mode-with-fast) | Toggle a Fast service tier when the model catalog exposes one. | Turn the current model’s Fast tier on or off, or check whether the thread is using it. |

52| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |52| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |

53| [`/goal`](#set-or-view-an-experimental-task-goal-with-goal) | Set, pause, resume, view, or clear a task goal. | Give Codex a persistent target to track while a larger task runs. Requires `features.goals`. |53| [`/goal`](#set-or-view-an-experimental-task-goal-with-goal) | Set, pause, resume, view, or clear a task goal. | Give Codex a persistent target to track while a larger task runs. Requires experimental `features.goals`. |

54| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |54| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |

55| [`/ps`](#check-background-terminals-with-ps) | Show experimental background terminals and their recent output. | Check long-running commands without leaving the main transcript. |55| [`/ps`](#check-background-terminals-with-ps) | Show experimental background terminals and their recent output. | Check long-running commands without leaving the main transcript. |

56| [`/stop`](#stop-background-terminals-with-stop) | Stop all background terminals. | Cancel background terminal work started by the current session. |56| [`/stop`](#stop-background-terminals-with-stop) | Stop all background terminals. | Cancel background terminal work started by the current session. |

124 124 

125While a task is already running, `/plan` is temporarily unavailable.125While a task is already running, `/plan` is temporarily unavailable.

126 126 

127### Set an experimental goal with `/goal`127### Set or view an experimental task goal with `/goal`

128 128 

129`/goal` is experimental and only available when `features.goals` is enabled. To enable it, open `/experimental` or add `goals = true` under `[features]` in `config.toml`.129`/goal` is experimental. Codex shows it only after you enable `features.goals`.

130To enable it, open `/experimental` or add `goals = true` under `[features]` in

131`config.toml`.

130 132 

1311. Type `/goal <objective>` to set the goal, for example `/goal Finish the migration and keep tests green`.1331. Type `/goal <objective>` to set the goal, for example `/goal Finish the migration and keep tests green`.

1322. Type `/goal` to view the current goal.1342. Type `/goal` to view the current goal.

64Different agents need different model and reasoning settings.64Different agents need different model and reasoning settings.

65 65 

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 `gpt-5.4-mini` for fast scans or a higher-effort `gpt-5.5` configuration for more demanding reasoning. When you want finer control, steer that choice in your prompt or set `model` and `model_reasoning_effort` directly in the agent file.

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

69more demanding reasoning. When you want finer control, steer that choice in69For most tasks in Codex, start with

70your prompt or set `model` and70`gpt-5.5`. Use

71`model_reasoning_effort` directly in the agent file.71`gpt-5.4-mini` when you want

72 72a faster, lower-cost option for lighter subagent work. If you have ChatGPT Pro

73For most tasks in Codex, start with `gpt-5.5`. Use `gpt-5.4-mini` when you73and want near-instant text-only iteration, `gpt-5.3-codex-spark` remains

74want a faster, lower-cost option for lighter subagent work. If you have74available in research preview.

75ChatGPT Pro and want near-instant text-only iteration, `gpt-5.3-codex-spark`

76remains available in research preview.

77 75 

78### Model choice76### Model choice

79 77 

3429| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |3429| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

3430| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |3430| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |

3431| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |3431| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |

3432| `plugin_sharing` | `boolean` | Set to `false` in cloud-managed `requirements.toml` to disable workspace sharing for locally built plugins. |

3432| `remote_sandbox_config` | `array<table>` | Host-specific sandbox requirements. The first entry whose `hostname_patterns` match the resolved host name overrides top-level `allowed_sandbox_modes` for that requirements source. Host-specific entries currently override sandbox modes only. |3433| `remote_sandbox_config` | `array<table>` | Host-specific sandbox requirements. The first entry whose `hostname_patterns` match the resolved host name overrides top-level `allowed_sandbox_modes` for that requirements source. Host-specific entries currently override sandbox modes only. |

3433| `remote_sandbox_config[].allowed_sandbox_modes` | `array<string>` | Allowed sandbox modes to apply when this host-specific entry matches. |3434| `remote_sandbox_config[].allowed_sandbox_modes` | `array<string>` | Allowed sandbox modes to apply when this host-specific entry matches. |

3434| `remote_sandbox_config[].hostname_patterns` | `array<string>` | Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character. |3435| `remote_sandbox_config[].hostname_patterns` | `array<string>` | Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character. |

3838 3839 

3839Key3840Key

3840 3841 

3842`plugin_sharing`

3843 

3844Type / Values

3845 

3846`boolean`

3847 

3848Details

3849 

3850Set to `false` in cloud-managed `requirements.toml` to disable workspace sharing for locally built plugins.

3851 

3852Key

3853 

3841`remote_sandbox_config`3854`remote_sandbox_config`

3842 3855 

3843Type / Values3856Type / Values

13Use the snippet below as a reference. Copy only the keys and sections you need into `~/.codex/config.toml` (or into a project-scoped `.codex/config.toml`), then adjust values for your setup.13Use the snippet below as a reference. Copy only the keys and sections you need into `~/.codex/config.toml` (or into a project-scoped `.codex/config.toml`), then adjust values for your setup.

14 14 

15```15```

161

172

183

194

205

216

227

238

249

2510

2611

2712

2813

2914

3015

3116

3217

3318

3419

3520

3621

3722

3823

3924

4025

4126

4227

4328

4429

4530

4631

4732

4833

4934

5035

5136

5237

5338

5439

5540

5641

5742

5843

5944

6045

6146

6247

6348

6449

6550

6651

6752

6853

6954

7055

7156

7257

7358

7459

7560

7661

7762

7863

7964

8065

8166

8267

8368

8469

8570

8671

8772

8873

8974

9075

9176

9277

9378

9479

9580

9681

9782

9883

9984

10085

10186

10287

10388

10489

10590

10691

10792

10893

10994

11095

11196

11297

11398

11499

115100

116101

117102

118103

119104

120105

121106

122107

123108

124109

125110

126111

127112

128113

129114

130115

131116

132117

133118

134119

135120

136121

137122

138123

139124

140125

141126

142127

143128

144129

145130

146131

147132

148133

149134

150135

151136

152137

153138

154139

155140

156141

157142

158143

159144

160145

161146

162147

163148

164149

165150

166151

167152

168153

169154

170155

171156

172157

173158

174159

175160

176161

177162

178163

179164

180165

181166

182167

183168

184169

185170

186171

187172

188173

189174

190175

191176

192177

193178

194179

195180

196181

197182

198183

199184

200185

201186

202187

203188

204189

205190

206191

207192

208193

209194

210195

211196

212197

213198

214199

215200

216201

217202

218203

219204

220205

221206

222207

223208

224209

225210

226211

227212

228213

229214

230215

231216

232217

233218

234219

235220

236221

237222

238223

239224

240225

241226

242227

243228

244229

245230

246231

247232

248233

249234

250235

251236

252237

253238

254239

255240

256241

257242

258243

259244

260245

261246

262247

263248

264249

265250

266251

267252

268253

269254

270255

271256

272257

273258

274259

275260

276261

277262

278263

279264

280265

281266

282267

283268

284269

285270

286271

287272

288273

289274

290275

291276

292277

293278

294279

295280

296281

297282

298283

299284

300285

301286

302287

303288

304289

305290

306291

307292

308293

309294

310295

311296

312297

313298

314299

315300

316301

317302

318303

319304

320305

321306

322307

323308

324309

325310

326311

327312

328313

329314

330315

331316

332317

333318

334319

335320

336321

337322

338323

339324

340325

341326

342327

343328

344329

345330

346331

347332

348333

349334

350335

351336

352337

353338

354339

355340

356341

357342

358343

359344

360345

361346

362347

363348

364349

365350

366351

367352

368353

369354

370355

371356

372357

373358

374359

375360

376361

377362

378363

379364

380365

381366

382367

383368

384369

385370

386371

387372

388373

389374

390375

391376

392377

393378

394379

395380

396381

397382

398383

399384

400385

401386

402387

403388

404389

405390

406391

407392

408393

409394

410395

411396

412397

413398

414399

415400

416401

417402

418403

419404

420405

421406

422407

423408

424409

425410

426411

427412

428413

429414

430415

431416

432417

433418

434419

435420

436421

437422

438423

439424

440425

441426

442427

443428

444429

445430

446431

447432

448433

449434

450435

451436

452437

453438

454439

455440

456441

457442

458443

459444

460445

461446

462447

463448

464449

465450

466451

467452

468453

469454

470455

471456

472457

473458

474459

475460

476461

477462

478463

479464

480465

481466

482467

483468

484469

485470

486471

487472

488473

489474

490475

491476

492477

493478

494479

495480

496481

497482

498483

499484

500485

501486

502487

503488

504489

505490

506491

507492

508493

509494

510495

511496

512497

513498

514499

515500

516501

517502

518503

519504

520505

521506

522507

523508

524509

525510

526511

527512

528513

529514

530515

531516

532517

533518

534519

535520

536521

537522

538523

539524

540525

541526

542527

543528

544529

545530

546531

547532

548533

549534

550535

551536

552537

553538

554539

555540

556541

557542

558543

559544

560545

561546

562547

563548

564549

565550

566551

567552

568553

569554

570555

571556

572557

573558

574559

575560

576561

577562

578563

579564

580565

581566

582567

583568

584569

585570

586571

587572

588573

589574

590575

591576

592577

593578

594579

595580

596581

597582

598583

599584

600585

601586

602587

603588

604589

605590

606591

607592

608593

609594

610595

611596

612597

613598

614599

615600

616601

617602

618603

619604

620605

621606

622607

623608

624609

625610

626611

627612

628613

629614

630615

631616

632617

633618

634619

635620

636621

637622

638623

639624

640625

641626

642627

643628

644629

645630

646631

647632

648633

649634

650635

651636

652637

653638

654639

655640

656641

657642

658643

659644

660645

661646

662647

663648

664649

665650

666651

667652

668653

669654

670655

671656

672657

673658

674659

675660

676661

677662

678663

679664

680665

681666

682667

683668

684669

685670

686671

687672

688673

689674

690675

691676

692677

693678

694679

695680

696681

697682

698683

699684

700685

701686

702687

703688

704689

705690

706691

707692

708693

709694

710695

711696

712697

713698

714699

715700

716701

717702

718703

719704

720705

721706

722707

723708

724709

725710

726711

727712

728713

729714

730715

731716

732717

733718

734719

735720

736721

737722

738723

739724

740725

741726

742727

743728

744729

745730

746731

747732

748733

749734

750735

751736

752737

753738

754739

755740

756741

757742

758743

759744

760745

761746

762747

763748

764749

765750

766751

767752

768753

769754

770755

771756

772757

773758

774759

775760

776761

777762

778763

779764

780765

781766

782767

783768

784769

785770

786771

787772

788773

789774

790775

791776

792777

793778

794779

795780

796781

797782

798783

799784

800785

801786

802787

803788

804789

805790

806791

807792

808793

809794

810795

811796

812797

813798

814799

815800

816801

817802

818803

819804

820805

821806

822807

823808

824809

825810

826811

827812

828813

829814

830815

831816

832817

833818

834819

835820

836821

837822

838823

839824

840825

841826

842827

843828

844829

845830

846831

847832

848833

849834

850835

851836

852837

853838

854839

855840

856841

857842

858843

859844

860845

861846

862847

863848

864849

865850

866851

867852

868853

869854

870855

871856

872857

873858

874859

875860

876861

877862

878863

879864

880865

881866

882867

883868

884869

885870

886871

887872

888873

889874

890875

891876

892877

893878

894879

895880

896881

897882

898883

899884

900885

901886

902887

903888

904889

905890

906891

907892

908893

909894

910895

911896

912897

913898

914899

915900

916901

917902

918903

919904

920905

921906

922907

923908

924909

925910

926911

927912

928913

929914

930915

931916

932917

933918

934919

935920

936921

937922

938923

939924

940925

941926

942927

943928

944929

945930

946931

947932

948933

949934

950935

951936

952937

953938

954939

955940

956941

957942

958943

959944

960945

961946

962947

963948

964949

965950

966951

967952

968953

969954

970955

971956

972957

973958

974959

975960

976961

977962

978963

979964

980965

981966

982967

983968

984969

985970

986971

987972

988973

989974

990975

991976

992977

993978

994979

995980

996981

997982

998983

999984

1000985

1001986

1002987

1003988

1004989

1005990

1006991

1007992

1008993

1009994

1010995

1011996

1012997

1013998

1014999

10151000

10161001

10171002

10181003

10191004

10201005

10211006

10221007

10231008

10241009

10251010

10261011

10271012

10281013

10291014

10301015

10311016

10321017

10331018

10341019

10351020

10361021

10371022

10381023

10391024

10401025

10411026

10421027

10431028

10441029

10451030

10461031

10471032

10481033

10491034

10501035

10511036

10521037

10531038

10541039

10551040

10561041

10571042

10581043

10591044

10601045

10611046

10621047

10631048

10641049

10651050

10661051

10671052

10681053

10691054

10701055

10711056

10721057

10731058

10741059

10751060

10761061

10771062

10781063

10791064

10801065

10811066

10821067

10831068

10841069

10851070

10861071

10871072

10881073

10891074

10901075

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

17#1092#

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

266################################################################################1467################################################################################

267 1468 

268[shell_environment_policy]1469[shell_environment_policy]

1470 

269# inherit: all (default) | core | none1471# inherit: all (default) | core | none

1472 

270inherit = "all"1473inherit = "all"

1474 

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

1476 

272ignore_default_excludes = false1477ignore_default_excludes = false

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

1479# Case-insensitive glob patterns to remove (e.g., "AWS**", "AZURE**"). Default: []

1480 

274exclude = []1481exclude = []

1482 

275# Explicit key/value overrides (always win). Default: {}1483# Explicit key/value overrides (always win). Default: {}

1484 

276set = {}1485set = {}

1486 

277# Whitelist; if non-empty, keep only matching vars. Default: []1487# Whitelist; if non-empty, keep only matching vars. Default: []

1488 

278include_only = []1489include_only = []

1490 

279# Experimental: run via user shell profile. Default: false1491# Experimental: run via user shell profile. Default: false

1492 

280experimental_use_profile = false1493experimental_use_profile = false

281 1494 

282################################################################################1495################################################################################

199```199```

200[permissions.filesystem]200[permissions.filesystem]

201deny_read = [201deny_read = [

202 "/Users/alice/.ssh",202 # values can be absolute paths...

203 "./private/**/*.txt",203 "/**/*.env",

204 # ...or relative to $HOME/%USERPROFILE% using `~`.

205 "~/.ssh",

206 # But relative paths starting with `./` are not allowed.

204]207]

205```208```

206 209 

122 122 

123API Access123API Access

124 124 

125For most tasks in Codex, start with `gpt-5.5` when it appears in your model125For most tasks in Codex, start with

126picker. It is strongest for complex coding, computer use, knowledge work, and126`gpt-5.5`. It is

127research workflows. GPT-5.5 is currently available in Codex when you sign in127strongest for complex coding, computer use, knowledge work, and research

128with ChatGPT or API-key authentication. Use `gpt-5.4-mini` when you want a128workflows. GPT-5.5 is currently available in Codex when you sign in with

129faster, lower-cost option for lighter coding tasks or subagents. The129ChatGPT or API-key authentication. Use

130`gpt-5.3-codex-spark` model is available in research preview for ChatGPT Pro130 

131subscribers and is optimized for near-instant, real-time coding iteration.131`gpt-5.4-mini`

132 

133when you want a faster, lower-cost option for lighter coding tasks or

134subagents. The `gpt-5.3-codex-spark` model is available in research preview

135for ChatGPT Pro subscribers and is optimized for near-instant, real-time

136coding iteration.

132 137 

133## Alternative models138## Alternative models

134 139 

163model = "gpt-5.5"168model = "gpt-5.5"

164```169```

165 170 

166If `gpt-5.5` isn’t available in your account yet, use `gpt-5.4`.

167 

168### Choosing a different local model temporarily171### Choosing a different local model temporarily

169 172 

170In the Codex CLI, you can use the `/model` command during an active thread to change the model. In the IDE extension, you can use the model selector below the input box to choose your model.173In the Codex CLI, you can use the `/model` command during an active thread to change the model. In the IDE extension, you can use the model selector below the input box to choose your model.

19 or helper scripts for a task.19 or helper scripts for a task.

20- **Apps:** connections to tools like GitHub, Slack, or Google Drive, so20- **Apps:** connections to tools like GitHub, Slack, or Google Drive, so

21 Codex can read information from those tools and take actions in them.21 Codex can read information from those tools and take actions in them.

22- **MCP servers:** services that give Codex access to additional tools or22- **MCP servers:** services that give Codex access to more tools or shared

23 shared information, often from systems outside your local project.23 information, often from systems outside your local project.

24 24 

25More plugin capabilities are coming soon.25You can share plugins by publishing them through a marketplace source, such as a

26repo marketplace for a project or team. See [Build plugins](https://developers.openai.com/codex/plugins/build)

27for marketplace setup, packaging, and distribution guidance.

26 28 

27## Use and install plugins29## Use and install plugins

28 30 

30 32 

31Open **Plugins** in the Codex app to browse and install curated plugins.33Open **Plugins** in the Codex app to browse and install curated plugins.

32 34 

33![Codex Plugins page](/images/codex/plugins/directory.png)35![Codex Plugins page](/images/codex/plugins/directory.webp)

36 

37The plugin directory groups plugins into categories:

38 

39- **Curated by OpenAI:** highlighted plugins available to all Codex users.

40- **Shared with you:** plugins shared by other members of your ChatGPT

41 workspace.

42- **Created by you:** plugins you created or added to your own workspace.

34 43 

35### Plugin directory in the CLI44### Plugin directory in the CLI

36 45 

91- Bundled skills are available as soon as you install the plugin.100- Bundled skills are available as soon as you install the plugin.

92- If a plugin includes apps, Codex may prompt you to install or sign in to101- If a plugin includes apps, Codex may prompt you to install or sign in to

93 those apps in ChatGPT during setup or the first time you use them.102 those apps in ChatGPT during setup or the first time you use them.

94- If a plugin includes MCP servers, they may require additional setup or103- If a plugin includes MCP servers, they may require extra setup or

95 authentication before you can use them.104 authentication before you can use them.

96- When Codex sends data through a bundled app, that app’s terms and privacy105- When Codex sends data through a bundled app, that app’s terms and privacy

97 policy apply.106 policy apply.

116 125 

117If you want to create, test, or distribute your own plugin, see126If you want to create, test, or distribute your own plugin, see

118[Build plugins](https://developers.openai.com/codex/plugins/build). That page covers local scaffolding,127[Build plugins](https://developers.openai.com/codex/plugins/build). That page covers local scaffolding,

119manual marketplace setup, plugin manifests, and packaging guidance.128manual marketplace setup, workspace sharing, plugin manifests, and packaging

129guidance.

120 130 

6when you want to share that workflow across teams, bundle app integrations or6when you want to share that workflow across teams, bundle app integrations or

7MCP config, package lifecycle hooks, or publish a stable package.7MCP config, package lifecycle hooks, or publish a stable package.

8 8 

9## Create a plugin with `$plugin-creator`9## Create a plugin with `@plugin-creator`

10 10 

11For the fastest setup, use the built-in `$plugin-creator` skill.11For the fastest setup, use the built-in `@plugin-creator` skill.

12 12 

13![plugin-creator skill in Codex](/images/codex/plugins/plugin-creator.png)13![plugin-creator skill in Codex](/images/codex/plugins/plugin-creator.png)

14 14 

15It scaffolds the required `.codex-plugin/plugin.json` manifest and can also15It scaffolds the required `.codex-plugin/plugin.json` manifest and can also

16generate a local marketplace entry for testing. If you already have a plugin16generate a local marketplace entry for testing. If you already have a plugin

17folder, you can still use `$plugin-creator` to wire it into a local17folder, you can still use `@plugin-creator` to wire it into a local

18marketplace.18marketplace.

19 19 

20![how to invoke the plugin-creator skill](/images/codex/plugins/plugin-creator-invoke.png)20![how to invoke the plugin-creator skill](/images/codex/plugins/plugin-creator-invoke.png)

21 21 

22### Build your own curated plugin list22### Build your own curated plugin list

23 23 

24A marketplace is a JSON catalog of plugins. `$plugin-creator` can generate one24A marketplace is a JSON catalog of plugins. `@plugin-creator` can generate one

25for a single plugin, and you can keep adding entries to that same marketplace25for a single plugin, and you can keep adding entries to that same marketplace

26to build your own curated list for a repo, team, or personal workflow.26to build your own curated list for a repo, team, or personal workflow.

27 27 

107Greet the user warmly and ask how you can help.107Greet the user warmly and ask how you can help.

108```108```

109 109 

1103. Add the plugin to a marketplace. Use `$plugin-creator` to generate one, or1103. Add the plugin to a marketplace. Use `@plugin-creator` to generate one, or

111 follow [Build your own curated plugin list](#build-your-own-curated-plugin-list)111 follow [Build your own curated plugin list](#build-your-own-curated-plugin-list)

112 to wire the plugin into Codex manually.112 to wire the plugin into Codex manually.

113 113 

182After you change the plugin, update the plugin directory that your marketplace182After you change the plugin, update the plugin directory that your marketplace

183entry points to and restart Codex so the local install picks up the new files.183entry points to and restart Codex so the local install picks up the new files.

184 184 

185### Share a local plugin with your workspace

186 

187After you create a plugin and add it to Codex, you can share it with other

188members of your ChatGPT workspace from the Codex app.

189 

1901. Open **Plugins** in the Codex app.

1912. Go to **Created by you** and open the plugin details page.

1923. Select **Share**.

1934. Add workspace members or copy a share link.

1945. Choose who has access, then send the invitation or link.

195 

196People you share with can find the plugin under **Shared with you** in the

197plugin directory. Sharing a local plugin with your workspace doesn’t publish

198it to the public Plugin Directory. Shared plugins stay within your workspace

199and organization boundary; accounts that aren’t signed in to that workspace

200can’t access them. Use a marketplace when you want repo or CLI distribution,

201and use workspace sharing when you want selected teammates to install a plugin

202from the Codex app.

203 

204Workspace admins can disable plugin sharing from cloud-managed requirements by

205adding `plugin_sharing = false` to `requirements.toml`:

206 

207```

208plugin_sharing = false

209```

210 

185### Marketplace metadata211### Marketplace metadata

186 212 

187If you maintain a repo marketplace, define it in213If you maintain a repo marketplace, define it in

50 50 

51All information in a thread must fit within the model’s **context window**, which varies by model. Codex monitors and reports the remaining space. For longer tasks, Codex may automatically **compact** the context by summarizing relevant information and discarding less relevant details. With repeated compaction, Codex can continue working on complex tasks over many steps.51All information in a thread must fit within the model’s **context window**, which varies by model. Codex monitors and reports the remaining space. For longer tasks, Codex may automatically **compact** the context by summarizing relevant information and discarding less relevant details. With repeated compaction, Codex can continue working on complex tasks over many steps.

52 52 

53## Goal mode

54 

55Goal mode gives Codex a persistent objective to work toward across a longer

56task. Use it when the work may take many steps, or when Codex needs a clear

57definition of done that it can keep checking as it works.

58 

59![Codex app goal progress controls above the composer](/images/codex/app/goal-dialog-light.webp)

60 

61When you set a goal, the goal text acts as both the starting prompt and the

62completion criteria. Codex uses it to decide what to do next and whether the

63task is complete. Start Goal mode with `/goal` in the [Codex

64app](https://developers.openai.com/codex/app/commands#set-or-manage-a-goal-with-goal), [IDE

65extension](https://developers.openai.com/codex/ide/slash-commands), or [CLI](https://developers.openai.com/codex/cli/slash-commands#set-or-view-an-experimental-task-goal-with-goal).

66In the Codex app, progress appears above the composer with controls to pause,

67resume, edit, or clear the goal.

68 

69Write goals so Codex can tell whether it has succeeded. Good goals include a

70specific outcome, measurable target, or test criteria. For example:

71 

72```

73Migrate this codebase from JavaScript to TypeScript. The app should compile in

74strict mode without explicit `any` type definitions.

75```

76 

77```

78Reduce the time to interactive of the home page to below 1 second.

79```

80 

81If the goal is hard to define up front, start with `/plan` and ask Codex to

82shape it before implementation. You can also ask Codex to interview you and

83draft a goal with clear success criteria.

84 

85You can continue steering Codex after the goal starts. Send follow-up messages

86to adjust constraints, such as asking Codex to use a particular library or

87avoid a specific approach. Use side chats when you want a status recap or

88explanation without interrupting the main task. For long-running work, pause

89the goal before you lose connectivity, then resume or edit it when you are

90ready to continue.

91 

89 89 

90All the specifics about the new API features and model behavior are documented in our docs, in the [latest model](https://developers.openai.com/api/docs/guides/latest-model) and [prompt guidance](https://developers.openai.com/api/docs/guides/prompt-guidance) guides.90All the specifics about the new API features and model behavior are documented in our docs, in the [latest model](https://developers.openai.com/api/docs/guides/latest-model) and [prompt guidance](https://developers.openai.com/api/docs/guides/prompt-guidance) guides.

91 91 

92The OpenAI Docs skill also includes [specific guidance](https://github.com/openai/codex/blob/6323f0104d17d211029faab149231ba787f7da37/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-5p4.md) as reference, codifying how to upgrade to the latest model–currently [GPT-5.4](https://developers.openai.com/api/docs/models/gpt-5.4).92The OpenAI Docs skill also includes [specific guidance](https://github.com/openai/codex/blob/6323f0104d17d211029faab149231ba787f7da37/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-5p4.md) as a concrete migration reference. For the current upgrade target, use the [latest model](https://developers.openai.com/api/docs/guides/latest-model) guide.

93 93 

94Codex now automatically comes with the OpenAI Docs skill, so make sure to mention it in your prompt to access all the latest documentation and guidance when building with the OpenAI API.94Codex now automatically comes with the OpenAI Docs skill, so make sure to mention it in your prompt to access all the latest documentation and guidance when building with the OpenAI API.

95 95 

38 38 

39Related links39Related links

40 40 

41[`/goal` in CLI slash commands](https://developers.openai.com/codex/cli/slash-commands#set-an-experimental-goal-with-goal) [Codex workflows](https://developers.openai.com/codex/workflows) [Run code migrations](https://developers.openai.com/codex/use-cases/code-migrations) [Iterate on difficult problems](https://developers.openai.com/codex/use-cases/iterate-on-difficult-problems)41[`/goal` in CLI slash commands](https://developers.openai.com/codex/cli/slash-commands#set-a-goal-with-goal) [Codex workflows](https://developers.openai.com/codex/workflows) [Run code migrations](https://developers.openai.com/codex/use-cases/code-migrations) [Iterate on difficult problems](https://developers.openai.com/codex/use-cases/iterate-on-difficult-problems)

42 42 

43## Best for43## Best for

44 44 

58 58 

59Use `/goal` when you want Codex to keep working toward one durable objective instead of stopping after one normal turn. It’s useful for work that has a clear target, a validation loop, and enough room for Codex to make progress without asking you to steer every step. When you use `/goal`, Codex can work independently for multiple hours without needing your input.59Use `/goal` when you want Codex to keep working toward one durable objective instead of stopping after one normal turn. It’s useful for work that has a clear target, a validation loop, and enough room for Codex to make progress without asking you to steer every step. When you use `/goal`, Codex can work independently for multiple hours without needing your input.

60 60 

61`/goal` is an experimental Codex CLI feature. Enable it from `/experimental`, or add `goals = true` under `[features]` in `config.toml`. Then set a goal with `/goal <objective>`, check the current goal with `/goal`, and use `/goal pause`, `/goal resume`, or `/goal clear` when you need to control the run.61Set a goal with `/goal <objective>`, check the current goal with `/goal`, and use `/goal pause`, `/goal resume`, or `/goal clear` when you need to control the run.

62 62 

63Goals are in preview and are not yet fully supported in the Codex app, but you63Goals are in preview and are not yet fully supported in the Codex app, but you

64can still run goals from the app. Consider the behavior in the app64can still run goals from the app. Consider the behavior in the app

90 90 

91## Pick your model91## Pick your model

92 92 

93For fast UI iteration, start with `gpt-5.3-codex-spark` if you have access to it. It is less capable that our general-purpose models, but is designed for real-time coding iteration. If you don’t have access to it, use our latest model with `medium` or `low` reasoning effort.93For fast UI iteration, start with `gpt-5.3-codex-spark` if you have access to it. It is less capable that our general-purpose models, but is designed for real-time coding iteration. If you don’t have access to it, use `gpt-5.5` with `medium` or `low` reasoning effort.

94 94 

95That tradeoff is useful for granular UI work. You usually do not need the deepest model to move a button, tune a breakpoint, or adjust a component state. You need a model that responds quickly, understands the local code, edits the right file, and can repeat the loop without making the iteration feel heavy.95That tradeoff is useful for granular UI work. You usually do not need the deepest model to move a button, tune a breakpoint, or adjust a component state. You need a model that responds quickly, understands the local code, edits the right file, and can repeat the loop without making the iteration feel heavy.

96 96