fix(models): discover Vercel AI Gateway catalog

CHANGELOG.md

@@ -54,6 +54,7 @@ Docs: https://docs.openclaw.ai
 ### Fixes
 
 - Models/MiniMax: stop advertising removed `MiniMax-M2.5-Lightning` in built-in provider catalogs, onboarding metadata, and docs; keep the supported fast-tier model as `MiniMax-M2.5-highspeed`.
+- Models/Vercel AI Gateway: synthesize the built-in `vercel-ai-gateway` provider from `AI_GATEWAY_API_KEY` and auto-discover the live `/v1/models` catalog so `/models vercel-ai-gateway` exposes current refs including `openai/gpt-5.4`.
 - Security/Config: fail closed when `loadConfig()` hits validation or read errors so invalid configs cannot silently fall back to permissive runtime defaults. (#9040) Thanks @joetomasone.
 - Memory/Hybrid search: preserve negative FTS5 BM25 relevance ordering in `bm25RankToScore()` so stronger keyword matches rank above weaker ones instead of collapsing or reversing scores. (#33757) Thanks @lsdcc01.
 - LINE/`requireMention` group gating: align inbound and reply-stage LINE group policy resolution across raw, `group:`, and `room:` keys (including account-scoped group config), preserve plugin-backed reply-stage fallback behavior, and add regression coverage for prefixed-only group/room config plus reply-stage policy resolution. (#35847) Thanks @kirisame-wang.

docs/providers/vercel-ai-gateway.md

@@ -13,6 +13,8 @@ The [Vercel AI Gateway](https://vercel.com/ai-gateway) provides a unified API to
 - Provider: `vercel-ai-gateway`
 - Auth: `AI_GATEWAY_API_KEY`
 - API: Anthropic Messages compatible
+- OpenClaw auto-discovers the Gateway `/v1/models` catalog, so `/models vercel-ai-gateway`
+  includes current model refs such as `vercel-ai-gateway/openai/gpt-5.4`.
 
 ## Quick start
 

src/agents/models-config.e2e-harness.ts

@@ -83,6 +83,7 @@ export async function withCopilotGithubToken<T>(
 }
 
 export const MODELS_CONFIG_IMPLICIT_ENV_VARS = [
+  "AI_GATEWAY_API_KEY",
   "CLOUDFLARE_AI_GATEWAY_API_KEY",
   "COPILOT_GITHUB_TOKEN",
   "GH_TOKEN",

src/agents/models-config.providers.ts

@@ -63,6 +63,7 @@ import {
   buildTogetherModelDefinition,
 } from "./together-models.js";
 import { discoverVeniceModels, VENICE_BASE_URL } from "./venice-models.js";
+import { discoverVercelAiGatewayModels, VERCEL_AI_GATEWAY_BASE_URL } from "./vercel-ai-gateway.js";
 
 type ModelsConfig = NonNullable<OpenClawConfig["models"]>;
 export type ProviderConfig = NonNullable<ModelsConfig["providers"]>[string];
@@ -953,6 +954,14 @@ async function buildHuggingfaceProvider(discoveryApiKey?: string): Promise<Provi
   };
 }
 
+async function buildVercelAiGatewayProvider(): Promise<ProviderConfig> {
+  return {
+    baseUrl: VERCEL_AI_GATEWAY_BASE_URL,
+    api: "anthropic-messages",
+    models: await discoverVercelAiGatewayModels(),
+  };
+}
+
 function buildTogetherProvider(): ProviderConfig {
   return {
     baseUrl: TOGETHER_BASE_URL,
@@ -1214,6 +1223,14 @@ export async function resolveImplicitProviders(params: {
     break;
   }
 
+  const vercelAiGatewayKey = resolveProviderApiKey("vercel-ai-gateway").apiKey;
+  if (vercelAiGatewayKey) {
+    providers["vercel-ai-gateway"] = {
+      ...(await buildVercelAiGatewayProvider()),
+      apiKey: vercelAiGatewayKey,
+    };
+  }
+
   // Ollama provider - auto-discover if running locally, or add if explicitly configured.
   // Use the user's configured baseUrl (from explicit providers) for model
   // discovery so that remote / non-default Ollama instances are reachable.

src/agents/models-config.providers.vercel-ai-gateway.test.ts

@@ -0,0 +1,87 @@
+import { mkdtempSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
+import { NON_ENV_SECRETREF_MARKER } from "./model-auth-markers.js";
+import { resolveImplicitProviders } from "./models-config.providers.js";
+import { VERCEL_AI_GATEWAY_BASE_URL } from "./vercel-ai-gateway.js";
+
+describe("vercel-ai-gateway provider resolution", () => {
+  it("adds the provider with GPT-5.4 models when AI_GATEWAY_API_KEY is present", async () => {
+    const envSnapshot = captureEnv(["AI_GATEWAY_API_KEY"]);
+    process.env.AI_GATEWAY_API_KEY = "vercel-gateway-test-key"; // pragma: allowlist secret
+    try {
+      const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
+      const providers = await resolveImplicitProviders({ agentDir });
+      const provider = providers?.["vercel-ai-gateway"];
+      expect(provider?.apiKey).toBe("AI_GATEWAY_API_KEY");
+      expect(provider?.api).toBe("anthropic-messages");
+      expect(provider?.baseUrl).toBe(VERCEL_AI_GATEWAY_BASE_URL);
+      expect(provider?.models?.some((model) => model.id === "openai/gpt-5.4")).toBe(true);
+      expect(provider?.models?.some((model) => model.id === "openai/gpt-5.4-pro")).toBe(true);
+    } finally {
+      envSnapshot.restore();
+    }
+  });
+
+  it("prefers env keyRef marker over runtime plaintext for persistence", async () => {
+    const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
+    const envSnapshot = captureEnv(["AI_GATEWAY_API_KEY"]);
+    delete process.env.AI_GATEWAY_API_KEY;
+
+    await writeFile(
+      join(agentDir, "auth-profiles.json"),
+      JSON.stringify(
+        {
+          version: 1,
+          profiles: {
+            "vercel-ai-gateway:default": {
+              type: "api_key",
+              provider: "vercel-ai-gateway",
+              key: "sk-runtime-vercel",
+              keyRef: { source: "env", provider: "default", id: "AI_GATEWAY_API_KEY" },
+            },
+          },
+        },
+        null,
+        2,
+      ),
+      "utf8",
+    );
+
+    try {
+      const providers = await resolveImplicitProviders({ agentDir });
+      expect(providers?.["vercel-ai-gateway"]?.apiKey).toBe("AI_GATEWAY_API_KEY");
+    } finally {
+      envSnapshot.restore();
+    }
+  });
+
+  it("uses non-env marker for non-env keyRef vercel profiles", async () => {
+    const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
+    await writeFile(
+      join(agentDir, "auth-profiles.json"),
+      JSON.stringify(
+        {
+          version: 1,
+          profiles: {
+            "vercel-ai-gateway:default": {
+              type: "api_key",
+              provider: "vercel-ai-gateway",
+              key: "sk-runtime-vercel",
+              keyRef: { source: "file", provider: "vault", id: "/vercel/ai-gateway/api-key" },
+            },
+          },
+        },
+        null,
+        2,
+      ),
+      "utf8",
+    );
+
+    const providers = await resolveImplicitProviders({ agentDir });
+    expect(providers?.["vercel-ai-gateway"]?.apiKey).toBe(NON_ENV_SECRETREF_MARKER);
+  });
+});

src/agents/vercel-ai-gateway.ts

@@ -0,0 +1,197 @@
+import type { ModelDefinitionConfig } from "../config/types.models.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+
+export const VERCEL_AI_GATEWAY_PROVIDER_ID = "vercel-ai-gateway";
+export const VERCEL_AI_GATEWAY_BASE_URL = "https://ai-gateway.vercel.sh";
+export const VERCEL_AI_GATEWAY_DEFAULT_MODEL_ID = "anthropic/claude-opus-4.6";
+export const VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF = `${VERCEL_AI_GATEWAY_PROVIDER_ID}/${VERCEL_AI_GATEWAY_DEFAULT_MODEL_ID}`;
+export const VERCEL_AI_GATEWAY_DEFAULT_CONTEXT_WINDOW = 200_000;
+export const VERCEL_AI_GATEWAY_DEFAULT_MAX_TOKENS = 128_000;
+export const VERCEL_AI_GATEWAY_DEFAULT_COST = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+} as const;
+
+const log = createSubsystemLogger("agents/vercel-ai-gateway");
+
+type VercelPricingShape = {
+  input?: number | string;
+  output?: number | string;
+  input_cache_read?: number | string;
+  input_cache_write?: number | string;
+};
+
+type VercelGatewayModelShape = {
+  id?: string;
+  name?: string;
+  context_window?: number;
+  max_tokens?: number;
+  tags?: string[];
+  pricing?: VercelPricingShape;
+};
+
+type VercelGatewayModelsResponse = {
+  data?: VercelGatewayModelShape[];
+};
+
+type StaticVercelGatewayModel = Omit<ModelDefinitionConfig, "cost"> & {
+  cost?: Partial<ModelDefinitionConfig["cost"]>;
+};
+
+const STATIC_VERCEL_AI_GATEWAY_MODEL_CATALOG: readonly StaticVercelGatewayModel[] = [
+  {
+    id: "anthropic/claude-opus-4.6",
+    name: "Claude Opus 4.6",
+    reasoning: true,
+    input: ["text", "image"],
+    contextWindow: 1_000_000,
+    maxTokens: 128_000,
+    cost: {
+      input: 5,
+      output: 25,
+      cacheRead: 0.5,
+      cacheWrite: 6.25,
+    },
+  },
+  {
+    id: "openai/gpt-5.4",
+    name: "GPT 5.4",
+    reasoning: true,
+    input: ["text", "image"],
+    contextWindow: 200_000,
+    maxTokens: 128_000,
+    cost: {
+      input: 2.5,
+      output: 15,
+      cacheRead: 0.25,
+    },
+  },
+  {
+    id: "openai/gpt-5.4-pro",
+    name: "GPT 5.4 Pro",
+    reasoning: true,
+    input: ["text", "image"],
+    contextWindow: 200_000,
+    maxTokens: 128_000,
+    cost: {
+      input: 30,
+      output: 180,
+      cacheRead: 0,
+    },
+  },
+] as const;
+
+function toPerMillionCost(value: number | string | undefined): number {
+  const numeric =
+    typeof value === "number"
+      ? value
+      : typeof value === "string"
+        ? Number.parseFloat(value)
+        : Number.NaN;
+  if (!Number.isFinite(numeric) || numeric < 0) {
+    return 0;
+  }
+  return numeric * 1_000_000;
+}
+
+function normalizeCost(pricing?: VercelPricingShape): ModelDefinitionConfig["cost"] {
+  return {
+    input: toPerMillionCost(pricing?.input),
+    output: toPerMillionCost(pricing?.output),
+    cacheRead: toPerMillionCost(pricing?.input_cache_read),
+    cacheWrite: toPerMillionCost(pricing?.input_cache_write),
+  };
+}
+
+function buildStaticModelDefinition(model: StaticVercelGatewayModel): ModelDefinitionConfig {
+  return {
+    id: model.id,
+    name: model.name,
+    reasoning: model.reasoning,
+    input: model.input,
+    contextWindow: model.contextWindow,
+    maxTokens: model.maxTokens,
+    cost: {
+      ...VERCEL_AI_GATEWAY_DEFAULT_COST,
+      ...model.cost,
+    },
+  };
+}
+
+function getStaticFallbackModel(id: string): ModelDefinitionConfig | undefined {
+  const fallback = STATIC_VERCEL_AI_GATEWAY_MODEL_CATALOG.find((model) => model.id === id);
+  return fallback ? buildStaticModelDefinition(fallback) : undefined;
+}
+
+export function getStaticVercelAiGatewayModelCatalog(): ModelDefinitionConfig[] {
+  return STATIC_VERCEL_AI_GATEWAY_MODEL_CATALOG.map(buildStaticModelDefinition);
+}
+
+function buildDiscoveredModelDefinition(
+  model: VercelGatewayModelShape,
+): ModelDefinitionConfig | null {
+  const id = typeof model.id === "string" ? model.id.trim() : "";
+  if (!id) {
+    return null;
+  }
+
+  const fallback = getStaticFallbackModel(id);
+  const contextWindow =
+    typeof model.context_window === "number" && Number.isFinite(model.context_window)
+      ? model.context_window
+      : (fallback?.contextWindow ?? VERCEL_AI_GATEWAY_DEFAULT_CONTEXT_WINDOW);
+  const maxTokens =
+    typeof model.max_tokens === "number" && Number.isFinite(model.max_tokens)
+      ? model.max_tokens
+      : (fallback?.maxTokens ?? VERCEL_AI_GATEWAY_DEFAULT_MAX_TOKENS);
+  const normalizedCost = normalizeCost(model.pricing);
+
+  return {
+    id,
+    name: (typeof model.name === "string" ? model.name.trim() : "") || fallback?.name || id,
+    reasoning:
+      Array.isArray(model.tags) && model.tags.includes("reasoning")
+        ? true
+        : (fallback?.reasoning ?? false),
+    input: Array.isArray(model.tags)
+      ? model.tags.includes("vision")
+        ? ["text", "image"]
+        : ["text"]
+      : (fallback?.input ?? ["text"]),
+    contextWindow,
+    maxTokens,
+    cost:
+      normalizedCost.input > 0 ||
+      normalizedCost.output > 0 ||
+      normalizedCost.cacheRead > 0 ||
+      normalizedCost.cacheWrite > 0
+        ? normalizedCost
+        : (fallback?.cost ?? VERCEL_AI_GATEWAY_DEFAULT_COST),
+  };
+}
+
+export async function discoverVercelAiGatewayModels(): Promise<ModelDefinitionConfig[]> {
+  if (process.env.VITEST || process.env.NODE_ENV === "test") {
+    return getStaticVercelAiGatewayModelCatalog();
+  }
+
+  try {
+    const response = await fetch(`${VERCEL_AI_GATEWAY_BASE_URL}/v1/models`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!response.ok) {
+      log.warn(`Failed to discover Vercel AI Gateway models: HTTP ${response.status}`);
+      return getStaticVercelAiGatewayModelCatalog();
+    }
+    const data = (await response.json()) as VercelGatewayModelsResponse;
+    const discovered = (data.data ?? [])
+      .map(buildDiscoveredModelDefinition)
+      .filter((entry): entry is ModelDefinitionConfig => entry !== null);
+    return discovered.length > 0 ? discovered : getStaticVercelAiGatewayModelCatalog();
+  } catch (error) {
+    log.warn(`Failed to discover Vercel AI Gateway models: ${String(error)}`);
+    return getStaticVercelAiGatewayModelCatalog();
+  }
+}