> ## 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

> Connect AI providers to WednesdayAI: API keys, OAuth tokens, key rotation, gateway-token rotation, and trusted-proxy auth.

# 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](/admin/providers).

## 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.

<Steps>
  <Step title="Create a key">
    Generate a key in your provider console (Anthropic, OpenAI, Google, etc.).
  </Step>

  <Step title="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:

    ```bash theme={"dark"}
    echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.openclaw/.env
    ```
  </Step>

  <Step title="Restart the gateway">
    <Tabs>
      <Tab title="Linux (systemd)">
        ```bash theme={"dark"}
        systemctl --user restart openclaw-gateway
        ```
      </Tab>

      <Tab title="macOS / manual">
        ```bash theme={"dark"}
        openclaw gateway stop && openclaw gateway start
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify">
    ```bash theme={"dark"}
    openclaw models status
    openclaw doctor
    ```
  </Step>
</Steps>

## Supported providers

<CardGroup cols={3}>
  <Card title="Anthropic (Claude)" href="/admin/providers/anthropic" icon="message-square">
    API key, OAuth token, or setup-token
  </Card>

  <Card title="OpenAI" href="/admin/providers/openai" icon="zap">
    API key or Codex OAuth
  </Card>

  <Card title="Google (Gemini)" href="/admin/providers/google" icon="globe">
    AI Studio key or Vertex AI
  </Card>

  <Card title="Ollama (local)" href="/admin/providers/ollama" icon="server">
    No auth — runs locally
  </Card>

  <Card title="OpenRouter" href="/admin/providers/openrouter" icon="shuffle">
    API key
  </Card>

  <Card title="LiteLLM / Bifrost" href="/admin/providers/litellm" icon="layers">
    Proxy key
  </Card>
</CardGroup>

The full list of built-in providers is larger — see [AI providers](/admin/providers).

## Environment variable lookup order

WednesdayAI resolves provider credentials in this order (first match wins):

| Priority | Variable                       | Notes                                           |
| -------- | ------------------------------ | ----------------------------------------------- |
| 1        | `OPENCLAW_LIVE_<PROVIDER>_KEY` | Single override, useful in CI                   |
| 2        | `<PROVIDER>_API_KEYS`          | Comma- or semicolon-separated list for rotation |
| 3        | `<PROVIDER>_API_KEY`           | Standard 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.

```bash theme={"dark"}
# ~/.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**:

```bash theme={"dark"}
claude setup-token
openclaw models auth paste-token --provider anthropic
```

<Warning>
  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](/admin/providers/anthropic).
</Warning>

## Auth profiles

Auth profiles let you maintain multiple sets of credentials for the same provider and switch between them per-session or per-agent.

```bash theme={"dark"}
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](/admin/gateway/configuration#gatewayauth) for the full resolution order.

### Rotating the gateway token

<Steps>
  <Step title="Generate a new token">
    ```bash theme={"dark"}
    openssl rand -hex 32
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>
</Steps>

## Automated auth monitoring

To detect expiring tokens in unattended deployments:

```bash theme={"dark"}
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](/admin/gateway/health-checks#automated-monitoring) 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.

<Warning>
  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.
</Warning>

**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).

```json5 theme={"dark"}
{
  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

<AccordionGroup>
  <Accordion title="&#x22;No credentials found&#x22;">
    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`
  </Accordion>

  <Accordion title="Token expired">
    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.
  </Accordion>

  <Accordion title="&#x22;This credential is only authorized for use with Claude Code&#x22;">
    Anthropic blocked the subscription credential for non-Claude-Code use. Use an API key instead.
  </Accordion>

  <Accordion title="WebSocket 1008 Unauthorized behind a reverse proxy">
    Browsers cannot pass bearer tokens in WebSocket handshakes. Enable trusted-proxy auth, or use Tailscale Serve with `gateway.auth.allowTailscale: true`.
  </Accordion>
</AccordionGroup>