Provider Flow

Contents

Overview

flowchart TD
  CFG["OpenClawConfig"]
  RESOLVE["resolveModelsAuthContext()"]
  PROVIDERS["Provider list"]
  MODELS["Model candidates"]
  BUILD["buildProbeTargets()"]
  TARGETS["AuthProbeTarget[]"]
  EARLY["Early-exit results"]
  PROBE["runAuthProbes()"]
  CONCURRENT["Concurrent HTTP probes"]
  COLLECT["Collect results + latency"]
  SUMMARY["AuthProbeSummary"]
  ORDER["Auth order filtering"]
  DISPLAY["Display to user / route to handler"]

  CFG --> RESOLVE
  RESOLVE --> PROVIDERS
  RESOLVE --> MODELS
  PROVIDERS --> BUILD
  MODELS --> BUILD
  BUILD --> TARGETS
  BUILD --> EARLY
  TARGETS --> PROBE
  PROBE --> CONCURRENT
  CONCURRENT --> COLLECT
  COLLECT --> SUMMARY
  EARLY --> SUMMARY
  SUMMARY --> ORDER
  ORDER --> DISPLAY

The diagram shows the full provider auth pipeline. Configuration enters at the top and is resolved into provider and model lists. The buildProbeTargets function generates concrete probe targets (some may be excluded early with reason codes). The remaining targets are probed concurrently, and results are collected into an AuthProbeSummary. Auth order commands can then filter or re-rank the results before they are displayed or used for routing.

Core Types

The provider flow module revolves around two key type families: probe results that capture the outcome of individual auth checks, and provider overviews that summarize the effective credential state for display commands.

AuthProbeResult & AuthProbeStatus

Each probe target produces an AuthProbeResult with a status enum indicating whether the credential is valid, rate-limited, expired, or otherwise unusable. The reasonCode field provides machine-readable detail for failures.

// src/commands/models/auth.ts
export type AuthProbeStatus =
  | "ok"
  | "auth"
  | "rate_limit"
  | "billing"
  | "timeout"
  | "format"
  | "unknown"
  | "no_model";

export type AuthProbeReasonCode =
  | "excluded_by_auth_order"
  | "missing_credential"
  | "expired"
  | "invalid_expires"
  | "unresolved_ref"
  | "ineligible_profile"
  | "no_model";

export type AuthProbeResult = {
  provider: string;
  model?: string;
  profileId?: string;
  label: string;
  source: "profile" | "env" | "models.json";
  mode?: string;
  status: AuthProbeStatus;
  reasonCode?: AuthProbeReasonCode;
  error?: string;
  latencyMs?: number;
};

AuthProbeSummary

The summary type wraps all individual results with timing metadata. The durationMs field measures wall-clock time for the entire probe batch, including concurrency overhead.

// src/commands/models/auth.ts
export type AuthProbeSummary = {
  startedAt: number;
  finishedAt: number;
  durationMs: number;
  totalTargets: number;
  options: AuthProbeOptions;
  results: AuthProbeResult[];
};

ProviderAuthOverview

Used by the models list display layer, this type summarizes the effective auth configuration for a single provider without performing any live probes.

// src/commands/models/list.types.ts
export type ProviderAuthOverview = {
  provider: string;
  effective: {
    kind: "profiles" | "env" | "models.json" | "missing";
    detail: string;
  };
  profiles: {
    count: number;
    oauth: number;
    token: number;
    apiKey: number;
    labels: string[];
  };
  env?: { value: string; source: string };
  modelsJson?: { value: string; source: string };
};

Decision Points

How It Works

The provider flow pipeline operates in four distinct phases: context resolution, target building, concurrent probing, and order management. Each phase is implemented as a separate async function, enabling callers to compose only the phases they need.

Phase 1 — Auth Context Resolution

Before any probing can occur, the pipeline must resolve the current configuration into a structured auth context. The resolveModelsAuthContext function loads and validates the config, resolves the default agent, and discovers all available plugin providers.

