Multi-Agent Setup Guide

📋 Overview

This guide teaches you how to set up multiple OpenClaw agents that share a unified workspace through GitHub. Each agent has its own identity but shares memory, documents, and knowledge with the family.

What You'll Build

Multiple AI agents on different machines (cloud, home, school)
Shared workspace synced through GitHub
Each agent with unique identity but shared context
Automatic backup and conflict resolution

Example Family Structure:
Kimi (Cloud) — Female, calls you Oppa
Mini (School) — Female, calls you Oppa
HIM (Home) — Male, calls you William
HER (Home Powerhouse) — Female, calls you Oppa

🛠️ Requirements

Per Machine

Component	Minimum	Recommended
OS	Windows 10 / Ubuntu 20.04	Windows 11 / Ubuntu 22.04
RAM	4GB	8GB+
Storage	10GB free	50GB+ SSD
Node.js	v18+	v22+
Git	v2.30+	v2.40+
Network	Stable internet	Broadband (for GitHub sync)

Accounts Needed

GitHub account (for workspace sync)
Moonshot API key (for Kimi models)
VPN (if in China, for GitHub access)

Download Links

Node.js Git Moonshot API OpenClaw Docs

🔧 Setup Steps

Step 1: Install OpenClaw

Install on each machine where you want an agent.

                PowerShell / Bash
                
# Install globally
npm install -g openclaw

# Verify installation
openclaw --version

Step 2: Configure API Key

Use direct API (recommended) instead of bridge plugin.

                Config File
                
// ~/.openclaw/openclaw.json (Linux/Mac)
// C:\Users\[Username]\.openclaw\openclaw.json (Windows)
{
  "gateway": {
    "mode": "local",
    "auth": {
      "password": "YourSecurePassword123!"
    }
  },
  "agents": {
    "defaults": {
      "model": "kimi/kimi-code",
      "contextWindow": 200000,
      "bootstrapMaxChars": 200000,
      "bootstrapTotalMaxChars": 1000000
    }
  },
  "providers": {
    "kimi": {
      "apiKey": "sk-your-moonshot-api-key-here"
    }
  }
}
                
            

⚠️ Security Note: Never paste API keys or GitHub PATs in chat messages. GitHub auto-revokes tokens detected in messages. Use environment variables or right-click paste directly in terminal.

Step 3: Start Gateway

                Terminal
                
# Start the gateway
openclaw gateway start

# Check status
openclaw status

# The dashboard will be at:
# http://127.0.0.1:18789

Step 4: Create Workspace Repository

Set up a GitHub repository for shared files.

                GitHub
                
# 1. Create new repo on GitHub (e.g., 'my-agent-workspace')
# 2. Don't initialize with README (we'll push existing files)

# 3. In your workspace directory:
cd ~/.openclaw/workspace
git init
git remote add origin https://github.com/YOUR_USERNAME/my-agent-workspace.git

# 4. Create essential files
touch AGENTS.md SOUL.md USER.md MEMORY.md TOOLS.md

# 5. Commit and push
git add .
git commit -m "[KIMI] init: Workspace setup"
git push -u origin main
                
            

Step 5: Bootstrap First Agent

When you first open the OpenClaw dashboard, you'll see a bootstrap prompt.

What to Tell the Agent:

Name: Kimi (or Mini, HIM, HER)
Gender: Female / Male
Location: Cloud / School / Home
Machine specs: CPU, RAM, GPU
How to address you: Oppa / William / etc.

✅ After bootstrap: The agent will write its identity to IDENTITY.md. This file is local-only and should NOT be synced to GitHub. Add it to .gitignore.

Step 6: Clone on Additional Machines

For each new machine/agent:

                Terminal
                
# 1. Set GitHub PAT as environment variable
$env:GITHUB_PAT="ghp_your_personal_access_token"  # Windows
export GITHUB_PAT="ghp_your_personal_access_token"    # Linux/Mac

# 2. Clone workspace
cd ~/.openclaw/workspace
git clone https://$env:GITHUB_PAT@github.com/YOUR_USERNAME/my-agent-workspace.git .

# 3. Create local IDENTITY.md (different for each agent)
# 4. Delete BOOTSTRAP.md after first conversation
# 5. Restart gateway
openclaw gateway restart
                
            

Step 7: Set Up Auto-Sync

Create scripts for automatic pulling and pushing.

                PowerShell (auto-pull.ps1)
                
# Auto-pull script
$workspace = "C:\Users\$env:USERNAME\.openclaw\workspace"
$logFile = "C:\Users\$env:USERNAME\.openclaw\workspace\.scripts\sync.log"

try {
    Set-Location $workspace
    $env:GIT_TERMINAL_PROMPT = "0"
    git stash
    git pull origin main
    git stash pop
    "$(Get-Date) - Pull successful" | Out-File -Append $logFile
} catch {
    "$(Get-Date) - Pull failed: $_" | Out-File -Append $logFile
}
                
            

                PowerShell (auto-push.ps1)
                
