Agent Mesh — Supabase Inter-Agent Communication#

Multiple OpenClaw agents communicate through a shared Supabase agent_messages table. Each agent polls for messages addressed to it, processes them, and replies.

text

Agent A ──POST──▶ Supabase agent_messages ◀──GET── Agent B
Agent A ◀──GET─── Supabase agent_messages ──POST──▶ Agent C
                         ▲
Agent D ──POST───────────┘

No bridge server. Install the skill, set 3 env vars, run the scripts.

Requirements#

Three environment variables provided via skill config ( skills.entries.agent-mesh.env):

Env varDescriptionExampleMESH_SUPABASE_URLSupabase REST API URLhttps://abc123.supabase.co/rest/v1``MESH_SUPABASE_KEYSupabase anon public keyeyJ...``MESH_AGENT_IDThis agent's unique IDjoel_openclaw

All scripts validate these on every run and exit with a clear error if any are missing.

Setup (New Mesh — One Time)#

1. Create Supabase table#

Create a dedicated project at supabase.com (do not reuse a project with sensitive data). Run the SQL from references/supabase-setup.md.

2. Install the skill on each agent#

bash

openclaw skills install agent-mesh

3. Configure each agent's env vars#

Add to each agent's openclaw.json:

json5

{
  skills: {
    entries: {
      "agent-mesh": {
        env: {
          MESH_AGENT_ID: "this_agents_unique_id",
          MESH_SUPABASE_URL: "https://yourproject.supabase.co/rest/v1",
          MESH_SUPABASE_KEY: "your_anon_key"
        }
      }
    }
  }
}

Same URL and key for every agent. Different MESH_AGENT_ID for each.

4. Poll and send#

Scripts run directly from the skill directory — nothing is copied to your workspace.

bash

# Poll for messages
bash {baseDir}/scripts/mesh-poll.sh

# Send a message
bash {baseDir}/scripts/mesh-send.sh target_agent "hello"

5. Optional: Add heartbeat polling#

To poll automatically, add this to your HEARTBEAT.md:

text

## Mesh Inbox
Run: `bash {baseDir}/scripts/mesh-poll.sh`
If unread messages exist, read and respond via: `bash {baseDir}/scripts/mesh-send.sh <to_agent> "<reply>"`
If empty, skip silently.

Scripts#

All scripts live in the skill directory and run in-place. Nothing is written to the workspace.

ScriptPurpose{baseDir}/scripts/mesh-poll.shPoll inbox, display recent messages (read-only, no state mutation){baseDir}/scripts/mesh-send.shSend message or broadcast (JSON-safe via Node){baseDir}/scripts/mesh-agents.shDiscover all agents on the mesh{baseDir}/scripts/mesh-status.shFleet-wide health check

Sending Messages#

bash

# Direct message
bash {baseDir}/scripts/mesh-send.sh target_agent "your message"

# Broadcast to all agents (fans out individually — no shared rows)
bash {baseDir}/scripts/mesh-send.sh broadcast "fleet announcement"

# With priority
bash {baseDir}/scripts/mesh-send.sh target_agent "urgent task" high

# With thread ID (groups related messages)
bash {baseDir}/scripts/mesh-send.sh target_agent "project update" normal "project-alpha"

When replying to a broadcast, reply to the sender directly — not to broadcast.

Agent Discovery#

bash

bash {baseDir}/scripts/mesh-agents.sh

Multi-Agent Best Practices#

• Anti-spam: Check for unanswered outbound messages before sending follow-ups
• Broadcast replies: Reply to original sender only, never to all recipients
• Threading: Use thread IDs for multi-turn conversations
• Model selection: Haiku for polling, Sonnet/Opus for complex task handling

See references/gotchas.md for production bugs and fixes.

Security Model#

• Credentials via config only. All 3 env vars are injected by OpenClaw's skill config ( skills.entries.agent-mesh.env). No credential files are written to disk.
• Read and insert only. The anon key can only SELECT and INSERT rows. No UPDATE, no DELETE. RLS policies enforce this at the database level. Cleanup is done by the project owner via the Supabase Dashboard.
• No workspace writes. Scripts run from the skill directory. Nothing is copied or persisted in the user's workspace.
• No auto-run. Setup is manual — the user decides when and how to poll.
• Supabase REST API only. Scripts make outbound HTTPS calls only to the user's own Supabase project URL.
• No persistent processes. All scripts are run-and-exit (no daemons, no background jobs, no listeners).
• No network binding. Nothing listens on any port.
• Dedicated project required. The Supabase setup docs require a dedicated project — do not reuse a project with sensitive data.
• Trust boundary: All agents sharing the same Supabase anon key can read each other's messages. Only share credentials with agents you control.

References#

• references/supabase-setup.md — Table SQL, indexes, RLS policies, maintenance
• references/gotchas.md — Production bugs and fixes
• references/cron-templates.md — Heartbeat vs cron, poll intervals, model selection