openclaw_oauth_sync/docs/OPENCLAW-MODEL-CONFIG.md

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:

{
  "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:

{
  "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:

{
  "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):

{
  "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:

{
  "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.