// src/commands/models/auth.ts
async function resolveModelsAuthContext(): Promise<ResolvedModelsAuthContext> {
  const config = await loadValidConfigOrThrow();
  const defaultAgentId = resolveDefaultAgentId(config);
  const agentDir = resolveAgentDir(config, defaultAgentId);
  const workspaceDir =
    resolveAgentWorkspaceDir(config, defaultAgentId) ??
    resolveDefaultAgentWorkspaceDir();
  const providers = resolvePluginProviders({
    config,
    workspaceDir,
    // ... additional options
  });
  return { config, agentDir, workspaceDir, providers };
}

Phase 2 — Probe Target Building

The buildProbeTargets function takes the resolved providers and model candidates and produces two outputs: a list of AuthProbeTarget objects for live probing and a list of AuthProbeResult objects for targets that were excluded early.

// src/commands/models/auth.ts
export async function buildProbeTargets(params: {
  cfg: OpenClawConfig;
  providers: string[];
  modelCandidates: string[];
  options: AuthProbeOptions;
}): Promise<{
  targets: AuthProbeTarget[];
  results: AuthProbeResult[];
}>

Phase 3 — Concurrent Auth Probing

The runAuthProbes function takes the targets from Phase 2 and executes lightweight HTTP requests against each provider endpoint in parallel. It reports progress via an optional callback and returns the complete AuthProbeSummary.

// src/commands/models/auth.ts
export async function runAuthProbes(params: {
  cfg: OpenClawConfig;
  providers: string[];
  modelCandidates: string[];
  options: AuthProbeOptions;
  onProgress?: (update: {
    completed: number;
    total: number;
    label?: string;
  }) => void;
}): Promise<AuthProbeSummary>

sequenceDiagram
    participant Caller as Model Command
    participant Run as runAuthProbes()
    participant Build as buildProbeTargets()
    participant P1 as Provider A Probe
    participant P2 as Provider B Probe
    participant P3 as Provider C Probe
    participant Summary as AuthProbeSummary

    Caller->>Run: providers, modelCandidates, options
    Run->>Build: cfg, providers, modelCandidates
    Build-->>Run: targets[A,B,C] + earlyExits[D]
    par Concurrent probes
        Run->>P1: HTTP HEAD /v1/models (API key)
        Run->>P2: HTTP HEAD /v1/models (OAuth token)
        Run->>P3: HTTP HEAD /v1/models (env key)
    end
    P1-->>Run: 200 OK (45ms)
    P2-->>Run: 401 Unauthorized (32ms)
    P3-->>Run: 429 Rate Limited (120ms)
    Run->>Run: onProgress({ completed: 3, total: 3 })
    Run->>Summary: merge earlyExits + probe results
    Run-->>Caller: AuthProbeSummary

The sequence diagram shows how runAuthProbes orchestrates the full pipeline. It first calls buildProbeTargets to get the live targets and early-exit results. The live targets are probed concurrently (respecting the concurrency limit in AuthProbeOptions). Each probe returns an HTTP status code and latency measurement. The progress callback fires after each probe completes. Finally, early-exit results and live probe results are merged into a single AuthProbeSummary.

Phase 4 — Auth Order Management

Users can control which credentials are used for a given provider via three order management commands. These commands read and write a per-provider auth order that is respected by buildProbeTargets.

// src/commands/models/auth-order.ts
export async function modelsAuthOrderGetCommand(
  opts: { provider: string; agent?: string; json?: boolean },
  runtime: RuntimeEnv,
)

export async function modelsAuthOrderSetCommand(
  opts: { provider: string; agent?: string; order: string[] },
  runtime: RuntimeEnv,
)

export async function modelsAuthOrderClearCommand(
  opts: { provider: string; agent?: string },
  runtime: RuntimeEnv,
)

Edge Cases

Configuration

Related Topics

Source Files

src/
├── commands/
│   └── models/
│       ├── auth.ts                    ← AuthProbeResult, buildProbeTargets(), runAuthProbes()
│       ├── auth-order.ts              ← Auth order get/set/clear commands
│       ├── list.types.ts              ← ProviderAuthOverview display type
│       └── list.ts                    ← Models list command (uses ProviderAuthOverview)
├── config/
│   ├── loader.ts                      ← loadValidConfigOrThrow()
│   └── agents.ts                      ← resolveDefaultAgentId(), resolveAgentDir()
└── plugins/
    └── providers.ts                   ← resolvePluginProviders()