The Models Manager is the subsystem within codex-core responsible for discovering, fetching remotely, caching with TTL, and resolving model metadata. It bridges the remote /models endpoint with caching layers and the rest of the agent system, making model capabilities available to prompt construction, tool configuration, and UI pickers. It also supports configuration overrides and collaboration mode presets.
This page documents the ModelsManager struct, refresh strategies for cache and remote fetch, slug resolution logic for matching model requests to ModelInfo entries, the caching mechanism including cache invalidation by TTL and client version, and collaboration mode presets used by the TUI and core agent system.
Model metadata types are defined primarily in codex-rs/protocol/src/openai_models.rs1-287 These types are serialized across core, TUI, app-server, and SDK boundaries, so field defaults are used to preserve compatibility when older payloads omit newly introduced attributes codex-rs/protocol/src/openai_models.rs3-5
| Type | Purpose |
|---|---|
ModelInfo | Full model metadata containing model name, description, reasoning levels, shell execution type, truncation policy, base instructions, and optional personality message templates codex-rs/protocol/src/openai_models.rs249-287 |
ModelPreset | A UI-friendly summary derived from model metadata, used for presenting models in pickers codex-rs/protocol/src/openai_models.rs196-234 |
ModelsResponse | Wrapper around a vector of ModelInfo for deserialization from model list endpoints codex-rs/protocol/src/openai_models.rs290-293 |
ReasoningEffort | Enum representing reasoning complexity levels: None, Minimal, Low, Medium, High, XHigh, Max, Ultra codex-rs/protocol/src/openai_models.rs40-52 |
ReasoningEffortPreset | Associates each reasoning effort level with a display description codex-rs/protocol/src/openai_models.rs171-177 |
ConfigShellToolType | Shell execution modes, such as Default, Local, UnifiedExec, Disabled, and ShellCommand codex-rs/protocol/src/openai_models.rs237-243 |
ModelVisibility | Model visibility control: List (visible in picker), Hide, or None codex-rs/protocol/src/openai_models.rs183-187 |
TruncationPolicyConfig | Defines token or byte limits to truncate tool outputs codex-rs/protocol/src/openai_models.rs221-226 |
ModelUpgrade | Recommended upgrade information for a model codex-rs/protocol/src/openai_models.rs180-185 |
ModelInfo Fields| Field | Type | Description |
|---|---|---|
slug | String | Stable model identifier used in configuration and API requests. |
shell_type | ConfigShellToolType | Determines the shell tool execution strategy the model supports codex-rs/protocol/src/openai_models.rs237-243 |
truncation_policy | TruncationPolicyConfig | Limits controlling the truncation behavior for tool outputs codex-rs/protocol/src/openai_models.rs221-226 |
base_instructions | String | System prompt or base instruction string for the model. |
context_window | Option<i64> | Maximum token window supported by the model codex-rs/protocol/src/openai_models.rs279 |
max_context_window | Option<i64> | The absolute maximum context window the model can handle, used for clamping overrides codex-rs/core/tests/suite/remote_models.rs131 |
input_modalities | Vec<InputModality> | Input types supported, e.g., Text, Image codex-rs/protocol/src/openai_models.rs149-154 |
Sources: codex-rs/protocol/src/openai_models.rs1-287 codex-rs/protocol/src/openai_models.rs40-52 codex-rs/protocol/src/openai_models.rs221-226 codex-rs/core/tests/suite/remote_models.rs122-132
SharedModelsManager (codex-models-manager)RefreshStrategy codex-rs/core/tests/suite/remote_models.rs32ModelInfo codex-rs/core/tests/suite/remote_models.rs57-116ModelsCacheManagermodels_cache.json file in the local Codex home directory codex-rs/app-server/tests/common/models_cache.rs9ModelProvider (codex-model-provider)image_generation or web_search codex-rs/model-provider/src/provider.rs34-38memory_extraction_preferred_model codex-rs/model-provider/src/provider.rs117-122Sources: codex-rs/model-provider/src/provider.rs101-108 codex-rs/model-provider/src/provider.rs34-38 codex-rs/model-provider/src/provider.rs117-122 codex-rs/core/tests/suite/remote_models.rs32 codex-rs/core/tests/suite/remote_models.rs57-116 codex-rs/model-provider/src/amazon_bedrock/catalog.rs20-55 codex-rs/app-server/tests/suite/v2/model_list.rs98-103
This diagram bridges the "Natural Language Space" (where users select models by name) to the "Code Entity Space" (where ModelInfo is resolved and used by the agent).
Sources: codex-rs/core/tests/suite/remote_models.rs101-111 codex-rs/app-server/tests/suite/v2/model_list.rs170-197 codex-rs/protocol/src/openai_models.rs196-197 codex-rs/model-provider/src/provider.rs101-108
The model list refresh behavior is controlled by the RefreshStrategy enum codex-rs/core/tests/suite/remote_models.rs32:
| Strategy | Behavior |
|---|---|
Online | Always perform network fetch, ignoring local cache. |
Offline | Use only the local cache; never perform network requests. |
OnlineIfUncached | Use local cached models if present and fresh; otherwise fetch online codex-rs/core/tests/suite/remote_models.rs108 |
models_cache.json contains a timestamp fetched_at which determines TTL freshness.ModelsManager loads the cache, it verifies that the cache version matches the running binary's client version to ensure field compatibility codex-rs/protocol/src/openai_models.rs3-5model/list response codex-rs/app-server/tests/suite/v2/model_list.rs170-185Sources: codex-rs/core/tests/suite/remote_models.rs32 codex-rs/core/tests/suite/remote_models.rs108 codex-rs/app-server/tests/suite/v2/model_list.rs170-185 codex-rs/protocol/src/openai_models.rs3-5
When a model slug is requested, SharedModelsManager resolves it by searching the cached list for the best matching ModelInfo based on longest matching slug prefix.
This diagram shows how a specific user request maps to a concrete code entity (ModelInfo) even when an exact match is missing.
Sources: codex-rs/core/tests/suite/remote_models.rs57-121 codex-rs/core/tests/suite/remote_models.rs113-118
After resolving the base ModelInfo, the system applies runtime overrides and clamps values to safety limits:
model_context_window override, the system clamps this value to the max_context_window advertised by the model codex-rs/core/tests/suite/remote_models.rs127-185config.base_instructions is provided, it replaces the model's default instructions verbatim and disables personality templates codex-rs/core/tests/suite/personality.rs109-127Personality feature is enabled codex-rs/core/tests/suite/personality.rs96-98 the manager uses get_model_instructions(personality) to inject personality-specific strings into the prompt codex-rs/core/tests/suite/personality.rs103-104 This involves replacing the {{ personality }} placeholder codex-rs/protocol/src/openai_models.rs34ModelInfo.input_modalities to ensure the model supports required types like InputModality::Image codex-rs/protocol/src/openai_models.rs149-154 This is enforced in handlers like ViewImageHandler codex-rs/core/src/tools/handlers/view_image.rs89-98service_tiers (e.g., fast) and a default_service_tier codex-rs/protocol/src/openai_models.rs194-226<model_switch> developer message to the context to inform the new model of the previous state codex-rs/core/tests/suite/model_switching.rs121-183Sources: codex-rs/core/tests/suite/remote_models.rs127-185 codex-rs/core/tests/suite/personality.rs109-127 codex-rs/protocol/src/openai_models.rs34 codex-rs/protocol/src/openai_models.rs149-154 codex-rs/protocol/src/openai_models.rs194-226 codex-rs/core/src/tools/handlers/view_image.rs89-98 codex-rs/core/tests/suite/model_switching.rs121-183
SharedModelsManager provides models with TruncationPolicyConfig which determines how large tool outputs are handled.
Bytes or Tokens codex-rs/protocol/src/openai_models.rs221-226Sources: codex-rs/protocol/src/openai_models.rs221-226 codex-rs/core/tests/suite/model_switching.rs108
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.