astradevlabsastradevlabs
← All posts
Tutorials4 min

Field Guide: Route Codex and Claude Code Through Vercel AI Gateway After the August CLI Update

Tutorials

Vercel shipped a small but useful update on August 12, 2026: one CLI command can now detect supported coding agents on your machine, create an AI Gateway key, and write the agent configuration for you. If your team is already bouncing between Codex and Claude Code, that changes the setup from a docs scavenger hunt into a repeatable rollout.

This field guide keeps the scope narrow: route OpenAI Codex and Claude Code through Vercel AI Gateway, keep each tool working normally, and centralize spend and traces without rewriting your prompts or local workflows.

1. Start with the August 12 shortcut

The new entry point is the Vercel CLI command announced on August 12, 2026:

bash
vercel ai-gateway coding-agents setup

Vercel says the command detects supported agents on your machine, provisions an AI Gateway API key, and writes configuration for them automatically. That is the fastest path if you want a clean first pass and do not need custom profiles yet.

Use it first for two reasons:

  • It reduces hand-edited config drift across machines.
  • It gives you a known-good baseline before you start customizing models.

If the CLI does not see one of your agents, fall back to the manual setup below. The Gateway still works either way.

2. Understand what you are actually standardizing

AI Gateway is not a new coding agent. It is the routing layer in front of them.

That means the win is operational, not ergonomic:

  • one API key instead of separate provider keys per tool
  • one place to watch spend and traces
  • one catalog of models across providers
  • one fallback layer if you later decide to route the same model across providers

For a studio team, that is the real point. You are not teaching Codex or Claude Code a new workflow. You are making both tools show up in the same observability and billing surface.

3. Wire up Codex when you need explicit control

Vercel's Codex guide uses an AI_GATEWAY_API_KEY environment variable plus a provider block in ~/.codex/config.toml. The minimal working shape looks like this:

toml
profile = "default"

[model_providers.vercel]
name = "Vercel AI Gateway"
base_url = "https://ai-gateway.vercel.sh/v1"
env_key = "AI_GATEWAY_API_KEY"
wire_api = "chat"

[profiles.default]
model_provider = "vercel"
model = "openai/gpt-5.2-codex"

That does three things:

  1. Points Codex at Vercel instead of a direct provider.
  2. Pulls credentials from one env var.
  3. Lets you swap models later without changing the rest of your workflow.

If you want separate profiles for speed versus deeper reasoning, add them now. If not, skip it. One default profile is enough.

4. Wire up Claude Code without fighting old auth

Claude Code is simpler but easier to get subtly wrong if you have old Anthropic credentials lying around.

Vercel's Claude Code guide says to log out first, then set the Gateway endpoint and auth variables:

bash
claude /logout

export ANTHROPIC_BASE_URL="https://ai-gateway.vercel.sh"
export ANTHROPIC_AUTH_TOKEN="$AI_GATEWAY_API_KEY"
export ANTHROPIC_API_KEY=""

The last line matters. Leaving ANTHROPIC_API_KEY populated can cause confusing mixed-auth behavior, because Claude Code may keep trying the direct Anthropic path instead of the Gateway path.

If your team reports that Claude still works but the requests never appear in Vercel observability, this is the first thing to check.

5. Pick one model policy before the team improvises

The easiest rollout mistake is letting every engineer choose a different default model with no naming convention.

A practical starting policy is:

  • Codex default: one coding-specialized model, kept stable for repeatability.
  • Claude Code default: one stronger reasoning model for broader repo work.
  • Changes to defaults happen in one place and on a schedule, not ad hoc.

The Gateway helps because the provider string lives in config, not in each project's source tree. You can standardize model choices per tool without touching app code.

6. Verify the rollout the lazy way

Do not overbuild validation. Run one prompt in each agent, then check the Gateway dashboard.

Your checklist is short:

  1. Codex starts and answers through the Vercel provider profile.
  2. Claude Code starts after logout and uses the Gateway endpoint.
  3. Both requests show up in AI Gateway / Observability.
  4. Spend is visible under one account instead of split across providers.

If those four things are true, you have the value of the August update already. Advanced routing, fallbacks, and per-model policies can wait.

7. When to use the CLI shortcut versus manual config

Use vercel ai-gateway coding-agents setup when you want the fastest team-wide baseline.

Use manual config when:

  • you need multiple Codex profiles
  • you want to pin a specific model per agent
  • you are debugging why one tool is bypassing the Gateway
  • you need to review the exact file diff before changing developer machines

That is the whole pattern. Start with the new CLI path from August 12, drop to manual config only where the shortcut stops being precise enough, and keep the policy surface small.

For most teams, the important change is not that Vercel added another agent feature. It is that two popular coding agents can now be brought under one routing and observability layer with a trivial first command and predictable escape hatches.

References