Switch Codex to Other WanAPIs Models

Setup steps

1. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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