Codex model discovery

How the Codex model catalog is discovered, and what happens when discovery fails. Part of the Codex harness reference; Where each section moved lists every section.

Model discovery

By default, the Codex plugin asks the app-server for available models. Model availability is owned by Codex app-server, so the list can change when OpenClaw upgrades the bundled @openai/codex version, when OpenClaw selects a newer installed Codex, or when a deployment points appServer.command at a different Codex binary. ChatGPT-login model discovery reports the selected binary's version as its client_version, so the list matches the binary that runs turns. Availability can also be account-scoped. Use /codex models on a running gateway to see the live catalog for that harness and account.

Automatic discovery and hosted-search model selection use visible picker entries. Bounded turns with an explicit model selection, including image understanding, structured extraction, isolated completion, and settled-turn finalization, also look up hidden entries returned by model/list. The model must still be listed and support the required input modalities. Listing does not prove account entitlement.

Native discovery is demand-driven. Gateway startup publishes configured model hints without starting an app-server for each agent. Opening an agent's model picker or catalog, creating a Codex session, running a turn, or requesting native auth/status information starts that agent's client when needed. Before discovery, native account readiness is unknown; configured hints are not proof of sign-in. First use of an idle agent can take a few seconds for the cold start.

Discovery reads model/list and account/read from the same scoped app-server client. An API-key account remains API-key authentication; model listing does not imply a ChatGPT transport or endpoint. Picker readiness is valid only while that native owner and its account/config observation remain current. A missing account, failed refresh, account/config mutation, or retired client leaves native models unavailable until discovery succeeds again. The next picker/catalog request or native execution reacquires retired observations.

A client with no owned work retires after 30 idle seconds. Requests in that grace period reuse it. Active requests, turns, retained or releasing threads, native children, background terminals, and ephemeral history retain their client until their owners release it. The existing warm-session executor and thread-retention policies remain in effect. Clients and accounts stay isolated by agent home.

Use the Models page Refresh action (models.list with view: "all" and refresh: true) to publish the full catalog for the selected agent. Prepared-only reads do not start discovery. Native configuration changes outside OpenClaw require the native owner's supported reload/restart and a catalog refresh; OpenClaw does not poll native home files for readiness. Authored host routes and explicit profile selections retain their existing auth and compatibility checks.

For the Codex runtime, the composer shows Ultrafast only when authenticated account discovery advertises that service tier for the selected model, account, route, and runtime. The OpenAI provider's existing account-scoped discovery supplies this observation; static catalog hints and the native app-server's fallback list do not establish access. Selecting a managed personal account prepares that account's catalog through the same provider discovery path, without changing shared auth order. Prepared-only reads do not start discovery. Account changes, failed discovery, and retired generations cannot reuse another account's tier support.

Native-only accounts without managed discovery credentials, token-sharing auth that cannot use model discovery, and catalogs without explicit service-tier metadata leave this capability unknown. The composer hides Ultrafast in those cases rather than offering a disabled option. Discovery support describes availability, not a guarantee that an upstream request will receive that tier.

The embedded OpenClaw runtime uses the available API-key OpenAI Responses route to offer Ultrafast without catalog metadata, whether the key comes from an auth profile, environment, or provider config (including SecretRefs). This remains subject to observed provider downgrades for the selected credential and route; see Fast mode. Codex-runtime Ultrafast with API-key authentication still requires the native catalog, including a pinned model_catalog_json, to list the tier for that model.

Native catalog identifiers are runtime identifiers, not privacy labels. A deployment using a broker-owned alias must supply an alias-safe native catalog before starting app-server: both id and model in model/list must be the alias, with the desired displayName. Different native runtime identifiers are preserved in OpenClaw model parameters. Renaming the picker label does not hide those identifiers from requests or session state.

Codex's startup model_catalog_json setting can supply a native catalog; a per-thread override does not reload it. Preserve the complete model capability, instruction, compaction, and reviewer metadata. Catalog membership does not reject arbitrary model overrides, so the broker must enforce allowed selectors on every request. Disable native session discovery with sessionCatalog.enabled: false when no native history should be imported.

A custom endpoint is not automatically a supported Codex route. Explicit agentRuntime.id: "codex" does not bypass prepared-route compatibility or the trusted-endpoint requirement for model-backed approval review. A workload API key also does not provide ChatGPT account identity or subscription refresh. Verify those contracts before using a broker with the native harness; do not substitute a custom provider, remove safety metadata, or weaken review to make an inference smoke test pass.

If discovery is temporarily unavailable or times out, the subscription route uses offline hints derived from the bundled OpenAI model manifest, with Codex plugin fallbacks for gpt-5.5 and gpt-5.5-pro reasoning efforts:

Offline hints never prove account entitlement. An authenticated discovery response remains authoritative even if it contains no visible models; HTTP 401 and 403 return an empty catalog rather than exposing fallback models.

Tune discovery under plugins.entries.codex.config.discovery:

The default budget is 10 seconds. It allows Codex's five-second remote catalog refresh to finish or return its native cached/bundled catalog, with time left for transport and the account read. Setting a shorter budget can cancel that native fallback and leave native models unavailable until discovery succeeds.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 10000,
          },
        },
      },
    },
  },
}

Disable discovery to avoid native model/account catalog checks even on demand:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: false,
          },
        },
      },
    },
  },
}