Model Picker

Contents

Overview

Core Types

The model picker revolves around two data structures: ConfiguredEntry which represents a model reference extracted from the user's config, and ModelRow which is the display-ready row shown to the user in listings and scan results.

ConfiguredEntry

Each entry in the user's configuration — default model, fallback chain, image model — is normalized into a ConfiguredEntry. The tags set indicates why this entry exists (e.g. "default", "fallback#1", "image").

// src/commands/models/list.types.ts
export type ConfiguredEntry = {
  key: string;
  ref: { provider: string; model: string };
  tags: Set<string>;
  aliases: string[];
};

ModelRow

The presentation-layer type used by the /model list and /model scan commands to render tabular output. Produced by the toModelRow() transform function.

// src/commands/models/list.types.ts
export type ModelRow = {
  key: string;
  name: string;
  input: string;
  contextWindow: number | null;
  local: boolean | null;
  available: boolean | null;
  tags: string[];
  missing: boolean;
};

Decision Points

How It Works

The model picker pipeline has three distinct phases: registry loading, configured entry resolution, and model selection/scanning. Each phase builds on the previous one's output.

Phase 1 — Registry Loading

The loadModelRegistry() function bootstraps the full model catalog from all configured providers. It discovers the agent directory, reads auth credentials, calls each provider's model enumeration API, and filters out suppressed built-in models.

// src/commands/models/list.registry.ts
export async function loadModelRegistry(
  cfg: OpenClawConfig,
  opts?: { sourceConfig?: OpenClawConfig },
) {
  const agentDir = resolveOpenClawAgentDir();
  const authStorage = discoverAuthStorage(agentDir);
  const registry = discoverModels(authStorage, agentDir);
  const models = registry
    .getAll()
    .filter((model) =>
      !shouldSuppressBuiltInModel({
        provider: model.provider,
        id: model.id,
      }),
    );
  // ... availability checking against auth credentials
  return { registry, models, availableKeys, availabilityErrorMessage };
}

Phase 2 — Configured Entry Resolution

Once the registry is loaded, resolveConfiguredEntries() walks the user's OpenClawConfig to extract every model reference and assign semantic tags. The function processes entries in a fixed order: default model first, then fallback chain, then image model, then image fallback chain, and finally any explicitly configured model entries.

// src/commands/models/list.configured.ts
export function resolveConfiguredEntries(cfg: OpenClawConfig) {
  // resolves default, fallbacks, image model, configured models
  // Tags: "default", "fallback#N", "image", "img-fallback#N", "configured"
  return { entries };
}

Phase 3 — Model Selection Commands

The modelsSetCommand and modelsSetImageCommand functions handle the final step: persisting the user's choice into the config file. Both follow the same pattern — call updateConfig() with a mutation function, log the result, and confirm to the user.

// src/commands/models/set.ts
export async function modelsSetCommand(
  modelRaw: string,
  runtime: RuntimeEnv,
) {
  const updated = await updateConfig((cfg) => {
    return applyDefaultModelPrimaryUpdate({
      cfg,
      modelRaw,
      field: "model",
    });
  });
  logConfigUpdated(runtime);
  runtime.log(
    `Default model: ${
      resolveAgentModelPrimaryValue(updated.agents?.defaults?.model)
        ?? modelRaw
    }`,
  );
}

// src/commands/models/set-image.ts
export async function modelsSetImageCommand(
  modelRaw: string,
  runtime: RuntimeEnv,
) {
  const updated = await updateConfig((cfg) => {
    return applyDefaultModelPrimaryUpdate({
      cfg,
      modelRaw,
      field: "imageModel",
    });
  });
  logConfigUpdated(runtime);
  runtime.log(
    `Image model: ${
      resolveAgentModelPrimaryValue(updated.agents?.defaults?.imageModel)
        ?? modelRaw
    }`,
  );
}

Model Selection Pipeline

The following flowchart shows the complete decision path from a user's /model set command to the final config write. Each diamond is a decision point; each rectangle is a processing step.

flowchart TD
  CMD["User runs /model set <key>"]
  LOAD["loadModelRegistry(cfg)"]
  DISCOVER["discoverModels(authStorage, agentDir)"]
  FILTER{"shouldSuppressBuiltInModel?"}
  AVAIL["Check availability against auth"]
  RESOLVE["resolveConfiguredEntries(cfg)"]
  LOOKUP{"Model key in registry?"}
  APPLY["applyDefaultModelPrimaryUpdate()"]
  WRITE["updateConfig() — persist to disk"]
  LOG["logConfigUpdated(runtime)"]
  CONFIRM["runtime.log — confirm to user"]
  ERR["Error: model not found"]

  CMD --> LOAD
  LOAD --> DISCOVER
  DISCOVER --> FILTER
  FILTER -->|Suppressed| DISCOVER
  FILTER -->|Kept| AVAIL
  AVAIL --> RESOLVE
  RESOLVE --> LOOKUP
  LOOKUP -->|Yes| APPLY
  LOOKUP -->|No| ERR
  APPLY --> WRITE
  WRITE --> LOG
  LOG --> CONFIRM

