Merge pull request #1016 from timolins/main

Models: add Vercel AI Gateway auth

CHANGELOG.md

@@ -39,6 +39,7 @@
 - Messages: debounce rapid inbound messages across channels with per-connector overrides. (#971) — thanks @juanpablodlc.
 - Messages: allow media-only sends (CLI/tool) and show Telegram voice recording status for voice notes. (#957) — thanks @rdev.
 - Auth/Status: keep auth profiles sticky per session (rotate on compaction/new), surface provider usage headers in `/status` and `clawdbot models status`, and update docs.
+- Models: add Vercel AI Gateway auth choice + onboarding docs. (#1016) — thanks @timolins.
 - CLI: add `--json` output for `clawdbot daemon` lifecycle/install commands.
 - Memory: make `node-llama-cpp` an optional dependency (avoid Node 25 install failures) and improve local-embeddings fallback/errors.
 - Browser: add `snapshot refs=aria` (Playwright aria-ref ids) for self-resolving refs across `snapshot` → `act`.

docs/cli/index.md

@@ -283,7 +283,7 @@ Options:
 - `--non-interactive`
 - `--mode <local|remote>`
 - `--flow <quickstart|advanced>`
-- `--auth-choice <setup-token|claude-cli|token|openai-codex|openai-api-key|openrouter-api-key|moonshot-api-key|codex-cli|antigravity|gemini-api-key|zai-api-key|apiKey|minimax-api|opencode-zen|skip>`
+- `--auth-choice <setup-token|claude-cli|token|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|codex-cli|antigravity|gemini-api-key|zai-api-key|apiKey|minimax-api|opencode-zen|skip>`
 - `--token-provider <id>` (non-interactive; used with `--auth-choice token`)
 - `--token <token>` (non-interactive; used with `--auth-choice token`)
 - `--token-profile-id <id>` (non-interactive; default: `<provider>:manual`)
@@ -291,6 +291,7 @@ Options:
 - `--anthropic-api-key <key>`
 - `--openai-api-key <key>`
 - `--openrouter-api-key <key>`
+- `--ai-gateway-api-key <key>`
 - `--moonshot-api-key <key>`
 - `--gemini-api-key <key>`
 - `--zai-api-key <key>`

docs/concepts/model-providers.md

@@ -93,6 +93,13 @@ Clawdbot ships with the pi‑ai catalog. These providers require **no**
 - CLI: `clawdbot onboard --auth-choice zai-api-key`
   - Aliases: `z.ai/*` and `z-ai/*` normalize to `zai/*`
 
+### Vercel AI Gateway
+
+- Provider: `vercel-ai-gateway`
+- Auth: `AI_GATEWAY_API_KEY`
+- Example model: `vercel-ai-gateway/anthropic/claude-opus-4.5`
+- CLI: `clawdbot onboard --auth-choice ai-gateway-api-key`
+
 ### Other built-in providers
 
 - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`)

docs/providers/index.md

@@ -27,6 +27,7 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/etc.)? See [Chann
 - [OpenAI (API + Codex)](/providers/openai)
 - [Anthropic (API + Claude Code CLI)](/providers/anthropic)
 - [OpenRouter](/providers/openrouter)
+- [Vercel AI Gateway](/providers/vercel-ai-gateway)
 - [Moonshot AI (Kimi)](/providers/moonshot)
 - [OpenCode Zen](/providers/opencode)
 - [Z.AI](/providers/zai)

docs/providers/models.md

@@ -25,6 +25,7 @@ model as `provider/model`.
 - [OpenAI (API + Codex)](/providers/openai)
 - [Anthropic (API + Claude Code CLI)](/providers/anthropic)
 - [OpenRouter](/providers/openrouter)
+- [Vercel AI Gateway](/providers/vercel-ai-gateway)
 - [Moonshot AI (Kimi)](/providers/moonshot)
 - [Synthetic](/providers/synthetic)
 - [OpenCode Zen](/providers/opencode)

docs/providers/vercel-ai-gateway.md

@@ -0,0 +1,49 @@
+---
+summary: "Vercel AI Gateway setup (auth + model selection)"
+read_when:
+  - You want to use Vercel AI Gateway with Clawdbot
+  - You need the API key env var or CLI auth choice
+---
+# Vercel AI Gateway
+
+
+The [Vercel AI Gateway](https://vercel.com/ai-gateway) provides a unified API to access hundreds of models through a single endpoint. 
+
+- Provider: `vercel-ai-gateway`
+- Auth: `AI_GATEWAY_API_KEY`
+- API: Anthropic Messages compatible
+
+## Quick start
+
+1) Set the API key (recommended: store it for the Gateway):
+
+```bash
+clawdbot onboard --auth-choice ai-gateway-api-key
+```
+
+2) Set a default model:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "vercel-ai-gateway/anthropic/claude-opus-4.5" }
+    }
+  }
+}
+```
+
+## Non-interactive example
+
+```bash
+clawdbot onboard --non-interactive \
+  --mode local \
+  --auth-choice ai-gateway-api-key \
+  --ai-gateway-api-key "$AI_GATEWAY_API_KEY"
+```
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure `AI_GATEWAY_API_KEY`
+is available to that process (for example, in `~/.clawdbot/.env` or via
+`env.shellEnv`).

docs/start/wizard.md

@@ -45,7 +45,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
 ## What the wizard does
 
 **Local mode (default)** walks you through:
-- Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or `claude setup-token`, plus MiniMax/GLM/Moonshot options)
+  - Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or `claude setup-token`, plus MiniMax/GLM/Moonshot/AI Gateway options)
 - Workspace location + bootstrap files
 - Gateway settings (port/bind/auth/tailscale)
 - Providers (Telegram, WhatsApp, Discord, Signal)
@@ -88,6 +88,8 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
    - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.clawdbot/.env` so launchd can read it.
    - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth).
    - **API key**: stores the key for you.
+   - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.
+   - More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway)
    - **MiniMax M2.1**: config is auto-written.
    - More detail: [MiniMax](/providers/minimax)
    - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.
@@ -211,6 +213,17 @@ clawdbot onboard --non-interactive \
   --gateway-bind loopback
 ```
 
+Vercel AI Gateway example:
+
+```bash
+clawdbot onboard --non-interactive \
+  --mode local \
+  --auth-choice ai-gateway-api-key \
+  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
 Moonshot example:
 
 ```bash

src/agents/model-auth.test.ts

@@ -256,4 +256,28 @@ describe("getApiKeyForModel", () => {
       }
     }
   });
