# Switch Codex to Other WanAPIs Models

> Once Codex is connected to WanAPIs, switch it to DeepSeek, GPT and other models. All three clients share ~/.codex/config.toml. Covers profiles for quick switching, the new profile file format and common errors.

Web page: https://wanapi.ai/docs/codex-switch-model

The Codex CLI, VS Code extension and desktop app all read the same ~/.codex/config.toml — change it once and all three follow. Using deepseek-v4.1-flash as the example, this guide covers switching for one session, switching permanently, and keeping several model setups as profiles you can swap between.

## Setup steps

### 1. Make sure you're connected to WanAPIs

config.toml should already contain a provider that points at WanAPIs. In the examples below it's named wanapis and reads its key from the WANAPIS_API_KEY environment variable.

**~/.codex/config.toml**

```
model_provider = "wanapis"
model = "gpt-5.5"

[model_providers.wanapis]
name = "WanAPIs"
base_url = "https://api.wanapis.com/v1"
wire_api = "responses"
env_key = "WANAPIS_API_KEY"
```

### 2. CLI: switch for one session

Launch with -m or --model — handy for trying a model. Inside a running session, /model opens the picker so you can switch on the spot. Note that slash commands are CLI-only; the extension and desktop app don't have them (see the next step).

**shell**

```
codex --model deepseek-v4.1-flash

# Non-interactive runs work the same way
codex exec -m deepseek-v4.1-flash 'make this function async'
```

### 3. VS Code extension / desktop app: use the model picker at the bottom of the panel

The GUI clients have no slash commands (typing /model is just sent as text). The switch is the model picker at the bottom of the Codex panel, where you choose both the model and the reasoning effort. The desktop app also opens it with Ctrl+Shift+M; the VS Code extension has no default shortcut.

### 4. Your model isn't in the picker? That's expected

The picker lists the models Codex knows about out of the box (GPT-5.4 / 5.4-mini / 5.5 and so on); names added through a custom provider (like deepseek-v4.1-flash) aren't there by default. One useful detail: the picker changes model but not model_provider, so if you pick GPT-5.5 while on the WanAPIs provider, the request still goes to WanAPIs — we serve all of those models, so they just work. You only need to touch the config for names that aren't in the picker at all — see the next step.

### 5. Models not in the picker: gear icon → Open config.toml

No need to leave the editor: click the gear icon in the Codex sidebar → Codex Settings → Open config.toml, change model and restart the extension. The config is shared, so the CLI and desktop app change too. If you switch back and forth a lot, the profile approach in the next step is easier.

**~/.codex/config.toml**

```
model = "deepseek-v4.1-flash"
```

### 6. Recommended: keep several setups as profiles

If you switch between models often, give each one a profile instead of editing the model line every time. Create ~/.codex/<name>.config.toml files and choose one at launch with --profile <name>. This is the new format: the old [profiles.xxx] tables are no longer supported, and using them now fails with an error asking you to migrate.

**~/.codex/ds.config.toml**

```
model = "deepseek-v4.1-flash"
model_provider = "wanapis"
model_reasoning_effort = "high"
model_context_window = 900000
```

### 7. Launch with a profile

One command switches the whole setup (model + reasoning effort + context limit). Create as many as you need — for example ds, gpt and cheap.

**shell**

```
codex --profile ds
```

### 8. Advanced: register custom models in the model catalog

If you want Codex to treat a custom model as a first-class citizen — no more "Model metadata not found" warning, and the real context limit — point model_catalog_json at a model catalog file and add a metadata entry for it. In our tests the warning disappears after registering and the context limit you enter takes effect. The entry's visibility field decides whether it appears in the picker (list shows it, hide hides it), but whether the GUI lists custom entries depends on the client version — if it doesn't appear, edit the config as in the previous step.

**~/.codex/config.toml**

```
model_catalog_json = "/Users/<you>/.codex/models.json"
```

### 9. ⚠️ Three pitfalls when writing the model catalog

1) The format is strict: missing fields fail outright — leave out shell_type and you get missing field `shell_type`. 2) Some fields don't accept null (such as web_search_tool_type); null gives invalid type: null. 3) The worst one — if the catalog file fails to parse, Codex won't start at all (failed to parse model_catalog_json), taking down both the CLI and the extension. So don't write entries from scratch: copy an existing entry from the catalog and change only slug, display_name, context_window and the reasoning levels. Back the file up first.

### 10. Verify

On launch Codex prints the active config at the top — check that the model and provider lines are what you expect. You can also check the model name and charge on the latest entry in the WanAPIs console's Usage Logs page.

**Output on launch**

```
model: deepseek-v4.1-flash
provider: wanapis
reasoning effort: high
```

## FAQ

### Does the "Model metadata for `xxx` not found" warning matter?

Not really — chat works normally. Codex only ships metadata for OpenAI's own models, so other models fall back to defaults. The main effect is on its idea of the context limit; add a model_context_window line to your profile to set it. To get rid of the warning entirely, give the model a metadata entry via model_catalog_json (see the advanced step above); in our tests the warning no longer appears after registering.

### How large a context can deepseek-v4.1-flash handle in Codex?

On the gateway side we've seen single requests of 940K tokens return normally, with our three routes reaching 940K / 850K / 720K respectively. model_context_window = 900000 is a safe value with some headroom, and far larger than the default Codex falls back to when metadata is missing.

### It says [profiles.xxx] is a legacy config — what now?

Newer Codex versions no longer support [profiles.xxx] tables inside config.toml. Move that section into its own ~/.codex/<name>.config.toml file and delete the old [profiles.xxx] section from config.toml.

### What do I type in the VS Code extension to switch models?

The extension doesn't support slash commands; /model is just sent as ordinary text. Use the model picker at the bottom of the Codex panel, where you choose both model and reasoning effort. Custom models like deepseek-v4.1-flash won't be listed there — use the gear icon → Codex Settings → Open config.toml (or a profile), then restart the extension. The desktop app also has a Ctrl+Shift+M shortcut for the picker.

### Do the VS Code extension and desktop app need separate setup?

No. All three read ~/.codex/config.toml, so one change applies everywhere. The only catch is that the extension and desktop app need a restart to re-read the config.

### How much can a cheaper model actually save?

Every Codex turn includes its own system prompt and tool definitions, so even a one-line message is over ten thousand input tokens. Because input volume is that large, moving to a model with a lower unit price saves a meaningful absolute amount — compare entries side by side in the console logs.

---

Generated by the WanAPIs website and kept in sync with the web page. All guides in Markdown: https://wanapi.ai/docs/index.md