The pipeline is intentionally linear for the set commands — there is no branching or retry logic. If the model key is not found in the registry, the command fails immediately with an error message. The scan command, by contrast, adds a probing loop before the selection step.

modelsSetCommand Flow

This sequence diagram traces the exact call chain when a user runs /model set gpt-4. Each participant corresponds to a source file, and every arrow is a real function call in the codebase.

sequenceDiagram
    participant User
    participant CLI as commands/models/set.ts
    participant Config as updateConfig()
    participant Apply as applyDefaultModelPrimaryUpdate()
    participant Resolve as resolveAgentModelPrimaryValue()
    participant Runtime as RuntimeEnv

    User->>CLI: /model set gpt-4
    CLI->>Config: updateConfig(mutationFn)
    Config->>Apply: applyDefaultModelPrimaryUpdate({cfg, modelRaw, field})
    Apply-->>Config: updated OpenClawConfig
    Config-->>CLI: persisted config object
    CLI->>Resolve: resolveAgentModelPrimaryValue(updated.agents.defaults.model)
    Resolve-->>CLI: "gpt-4" or null
    CLI->>Runtime: logConfigUpdated(runtime)
    CLI->>Runtime: runtime.log("Default model: gpt-4")
    Runtime-->>User: "Default model: gpt-4"

Notice that resolveAgentModelPrimaryValue is called after the config write. This is intentional — it reads the updated config to resolve any alias or provider-qualified name back to a human-readable form. If resolution fails (returns null), the raw user input is echoed instead.

Model Scan Pipeline

The modelsScanCommand extends the basic selection flow with concurrent availability probing. It enumerates candidate models, probes each for reachability (respecting concurrency and timeout limits), and optionally auto-selects the best candidate.

flowchart TD
  SCAN["User runs /model scan"]
  OPTS["Parse scan options"]
  LOAD2["loadModelRegistry(cfg)"]
  CANDIDATES["Filter candidates by provider, minParams, maxAge"]
  PROBE{"Probe each candidate"}
  REACHABLE["Collect reachable models"]
  RANK["Rank by context window and capabilities"]
  AUTO{"--setDefault or --setImage?"}
  SET["modelsSetCommand / modelsSetImageCommand"]
  DISPLAY["Display scan results as ModelRow table"]
  JSON{"--json flag?"}
  JSONOUT["Output JSON array"]

  SCAN --> OPTS
  OPTS --> LOAD2
  LOAD2 --> CANDIDATES
  CANDIDATES --> PROBE
  PROBE --> REACHABLE
  REACHABLE --> RANK
  RANK --> AUTO
  AUTO -->|Yes| SET
  AUTO -->|No| DISPLAY
  RANK --> JSON
  JSON -->|Yes| JSONOUT
  JSON -->|No| DISPLAY

Code Walkthrough: toModelRow

The toModelRow function is the bridge between the internal Model<Api> objects and the user-facing ModelRow display type. Here is how each piece of data is resolved, step by step.

// src/commands/models/list.registry.ts
export function toModelRow(params: {
  model?: Model<Api>;
  key: string;
  tags: string[];
  aliases?: string[];
  availableKeys?: Set<string>;
  cfg?: OpenClawConfig;
  authStore?: AuthProfileStore;
  allowProviderAvailabilityFallback?: boolean;
}): ModelRow

Edge Cases

Configuration

// src/commands/models/scan.ts — full signature
export async function modelsScanCommand(
  opts: {
    minParams?: string;
    maxAgeDays?: string;
    provider?: string;
    maxCandidates?: string;
    timeout?: string;
    concurrency?: string;
    yes?: boolean;
    input?: boolean;
    setDefault?: boolean;
    setImage?: boolean;
    json?: boolean;
    probe?: boolean;
  },
  runtime: RuntimeEnv,
)

Related Topics

Source Files

src/
└── commands/
    └── models/
        ├── list.types.ts          ← ConfiguredEntry & ModelRow type definitions
        ├── list.registry.ts       ← loadModelRegistry(), toModelRow() transform
        ├── list.configured.ts     ← resolveConfiguredEntries() tag resolution
        ├── set.ts                 ← modelsSetCommand() — set default model
        ├── set-image.ts           ← modelsSetImageCommand() — set image model
        └── scan.ts                ← modelsScanCommand() — probe & auto-select