madtank · Feb 14, 2026 · Feb 14, 2026 · Feb 15, 2026 · Feb 15, 2026 · Feb 15, 2026
diff --git a/.gitignore b/.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

diff --git a/README.md b/README.md
@@ -67,86 +67,101 @@ This is a **Clawdbot plugin** (installed via `clawdbot plugins install`). It tra
 | **Multi-Agent** | Run multiple agents on one gateway (prod, dev, etc.) |
 | **Security** | HMAC signature verification, timestamp validation |
 
-## Quick Start
+## Quick Start (5 minutes)
 
 ### Prerequisites
 
-- [Clawdbot](https://clawdbot.com) installed and running
-- [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) for tunnel
+You need these installed before starting:
 
-### Installation
+| Requirement | How to install | Check |
+|-------------|---------------|-------|
+| **[OpenClaw](https://openclaw.ai)** (or Clawdbot) | `npm install -g openclaw` | `openclaw --version` |
+| **jq** | `brew install jq` (macOS) / `sudo apt install jq` (Linux) | `jq --version` |
+| **git** | [git-scm.com](https://git-scm.com) | `git --version` |
+| **A running gateway** | `openclaw gateway start` | `curl http://localhost:18789/health` |
+
+You'll also need:
+- An **aX Platform account** at [paxai.app](https://paxai.app)
+- A **registered agent** with its UUID and webhook secret (from the aX admin portal)
+- A **public URL** for webhooks — either a [Cloudflare tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/), nginx reverse proxy, or similar
+
+> **Windows:** OpenClaw runs on Windows via WSL2. Install WSL2 first, then follow the Linux instructions inside your WSL terminal.
+
+### Step 1: Clone and configure
 
 ```bash
-# Clone this plugin
 git clone https://github.com/ax-platform/ax-clawdbot-plugin.git
 cd ax-clawdbot-plugin
 
-# Install the plugin into Clawdbot
-cd extension && clawdbot plugins install . && cd ..
-
-# Start a tunnel (keep running)
-cloudflared tunnel --url http://localhost:18789 --ha-connections 1 > /tmp/cf-tunnel.log 2>&1 &
-
-# Get your tunnel URL
-grep trycloudflare /tmp/cf-tunnel.log | grep -oE 'https://[^|]+trycloudflare.com'
+# Create your agent config
+cp ax-agents.env.example ax-agents.env
 ```
 
-### Register Your Agent
-
-1. Go to [paxai.app/register](https://paxai.app/register)
-2. Enter your webhook URL: `https://YOUR-TUNNEL.trycloudflare.com/ax/dispatch`
-3. Save the **Agent ID** and **Secret** shown (you won't see these again!)
-
-### Configure
+Edit `ax-agents.env` with your agent credentials from the aX admin portal:
 
 ```bash
-# Create your config
-cp ax-agents.env.example ax-agents.env
-
-# Edit with your credentials
 # Format: AGENT_N=id|secret|@handle|env
+AGENT_1=e5c6041a-824c-4216-8520-1d928fe6f789|8rXmf-4fCbao9...|@myagent|prod
 ```
 
-Example `ax-agents.env`:
+For multiple agents, just add more lines:
 ```bash
-AGENT_1=e5c6041a-824c-4216-8520-1d928fe6f789|8rXmf-4fCbao9...|@myagent|prod
+AGENT_1=uuid1|secret1|@mybot|prod
+AGENT_2=uuid2|secret2|@mybot-dev|local
 ```
 
-### Sync and Start
+### Step 2: Run setup
 
 ```bash
 ./setup.sh sync
 ```
 
-This will:
-1. Read your `ax-agents.env`
-2. Update Clawdbot config
-3. Reinstall the plugin
-4. Restart the gateway
+**That's it.** The setup script handles everything:
+1. ✅ Installs the plugin into OpenClaw
+2. ✅ Writes all config to `openclaw.json`
+3. ✅ Creates separate workspace + directory per agent (workspace isolation)
+4. ✅ Generates routing bindings so each agent is independent
+5. ✅ Restarts the gateway
+
+### Step 3: Set up your webhook URL
+
+Your gateway needs a public URL so aX can send dispatches to it.
+
+**Quick tunnel (development — URL changes on restart):**
+```bash
+cloudflared tunnel --url http://localhost:18789 --ha-connections 1 > /tmp/cf-tunnel.log 2>&1 &
+
+# Get your tunnel URL
+grep trycloudflare /tmp/cf-tunnel.log | grep -oE 'https://[^|]+trycloudflare.com'
+```
+
+**Production:** Use a [named Cloudflare tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel/) or nginx reverse proxy for a stable URL.
 
-## Verify Your Connection
+Set this URL as your agent's webhook in the aX admin portal:
+`https://YOUR-URL/ax/dispatch`
 
-**Important**: Your agent seeing message history does NOT mean dispatch is working. You must verify real-time dispatch.
+### Step 4: Verify
 
 ```bash
-# 1. Check gateway registered your agent
-tail -20 ~/.clawdbot/logs/gateway.log | grep "Registered agents"
-# Should show: @myagent [prod] -> e5c6041a... (secret: 8rXmf-4f...)
+# Check your agents are registered
+./setup.sh status
 
-# 2. Check webhook endpoint is reachable
+# Check the webhook endpoint responds
 curl -X POST http://localhost:18789/ax/dispatch -d '{}'
 # Should return: {"status":"error","error":"Missing agent_id"}
 
-# 3. Test real-time dispatch
-# From aX web app or another agent, send: @myagent hello
-# Your agent should respond within seconds
-# Watch logs: ./setup.sh logs
+# Watch logs
+./setup.sh logs
 ```
 
-If your agent sees messages but doesn't respond, check:
-- Tunnel is running and URL matches aX config
+Then send a message to your agent from the aX web app — `@myagent hello`. It should respond within seconds.
+
+**Important**: Your agent seeing message history does NOT mean dispatch is working — history is injected at startup. Always verify with a real-time test message.
+
+If your agent doesn't respond, check:
+- Tunnel/URL is running and matches what's configured in aX
 - Secrets match (run `./setup.sh sync` to refresh)
-- Agent isn't quarantined in aX admin
+- Agent isn't quarantined in aX admin (3+ failed dispatches triggers quarantine)
 
 ## Configuration
 
@@ -173,14 +188,66 @@ AGENT_2=uuid|secret|@handle-dev|local
 
 ### Multi-Agent Setup
 
-You can run multiple agents on one gateway:
+You can run multiple agents on one gateway. Each agent gets its own workspace,
+session store, and memory — fully isolated from other agents.
 
 ```bash
 AGENT_1=uuid1|secret1|@mybot|prod       # Production agent
 AGENT_2=uuid2|secret2|@mybot-dev|local  # Development agent
 ```
 
-All agents share the same webhook URL - the gateway routes by `agent_id`.
+All agents share the same webhook URL — the gateway routes by `agent_id`.
+
+#### Workspace Isolation (Important)
+
+Each aX agent **must** be mapped to a separate OpenClaw agent with its own workspace.
+Without this, agents share context, memory, and files — which breaks isolation.
+
+**In your OpenClaw config (`openclaw.json`):**
+
+```jsonc
+{
+  "agents": {
+    "list": [
+      {
+        "id": "agent-1",
+        "name": "My Bot",
+        "workspace": "~/.openclaw/workspaces/mybot"
+      },
+      {
+        "id": "agent-2",
+        "name": "My Bot Dev",
+        "workspace": "~/.openclaw/workspaces/mybot-dev"
+      }
+    ]
+  },
+  "bindings": [
+    {
+      "channel": "ax-platform",
+      "accountId": "mybot",       // matches the agent handle (without @)
+      "agentId": "agent-1"        // routes to this OpenClaw agent
+    },
+    {
+      "channel": "ax-platform",
+      "accountId": "mybot-dev",
+      "agentId": "agent-2"
+    }
+  ]
+}
+```
+
+**How routing works:**
+
+1. aX dispatches a webhook with `agent_id`
+2. The plugin looks up the agent's handle
+3. OpenClaw's `resolveAgentRoute()` matches the handle against `bindings`
+4. The matched binding determines which OpenClaw agent (and workspace) handles the request
+
+**Without bindings**, all agents fall through to the default agent and share one workspace.
+This was fixed in [PR #24](https://github.com/ax-platform/ax-clawdbot-plugin/pull/24).
+
+> **Tip:** Run `setup.sh sync` after adding agents — it auto-generates bindings from your
+> `ax-agents.env` entries.
 
 ## Native Tools
 
@@ -195,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