Core serves a native Codex catalog at
GET /codex/models?client_version=<major.minor.patch>. It uses the same gateway
keys, allowed source addresses, model directory, aliases and key allow rules
as inference. The standard /v1/models endpoint keeps its OpenAI response shape.
ThinkWatch Lite configures this connection when adopting Codex. For a manual
connection, use a provider like this in Codex's config.toml:
model_provider = "thinkwatch"
[features]
api_key_model_discovery = true
[model_providers.thinkwatch]
name = "ThinkWatch"
base_url = "http://127.0.0.1:8788/v1"
model_catalog_url = "http://127.0.0.1:8788/codex/models"
wire_api = "responses"
env_key = "THINKWATCH_GATEWAY_KEY"
requires_openai_auth = false
supports_websockets = falseUse your gateway's actual address and set THINKWATCH_GATEWAY_KEY to an enabled
gateway key. Remove any effective model_catalog_json setting: that local file
takes precedence over the remote catalog. A selected profile can also override
the provider, local catalog or discovery feature. Lite handles the selected
default profile and restores its original fields when disconnected. Explicitly
selecting a different profile or passing command-line overrides can still change
which provider Codex uses.
The connection is configured once. After that, changes to upstream models, aliases, enabled ranges, manual model capabilities or key permissions are projected on the next catalog request. Changes made through Lite or the control API use the normal hot reload path; no model list is written to the Codex config. The initial connection requires restarting Codex. Codex also maintains its own model cache, so an already open picker may show its previous list until the client refreshes it or restarts. This endpoint does not push updates to clients.
For Responses, Chat Completions and ChatGPT providers, Core requests metadata
with the requesting Codex client_version, using that provider's credentials
and configured proxy. The inbound gateway key is never forwarded. ChatGPT uses
its native models URL. Direct OpenAI API providers use OpenAI's documented native
Codex endpoint; other providers use their models endpoint. A full native
models entry retains its instructions, tools and unknown version-specific
fields. A standard OpenAI data list uses a generic coding profile; reported model
capabilities are projected onto it without adopting native instructions or tools. Core does not copy bundled OpenAI model
instructions onto unrelated providers.
Only models already in the shared gateway directory are exposed. A native catalog does not independently add models or grant inference access. Alias names become the exposed slugs, with no migration target. If routing candidates have different native definitions, Core uses the generic profile and intersects their known capabilities. Explicit model specifications override native values; native values take precedence over the price table. Unknown context windows are omitted. Image input requires affirmative support from every candidate.
For ordinary upstream model lists, Core reads data[].context_window,
data[].input_modalities, data[].effort.supported_levels, and
data[].effort.default_level. For example, DeepSeek documents these fields in
its models endpoint. The effort
list becomes Codex's supported_reasoning_levels; the reported default is kept
when it is in the list. Optional or malformed fields do not create capabilities.
No model-name table or inference from reasoning: true supplies missing levels.
A relay can preserve this metadata for automatic discovery; missing or incorrect effort profiles can also be overridden manually.
Aliases inherit the actual routing targets' reported capabilities. Effort
choices are intersected separately from full native definitions, so differences
in prompts or tools do not discard shared levels. Defaults must belong to the
intersection. Manual model_specs.reasoning: false removes choices. When any
candidate requires protocol translation, choices are also limited to efforts
Core can translate; Responses and ChatGPT passthrough can retain newer native
efforts such as ultra.
Core uses reported capabilities automatically. Background inventory retains the same specifications for Lite and standard model discovery; the Codex catalog prefers metadata for the requesting client version. Missing effort metadata remains unknown. Model names and price-table reasoning flags do not generate effort choices.
If the upstream has no model list, first add its actual model ID to models. Supply missing or
incorrect effort metadata for that exact model and provider:
providers:
- name: relay
base_url: https://relay.example.com/v1
protocol: openai-chat
models: [private-model]
model_specs:
private-model:
reasoning_effort:
supported_levels: [low, high, max]
default_level: highThe entire manual profile replaces the upstream profile. Nonempty levels imply reasoning support;
reasoning: true is unnecessary. Omitting reasoning_effort restores automatic discovery, while
supported_levels: [] explicitly declares no adjustable effort. default_level is optional: Core
prefers medium in the final available set, otherwise its lowest level. An explicit default must
belong to the declared set. Duplicate levels and reasoning: false with nonempty manual levels
are rejected. Alias intersections and protocol restrictions apply to manual profiles as well.
Control API model rows expose reported, manual and effective efforts separately, together with
levels excluded by protocol conversion. In PUT /provider-model-spec, reasoning_effort uses
mode: keep (also the omitted default), mode: auto, or mode: set with value to retain,
remove or replace the override. Editing other specifications preserves the effort override.
Only upstream metadata is cached. Entries are isolated by the provider,
resolved credentials and headers, URL, client version and proxy configuration.
There are at most 32 cache entries and four concurrent metadata fetches. Fetches
have an eight-second deadline. Successful upstream cache lifetimes are capped at
five minutes, subtract Age, and honor no-cache and no-store; failed fetches
use a generic fallback and are retried after 30 seconds. Oversized or unavailable
upstream metadata also falls back to the generic profile.
Gateway names, permissions and capabilities are rebuilt even on conditional
requests. Authentication happens before an ETag can yield 304. A configuration
reload during a metadata fetch discards that fetch's native definitions before
projecting the current configuration. Responses are private, revalidate after
30 seconds and carry an ETag. Inference continues enforcing the current key and
model permissions independently of anything cached by Codex.
The final native response is limited to 1 MiB, as required by Codex. A catalog
larger than that returns 413 instead of silently omitting models. Restrict the
models available to the gateway key to reduce its size. Missing, duplicate or
invalid client_version parameters return 400.
The remote catalog and generic profile have been checked with Codex CLI 0.166.0. See OpenAI's catalog endpoint contract for the client configuration and versioned schema requirements.