+
+  it("resolves Vercel AI Gateway API key from env", async () => {
+    const previousGatewayKey = process.env.AI_GATEWAY_API_KEY;
+
+    try {
+      process.env.AI_GATEWAY_API_KEY = "gateway-test-key";
+
+      vi.resetModules();
+      const { resolveApiKeyForProvider } = await import("./model-auth.js");
+
+      const resolved = await resolveApiKeyForProvider({
+        provider: "vercel-ai-gateway",
+        store: { version: 1, profiles: {} },
+      });
+      expect(resolved.apiKey).toBe("gateway-test-key");
+      expect(resolved.source).toContain("AI_GATEWAY_API_KEY");
+    } finally {
+      if (previousGatewayKey === undefined) {
+        delete process.env.AI_GATEWAY_API_KEY;
+      } else {
+        process.env.AI_GATEWAY_API_KEY = previousGatewayKey;
+      }
+    }
+  });
 });

src/agents/model-auth.ts

@@ -154,6 +154,7 @@ export function resolveEnvApiKey(provider: string): EnvApiKeyResult | null {
     cerebras: "CEREBRAS_API_KEY",
     xai: "XAI_API_KEY",
     openrouter: "OPENROUTER_API_KEY",
+    "vercel-ai-gateway": "AI_GATEWAY_API_KEY",
     moonshot: "MOONSHOT_API_KEY",
     minimax: "MINIMAX_API_KEY",
     synthetic: "SYNTHETIC_API_KEY",

src/cli/program/register.onboard.ts

@@ -51,7 +51,7 @@ export function registerOnboardCommand(program: Command) {
     .option("--mode <mode>", "Wizard mode: local|remote")
     .option(
       "--auth-choice <choice>",
-      "Auth: setup-token|claude-cli|token|chutes|openai-codex|openai-api-key|openrouter-api-key|moonshot-api-key|synthetic-api-key|codex-cli|antigravity|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip",
+      "Auth: setup-token|claude-cli|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|synthetic-api-key|codex-cli|antigravity|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip",
     )
     .option(
       "--token-provider <id>",
@@ -66,6 +66,7 @@ export function registerOnboardCommand(program: Command) {
     .option("--anthropic-api-key <key>", "Anthropic API key")
     .option("--openai-api-key <key>", "OpenAI API key")
     .option("--openrouter-api-key <key>", "OpenRouter API key")
+    .option("--ai-gateway-api-key <key>", "Vercel AI Gateway API key")
     .option("--moonshot-api-key <key>", "Moonshot API key")
     .option("--gemini-api-key <key>", "Gemini API key")
     .option("--zai-api-key <key>", "Z.AI API key")
@@ -113,6 +114,7 @@ export function registerOnboardCommand(program: Command) {
             anthropicApiKey: opts.anthropicApiKey as string | undefined,
             openaiApiKey: opts.openaiApiKey as string | undefined,
             openrouterApiKey: opts.openrouterApiKey as string | undefined,
+            aiGatewayApiKey: opts.aiGatewayApiKey as string | undefined,
             moonshotApiKey: opts.moonshotApiKey as string | undefined,
             geminiApiKey: opts.geminiApiKey as string | undefined,
             zaiApiKey: opts.zaiApiKey as string | undefined,

src/commands/auth-choice-options.test.ts

@@ -102,6 +102,18 @@ describe("buildAuthChoiceOptions", () => {
     expect(options.some((opt) => opt.value === "moonshot-api-key")).toBe(true);
   });
 
+  it("includes Vercel AI Gateway auth choice", () => {
+    const store: AuthProfileStore = { version: 1, profiles: {} };
+    const options = buildAuthChoiceOptions({
+      store,
+      includeSkip: false,
+      includeClaudeCliIfMissing: true,
+      platform: "darwin",
+    });
+
+    expect(options.some((opt) => opt.value === "ai-gateway-api-key")).toBe(true);
+  });
+
   it("includes Synthetic auth choice", () => {
     const store: AuthProfileStore = { version: 1, profiles: {} };
     const options = buildAuthChoiceOptions({

src/commands/auth-choice-options.ts

@@ -14,6 +14,7 @@ export type AuthChoiceGroupId =
   | "anthropic"
   | "google"
   | "openrouter"
+  | "ai-gateway"
   | "moonshot"
   | "zai"
   | "opencode-zen"
@@ -69,6 +70,12 @@ const AUTH_CHOICE_GROUP_DEFS: {
     hint: "API key",
     choices: ["openrouter-api-key"],
   },
+  {
+    value: "ai-gateway",
+    label: "Vercel AI Gateway",
+    hint: "API key",
+    choices: ["ai-gateway-api-key"],
+  },
   {
     value: "moonshot",
     label: "Moonshot AI",
@@ -168,6 +175,10 @@ export function buildAuthChoiceOptions(params: {
   options.push({ value: "chutes", label: "Chutes (OAuth)" });
   options.push({ value: "openai-api-key", label: "OpenAI API key" });
   options.push({ value: "openrouter-api-key", label: "OpenRouter API key" });
+  options.push({
+    value: "ai-gateway-api-key",
+    label: "Vercel AI Gateway API key",
+  });
   options.push({ value: "moonshot-api-key", label: "Moonshot AI API key" });
   options.push({ value: "synthetic-api-key", label: "Synthetic API key" });
   options.push({

src/commands/auth-choice.apply.api-providers.ts

@@ -21,15 +21,19 @@ import {
   applyOpenrouterProviderConfig,
   applySyntheticConfig,
   applySyntheticProviderConfig,
+  applyVercelAiGatewayConfig,
+  applyVercelAiGatewayProviderConfig,
   applyZaiConfig,
   MOONSHOT_DEFAULT_MODEL_REF,
   OPENROUTER_DEFAULT_MODEL_REF,
   SYNTHETIC_DEFAULT_MODEL_REF,
+  VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF,
   setGeminiApiKey,
   setMoonshotApiKey,
   setOpencodeZenApiKey,
   setOpenrouterApiKey,
   setSyntheticApiKey,
+  setVercelAiGatewayApiKey,
   setZaiApiKey,
   ZAI_DEFAULT_MODEL_REF,
 } from "./onboard-auth.js";
@@ -121,6 +125,48 @@ export async function applyAuthChoiceApiProviders(
     return { config: nextConfig, agentModelOverride };
   }
 
+  if (params.authChoice === "ai-gateway-api-key") {
+    let hasCredential = false;
+    const envKey = resolveEnvApiKey("vercel-ai-gateway");
+    if (envKey) {
+      const useExisting = await params.prompter.confirm({
+        message: `Use existing AI_GATEWAY_API_KEY (${envKey.source}, ${formatApiKeyPreview(envKey.apiKey)})?`,
+        initialValue: true,
+      });
+      if (useExisting) {
+        await setVercelAiGatewayApiKey(envKey.apiKey, params.agentDir);
+        hasCredential = true;
+      }
+    }
+    if (!hasCredential) {
+      const key = await params.prompter.text({
+        message: "Enter Vercel AI Gateway API key",
+        validate: validateApiKeyInput,
+      });
+      await setVercelAiGatewayApiKey(normalizeApiKeyInput(String(key)), params.agentDir);
+    }
+    nextConfig = applyAuthProfileConfig(nextConfig, {
+      profileId: "vercel-ai-gateway:default",
+      provider: "vercel-ai-gateway",
+      mode: "api_key",
+    });
+    {
+      const applied = await applyDefaultModelChoice({
+        config: nextConfig,
+        setDefaultModel: params.setDefaultModel,
+        defaultModel: VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF,
+        applyDefaultConfig: applyVercelAiGatewayConfig,
+        applyProviderConfig: applyVercelAiGatewayProviderConfig,
+        noteDefault: VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF,
+        noteAgentModel,
+        prompter: params.prompter,
+      });
+      nextConfig = applied.config;
+      agentModelOverride = applied.agentModelOverride ?? agentModelOverride;
+    }
+    return { config: nextConfig, agentModelOverride };
+  }
+
   if (params.authChoice === "moonshot-api-key") {
     let hasCredential = false;
     const envKey = resolveEnvApiKey("moonshot");

src/commands/auth-choice.preferred-provider.ts

@@ -11,6 +11,7 @@ const PREFERRED_PROVIDER_BY_AUTH_CHOICE: Partial<Record<AuthChoice, string>> = {
   chutes: "chutes",
   "openai-api-key": "openai",
   "openrouter-api-key": "openrouter",
+  "ai-gateway-api-key": "vercel-ai-gateway",
   "moonshot-api-key": "moonshot",
   "gemini-api-key": "google",
   "zai-api-key": "zai",

src/commands/auth-choice.test.ts

@@ -27,6 +27,7 @@ describe("applyAuthChoice", () => {
   const previousAgentDir = process.env.CLAWDBOT_AGENT_DIR;
   const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
   const previousOpenrouterKey = process.env.OPENROUTER_API_KEY;
+  const previousAiGatewayKey = process.env.AI_GATEWAY_API_KEY;
   const previousSshTty = process.env.SSH_TTY;
   const previousChutesClientId = process.env.CHUTES_CLIENT_ID;
   let tempStateDir: string | null = null;
@@ -57,6 +58,11 @@ describe("applyAuthChoice", () => {
     } else {
       process.env.OPENROUTER_API_KEY = previousOpenrouterKey;
     }
+    if (previousAiGatewayKey === undefined) {
+      delete process.env.AI_GATEWAY_API_KEY;
+    } else {
+      process.env.AI_GATEWAY_API_KEY = previousAiGatewayKey;
+    }
     if (previousSshTty === undefined) {
       delete process.env.SSH_TTY;
     } else {
@@ -330,6 +336,69 @@ describe("applyAuthChoice", () => {
     delete process.env.OPENROUTER_API_KEY;
   });
 
+  it("uses existing AI_GATEWAY_API_KEY when selecting ai-gateway-api-key", async () => {
+    tempStateDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-auth-"));
+    process.env.CLAWDBOT_STATE_DIR = tempStateDir;
+    process.env.CLAWDBOT_AGENT_DIR = path.join(tempStateDir, "agent");
+    process.env.PI_CODING_AGENT_DIR = process.env.CLAWDBOT_AGENT_DIR;
+    process.env.AI_GATEWAY_API_KEY = "gateway-test-key";
+
+    const text = vi.fn();
+    const select: WizardPrompter["select"] = vi.fn(
+      async (params) => params.options[0]?.value as never,
+    );
+    const multiselect: WizardPrompter["multiselect"] = vi.fn(async () => []);
+    const confirm = vi.fn(async () => true);
+    const prompter: WizardPrompter = {
+      intro: vi.fn(noopAsync),
+      outro: vi.fn(noopAsync),
+      note: vi.fn(noopAsync),
+      select,
+      multiselect,
+      text,
+      confirm,
+      progress: vi.fn(() => ({ update: noop, stop: noop })),
+    };
+    const runtime: RuntimeEnv = {
+      log: vi.fn(),
+      error: vi.fn(),
+      exit: vi.fn((code: number) => {
+        throw new Error(`exit:${code}`);
+      }),
+    };
+
+    const result = await applyAuthChoice({
+      authChoice: "ai-gateway-api-key",
+      config: {},
+      prompter,
+      runtime,
+      setDefaultModel: true,
+    });
+
+    expect(confirm).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: expect.stringContaining("AI_GATEWAY_API_KEY"),
+      }),
+    );
+    expect(text).not.toHaveBeenCalled();
+    expect(result.config.auth?.profiles?.["vercel-ai-gateway:default"]).toMatchObject({
+      provider: "vercel-ai-gateway",
+      mode: "api_key",
+    });
+    expect(result.config.agents?.defaults?.model?.primary).toBe(
+      "vercel-ai-gateway/anthropic/claude-opus-4.5",
+    );
+
+    const authProfilePath = authProfilePathFor(requireAgentDir());
+    const raw = await fs.readFile(authProfilePath, "utf8");
+    const parsed = JSON.parse(raw) as {
+      profiles?: Record<string, { key?: string }>;
+    };
+    expect(parsed.profiles?.["vercel-ai-gateway:default"]?.key).toBe("gateway-test-key");
+
+    delete process.env.AI_GATEWAY_API_KEY;
+  });
+
   it("writes Chutes OAuth credentials when selecting chutes (remote/manual)", async () => {
     tempStateDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-auth-"));
     process.env.CLAWDBOT_STATE_DIR = tempStateDir;

src/commands/onboard-auth.config-core.ts

@@ -5,7 +5,11 @@ import {
   SYNTHETIC_MODEL_CATALOG,
 } from "../agents/synthetic-models.js";
 import type { ClawdbotConfig } from "../config/config.js";
-import { OPENROUTER_DEFAULT_MODEL_REF, ZAI_DEFAULT_MODEL_REF } from "./onboard-auth.credentials.js";
+import {
+  OPENROUTER_DEFAULT_MODEL_REF,
+  VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF,
+  ZAI_DEFAULT_MODEL_REF,
+} from "./onboard-auth.credentials.js";
 import {
   buildMoonshotModelDefinition,
   MOONSHOT_BASE_URL,
@@ -60,6 +64,47 @@ export function applyOpenrouterProviderConfig(cfg: ClawdbotConfig): ClawdbotConf
   };
 }
 
+export function applyVercelAiGatewayProviderConfig(cfg: ClawdbotConfig): ClawdbotConfig {
+  const models = { ...cfg.agents?.defaults?.models };
+  models[VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF] = {
+    ...models[VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF],
+    alias: models[VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF]?.alias ?? "Vercel AI Gateway",
+  };
+
+  return {
+    ...cfg,
+    agents: {
+      ...cfg.agents,
+      defaults: {
+        ...cfg.agents?.defaults,
+        models,
+      },
+    },
+  };
+}
+
+export function applyVercelAiGatewayConfig(cfg: ClawdbotConfig): ClawdbotConfig {
+  const next = applyVercelAiGatewayProviderConfig(cfg);
+  const existingModel = next.agents?.defaults?.model;
+  return {
+    ...next,
+    agents: {
+      ...next.agents,
+      defaults: {
+        ...next.agents?.defaults,
+        model: {
+          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
+            ? {
+                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
+              }
+            : undefined),
+          primary: VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF,
+        },
+      },
+    },
+  };
+}
+
 export function applyOpenrouterConfig(cfg: ClawdbotConfig): ClawdbotConfig {
   const next = applyOpenrouterProviderConfig(cfg);
   const existingModel = next.agents?.defaults?.model;

src/commands/onboard-auth.credentials.ts

@@ -88,6 +88,8 @@ export async function setSyntheticApiKey(key: string, agentDir?: string) {
 
 export const ZAI_DEFAULT_MODEL_REF = "zai/glm-4.7";
 export const OPENROUTER_DEFAULT_MODEL_REF = "openrouter/auto";
+export const VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF =
+  "vercel-ai-gateway/anthropic/claude-opus-4.5";
 
 export async function setZaiApiKey(key: string, agentDir?: string) {
   // Write to resolved agent dir so gateway finds credentials on startup.
@@ -114,6 +116,18 @@ export async function setOpenrouterApiKey(key: string, agentDir?: string) {
   });
 }
 
+export async function setVercelAiGatewayApiKey(key: string, agentDir?: string) {
+  upsertAuthProfile({
+    profileId: "vercel-ai-gateway:default",
+    credential: {
+      type: "api_key",
+      provider: "vercel-ai-gateway",
+      key,
+    },
+    agentDir: resolveAuthAgentDir(agentDir),
+  });
+}
+
 export async function setOpencodeZenApiKey(key: string, agentDir?: string) {
   upsertAuthProfile({
     profileId: "opencode:default",

src/commands/onboard-auth.ts

@@ -10,6 +10,8 @@ export {
   applyOpenrouterProviderConfig,
   applySyntheticConfig,
   applySyntheticProviderConfig,
+  applyVercelAiGatewayConfig,
+  applyVercelAiGatewayProviderConfig,
   applyZaiConfig,
 } from "./onboard-auth.config-core.js";
 export {
@@ -34,8 +36,10 @@ export {
   setOpencodeZenApiKey,
   setOpenrouterApiKey,
   setSyntheticApiKey,
+  setVercelAiGatewayApiKey,
   setZaiApiKey,
   writeOAuthCredentials,
+  VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF,
   ZAI_DEFAULT_MODEL_REF,
 } from "./onboard-auth.credentials.js";
 export {

src/commands/onboard-non-interactive.ai-gateway.test.ts

@@ -0,0 +1,95 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+describe("onboard (non-interactive): Vercel AI Gateway", () => {
+  it("stores the API key and configures the default model", async () => {
+    const prev = {
+      home: process.env.HOME,
+      stateDir: process.env.CLAWDBOT_STATE_DIR,
+      configPath: process.env.CLAWDBOT_CONFIG_PATH,
+      skipChannels: process.env.CLAWDBOT_SKIP_CHANNELS,
+      skipGmail: process.env.CLAWDBOT_SKIP_GMAIL_WATCHER,
+      skipCron: process.env.CLAWDBOT_SKIP_CRON,
+      skipCanvas: process.env.CLAWDBOT_SKIP_CANVAS_HOST,
+      token: process.env.CLAWDBOT_GATEWAY_TOKEN,
+      password: process.env.CLAWDBOT_GATEWAY_PASSWORD,
+    };
+
+    process.env.CLAWDBOT_SKIP_CHANNELS = "1";
+    process.env.CLAWDBOT_SKIP_GMAIL_WATCHER = "1";
+    process.env.CLAWDBOT_SKIP_CRON = "1";
+    process.env.CLAWDBOT_SKIP_CANVAS_HOST = "1";
+    delete process.env.CLAWDBOT_GATEWAY_TOKEN;
+    delete process.env.CLAWDBOT_GATEWAY_PASSWORD;
+
+    const tempHome = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-onboard-gateway-"));
+    process.env.HOME = tempHome;
+    delete process.env.CLAWDBOT_STATE_DIR;
+    delete process.env.CLAWDBOT_CONFIG_PATH;
+
+    const runtime = {
+      log: () => {},
+      error: (msg: string) => {
+        throw new Error(msg);
+      },
+      exit: (code: number) => {
+        throw new Error(`exit:${code}`);
+      },
+    };
+
+    try {
+      const { runNonInteractiveOnboarding } = await import("./onboard-non-interactive.js");
+      await runNonInteractiveOnboarding(
+        {
+          nonInteractive: true,
+          authChoice: "ai-gateway-api-key",
+          aiGatewayApiKey: "gateway-test-key",
+          skipHealth: true,
+          skipChannels: true,
+          skipSkills: true,
+          json: true,
+        },
+        runtime,
+      );
+
+      const { CONFIG_PATH_CLAWDBOT } = await import("../config/config.js");
+      const cfg = JSON.parse(await fs.readFile(CONFIG_PATH_CLAWDBOT, "utf8")) as {
+        auth?: {
+          profiles?: Record<string, { provider?: string; mode?: string }>;
+        };
+        agents?: { defaults?: { model?: { primary?: string } } };
+      };
+
+      expect(cfg.auth?.profiles?.["vercel-ai-gateway:default"]?.provider).toBe(
+        "vercel-ai-gateway",
+      );
+      expect(cfg.auth?.profiles?.["vercel-ai-gateway:default"]?.mode).toBe("api_key");
+      expect(cfg.agents?.defaults?.model?.primary).toBe(
+        "vercel-ai-gateway/anthropic/claude-opus-4.5",
+      );
+
+      const { ensureAuthProfileStore } = await import("../agents/auth-profiles.js");
+      const store = ensureAuthProfileStore();
+      const profile = store.profiles["vercel-ai-gateway:default"];
+      expect(profile?.type).toBe("api_key");
+      if (profile?.type === "api_key") {
+        expect(profile.provider).toBe("vercel-ai-gateway");
+        expect(profile.key).toBe("gateway-test-key");
+      }
+    } finally {
+      await fs.rm(tempHome, { recursive: true, force: true });
+      process.env.HOME = prev.home;
+      process.env.CLAWDBOT_STATE_DIR = prev.stateDir;
+      process.env.CLAWDBOT_CONFIG_PATH = prev.configPath;
+      process.env.CLAWDBOT_SKIP_CHANNELS = prev.skipChannels;
+      process.env.CLAWDBOT_SKIP_GMAIL_WATCHER = prev.skipGmail;
+      process.env.CLAWDBOT_SKIP_CRON = prev.skipCron;
+      process.env.CLAWDBOT_SKIP_CANVAS_HOST = prev.skipCanvas;
+      process.env.CLAWDBOT_GATEWAY_TOKEN = prev.token;
+      process.env.CLAWDBOT_GATEWAY_PASSWORD = prev.password;
+    }
+  }, 60_000);
+});

src/commands/onboard-non-interactive/local/auth-choice.ts

@@ -19,6 +19,7 @@ import {
   applyOpencodeZenConfig,
   applyOpenrouterConfig,
   applySyntheticConfig,
+  applyVercelAiGatewayConfig,
   applyZaiConfig,
   setAnthropicApiKey,
   setGeminiApiKey,
@@ -27,6 +28,7 @@ import {
   setOpencodeZenApiKey,
   setOpenrouterApiKey,
   setSyntheticApiKey,
+  setVercelAiGatewayApiKey,
   setZaiApiKey,
 } from "../../onboard-auth.js";
 import type { AuthChoice, OnboardOptions } from "../../onboard-types.js";
@@ -191,6 +193,25 @@ export async function applyNonInteractiveAuthChoice(params: {
     return applyOpenrouterConfig(nextConfig);
   }
 
+  if (authChoice === "ai-gateway-api-key") {
+    const resolved = await resolveNonInteractiveApiKey({
+      provider: "vercel-ai-gateway",
+      cfg: baseConfig,
+      flagValue: opts.aiGatewayApiKey,
+      flagName: "--ai-gateway-api-key",
+      envVar: "AI_GATEWAY_API_KEY",
+      runtime,
+    });
+    if (!resolved) return null;
+    if (resolved.source !== "profile") await setVercelAiGatewayApiKey(resolved.key);
+    nextConfig = applyAuthProfileConfig(nextConfig, {
+      profileId: "vercel-ai-gateway:default",
+      provider: "vercel-ai-gateway",
+      mode: "api_key",
+    });
+    return applyVercelAiGatewayConfig(nextConfig);
+  }
+
   if (authChoice === "moonshot-api-key") {
     const resolved = await resolveNonInteractiveApiKey({
       provider: "moonshot",

src/commands/onboard-types.ts

@@ -12,6 +12,7 @@ export type AuthChoice =
   | "openai-codex"
   | "openai-api-key"
   | "openrouter-api-key"
+  | "ai-gateway-api-key"
   | "moonshot-api-key"
   | "synthetic-api-key"
   | "codex-cli"
@@ -55,6 +56,7 @@ export type OnboardOptions = {
   anthropicApiKey?: string;
   openaiApiKey?: string;
   openrouterApiKey?: string;
+  aiGatewayApiKey?: string;
   moonshotApiKey?: string;
   geminiApiKey?: string;
   zaiApiKey?: string;

src/config/io.ts

@@ -38,6 +38,7 @@ const SHELL_ENV_EXPECTED_KEYS = [
   "GEMINI_API_KEY",
   "ZAI_API_KEY",
   "OPENROUTER_API_KEY",
+  "AI_GATEWAY_API_KEY",
   "MINIMAX_API_KEY",
   "SYNTHETIC_API_KEY",
   "ELEVENLABS_API_KEY",