bug(ai-gateway): document that provider API key env vars must be ABSENT (not empty) for auto-routing

[sakdbag]

What I observed

Migrating a classifier from @anthropic-ai/sdk to the AI SDK + Gateway pattern (per the ai-gateway skill) produced 401 invalid x-api-key from api.anthropic.com on every call, even after:

• Enabling AI Gateway in the project's Vercel dashboard
• Updating the model string to "anthropic/claude-haiku-4.5"
• Confirming VERCEL_OIDC_TOKEN is auto-injected on deploys

Vercel runtime logs showed the request hit api.anthropic.com directly (cookie Domain confirmed upstream), not ai-gateway.vercel.sh.

Cause: ANTHROPIC_API_KEY was still set in Vercel env (with an empty-string value, leftover from the previous direct-provider integration). The AI SDK detects the env-var presence (regardless of value) and chooses direct-provider mode over gateway routing. Empty key then 401s upstream.

What I expected

The current skill says:

Pass a "provider/model" string to the model parameter — the AI SDK automatically routes it through the AI Gateway
No gateway() wrapper or additional package needed.

I expected the model-string approach to route through the gateway once the dashboard had it enabled. Env-var absence wasn't a precondition I'd noticed.

Proposed fix

Add a gotcha note in the Setup or Authentication (OIDC) section:

Gotcha: provider-specific API key env vars must be ABSENT for auto-routing

If your Vercel project has a provider's static API key in env (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY), the AI SDK detects it and uses direct-provider mode instead of gateway routing — even when the value is an empty string. To force gateway routing, REMOVE the env var entirely:

vercel env rm ANTHROPIC_API_KEY production --yes
vercel env rm ANTHROPIC_API_KEY preview --yes
vercel env rm ANTHROPIC_API_KEY development --yes

Then trigger a redeploy so warm function instances cold-start with the new env. Verification: successful gateway-routed requests do NOT hit api.anthropic.com. Symptom of the misroute is 401 invalid x-api-key from the upstream provider despite AI Gateway showing as enabled.

Why this matters

Bites projects migrating from direct-provider SDK to AI Gateway — the most common migration the skill is helping with. The upstream-provider 401 is misleading because it looks like a key problem, not a routing problem, and the cure (REMOVE the env var, don't reset it) is non-obvious.

Context

• Plugin: vercel @ 0.40.0
• Skill: skills/ai-gateway/SKILL.md
• AI SDK: ai@^6.0.191
• Time debugging: ~20 minutes