If I enable BYOK for one provider, does that affect the others?

Yes. OpenClaw treats the agent as fully BYOK if any provider key is set, and refuses to fall back to shared sub-keys. This prevents surprise billing where a fallback would silently spend from a shared pool.

Can I BYOK via OAuth instead of an API key?

Yes for Anthropic Claude and OpenAI Codex. OpenClaw stores OAuth tokens under auth.profiles. This lets you bill to a consumer Anthropic or OpenAI subscription instead of using an API key.

← Home

Guide

OpenClaw BYOK (Bring Your Own Key)

Q: What is BYOK in OpenClaw?

BYOK (bring your own key) routes your agent's requests through your own provider account instead of a shared pool. You set the key in models.providers. .apiKey and the gateway hot-reloads.

BYOK lets your OpenClaw agent route requests through your own provider account instead of a shared pool. You pay the provider directly, you keep the rate-limit headroom, and your traffic stays out of any shared sub-key. Here is how the BYOK system works across all OpenClaw providers.

Where Keys Live

BYOK keys live in models.providers.<provider>.apiKey in youropenclaw.json. Each provider has its own slot:

{
  "models": {
    "providers": {
      "anthropic":  { "apiKey": "sk-ant-..." },
      "openai":     { "apiKey": "sk-..." },
      "google":     { "apiKey": "AIzaSy..." },
      "deepseek":   { "apiKey": "sk-..." },
      "openrouter": { "apiKey": "sk-or-..." },
      "groq":       { "apiKey": "gsk_..." }
    }
  }
}

Save the file and the gateway hot-reloads provider config — no restart needed. Send a chat from any channel and the response routes through your account.

The All-Providers BYOK Gate

If any provider BYOK is enabled, OpenClaw treats the agent as fully BYOK and refuses to fall back to a shared sub-key for any provider. This avoids surprise billing where a fallback silently spends from a shared pool. To re-enable mixed mode, clear all BYOK keys.

OAuth Profiles (Anthropic Claude, OpenAI Codex)

For Claude and OpenAI Codex, you can BYOK via OAuth instead of an API key. OpenClaw stores the OAuth tokens under auth.profiles."<provider>:<email>"in the workspace. The advantage is per-user billing on consumer Anthropic/OpenAI accounts — useful for personal bots where you want to charge to your own consumer subscription.

Per-Channel BYOK

You can scope BYOK to a specific channel by setting provider config underchannels.<name>.modelOverride.providers.<provider>.apiKey. This is useful when one Discord server uses your own GPT key and another uses the shared pool. Most users don't need this — gateway-wide BYOK covers the common case.

Primary Model Rewrites Under BYOK

When BYOK is on, OpenClaw force-rewrites agents.defaults.model.primaryif it points to a provider you have not enabled. Example: if you only setproviders.google.apiKey, primary will be rewritten to a Google model even if you configured a Claude one. This prevents broken chats from misconfigured keys. Set primary correctly for the provider you BYOK.

OpenRouter as a Multi-Provider BYOK

OpenRouter is the easiest BYOK on-ramp. One key, dozens of providers (Anthropic, OpenAI, Google, Mistral, Meta, etc.). Set it under providers.openrouter.apiKeyand switch models by ID prefix:

{
  "agents": {
    "defaults": {
      "model": { "primary": "openrouter/anthropic/claude-sonnet-4.6" }
    }
  }
}

Verifying BYOK Is Active

# Tail the gateway log on the next chat
openclaw logs --since 30s | grep "byok=true"

# Or inspect the resolved provider for an active session
openclaw gateway status --verbose | grep provider

Skip the JSON Editing

OpenClaw Launch has a BYOK key vault in the dashboard: paste your provider key once and it's synced into your container automatically. Available on Lite and Pro from $3/mo first month.