diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7847e2cf5..ee69c343c 100644
--- a/CHANGELOG.md
+++ b/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`.
diff --git a/docs/start/wizard.md b/docs/start/wizard.md
index 333d332a9..761ef5a59 100644
--- a/docs/start/wizard.md
+++ b/docs/start/wizard.md
@@ -88,9 +88,9 @@ 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.
+   - **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`.
    - More detail: [Synthetic](/providers/synthetic)
@@ -211,6 +211,7 @@ clawdbot onboard --non-interactive \
   --zai-api-key "$ZAI_API_KEY" \
   --gateway-port 18789 \
   --gateway-bind loopback
+```
 
 Vercel AI Gateway example:
 
@@ -222,7 +223,6 @@ clawdbot onboard --non-interactive \
   --gateway-port 18789 \
   --gateway-bind loopback
 ```
-```
 
 Moonshot example:
 
diff --git a/src/commands/auth-choice.test.ts b/src/commands/auth-choice.test.ts
index b1f81acb1..598fd2320 100644
--- a/src/commands/auth-choice.test.ts
+++ b/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;
diff --git a/src/commands/onboard-non-interactive.ai-gateway.test.ts b/src/commands/onboard-non-interactive.ai-gateway.test.ts
new file mode 100644
index 000000000..1107f1e2a
--- /dev/null
+++ b/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);
+});