Skip to main content

​
Authentication

WednesdayAI supports API keys and OAuth tokens for AI providers, plus delegated authentication through a trusted reverse proxy for multi-user deployments. This page covers provider authentication and the gateway access token. For per-provider details, see the provider guides.

​
Quick start — API key

For a long-lived gateway, an API key is the most reliable option. OAuth/subscription tokens can expire and require interactive renewal; API keys do not.
1

Create a key

Generate a key in your provider console (Anthropic, OpenAI, Google, etc.).
2

Persist it for the daemon

Put the key in ~/.openclaw/.env so the gateway service reads it at startup — shell environment is not inherited by systemd/launchd services:
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.openclaw/.env
3

Restart the gateway

systemctl --user restart openclaw-gateway
4

Verify

openclaw models status
openclaw doctor

​
Supported providers

Anthropic (Claude)

API key, OAuth token, or setup-token

OpenAI

API key or Codex OAuth

Google (Gemini)

AI Studio key or Vertex AI

Ollama (local)

No auth — runs locally

OpenRouter

API key

LiteLLM / Bifrost

Proxy key
The full list of built-in providers is larger — see AI providers.

​
Environment variable lookup order

WednesdayAI resolves provider credentials in this order (first match wins):
PriorityVariableNotes
1OPENCLAW_LIVE_<PROVIDER>_KEYSingle override, useful in CI
2<PROVIDER>_API_KEYSComma- or semicolon-separated list for rotation
3<PROVIDER>_API_KEYStandard single key
4<PROVIDER>_API_KEY_*Numbered variants (_KEY_1, _KEY_2, …)
Replace <PROVIDER> with the uppercase provider name: ANTHROPIC, OPENAI, OPENROUTER, etc. Google/Gemini providers also fall back to the bare GOOGLE_API_KEY. The gateway deduplicates entries before use.

​
Key rotation

When a provider returns a rate-limit error (HTTP 429 or rate_limit/quota/resource exhausted in the body), the gateway retries with the next key in the rotation list. Non-rate-limit errors are not retried with alternate keys. 
# ~/.openclaw/.env
ANTHROPIC_API_KEYS=sk-ant-key1...,sk-ant-key2...,sk-ant-key3...

​
Anthropic subscription (setup-token)

If you have a Claude subscription rather than an API key, the setup-token flow is supported. Generate the token on any machine, then paste it on the gateway host: 
claude setup-token
openclaw models auth paste-token --provider anthropic
Anthropic has restricted subscription credential use outside Claude Code in the past. This is technical compatibility only — verify Anthropic’s current terms before relying on it. API key auth is the safe path. See Anthropic.

​
Auth profiles

Auth profiles let you maintain multiple sets of credentials for the same provider and switch between them per-session or per-agent. 
openclaw models status                                            # current profiles and which is active
openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic
Use --agent <id> to target a specific agent. Per-session override in a running chat: 
/model <model>@<profileId>
Example: /model anthropic/claude-sonnet-4-6@anthropic:work

​
Gateway access token

Provider credentials are separate from the gateway access token, which authenticates callers to the gateway API and control panel. It is configured under gateway.auth (not the top-level auth key, which is the provider credential store). See Gateway configuration for the full resolution order.

​
Rotating the gateway token

1

Generate a new token

openssl rand -hex 32
2

Update config (and env if used)

Set gateway.auth.token in ~/.openclaw/openclaw.json. If OPENCLAW_GATEWAY_TOKEN is also set (for example in a systemd EnvironmentFile), update or remove it too — the env var takes precedence and will block the config change otherwise.
3

Restart and re-pair clients

In hybrid reload mode, saving the config restarts the gateway automatically and drops active sessions. Update the token in any CLI/app clients (and gateway.remote.token if you persist a remote target).

​
Automated auth monitoring

To detect expiring tokens in unattended deployments: 
openclaw models status --check
# Exit codes: 0 = OK, 1 = expired/missing, 2 = expiring soon
Wire this into a cron job or systemd timer. See Health checks for a worked systemd-timer example.

​
Trusted-proxy auth (multi-user)

For deployments behind an identity-aware reverse proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy), you can delegate authentication to the proxy.
This mode bypasses WednesdayAI’s built-in authentication. Misconfiguration can expose your gateway. Ensure there is no path to the gateway that bypasses the proxy.
Use it when: you are behind an identity-aware proxy, want SSO/IdP login, or hit WebSocket 1008 Unauthorized because browsers cannot pass tokens in WebSocket handshakes. Do not use it when: the proxy is a TLS terminator only, any path bypasses the proxy, or you only need single-user access (use Tailscale Serve + loopback instead). 
{
  gateway: {
    bind: "loopback",                       // or "lan" if the proxy is on another host
    trustedProxies: ["127.0.0.1", "::1"],   // proxy IP(s) ONLY
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
        requiredHeaders: ["x-forwarded-proto"],
        allowUsers: ["admin@example.com"],   // empty = allow all authenticated users
      },
    },
  },
}
With trusted-proxy auth active, Control UI WebSocket sessions connect without device pairing. The proxy’s policy and allowUsers become the effective access control.

​
Troubleshooting

  1. Check the env var is set on the gateway host: echo $ANTHROPIC_API_KEY
  2. For a daemon, the key must be in ~/.openclaw/.env — shell env is not inherited by systemd/launchd.
  3. Restart the daemon after adding the key.
  4. Verify: openclaw models status
For setup-token (subscription) auth, re-run claude setup-token and openclaw models auth paste-token --provider anthropic. For long-lived deployments, switch to an API key.
Anthropic blocked the subscription credential for non-Claude-Code use. Use an API key instead.
Browsers cannot pass bearer tokens in WebSocket handshakes. Enable trusted-proxy auth, or use Tailscale Serve with gateway.auth.allowTailscale: true.