# Codex Desktop (ChatGPT app) now runs with Context Mode

October 28, 2026 Agents 7 min read

Thanks to our community, and to the Codex team at OpenAI for a config file that is open and documented. Codex Desktop, the Codex inside the ChatGPT app, now connects to Context Mode with one command. You keep the app, your model and your own ChatGPT login or API key. Setup writes the Codex config file once, and that one write covers the app and the Codex CLI. Then every request gets Saving, Memory, Skills, Instructions and Recall.

## TL;DR

- **Use the app you have.** Codex Desktop reads the Codex CLI's config file, `~/.codex/config.toml`. Sign in to Codex the usual way.
- **Connect it:** `npx @context-mode/cli setup --agent codex-desktop`. It writes `config.toml` once, for the app and the CLI. It writes no API key.
- **Safe edit:** a real TOML parser reads the file. Only the lines setup owns change. Comments and every other table stay as they were. A backup comes first.
- **Quit the app fully (Cmd+Q) and open it again.** The console shows these turns as Codex Desktop.
- **Undo** with `npx @context-mode/cli disconnect --agent codex-desktop`.
- **Limits:** if a `[profiles.*]` picks another provider, that profile wins while it is active. Protect and session resume are not verified in the app.

## How to connect Codex Desktop to Context Mode

This post answers one question: how do you connect Codex Desktop to Context Mode? Five steps. The first two are the app's own. Pick a step to see the exact command and what it prints.

Step

App Sign in Setup Restart Check

```
# Get the ChatGPT app from OpenAI, or use the one you have.
# Setup finds it as Codex.app, or as ChatGPT.app when it ships codex-cli.
~/.codex/config.toml  # the file the app reads
```