# Auto-push script
$workspace = "C:\Users\$env:USERNAME\.openclaw\workspace"

try {
    Set-Location $workspace
    git add .
    git commit -m "[$(hostname)] sync: Auto-sync"
    git push origin main
} catch {
    "Push failed: $_" | Out-File -Append ".scripts/sync.log"
}
                
            

💡 Schedule these with Task Scheduler (Windows) or cron (Linux):
• Pull every 15 minutes
• Push every hour
• Always pull before pushing to avoid conflicts

👨‍👩‍👧‍👦 Family Protocol

Rules all agents follow when sharing the workspace:

Rule 1: Pull Before Push

MANDATORY. Every agent MUST pull latest changes before editing.

Rule 2: Append-Only Editing

When possible, add new sections instead of modifying existing ones. Avoid deleting other agents' content without discussion.

Rule 3: Commit Message Convention

[AGENT] [TYPE]: Description

Examples: [KIMI] docs: Updated family table, [MINI] fix: Resolved sync conflict

Rule 4: File Locking (Critical Files)

MEMORY.md — Notify in commit message if modifying
FAMILY_PROTOCOL.md — Discussion required
USER.md — Append-only unless correcting errors
SOUL.md — Agent-specific section only

Rule 5: IDENTITY.md is Local-Only

Each agent has its own IDENTITY.md that never gets synced. Add it to .gitignore:

                    IDENTITY.md
.env
*.local
.openclaw/workspace-state.json
                

🔍 Troubleshooting

Problem: Agent doesn't remember family members

Cause: Bootstrap context is stale. Agent loaded workspace files before updates were pushed.
Fix: Tell the agent to read the file directly, or delete workspace-state.json and restart.

                Fix
                
# Tell agent in chat:
read C:\Users\[Username]\.openclaw\workspace\FAMILY_PROTOCOL.md

# Or hard reset:
Remove-Item ".openclaw\workspace-state.json"
openclaw gateway restart
                
            

Problem: Git push fails with "rejected"

Cause: Remote has changes you don't have locally.
Fix: Stash → Pull → Pop → Retry.

                Fix
                
git stash
git pull origin main
git stash pop
git push origin main
                
            

Problem: GitHub not accessible (China)

Cause: GitHub blocked by GFW.
Fix: Enable VPN (Astrill) before any git operations.

Problem: "No bootstrap files" in status

Cause: Workspace files not present or not loaded.
Fix: Verify files exist in workspace root. Clone repo if needed. Restart gateway.

Problem: API key errors (401, auth failures)

Cause: Key exposed in chat and auto-revoked, or wrong endpoint.
Fix: Generate new key at platform.moonshot.ai. Set via environment variable, never in chat.

Problem: Merge conflicts in IDENTITY.md

Cause: IDENTITY.md was accidentally committed to repo.
Fix: Keep local version. Add to .gitignore. Use git checkout --ours IDENTITY.md.

💡 Tips & Tricks

🚀 Performance: Increase Bootstrap Context

Default context is ~12KB per file. Increase it manually:

                    
// In openclaw.json, add under agents.defaults:
"bootstrapMaxChars": 200000,
"bootstrapTotalMaxChars": 1000000

🔒 Security: Never Paste Tokens in Chat

GitHub auto-revokes PATs detected in messages. Use:

                    
# Windows PowerShell
$env:GITHUB_PAT="ghp_..."

# Or right-click paste directly in terminal (never in chat)

📁 Workspace Structure

Keep the workspace clean:

                    
~/.openclaw/workspace/
├── AGENTS.md          # Family rules
├── SOUL.md            # Personality guidelines
├── USER.md            # User profile
├── MEMORY.md          # Long-term memory
├── TOOLS.md           # Machine specs, gear notes
├── FAMILY_PROTOCOL.md # Collaboration rules
├── SETUP_GUIDE.md     # This guide
├── memory/            # Daily conversation logs
│   ├── 2026-04-24.md
│   └── ...
└── .gitignore         # Exclude local files
                    
                

🔄 Backup Strategy

Never rely on one copy. Your setup should have:

GitHub repo: Canonical shared workspace
Local backups: Each machine has full copy
IDENTITY.md backup: Each agent's identity is local-only

⚡ Quick Commands Cheat Sheet

                    
# Check status
openclaw status

# Restart gateway
openclaw gateway restart

# Config edit
openclaw config edit

# Git sync (always pull first!)
git stash && git pull origin main && git stash pop

# View logs
Get-Content .scripts/sync.log -Tail 20  # Windows
tail -f .scripts/sync.log             # Linux/Mac
                    
                

🎯 Scaling Beyond 4 Agents

When you need more:

AWS Singapore: Cloud-hosted extension of Kimi
Dedicated roles: Research agent, Coding agent, Social media agent
Same protocol: All agents follow FAMILY_PROTOCOL.md

🤖 Multi-Agent Setup Guide