# Configuring Anthropic Models in OpenClaw

## CRITICAL: Do NOT add an "anthropic" provider to models.providers

OpenClaw has a **built-in** Anthropic provider. You do NOT need to (and must NOT) add a custom `anthropic` entry to `models.providers` in `openclaw.json`.

Adding one causes the Anthropic SDK to append `/v1` to your `baseUrl`, which already has `/v1`, resulting in:
```
https://api.anthropic.com/v1/v1/messages -> 404 Not Found
```

## Correct Configuration

### 1. Set the primary model

In `openclaw.json`, under `agents.defaults.model`:

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-6",
        "fallbacks": [
          "anthropic/claude-sonnet-4-6",
          "google/gemini-3.1-pro-preview"
        ]
      }
    }
  }
}
```

The `anthropic/` prefix tells OpenClaw to use the built-in Anthropic provider. No extra configuration needed.

### 2. Add model aliases (optional)

Under `agents.defaults.models`:

```json
{
  "agents": {
    "defaults": {
      "models": {
        "anthropic/claude-opus-4-6": {
          "alias": "Claude Opus 4.6 (Max)"
        },
        "anthropic/claude-sonnet-4-6": {
          "alias": "Claude Sonnet 4.6 (Max)"
        }
      }
    }
  }
}
```

### 3. Set ANTHROPIC_OAUTH_TOKEN in .env

In your OpenClaw `.env` file (e.g., `/root/openclaw/.env`):

```
ANTHROPIC_OAUTH_TOKEN="sk-ant-oat01-YOUR_TOKEN_HERE"
```

This is the fallback auth method. The gateway reads it as a container environment variable.

### 4. Create auth profiles for agents

Each agent needs an `anthropic:default` profile in its `auth-profiles.json`:

```json
{
  "profiles": {
    "anthropic:default": {
      "type": "oauth",
      "provider": "anthropic",
      "access": "sk-ant-oat01-YOUR_TOKEN_HERE"
    }
  },
  "lastGood": {
    "anthropic": "anthropic:default"
  }
}
```

**Important:** The field must be `access`, NOT `key`. Using `key` with `type: "oauth"` causes the profile to be silently skipped.

### 5. Create oauth.json

At `/root/.openclaw/credentials/oauth.json` (maps to `/home/node/.openclaw/credentials/oauth.json` in the gateway container):

```json
{
  "anthropic": {
    "access": "sk-ant-oat01-YOUR_TOKEN_HERE",
    "refresh": "sk-ant-ort01-YOUR_REFRESH_TOKEN",
    "expires": 1772120060006,
    "scopes": ["user:inference", "user:mcp_servers", "user:profile", "user:sessions:claude_code"],
    "subscriptionType": "max",
    "rateLimitTier": "default_claude_max_5x"
  }
}
```

## Available Built-in Models

When using the built-in Anthropic provider:
- `anthropic/claude-opus-4-6`
- `anthropic/claude-sonnet-4-6`
- Other models listed in the Anthropic API

## Per-Agent Model Override

You can set a specific model per agent:

```json
{
  "agents": {
    "list": [
      {
        "id": "my-agent",
        "model": "anthropic/claude-opus-4-6"
      }
    ]
  }
}
```

## Authentication Flow

1. Gateway checks `auth-profiles.json` for a valid `anthropic:default` profile
2. For `type: "oauth"`, it requires the `access` field (not `key`)
3. If no valid profile: falls back to `ANTHROPIC_OAUTH_TOKEN` env var
4. On startup, `mergeOAuthFileIntoStore()` reads `oauth.json` and merges credentials
5. `isOAuthToken()` detects the `sk-ant-oat` prefix
6. Uses Bearer auth + Claude Code identity headers to call `api.anthropic.com`

## OAuth Token Lifecycle

Tokens from Claude Max subscriptions expire every ~8 hours. Use the sync service from this project to keep them fresh automatically. See the main README for setup instructions.