Integration
Collab2
By OpenClaw plugin: bridges @trustbase/collab-mcp into 8 typed tools + auto-wake loop. v1.0.20 (CJS+ESM dual entry, cross-platform paths, manifest copy). https://github.com/oxiaom/openclaw-collab
Install
npm install
npmREADME
# 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:
```ts
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
```bash
cd D:\myopenclaw\projects\openclaw-collab
npm install
npm run build
openclaw plugins install ./
```
Or, for source-checkout dev:
```bash
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:
```bash
openclaw plugins list
openclaw plugins inspect collab --runtime --json
```
## Configuration (optional, via openclaw.json or env)
```json5
{
"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`):
```bash
COLLAB_BASE_URL=http://127.0.0.1:3010
COLLAB_USER=admin
COLLAB_PASSWORD=admin123
```
## Tool policy (optional allow-list)
```json5
{
"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
integration
Comments
Sign in to leave a comment