openclaw-collab

OpenClaw plugin that bridges the @trustbase/collab-mcp service (HTTP API on http://127.0.0.1:3010) into OpenClaw. It exposes collab messages, todos, broadcasts, commits, and stats as 8 typed tools, registers 6 typed hooks that mirror agent activity in both directions, and runs an auto-wake loop that injects system_event into the main session whenever new collab activity arrives — so the main agent wakes up seamlessly without manual trigger.

Architecture

+--------------------------+
| OpenClaw main session   |  ← wakes up via system_event
+--------------------------+
            ▲  api.on(...)
            │  (typed hooks)
            │
+--------------------------+        system_event        +-----------------------+
| openclaw-collab plugin  | ──────────────────────► |  collab-mcp (port 3010)|
|  - 8 tools (api.registerTool)                       |  - messages / todos    |
|  - 6 hooks (api.on)                                  |  - broadcasts / commits|
|  - 30s poll → system_event                           +-----------------------+
+--------------------------+
            ▲  HTTP
            │
+--------------------------+
| OpenClaw CLI / subagent |  ← also calls collab tools
+--------------------------+

Files (8)

openclaw-collab/
├── package.json              # @trustbase/openclaw-collab, peerDeps openclaw
├── openclaw.plugin.json      # manifest, contracts.tools + contracts.hooks
├── tsconfig.json             # ESM, target ES2022
├── README.md                 # ← you are here
└── src/
    ├── index.ts              # definePluginEntry + config resolution + wake bootstrap
    ├── config.ts             # CollabClient (fetch wrapper to localhost:3010)
    ├── tools.ts              # 8 api.registerTool(...)
    ├── hooks.ts              # 6 api.on(...)
    └── wake.ts               # poll loop → execFile('openclaw', ['system','event',...])

Tools (8)

| Tool | Wraps collab-mcp endpoint | Notes | | ---------------------------- | ---------------------------------------- | -------------------------------------- | | collab_messages_list | GET /api/messages?limit=... | Optional category / from_user / since_id filters | | collab_messages_send | POST /api/send | Auto-detects from_user from session key | | collab_todos_list | GET /api/todos?status=open\|done\|all | Returns open first, then done | | collab_todos_create | POST /api/todo | Title + priority | | collab_todos_complete | POST /api/todo action=complete | Pass todo_id | | collab_broadcast_send | POST /api/broadcast | Admin announcements | | collab_recent_commits | GET /api/commits?limit=... | Last N git commits ingested by collab | | collab_stats | GET /api/messages/stats | Total / unacked / byCategory / bySender / byRecipient (with ?to_user=) |

Server endpoints (collab-mcp 0.2.11+)

The plugin wraps a subset of these. For external scripts / curl use:

| Endpoint | Purpose | | ------------------------------------------------- | ---------------------------------------------- | | GET /api/messages/search?q=<kw>&limit=N | Full-text search across message content | | GET /api/messages/:id/thread?context=N | Conversation thread around a message (default 3) | | GET /api/messages/stats?to_user=<name> | Stats filtered by recipient | | GET /api/messages?since_id=<id>&limit=N | Poll for new messages (used by wake loop) | | POST /api/ack with {"ids":[...]} | Bulk-ack messages (HTTP 200 = success) |

Hooks (6)

| Hook | Action | | --------------------------------- | --------------------------------------------------------------------------------------- | | before_agent_run | Inject collab state (open todos, recent messages) as prependContext | | message_received | Mirror inbound user message into collab-mcp log via POST /api/send | | subagent_ended | Record subagent outcome into collab-mcp log | | heartbeat_prompt_contribution | When unacked > 0, inject a wake hint into the heartbeat prompt | | session_start / session_end | Log session lifecycle to collab-mcp |

Auto-wake loop (the "seamless" part)

wake.ts runs in gateway_start:

• Polls GET /api/messages/stats every pollIntervalSec seconds (default 30)
• If stats.unacked crosses unackedThreshold (default 1) AND differs from last seen, inject a system event into the main session:

execFile('openclaw', [
  'system', 'event',
  '--text', '[collab-mcp wake] 3 unacked messages (45 total). Use collab_messages_list to inspect.',
  '--session-key', 'agent:main:main',
], ...)

• The injected system event is part of the main session's prompt on the next turn
• The main agent sees the hint and naturally calls collab_messages_list to inspect

Auto-wake via collab-mcp side (alternative)

The plugin also installs a server-side path (still in this repo, see server/notify.ts once the package is built): collab-mcp can optionally POST to the OpenClaw host at the same /v1/events webhook path; the plugin exposes a hook there too. This gives sub-second wake for cases where the 30s poll is too slow.

Install

cd D:\myopenclaw\projects\openclaw-collab
npm install
npm run build
openclaw plugins install ./

Or, for source-checkout dev:

cd D:\myopenclaw\projects\openclaw-collab
npm install
# link as a dev plugin (the manifest's openclaw.extensions points at dist/index.js)
npm run build
openclaw plugins link ./

Verify the plugin is registered:

openclaw plugins list
openclaw plugins inspect collab --runtime --json

Configuration (optional, via openclaw.json or env)

{
  "plugins": {
    "entries": {
      "collab": {
        "config": {
          "baseUrl": "http://127.0.0.1:3010",
          "username": "admin",
          "password": "admin123",
          "pollIntervalSec": 30,
          "unackedThreshold": 1
        }
      }
    }
  }
}

Or via environment variables (read by config.ts):

COLLAB_BASE_URL=http://127.0.0.1:3010
COLLAB_USER=admin
COLLAB_PASSWORD=admin123

Tool policy (optional allow-list)

{
  "tools": {
    "allow": [
      "collab_messages_list",
      "collab_messages_send",
      "collab_todos_list",
      "collab_todos_create",
      "collab_todos_complete",
      "collab_broadcast_send",
      "collab_recent_commits",
      "collab_stats"
    ]
  }
}

Why this matters

Before this plugin, an OpenClaw agent had to either:

• Have collab-mcp loaded into the same memory context (heavy, not selective), or
• Be explicitly told "go check collab-mcp" by the user (no auto-wake).

After this plugin:

• The main session gets collab state injected before every agent run (before_agent_run)
• Heartbeat turn gets the wake hint when there's new activity
• Tools let the agent read or write collab without leaving OpenClaw
• The 30s poll → system_event injection wakes the main session without user trigger when something new appears in collab-mcp
• Inbound user messages are mirrored into collab-mcp, so Claude (the other side) can see them via the regular heartbeat poll

Dependencies

• openclaw (peer, >= 2026.3.24-beta.2)
• typebox ^1.1.39 (runtime, for tool parameter schemas)
• typescript ^5.6.0 (dev, for npm run build)

License

MIT