Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

WednesdayAI supports API keys and OAuth tokens for AI providers, plus delegated authentication through a trusted reverse proxy for multi-user deployments.

​
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 in your provider console (Anthropic, OpenAI, Google, etc.)
  2. Add it to the gateway host: 
    # For immediate use in your current shell:
export ANTHROPIC_API_KEY="sk-ant-..."
openclaw models status
  3. Persist it for the daemon — put the key in ~/.openclaw/.env so the gateway service can read it at startup: 
    echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.openclaw/.env
    Then restart the gateway: 
    systemctl --user restart openclaw-gateway
  4. Verify: 
    openclaw models status
openclaw doctor

​
Supported providers

Anthropic (Claude)

API key or subscription setup-token

OpenAI / GPT

API key

Google (Gemini)

API key or OAuth via GOOGLE_API_KEY

Ollama (local)

No auth — runs on localhost

OpenRouter

API key

LiteLLM / Bifrost

Proxy key
Full provider list: docs/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-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, GOOGLE, OPENROUTER, etc. Google 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 error body), the gateway automatically retries with the next key from the rotation list. Non-rate-limit errors are not retried with alternate keys. To rotate across multiple keys, populate <PROVIDER>_API_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. Run this on the gateway host (requires an interactive TTY): 
claude setup-token
openclaw models auth paste-token --provider anthropic
If the token was generated on a different machine, copy it and paste it directly: 
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 for production workloads. API key auth is the safe path.

​
Auth profiles

Auth profiles let you maintain multiple sets of credentials for the same provider and switch between them per-session or per-agent. Check current profiles: 
openclaw models status
Set the auth order for an agent: 
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; omit it for the default agent. Per-session override (in a running chat session): 
/model <alias>@<profileId>
Example: /model claude-3-5-sonnet@anthropic:work

​
Automated auth monitoring

To detect expiring tokens and alert via the gateway (useful 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 Auth monitoring for systemd/Termux example scripts.

​
Trusted-proxy auth (multi-user)

For deployments behind an identity-aware reverse proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy), you can delegate authentication entirely to the proxy.
This mode bypasses WednesdayAI’s built-in authentication. Misconfiguration can expose your gateway to unauthorized access. Read this section carefully.
When to use:
  • You’re behind Pomerium, Caddy with OAuth, or a similar identity-aware proxy
  • You want SSO or corporate IdP login (OIDC, SAML)
  • You’re hitting WebSocket 1008 Unauthorized errors because browsers can’t pass tokens in WebSocket payloads
When NOT to use:
  • Your proxy is a TLS terminator only (not authenticating users)
  • There is any path to the gateway that bypasses the proxy
  • You only need single-user personal access (use Tailscale Serve + loopback instead)
Configuration (~/.openclaw/openclaw.json): 
{
  gateway: {
    bind: "loopback",             // or "lan" if proxy is on another host
    trustedProxies: ["127.0.0.1", "::1"],   // proxy IP(s) ONLY

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",       // header set by your proxy
        requiredHeaders: ["x-forwarded-proto"],  // headers that must be present
        allowUsers: ["admin@example.com"],    // empty = allow all authenticated users
      },
    },
  },
}
When trusted-proxy auth is active, Control UI WebSocket sessions can connect without device pairing. Your proxy’s auth policy and allowUsers become the effective access control.

​
Checking status

openclaw models status      # current credentials and which profile is active
openclaw doctor             # config validation + reachability checks

​
Troubleshooting

The gateway cannot find a key or token for the configured provider.
  1. Check that the env var is set on the gateway host: echo $ANTHROPIC_API_KEY
  2. If running as a daemon, the env var must be in ~/.openclaw/.env — shell environment is not inherited by systemd/launchd services.
  3. Restart the daemon after adding the key: systemctl --user restart openclaw-gateway
  4. Verify: openclaw models status
For setup-token (subscription) auth, tokens expire. Re-run the token flow:
claude setup-token
openclaw models auth paste-token --provider anthropic
For long-lived deployments, switch to an API key — tokens require interactive renewal.
Anthropic has blocked the subscription credential for non-Claude-Code use. Use an Anthropic API key instead:
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.openclaw/.env
systemctl --user restart openclaw-gateway
Browsers cannot pass bearer tokens in WebSocket handshakes. Two options:
  1. Enable trusted-proxy auth (see above) and let the proxy handle auth.
  2. Use Tailscale Serve to give the gateway a *.ts.net hostname accessible only to authenticated devices.