Add complete OAuth token refresh and sync solution

- Setup wizard with auto-detection of OpenClaw paths and Claude CLI - Token sync watcher (inotifywait) for real-time credential updates - Auto-refresh trigger timer that runs Claude CLI every 30 min - Supports Claude CLI in Docker container or on host - Temporary ANTHROPIC_BASE_URL override for container environments - Anthropic model configuration for OpenClaw - Auth profile management (fixes key vs access field) - Systemd services and timers for both sync and trigger - Comprehensive documentation and troubleshooting guides - Re-authentication notification system Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-27 01:51:18 +07:00
parent 3ae5d5274a
commit 22731fff60
24 changed files with 2846 additions and 6 deletions
--- a/docs/OPENCLAW-MODEL-CONFIG.md
+++ b/docs/OPENCLAW-MODEL-CONFIG.md
@@ -0,0 +1,140 @@
+# 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.