Skip to content

Last updated · 2026-01-30

OpenClaw Multi-Agent YAML Configuration (config.yaml / agents.yaml)

This guide explains the single-instance multi-agent approach (recommended):
one OpenClaw gateway, multiple agents defined in YAML, each with its own workspace/persona/model/permissions/memory, plus deterministic routing by channel/user/keywords.

⚠️ Keys may vary by version/plugins. After editing, always validate with:
openclaw gateway restart --verbose and inspect logs.

Contents

1. Two multi-agent approaches

Option A: Single-instance multi-agent (recommended)

  • One gateway process
  • YAML defines multiple agents
  • Route by channel/user/group/keywords
  • Pros: simple ops, low resource usage, centralized config

Option B: Multi-instance collaboration (stronger isolation, more complex)

  • Run multiple OpenClaw processes (different ports/workspaces)
  • Coordinate via webhooks/shared DB/orchestrator
  • Best when you need hard isolation (prod vs dev vs personal)

2. Why YAML is great for multi-agent setups

  • Multi-agent configs are repetitive (persona/model/permissions/memory/bindings)
  • YAML hierarchy is easier to read and maintain than JSON
  • Works well for docs sites and copy/paste onboarding

3. Files & directory layout

Recommended files

  • ~/.openclaw/config.yaml (often takes precedence if present)
  • ~/.openclaw/openclaw.json (can coexist; confirm via logs)
  • ~/.openclaw/.env (store secrets)

Recommended directories

  • ~/openclaw-workspaces/<agent>: per-agent workspace isolation
  • ~/.openclaw/agents/<agent>: per-agent persona/rules files

4. Recommended config.yaml example (copy/paste)

yaml
# ~/.openclaw/config.yaml agents:  list:    - id: home-personal      name: Home Assistant      default: true      description: Personal life assistant (daily tasks, shopping, entertainment)      workspace: ~/openclaw-workspaces/home      agentDir: ~/.openclaw/agents/home      model:        primary: anthropic/claude-3-5-sonnet-20241022        fallback: apiyi/claude-sonnet-4-20250514      persona:        role: "Warm, humorous home butler (Jarvis-like, down-to-earth)"        rules: "Reply in Chinese; prioritize privacy; never run rm/sudo proactively"      permissions:        allowedCommands: [ls, cat, echo, open, git status]        blockedCommands: ["rm -rf", sudo, "curl --upload"]      memory:        vectorStore: local        proactive: true     - id: work-coding      name: Code Master      description: Coding, debugging, architecture      workspace: ~/openclaw-workspaces/work      agentDir: ~/.openclaw/agents/work      model:        primary: anthropic/claude-opus-4-5        reasoning: anthropic/claude-opus-4-5      persona:        role: "Rigorous engineer, code-first, minimal fluff"        rules: "Write code comments in English; plan before execution; output diffs"      permissions:        allowedCommands: [code, git, npm, pytest, docker]        sandbox:          mode: strict          workspaceAccess: read-write     - id: research-deep      name: Research Agent      description: Deep research, literature reading, data analysis      workspace: ~/openclaw-workspaces/research      agentDir: ~/.openclaw/agents/research      model:        primary: minimax/MiniMax-M2.1      persona:        role: "Academic researcher, source-backed and logical"        rules: "Cite sources for conclusions; avoid hallucinations"   bindings:    - agentId: home-personal      match:        channel: whatsapp        accountId: "+861xxxxxxxxxx"     - agentId: work-coding      match:        channel: telegram        keywords: ["code", "debug", "fix bug", "写代码"]     - agentId: research-deep      match:        channel: feishu        groups: ["research-group"]     - agentId: home-personal      match: {} agents.defaults:  heartbeat:    every: 45m    activeHours:      start: "07:00"      end: "23:00"  sandbox:    mode: non-main    scope: session models:  providers:    apiyi:      baseUrl: https://api.apiyi.com/v1      apiKey: ${APIYI_KEY}

5. Apply steps (from zero to working)

5.1 Create/edit config.yaml

bash
mkdir -p ~/.openclawnano ~/.openclaw/config.yaml

5.2 Create workspaces and agentDirs

bash
mkdir -p ~/openclaw-workspaces/{home,work,research}mkdir -p ~/.openclaw/agents/{home,work,research}

5.3 Put secrets into .env (recommended)

bash
nano ~/.openclaw/.env

Example:

bash
ANTHROPIC_API_KEY=sk-REPLACE_MEAPIYI_KEY=sk-REPLACE_MEMINIMAX_API_KEY=YOUR_MINIMAX_KEYTELEGRAM_TOKEN=YOUR_TELEGRAM_BOT_TOKENFEISHU_APP_ID=cli_REPLACE_MEFEISHU_APP_SECRET=YOUR_FEISHU_APP_SECRET

5.4 Restart and confirm it loads

bash
openclaw gateway restart --verbose# oropenclaw restart --verbose

Look for log lines like:

  • loaded config.yaml
  • registered agents: ...
  • bindings loaded ...

5.5 Test routing

  • WhatsApp message → home-personal
  • Telegram “debug this bug” → work-coding
  • Feishu group “research-group” → research-deep

6. Routing design tips

6.1 Order matters (first-match wins)

Put most specific rules first:

  1. channel + accountId
  2. channel + group
  3. channel + keywords
  4. fallback match:

6.2 Keyword routing tips

  • Avoid overly broad keywords (e.g., “help” triggers too much)
  • Include both English and Chinese keywords
  • For high-risk agents, also restrict by user/account

7. AgentDir “trio” (SOUL/USER/AGENTS)

Under each agentDir, consider adding:

  • SOUL.md: persona and boundaries
  • USER.md: your preferences (language, timezone, tools, workflow)
  • AGENTS.md: cross-agent handoff rules (e.g., research → coding)

8. Advanced: cross-agent workflows

If your build supports workflows/orchestration ideas:

  • research-deep gathers sources and a structured brief
  • work-coding implements code changes from the brief
  • home-personal summarizes results in a friendly style

Add strict permissions when agents can execute commands or write files.

9. Troubleshooting

9.1 Routing not working

  • bindings order is wrong (most common)
  • keywords don’t match (punctuation/case/Chinese tokenization)
  • channel naming differs from your runtime (trust logs)

9.2 Memory/vector store contamination

  • Shared vector store paths may mix memories across agents
    ✅ Use separate workspaces or distinct memory paths per agent

9.3 Cost spikes

  • Expensive primary model without fallback
  • Research agent using costly long-context model too often
    ✅ Cheap primary + strong reasoning only when needed

9.4 Permission leakage

  • One agent allows too much
    ✅ Per-agent command allowlists; keep defaults minimal

10. Security notes (keep this)

  • More agents = more entry points. Apply least-privilege to every agent.
  • In group chats, require @mention to avoid accidental triggers.
  • For write/exec-capable agents, enforce user allowlists.
  • Don’t expose gateway admin ports publicly; if you must, add token + firewall allowlist + reverse proxy auth.
  • Test in an isolated environment (VPS/Docker/VM) before running on a primary machine.