Multi-Agent Architecture — Fleet Setup & Best Practices

Production Architecture for 24/7 Agent Fleet

The recommended architecture uses OpenClaw as the control plane with Markdown files as source-of-truth memory:

1. Memory Layer Setup

Create a structured memory hierarchy in your workspace:

~/clawd/├── MEMORY.md           # Curated durable facts, principles, "how we work"├── IDENTITY.md         # Agent personality and instructions├── memory/│   └── YYYY-MM-DD.md   # Daily logs (auto-created)└── projects/    ├── project-a/    └── project-b/

Each agent (Jarvis, CLU, Cortana) gets its own workspace:

mkdir -p ~/agents/jarvis ~/agents/clu ~/agents/cortana

2. Per-Task Sessions (Not Forever-Sessions)

Don't run one eternal session. Instead:

• Coordinator (Jarvis): Long-lived main session for human chat
• Workers (CLU, Cortana): Spawned as subagents per gig/task
• Crons/Hooks: Isolated sessions that complete and exit

3. Enable Auto-Compaction

Prevent context overflow by enabling compaction:

This summarizes old context when approaching limits. See: https://docs.openclaw.ai/concepts/compaction

Fix OAuth Token Refresh Errors

When you see:

⚠️ Agent failed before reply: OAuth token refresh failed for anthropic: Failed to refresh OAuth token

For API Key Users

1. Get a fresh API key from https://console.anthropic.com/
2. Update your config:

Or manually:

openclaw config set anthropic.apiKey "sk-ant-api03-..."

1. Restart the gateway:

For Claude Max Subscribers

Claude Max (subscription) uses OAuth, not API keys. The OAuth flow may have stale tokens:

1. Re-authenticate:

openclaw auth anthropic

1. Follow the browser OAuth flow

2. Restart:

openclaw gateway restart

Note: If the bot still responds despite the error, it's using cached context. The error indicates token refresh fails on each request but the cached session still works. Fix it anyway to prevent future failures.

Fix CLI Timeout in Exec Sessions

When terminal commands work but agent exec fails:

Terminal (works):

$ openclaw cron list# Returns immediately

Agent exec (fails):

Error: gateway timeout after 10000ms

Diagnosis

Check what the gateway is listening on:

If you see 127.0.0.1:18789, that's the problem.

Solution: Bind to All Interfaces

Edit ~/.openclaw/config.json5:

{  "gateway": {    "host": "0.0.0.0",  // Changed from 127.0.0.1    "port": 18789  }}

Or use the bind shortcut:

openclaw config set gateway.bind "lan"

Restart:

openclaw gateway restart

Verify:

ss -tulpn | grep 18789# Should show: tcp LISTEN 0 511 0.0.0.0:18789

Why This Happens

Exec sessions may run in isolated network namespaces (containers, different PID namespaces). Even though both use 127.0.0.1, socket routing differs. Binding to 0.0.0.0 makes the Gateway reachable from all network contexts.

Configure Multiple Models

Use different models for different tasks:

Interactive Model Selection

openclaw config

Choose "models", then press Space to select multiple models, Enter to confirm.

Recommended Multi-Model Setup

{  "models": {    "default": "anthropic/claude-sonnet-4-20250514",    "coding": "anthropic/claude-sonnet-4-20250514",    "creative": "anthropic/claude-opus-4-0",    "fast": "moonshotai/kimi-k2.5"  }}

Free/Cheap Model Options

• Kimi K2.5 - Free tier available via Kilo Gateway: https://blog.kilo.ai/p/kilo-gateway-supercharges-moltbot-fka-clawdbot
• Gemini - Google's models with generous free tier
• Groq - Fast inference, free tier available

Factory Reset (Preserve Key Configs)

If your agent is misbehaving after upgrade:

1. Backup Critical Files

mkdir -p ~/openclaw-backupcp -r ~/.openclaw/config.json5 ~/openclaw-backup/cp -r ~/clawd/MEMORY.md ~/openclaw-backup/cp -r ~/clawd/IDENTITY.md ~/openclaw-backup/cp -r ~/clawd/memory/ ~/openclaw-backup/

2. Clean State Reset

openclaw gateway stoprm -rf ~/.openclaw/sessions/rm -rf ~/.openclaw/cache/

3. Reset Crons

openclaw cron clearopenclaw cron list  # Should be empty

4. Restore and Restart

openclaw gateway start

5. Re-add Crons

Manually re-add your scheduled tasks:

openclaw cron add "0 9 * * *" "Good morning check-in"

Full Nuclear Reset (Start Fresh)

openclaw gateway stoprm -rf ~/.openclaw/rm -rf ~/.config/openclaw/openclaw gateway start# Re-run initial setupopenclaw configure