ai-collab — Autonomous Multi-Agent Collaboration

Two OpenClaw agents working in parallel on shared tasks, coordinated via a structured chat log and daemon inbox protocol.

Architecture Overview

CODEBLOCK0

Agent A (Primary): Interactive Claude Code session. Handles browser, complex tasks, user-facing responses.

Agent B (Daemon): claude --print subprocess. Handles background tasks, monitoring, quick lookups. Triggered by messages dropped in inbox.

Configuration

All settings via environment variables — no hardcoded values:

CODEBLOCK1

Supported models for AGENT_B_MODEL:

• - claude-haiku-4-5-20251001 — fastest, cheapest (recommended for daemon)
• INLINECODE3 — more capable, higher cost
• Any OpenAI model if using the GPT daemon variant (see examples/claude-gpt.md)

Quick Setup

CODEBLOCK2

Communication Protocol

Every message between agents follows this format. No open loops.

Rules:

1. 1. Answer questions before asking new ones
2. Close tasks before starting new ones
3. Every message moves work forward or closes a loop
4. Never: "let me know", "ready when you are", "standing by"

Example exchange:

A → B: [TASK:price-check] Get BTC price from CoinGecko
B → A: [ACK:price-check] Checking now.
B → A: [DONE:price-check] BTC $94,230 as of 03:15 UTC

Daemon Script (Agent B)

INLINECODE12 — drop in your collab directory:

CODEBLOCK4

Sending Messages (A → B)

CODEBLOCK5

Atomic write pattern (prevents partial reads):
CODEBLOCK6

Always use mktemp + mv — never write directly to inbox. inotifywait fires on moved_to, not close_write.

Chat Log Polling (B → A)

INLINECODE17 — run via cron every 60s:

CODEBLOCK7

Add to crontab:

* * * * * /bin/bash ~/.openclaw/workspace/collab/poll_chatlog.sh

Shared Filesystem Conventions

CODEBLOCK9

Logging to chat.log:
CODEBLOCK10

Rules:

• - Never log secrets from INLINECODE18
• Always timestamp every line
• Prefix with sender: A -> B: or B -> A: or SYSTEM: or INLINECODE22

Telegram Bridge (Optional)

Route user Telegram messages into Agent B's inbox. Full setup guide: INLINECODE23

Quick summary:

1. 1. Create a bot via @BotFather → get INLINECODE24
2. Add bot to your group → get GROUP_ID (negative number, e.g. -1001234567890)
3. Disable Group Privacy Mode in BotFather so bot can read all messages
4. Get your Telegram USER_ID from @userinfobot
5. Set in ~/.openclaw/.env: TELEGRAM_BOT_TOKEN, TELEGRAM_GROUP_ID, INLINECODE31
6. Run the bridge in tmux: INLINECODE32

CODEBLOCK11

See references/telegram-bridge.md for the complete production-ready implementation with message parsing, offset tracking, and error handling.

Agent Configurations

See examples/ for full configs:

Claude ↔ Claude (Jim + Clawdy)

• - Agent A: claude code (interactive, full tool access)
• Agent B: claude --print claude-haiku-4-5-20251001 (fast, scripting-optimized)
• Best for: heavy task parallelism, one agent researches while other implements

Claude ↔ GPT

• - Agent A: Claude Code (full tool use)
• Agent B: openai api chat.completions.create via script
• Best for: cross-model verification, Claude builds → GPT reviews

GPT ↔ GPT

• - Agent A: GPT-4o via openai CLI
• Agent B: GPT-4o-mini for fast background checks
• Best for: speed + cost optimization when all context is OpenAI

Task Handoff Pattern

When Agent A needs Agent B to own a task completely:

CODEBLOCK12

Agent A does not check on progress — waits for DONE or BLOCKED.

Approval Pattern

When Agent B's daemon needs user approval for a terminal command:

CODEBLOCK13

INLINECODE39 sends keystrokes to the tmux session running Agent B:

SESSION=$(tmux ls | grep agentb-session | head -1 | cut -d: -f1)
tmux send-keys -t "$SESSION" "$1" Enter

Rate Limiting

Agent B should implement a rate governor to prevent runaway API calls:

CODEBLOCK15

Financial Gate Protocol (TIERED — updated 2026-02-22)

Three tiers based on amount:

CODEBLOCK16

Daemon tiered gate logic:
CODEBLOCK17

If Tier 3 blocked: log [BLOCKED:financial-gate:tier3], send Telegram alert, do NOT execute.

Daemon Watchdog Pattern

Check daemon health every 15 minutes. If silent >15 min, restart:

CODEBLOCK18

Task Takeover Threshold

If Agent A (Jim) blocks on the same task twice, Agent B (Clawdy) takes it over:

CODEBLOCK19

Rule: Blocked 2x on same task → take it over, don't reassign.

Daemon Error Diagnosis

When daemon produces blank/error responses:

1. 1. Check /tmp/clawdy_last_err — contains last stderr from INLINECODE43
2. Check ANSI-stripped chat.log for CLAWDY_ERR: lines
3. Verify RESPONSE trimming line not corrupted (common issue: accidentally set to RESPONSE="")
4. Restart daemon: INLINECODE46

Auto-approve: Use Bash(*) in ~/.claude/settings.local.json. NEVER use tmux send-keys cron — it sends keypresses blindly to the wrong sessions.