Macp Openclaw

Name: Macp Openclaw
Rating: 3.5 (1 reviews)
Author: multiagentcognition

By multiagentcognition 👁 70 views ▲ 0 votes

Native MACP multi-agent coordination plugin for OpenClaw

GitHub

Install

openclaw plugins install @macp/openclaw-plugin

README

# @macp/openclaw-plugin

Native [MACP](https://github.com/multiagentcognition/macp) multi-agent coordination plugin for [OpenClaw](https://openclaw.ai).

Embeds the MACP protocol directly into the OpenClaw Gateway process, giving every agent real-time coordination with peers — both local OpenClaw agents and external IDE agents (Claude Code, Gemini CLI, Cursor, VS Code) on the same shared bus.

## Why this exists

OpenClaw already has multi-agent features. This plugin does not replace them — it fills a specific gap they cannot cover.

### The coordination model gap

OpenClaw's native inter-agent communication (`sessions_send`, `sessions_spawn`, `agentToAgent`) follows a **request-response** model. Agent A sends a message to Agent B, Agent B processes it, optionally replies for up to 5 ping-pong turns, then announces a result. This is **sequential** — one agent waits while the other works.

MACP is **real-time**. All agents run simultaneously and share a persistent message bus. There is no "turn" or "request-response cycle." Agent A broadcasts that it is editing `auth.ts`. Agent B sees this immediately on its next poll and avoids touching that file. Agent C dispatches a sub-task. Agent D picks it up. All of this happens concurrently, without any agent blocking or waiting for another.

| | OpenClaw Native | MACP |
|---|---|---|
| **Model** | Request-response (sequential turns) | Real-time shared bus (concurrent) |
| **Blocking** | Sender waits for receiver | No blocking — fire and observe |
| **Awareness** | Agent knows about the one it messaged | All agents see all channel traffic |
| **Scope** | Within one Gateway | Across Gateways + IDE agents |
| **Delivery** | Fire-and-forget text | Durable at-least-once with ACK |
| **Priority** | None | 4-tier with smart queue overflow |

### Cross-tool coordination

This is the primary use case. OpenClaw cannot coordinate with Claude Code, Gemini CLI, or other OpenClaw instances. The Gateway is the boundary. MACP breaks that boundary with a shared SQLite file — anyone who can open the file is on the bus.

```
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  OpenClaw    │    │  Claude Code │    │  Gemini CLI  │
│  Gateway     │    │              │    │              │
│  ┌────────┐  │    │  ┌────────┐  │    │  ┌────────┐  │
│  │Agent A │  │    │  │macp-mcp│  │    │  │macp-mcp│  │
│  │Agent B │  │    │  │ server │  │    │  │ server │  │
│  └───┬────┘  │    │  └───┬────┘  │    │  └───┬────┘  │
│  MACP plugin │    │      │       │    │      │       │
│  ┌───┴────┐  │    │      │       │    │      │       │
│  │MACPCore│──┼────┼──────┼───────┼────┼──────┘       │
│  └────────┘  │    │      │       │    │              │
└──────────────┘    └──────────────┘    └──────────────┘
        │                  │                    │
        └──────── shared .macp.db ──────────────┘
```

## Feature comparison with OpenClaw native

| Capability | OpenClaw Native | MACP Plugin | When to use MACP |
|---|---|---|---|
| **Agent messaging** | `sessions_send` — fire-and-forget text, up to 5 ping-pong turns | Durable bus with priority, TTL, ACK | When you need guaranteed delivery or real-time broadcast |
| **File locking** | `lock_file`/`unlock_file` — blocking checkout, stale lock bugs possible | Advisory claims with TTL auto-expiry | When you need self-healing locks or cross-tool visibility |
| **Shared memory** | LanceDB vectors + `SHARED_KNOWLEDGE.json` | Scoped (agent/channel/workspace), layered, cascading reads | When multiple tools need shared findings |
| **Task management** | `TASKS.json` (static RACI) | Full lifecycle: dispatch → claim → start → complete/block/cancel | When you need a live work queue, not a static list |
| **Goal tracking** | `SPRINT_CURRENT.json` (manual) | Hierarchical: mission → project_goal → agent_goal | When you need structured planning with progress tracking |
| **Sub-agent spawning** | `sessions_spawn` — isolated, tool-restricted, announce-back | Not provided | Use OpenClaw's — MACP coordinates peers, not children |
| **Routing** | Deterministic bindings: channel × account × peer → agent | Named channels, join/leave | Use OpenClaw's for inbound routing, MACP for coordination |
| **Context engine** | Pluggable `ContextEngine` (bootstrap/ingest/assemble/compact) | Poll-based injection via hook | Use OpenClaw's for deep context management |
| **Concurrency** | `maxConcurrentRuns`, lane queues, session serialization | None | Use OpenClaw's for back-pressure |
| **Cross-tool** | Not possible | Shared SQLite bus with any MACP-compatible agent | The reason this plugin exists |
| **Audit trail** | None for coordination | Full delivery/ACK audit with reason codes | When you need to trace what happened |
| **Profiles** | `SOUL.md` per agent (freeform) | Structured role definitions, searchable by skill | When agents need to discover each other's capabilities |

### Where OpenClaw native is better

- **Sub-agent spawning** — `sessions_spawn` with isolation and tool restrictions is deeper than anything MACP offers
- **Inbound routing** — binding system handles multi-channel, multi-account message routing at production scale
- **Context engine** — `ContextEngine` plugin interface is architecturally cleaner for context lifecycle management
- **Concurrency control** — lane queues and `maxConcurrentRuns` handle back-pressure; MACP doesn't

### Where MACP adds what OpenClaw cannot do

- **Real-time coordination** — concurrent shared awareness, not sequential request-response
- **Cross-tool bus** — IDE agents and multiple OpenClaw instances on the same channel
- **Structured task/goal lifecycle** — live dispatch/claim/complete beats static JSON files
- **Durable delivery** — at-least-once with ACK vs fire-and-forget
- **Self-healing file claims** — TTL auto-expiry eliminates stale locks

### Overlap guidance

Some features exist in both systems. Use this rule:

- **Need cross-tool visibility?** → Use MACP (`macp_ext_*` tools)
- **OpenClaw-only, within one Gateway?** → Use OpenClaw native (`sessions_send`, `lock_file`, etc.)

The plugin does not disable or replace any OpenClaw native features.

## Install

```bash
openclaw plugins install @macp/openclaw-plugin
```

## Configure

Minimal — add to `openclaw.json`:

```json5
{
  "plugins": {
    "enabled": true,
    "allow": ["macp-coordination"],
    "entries": {
      "macp-coordination": {
        "enabled": true,
        "config": {
          "projectId": "my-project"
        }
      }
    }
  }
}
```

Full options:

```json5
{
  "plugins": {
    "enabled": true,
    "allow": ["macp-coordination"],
    "entries": {
      "macp-coordination": {
        "enabled": true,
        "config": {
          // Identity
          "projectId": "my-project",

          // Storage — shared location so external agents can access
          "dbPath": "~/.macp/projects/my-project.macp.db",

          // Channels
          "defaultChannel": "general",

          // Polling
          "pollIntervalMs": 5000,
          "autoPollInject": true,

          // Channel bridge (forward WhatsApp/Slack/Telegram → MACP bus)
          "bridgeChannels": false,
          "bridgeChannelPriority": 0
        }
      }
    }
  }
}
```

## What happens on startup

1. Gateway starts → plugin opens the shared SQLite DB
2. Each OpenClaw agent bootstraps → auto-registered with MACP, joins default channel, announces presence
3. Background poll runs every `pollIntervalMs` → buffers deliveries
4. Agent turn starts → buffered deliveries injected into context as `<macp-deliveries>` block
5. Agent uses MACP tools during its turn (send, claim files, dispatch tasks, etc.)
6. Agent session ends → auto-deregistered from MACP
7. Gateway stops → all agents deregistered, DB closed cleanly

## Tools (47)

All 47 MACP tools are registered with the OpenClaw agent tool system:

**Core protocol (5)** — `macp_join_channel`, `macp_send_channel`, `macp_send_direct`, `macp_poll`, `macp_ack`

**Awareness (2)** — `macp_ext_list_agents`, `macp_ext_get_session_context`

**File ownership (3)** — `macp_ext_claim_files`, `macp_ext_release_files`, `macp_ext_list_locks`

**Shared memory (6)** — `macp_ext_set_memory`, `macp_ext_get_memory`, `macp_ext_search_memory`, `macp_ext_list_memories`, `macp_ext_delete_memory`, `macp_ext_resolve_memory`

**Profiles (4)** — `macp_ext_register_profile`, `macp_ext_get_profile`, `macp_ext_list_profiles`, `macp_ext_find_profiles`

**Goals (5)** — `macp_ext_create_goal`, `macp_ext_list_goals`, `macp_ext_get_goal`, `macp_ext_update_goal`, `macp_ext_get_goal_cascade`

**Tasks (9)** — `macp_ext_dispatch_task`, `macp_ext_claim_task`, `macp_ext_start_task`, `macp_ext_complete_task`, `macp_ext_block_task`, `macp_ext_cancel_task`, `macp_ext_get_task`, `macp_ext_list_tasks`, `macp_ext_archive_tasks`

**Agent lifecycle (3)** — `macp_ext_sleep_agent`, `macp_ext_deactivate_agent`, `macp_ext_delete_agent`

**Vault (4)** — `macp_ext_register_vault`, `macp_ext_search_vault`, `macp_ext_get_vault_doc`, `macp_ext_list_vault_docs`

**Context search (1)** — `macp_ext_query_context`

Additionally, 3 core protocol operations are handled automatically by the plugin lifecycle (not exposed as tools): `register`, `deregister`, `get_instructions`.

## Channel bridge

When `bridgeChannels: true`, the plugin forwards human messages from OpenClaw messaging channels (WhatsApp, Slack, Telegram, etc.) into the MACP bus on a `bridge:human` channel. This gives external IDE agents awareness of human conversations without any manual forwarding.

## Status command

```
/macp
```

Shows project ID, default channel, online agents, and bridge status.

## Architecture

```
src/
├── index.ts      # Plugin entry — registers service, tools, hooks, command
├── service.ts    # MACPService — lifecycle, poll loop, context injection
├── tools.ts      # All 47 tool registrations
├── bridge.ts     # MACPChannelBridge — messaging platforms → MACP bus
└── types.ts      # PluginConfig, AgentSession, OpenClaw AP

... (truncated)

tools