# Vercel AI Gateway Provider — Implementation Checklist

**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:

```yaml
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).
