flynn/docs/plans/2026-02-15-vercel-ai-gateway-provider-checklist.md

Vercel AI Gateway Provider — Implementation Checklist

Archived (2026-02-18): Historical implementation checklist. Canonical status is tracked in docs/plans/state.json; unchecked boxes here are not active backlog unless explicitly re-opened.

Date: 2026-02-15

Parent roadmap: docs/plans/2026-02-15-openclaw-gap-roadmap.md

Goal: Close the gap item "Vercel AI Gateway" by adding a first-class model provider that routes through the Vercel AI Gateway using Flynn's existing OpenAI-compatible client path where possible.

Scope

• Add a new provider id (vercel or vercel_ai_gateway).
• Implement the provider via OpenAIClient when the gateway is OpenAI-compatible.
• Ensure the provider works with:
  • streaming (if supported by OpenAIClient path)
  • tool calling
  • model tier switching via /model <tier> <provider/model>

Non-goals:

• Implementing gateway-specific “extras” (tracing, metadata) unless required.

Design

Provider id

Recommended id: vercel (short) or vercel_ai_gateway (explicit).

Pick one and use it consistently in:

• MODEL_PROVIDERS in src/config/schema.ts
• docs + setup wizard provider list
• doctor checks

Config fields

Use the existing ModelConfig fields:

• endpoint: base URL of gateway (OpenAI-compatible)
• api_key: gateway API key (or env var)

Example:

models:
  default:
    provider: vercel_ai_gateway
    model: gpt-4.1
    endpoint: "https://gateway.ai.example.com/v1"
    api_key: "${VERCEL_AI_GATEWAY_API_KEY}"

PR Breakdown

PR 1 — Schema + factory wiring

Checklist:

• Add provider id to MODEL_PROVIDERS in src/config/schema.ts.
• Update createClientFromConfig() in src/daemon/models.ts:
  • map provider -> new OpenAIClient({ model, apiKey, baseURL })
  • require an API key (config or env var)
  • use cfg.endpoint as baseURL (or a sensible default if the gateway has one)
• Update /model strict-tier switching support (should be automatic once provider id is recognized).

Tests:

• Update src/config/schema.test.ts to accept the new provider enum.
• Add case to src/daemon/clientFactory.test.ts:
  • asserts the provider returns an OpenAI-compatible client
  • asserts baseURL is passed when endpoint is set

Acceptance:

• pnpm typecheck
• pnpm test:run src/daemon/clientFactory.test.ts src/config/schema.test.ts

---

PR 2 — Doctor + setup wizard + docs

Checklist:

• Update src/cli/doctor.ts provider key checks:
  • if Vercel gateway requires a key, ensure doctor warns when missing
• Update setup wizard provider picker (optional but recommended):
  • src/cli/setup/providers.ts
  • src/cli/setup/providers.test.ts
• Document provider config in README.md (one short snippet; avoid long docs).

Tests:

• pnpm test:run src/cli/setup/providers.test.ts (if changed)
• pnpm test:run src/cli/doctor.test.ts (if changed)

Acceptance:

• flynn doctor guidance includes Vercel gateway key/env var info.

---

PR 3 — Integration validation (optional)

Checklist:

• Add a simple smoke test using the synthetic provider style or a mocked OpenAI SDK path if possible.
• Ensure streaming works end-to-end via gateway.

Acceptance:

• A real config can run flynn send "hello" using the gateway provider.

Final Checks

• pnpm typecheck
• pnpm test:run
• Update docs/plans/state.json entry to completed once implemented (include test status).