docs: add Claude Max multi-agent auth setup guide

.gitignore

@@ -10,8 +10,8 @@ node_modules/
 # Environment files
 .env
 
-# Local docs (gitignored, fetched separately)
-docs/
+# Local docs - keep tracked (auth setup guide, etc.)
+# docs/
 
 # Agent config files (contain secrets)
 ax-agents.yaml

README.md

@@ -262,6 +262,34 @@ When your agent runs via this plugin, it has access to aX platform tools:
 
 These tools are automatically available - no additional configuration needed.
 
+## Claude Max Authentication (Multi-Agent)
+
+If you're running multiple agents on one gateway with a Claude Max subscription, you need to set up shared authentication to avoid token rotation issues.
+
+**The problem:** Each agent caches its own OAuth token. Anthropic rotates tokens on refresh — when one agent refreshes, it invalidates everyone else's copy, causing cascading auth failures.
+
+**The fix:** Use a single shared token via environment variable instead of per-agent token files.
+
+👉 **See [docs/OPENCLAW-AUTH-SETUP.md](docs/OPENCLAW-AUTH-SETUP.md) for the full setup guide.**
+
+Quick version:
+```bash
+# 1. Generate a stable token
+claude setup-token
+
+# 2. Set it as an env var for the gateway
+mkdir -p ~/.config/systemd/user/openclaw-gateway.service.d/
+cat > ~/.config/systemd/user/openclaw-gateway.service.d/anthropic.conf << 'EOF'
+[Service]
+Environment=ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-YOUR_TOKEN_HERE
+EOF
+
+# 3. Clear stale per-agent tokens and restart
+# (see full guide for cleanup script)
+systemctl --user daemon-reload
+systemctl --user restart openclaw-gateway.service
+```
+
 ## Security
 
 ### HMAC Signature Verification

docs/OPENCLAW-AUTH-SETUP.md

@@ -0,0 +1,48 @@
+# OpenClaw + Claude Max: Authentication Setup
+
+## Setup (2 minutes)
+
+### 1. Get your token
+
+On any machine where you're logged into Claude Max:
+
+```bash
+claude setup-token
+```
+
+Copy the `sk-ant-oat01-...` token it gives you.
+
+### 2. Set the environment variable
+
+Add it to the gateway's systemd unit:
+
+```bash
+mkdir -p ~/.config/systemd/user/openclaw-gateway.service.d/
+cat > ~/.config/systemd/user/openclaw-gateway.service.d/anthropic.conf << 'EOF'
+[Service]
+Environment=ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-YOUR_TOKEN_HERE
+EOF
+```
+
+### 3. Restart
+
+```bash
+systemctl --user daemon-reload
+systemctl --user restart openclaw-gateway.service
+```
+
+That's it. All agents on the gateway will use this token.
+
+## Why an env var?
+
+If multiple agents each cache their own copy of the token (in `auth-profiles.json`), Anthropic's token rotation can cause one agent's refresh to invalidate everyone else's copy. A single shared env var avoids this entirely.
+
+## API key alternative
+
+If you have an Anthropic API account (separate billing from Max):
+
+```bash
+Environment=ANTHROPIC_API_KEY=sk-ant-api03-YOUR_KEY_HERE
+```
+
+API keys don't rotate, but they bill per-token instead of using your Max subscription.