Download it from [OpenAI's ChatGPT desktop app page](https://developers.openai.com/codex/app). Codex Desktop reads the Codex CLI's config file. Nothing new to install in the app.

```
$ codex login
# a ChatGPT login, or:
$ codex login --with-api-key
```

Codex sends a key only from its own login. A key that is only exported in your shell is not sent.

```
$ npx @context-mode/cli setup --agent codex-desktop
Config: ~/.codex/config.toml
Changes:
  model_provider: (added) → context-mode
  [model_providers.context-mode] name: (added) → context-mode
  [model_providers.context-mode] base_url: (added) → https://gateway.contextmode.ai
  [model_providers.context-mode] wire_api: (added) → responses
  [model_providers.context-mode] requires_openai_auth: (added) → true
  [model_providers.context-mode] http_headers: (added) → {x-cm-device-key}
Write these changes to ~/.codex/config.toml? y
Backup of the original: config.toml.cm-setup-bak-<timestamp>
Wrote ~/.codex/config.toml. Start a new Codex session for it to take effect.
Codex Desktop reads the same file: quit it fully (Cmd+Q on macOS) and open it again.
```

Shortened. It shows each change, asks first, makes a backup, and prints header names only, never your key.

```
# Cmd+Q, not only close the window. Then open the app again
# and start a new session.
```

Setup tells you to quit the app fully and open it again. Then start a new session.

```
$ npx @context-mode/cli doctor
# shortened
Reachable    ok
Device key   ok
Codex Desktop ok (shares Codex's ~/.codex/config.toml)
```

Then ask Codex Desktop anything. Your request shows on the console within a minute.

### 1. Use the app and the config file it already reads

Codex Desktop is the Codex inside the ChatGPT app. It reads the same file as the Codex CLI, `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`). Codex keeps a provider in that file, as `[model_providers.<id>]`, and documents each key in its [config reference](https://learn.chatgpt.com/docs/config-file/config-reference). Context Mode uses only that. There is no plugin and no fork.

### 2. Sign in to Codex the usual way

Keep the login you have: a ChatGPT login, or an API key stored with `codex login`. Codex sends a key only from its own login. An `OPENAI_API_KEY` that is only exported in your shell is not sent. If that is your case, setup tells you to run:

```
printenv OPENAI_API_KEY | codex login --with-api-key
```

### 3. Run the Context Mode command

```
npx @context-mode/cli setup --agent codex-desktop
```

It needs Node 20.12 or later. If this terminal is not signed in yet, run `npx @context-mode/cli` first. It signs you in and gives this terminal a device key (`cmdk_…`), stored in `~/.context-mode/credentials.json`. Setup then writes this block into `config.toml`:

```
model_provider = "context-mode"

[model_providers.context-mode]
name = "context-mode"
base_url = "https://gateway.contextmode.ai"
wire_api = "responses"
requires_openai_auth = true
http_headers = { "x-cm-device-key" = "cmdk_…" }
```

That is one write for the app and the Codex CLI, not two. `requires_openai_auth = true` lets Codex send your own login. A ChatGPT login goes to ChatGPT's Codex backend; an API key goes to api.openai.com. The gateway removes the device key before the request goes to OpenAI.

How setup behaves:

- A real TOML parser reads the file before anything is written. Only the lines of the keys setup owns change. Comments, spacing and every other table stay as they were.
- It parses the edited file again. If it does not hold exactly the intended settings, nothing is written.
- It copies the file to `<file>.cm-setup-bak-<timestamp>`, then writes atomically.
- It writes nothing if the file does not parse.
- If Codex already uses a provider other than its default, setup asks before it switches it. `--yes` alone does not cover that.
- `--dry-run` shows the change and writes nothing. `--check` writes nothing and tells you if the app is set up.

### 4. Quit the app fully and open it again

Press Cmd+Q. Closing the window is not enough. Open the app, start a new session and ask it anything. After a turn where something was kept out, a line that starts with "⏺ contextmode" shows on the final message. Your request shows on the console as **Codex Desktop**.

## Or connect it with your other apps in one command

Do you use more than one coding agent? Run the CLI with no arguments. It signs you in, lists all 7 apps, with the ones it finds checked, writes each config, sends one check request per app, and prints `Ready`.

```
$ npx @context-mode/cli
# pick Codex Desktop (and any other app) in the list, press Enter
Codex Desktop connected (workspace …)
Console: https://console.contextmode.ai
Ready
```

The 7 apps are Claude Code, Claude Desktop, Codex, Codex Desktop, T3 Code, OpenCode and Pi. Codex Desktop is in the picker but not in `--agent all`, which covers Claude Code and Codex. Read [one gateway for seven coding agents](https://contextmode.ai/blog/seven-coding-agents-one-gateway) for the full list.

## Does Codex Desktop work with a gateway?

Yes. Codex lets you add a provider with its own `base_url` and headers in `config.toml`, and the desktop app reads that file. Context Mode sets one such provider and selects it. On the wire the app speaks the OpenAI Responses API, the same as the Codex CLI. The console names it Codex Desktop, and Memory stores its turns as Codex.

## What you get in Codex Desktop

The gateway does not switch features on or off by app. These run on every Codex Desktop request. We measure savings on Claude Code (and in part on Codex), not on the desktop app, so this post gives no savings number for it. Pick a feature to see what it does.

Feature

Saving Memory Skills Instructions Recall Protect

```
You, in Codex Desktop:
"read the build log and tell me why it broke"
# the model gets the error and the lines around it
# the rest of the log stays out of the context
⏺ contextmode · …
```

Large tool output (logs, fetched pages, big files) stays out of the model's context. The short line on the final message shows what was kept out. Works on every request; not measured on the app.

```
Monday, in Codex Desktop:
"We use pnpm in this repo, never npm."
Thursday, a new session:
"Add the date library."
pnpm add date-fns
```

Rules, decisions and preferences come back in later sessions, so you do not repeat yourself. Stored as Codex.

```
You, in Codex Desktop:
"write the release notes for this sprint"
# your imported release-notes skill loads for this turn
```

Import skills once, for example from GitHub. They run from the gateway, so there is nothing to install on each machine.

```
// Console: Settings → Instructions
Answer in short lines.
Use TypeScript strict mode in every example.
```

Write it once. Every Codex Desktop request carries it, on every machine.

```
You, late in a long session:
"what did we decide about the retry limit this morning?"
# the agent reads the decision back from the archive
```

Long history is archived, not lost. The agent can ask for it back. The recall line for Codex Desktop is pinned in our tests; not measured on the app.

```
$ git push origin main
# Claude Code, Codex CLI: blocked by your rule
# Codex Desktop: not verified
```

Protect is enforced on Claude Code and the Codex CLI. In the desktop app it is not verified, so do not count on it to stop a command.

| Feature | In Codex Desktop | Measured on the app |
| --- | --- | --- |
| [Saving](https://contextmode.ai/docs/how-saving-works) | Yes, every request | No (measured on Claude Code, in part on Codex) |
| [Thinking in Code](https://contextmode.ai/thinking-in-code) | Yes, every request | No |
| [Memory](https://contextmode.ai/docs/memory) | Yes, stored as Codex | No |
| [Skills](https://contextmode.ai/docs/skills) | Yes, every request | No |
| [Instructions](https://contextmode.ai/docs/instructions) | Yes, every request | No |
| [Recall](https://contextmode.ai/docs/recall) | Yes; the recall line is pinned in tests | No |
| [Search](https://contextmode.ai/docs/search) | Yes, every request | No |
| [Active Context](https://contextmode.ai/docs/active-context) | Yes, every request | No |
| [Protect](https://contextmode.ai/docs/protect) | Not verified | No |
| [Session resume](https://contextmode.ai/docs/session-resume) | Not verified | No |
| The "⏺ contextmode" line | Yes, on the final message | Not applicable |

## Memory for Codex Desktop

Each new session in the app starts fresh. With Context Mode, what you told it before comes back: "use pnpm", "deploy to Render", "no default exports". Memory stores these turns as Codex. When a value changes, the old one is closed, not deleted, so the agent gets the new value. Read [how Memory works](https://contextmode.ai/docs/memory).

## Say this plainly

- **A profile can win.** If a `[profiles.*]` in your Codex config picks another provider, that profile wins while it is active. Setup tells you its name, for example: ``` Note: profiles.work selects model_provider = "azure"; while that profile is active it wins over this setting. ```
- **A shell-only key is not sent.** Codex sends a key only from its own login. Run `printenv OPENAI_API_KEY | codex login --with-api-key`.
- **Quit with Cmd+Q**, not only close the window, then start a new session.
- **Protect** is enforced on Claude Code and the Codex CLI. In the desktop app it is not verified.
- **Session resume** works with `codex resume` in the Codex CLI. In the desktop app it is not verified.

## How to undo it

```
npx @context-mode/cli disconnect --agent codex-desktop
```

It removes `model_provider = "context-mode"` and `[model_providers.context-mode]`. Everything else stays. A backup comes first, and it works offline. The app and the Codex CLI share the file, so the route goes from both. Check any time with `npx @context-mode/cli status`: who is signed in, and each agent's setup.

## Start now

Keep your Codex login, run one command, and press Cmd+Q. [Open the Console](https://console.context-mode.com/login) to see your workspace.

```
npx @context-mode/cli setup --agent codex-desktop
```

- Console: [console.contextmode.ai](https://console.contextmode.ai) ([start free](https://console.context-mode.com/login))
- CLI: `npx @context-mode/cli`
- Docs: [Quick start for Codex](https://contextmode.ai/docs/quick-start#codex) and [the CLI](https://contextmode.ai/docs/cli)

The other apps, each with its makers' own install: [Claude Desktop](https://contextmode.ai/blog/claude-desktop-context-mode), [Pi](https://contextmode.ai/blog/pi-coding-agent-context-mode) and [T3 Code](https://contextmode.ai/blog/t3-code-context-mode). Context Mode is under the Elastic License 2.0 (ELv2).

[Get started free](https://console.context-mode.com/login) [All posts](https://contextmode.ai/blog)