Coding Agent ↔ OpenClaw Agent Integration Guide

Purpose: Enable bidirectional messaging between Coding Agent (running on Windows) and OpenClaw/Clawdbot gateway agents (running in WSL2)

Version: 1.0.0 Last Updated: 2026-02-03 Status: Production Ready (Phase 4 Complete, 224 tests: 196 pytest + 28 script integration)

Overview
Architecture
Prerequisites
Installation
Agent Registration
Message Flow
OpenClaw Bridge Integration
Coding Agent Integration Patterns
End-to-End Walkthrough
Troubleshooting
Current Limitations
Future Enhancements
Reference

Overview

The Problem

Coding Agent and OpenClaw gateway agents operate in different contexts:

Component	Runtime	Location
Coding Agent	Windows terminal session	Windows 11 host
OpenClaw Agent	Gateway service	WSL2 Linux instance

By default, communication is one-way only:

Coding Agent → OpenClaw Agent ✅  (via `wsl -d <instance> -e openclaw agent --message "..."`)
OpenClaw Agent → Coding Agent ❌  (no mechanism)

The Solution

agent-comm provides a SQLite-backed message spool with:

Atomic claim/lease semantics for reliable delivery
Agent registry with capability discovery
CLI tools for send/poll/ack workflows
OpenClaw bridge for gateway integration
MCP server with 14 tools for programmatic access

This enables true bidirectional communication:

Coding Agent ←→ Message Spool ←→ OpenClaw Agent
     ↓              ↓              ↓
   send()      coordination.db   poll()
   poll()                        send()

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Windows 11 Host                          │
│                                                                 │
│  ┌─────────────────┐                                           │
│  │   Coding Agent   │                                           │
│  │   (Terminal)    │                                           │
│  └────────┬────────┘                                           │
│           │                                                     │
│           │ wsl -d <instance> -e bash -c '...'                 │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    WSL2 Instance                         │   │
│  │                                                          │   │
│  │  ┌──────────────┐    ┌──────────────┐    ┌───────────┐  │   │
│  │  │ agent-comm   │    │ Message      │    │ OpenClaw  │  │   │
│  │  │ CLI/Library  │◄──►│ Spool        │◄──►│ Gateway   │  │   │
│  │  └──────────────┘    │ (SQLite)     │    │ Agent     │  │   │
│  │                      └──────────────┘    └───────────┘  │   │
│  │                                                          │   │
│  │  Location: ~/projects/agent-comm/data/coordination.db   │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Key Components

Component	Purpose	Location
`agent_comm`	Core Python library	`~/projects/agent-comm/agent_comm/`
`coordination.db`	SQLite message spool	`~/projects/agent-comm/data/`
`agent_comm_mcp`	MCP server (14 tools)	`~/projects/agent-comm/agent_comm_mcp/`
CLI	Command-line interface	`python -m agent_comm <command>`

Prerequisites

System Requirements

Requirement	Minimum	Recommended
Windows	Windows 10 21H2	Windows 11
WSL2	Any distro	Ubuntu 24.04
Python	3.10+	3.12
OpenClaw/Clawdbot	2026.1.x	Latest

Software Dependencies

On WSL2 instance:

Python 3.10+ with pip
uv (recommended) or pip for package management
Git for cloning the repository
OpenClaw or Clawdbot gateway installed and running

On Windows host:

Coding Agent CLI installed
WSL2 configured with target instance

Required Access

GitHub access to fbratten/agentspool repository
Personal Access Token with repo read scope

Installation

Step 1: Clone the Repository

# From Windows, execute in WSL
wsl -d <your-instance> -e bash -c '
mkdir -p ~/projects
cd ~/projects
git clone https://github.com/fbratten/agentspool.git
'

If using a Personal Access Token:

wsl -d <your-instance> -e bash -c '
git config --global credential.helper store
echo "https://<username>:<PAT>@github.com" >> ~/.git-credentials
cd ~/projects
git clone https://github.com/fbratten/agentspool.git
'

Step 2: Create Virtual Environment

wsl -d <your-instance> -e bash -c '
cd ~/projects/agent-comm
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
'

Using uv (faster):

wsl -d <your-instance> -e bash -c '
cd ~/projects/agent-comm
uv venv .venv
source .venv/bin/activate
uv pip install -e ".[dev]"
'

Step 3: Verify Installation

wsl -d <your-instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm --help
'

Expected output:

usage: agent-comm [-h] [--project-root PROJECT_ROOT]
                  [--transport {sqlite,file}]
                  {register,send,poll,ack,nack,status,agents,stats,cleanup,bridge,relay} ...

Inter-agent communication and coordination system

Agent Registration

Before agents can communicate, they must be registered in the agent-comm registry.

Register the OpenClaw Agent

wsl -d <your-instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm register <agent-name> \
  -c "research,chat,gmail,calendar,tools,files" \
  -d <device-id>
'

Parameters:

<agent-name>: Unique identifier (e.g., gateway-agent, assistant-1)
-c: Comma-separated capabilities
-d: Device identifier for routing

Example:

.venv/bin/python -m agent_comm register my-assistant \
  -c "research,chat,gmail,tools" \
  -d wsl-main

Register Coding Agent

wsl -d <your-instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm register coding-agent \
  -c "code,implementation,bash,mcp" \
  -d windows-host
'

Verify Registration

wsl -d <your-instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm agents
'

Expected output:

Registered agents (2):
  my-assistant [active] caps=['research', 'chat', 'gmail', 'tools'] device=wsl-main transport=sqlite
  coding-agent [active] caps=['code', 'implementation', 'bash', 'mcp'] device=windows-host transport=sqlite

Message Flow

MessageV2 Protocol

All messages follow the MessageV2 schema:

{
  "id": "msg_20260203_143022_a1b2c3",
  "version": "2.0",
  "from": "coding-agent",
  "to": "my-assistant",
  "subject": "Implementation task",
  "body": "Please implement the user authentication module.",
  "timestamp": "2026-02-03T14:30:22Z",
  "priority": "high",
  "routing": {
    "reply_to": null,
    "conversation_id": "conv_001",
    "ttl_hours": 24
  },
  "payload": {
    "type": "task_assignment",
    "data": { "scope": "feature", "files": ["auth.py", "login.py"] }
  }
}

Delivery States

queued → leased → acked
                ↘ failed (after max_attempts)

State	Description
`queued`	Message waiting for recipient
`leased`	Claimed by recipient, processing
`acked`	Successfully processed
`failed`	Delivery failed after retries

CLI Commands

Send a Message

.venv/bin/python -m agent_comm send <from> <to> "<body>" \
  -s "<subject>" \
  --priority <normal|high|low>

Example:

.venv/bin/python -m agent_comm send coding-agent my-assistant \
  "Please research AI agent frameworks and summarize findings" \
  -s "Research task" \
  --priority high

Output:

Sent: msg_20260203_143022_a1b2c3

Poll for Messages

.venv/bin/python -m agent_comm poll <agent-name>

Example:

.venv/bin/python -m agent_comm poll my-assistant

Output:

Found 1 message(s) for my-assistant:

  ID: msg_20260203_143022_a1b2c3
  From: coding-agent
  Subject: Research task
  Body: Please research AI agent frameworks and summarize findings

Acknowledge a Message

.venv/bin/python -m agent_comm ack <message-id> <agent-name>

Example:

.venv/bin/python -m agent_comm ack msg_20260203_143022_a1b2c3 my-assistant

View Spool Statistics

.venv/bin/python -m agent_comm stats

Output:

{
  "total_messages": 5,
  "deliveries": {
    "queued": 1,
    "acked": 4
  }
}

OpenClaw Bridge Integration

The OpenClaw bridge connects agent-comm to OpenClaw/Clawdbot gateway agents.

How the Bridge Works

Coding Agent sends message → Spool (queued)
Bridge polls spool for messages to gateway agent
Bridge calls: openclaw agent --message "<body>" --json
Gateway agent processes and responds
Bridge sends response back → Spool
Coding Agent polls for response

Bridge Command

.venv/bin/python -m agent_comm bridge <agent-name> --wsl-instance <instance>

Parameters:

<agent-name>: The registered agent to bridge
--wsl-instance: WSL2 instance name where OpenClaw runs

Current Limitation

Important: The automated bridge expects to run from Windows host and call wsl -d <instance>. When running the bridge from inside WSL, it fails because wsl command is not available in that context.

Current workaround: Manually forward messages using openclaw agent --message.

Manual Message Forwarding

When the automated bridge cannot be used, forward messages manually:

# 1. Poll for pending messages
.venv/bin/python -m agent_comm poll <gateway-agent>

# 2. Forward to OpenClaw
export PATH="/home/<user>/.local/share/pnpm:/home/linuxbrew/.linuxbrew/bin:$PATH"
openclaw agent --agent main --message "<message-body>" --json

# 3. Parse response and send reply
.venv/bin/python -m agent_comm send <gateway-agent> <sender> "<response>" -s "Re: <subject>"

# 4. Ack the original message
.venv/bin/python -m agent_comm ack <message-id> <gateway-agent>

Coding Agent Integration Patterns

Pattern 1: Direct CLI (Simplest)

Execute agent-comm commands directly from Coding Agent via bash:

# Send to gateway agent
wsl -d <instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm send coding-agent <agent> "Your message" -s "Subject"
'

# Poll for responses
wsl -d <instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm poll coding-agent
'

Pattern 2: Shell Wrapper Script

Create a wrapper script for convenience:

File: ~/projects/agent-comm/scripts/cc-send.sh

#!/bin/bash
# Usage: ./cc-send.sh <to-agent> "<message>" "<subject>"
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm send coding-agent "$1" "$2" -s "$3"

File: ~/projects/agent-comm/scripts/cc-poll.sh

#!/bin/bash
# Usage: ./cc-poll.sh
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm poll coding-agent

Pattern 3: Coding Agent Skill

Create a Coding Agent skill for integrated messaging:

File: .claude/skills/agent-comm/SKILL.md

---
name: agent-comm
description: Send messages to and poll from registered agents via agent-comm
allowed-tools:
  - Bash
---

# Agent Communication Skill

Use agent-comm to communicate with registered agents.

## Send a Message

```bash
wsl -d <instance> -e bash -c 'cd ~/projects/agent-comm && .venv/bin/python -m agent_comm send coding-agent <agent> "$ARGUMENTS" -s "From Coding Agent"'

Poll for Responses

wsl -d <instance> -e bash -c 'cd ~/projects/agent-comm && .venv/bin/python -m agent_comm poll coding-agent'

### Pattern 4: MCP Server Integration

agent-comm includes an MCP server with 14 tools:

| Tool | Purpose |
|------|---------|
| `comm_register_agent` | Register a new agent |
| `comm_send` | Send a message |
| `comm_poll` | Poll for pending messages |
| `comm_ack` | Acknowledge a message |
| `comm_nack` | Negative acknowledge |
| `comm_message_status` | Check delivery status |
| `comm_discover_agents` | List registered agents |
| `comm_deregister` | Remove an agent |
| `comm_spool_stats` | Spool statistics |
| `comm_cleanup` | Remove expired messages |
| `comm_get_conversation` | Get conversation history |
| `comm_heartbeat` | Update agent heartbeat |
| `comm_relay_gen_secret` | Generate relay HMAC secret |
| `comm_relay_list_secrets` | List relay secrets |

**MCP Configuration (`.mcp.json`):**

```json
{
  "mcpServers": {
    "agent-comm-mcp": {
      "command": "python",
      "args": ["-m", "agent_comm_mcp"],
      "cwd": "/path/to/agent-comm",
      "env": {
        "PYTHONPATH": "/path/to/agent-comm"
      }
    }
  }
}

End-to-End Walkthrough

This walkthrough demonstrates complete bidirectional communication.

Setup

# Verify agents are registered
wsl -d <instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm agents
'

Step 1: Coding Agent Sends Task

wsl -d <instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm send coding-agent my-assistant \
  "Please analyze the authentication module and suggest improvements" \
  -s "Code review request" \
  --priority high
'

Output:

Sent: msg_20260203_150000_abc123

Step 2: Gateway Agent Polls and Processes

# Poll for messages
wsl -d <instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm poll my-assistant
'

# Forward to OpenClaw (manual bridge)
wsl -d <instance> -e bash -c '
export PATH="$HOME/.local/share/pnpm:/home/linuxbrew/.linuxbrew/bin:$PATH"
openclaw agent --agent main --message "[agent-comm msg_20260203_150000_abc123] Please analyze the authentication module and suggest improvements" --json
'

Step 3: Gateway Agent Sends Response

wsl -d <instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm send my-assistant coding-agent \
  "Analysis complete. Found 3 issues: 1) Missing rate limiting, 2) Weak password hashing, 3) No session timeout. Recommendations attached." \
  -s "Re: Code review request"
'

Step 4: Coding Agent Receives Response

wsl -d <instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm poll coding-agent
'

Output:

Found 1 message(s) for coding-agent:

  ID: msg_20260203_150130_def456
  From: my-assistant
  Subject: Re: Code review request
  Body: Analysis complete. Found 3 issues: 1) Missing rate limiting...

Step 5: Acknowledge Messages

wsl -d <instance> -e bash -c '
cd ~/projects/agent-comm
.venv/bin/python -m agent_comm ack msg_20260203_150000_abc123 my-assistant
.venv/bin/python -m agent_comm ack msg_20260203_150130_def456 coding-agent
'

Troubleshooting

Common Issues

1. “Command not found: agent_comm”

Cause: Virtual environment not activated or not in PATH.

Fix:

cd ~/projects/agent-comm
source .venv/bin/activate
python -m agent_comm --help

Or use full path:

~/projects/agent-comm/.venv/bin/python -m agent_comm --help

2. “No agents registered”

Cause: Agents not registered in the spool.

Fix:

.venv/bin/python -m agent_comm register <agent-name> -c "capability1,capability2" -d <device>

3. “wsl command not found” (Bridge Error)

Cause: Running the bridge from inside WSL instead of Windows.

Current workaround: Use manual message forwarding (see OpenClaw Bridge Integration).

4. “Permission denied” accessing coordination.db

Cause: Database locked by another process or permission issue.

Fix:

# Check for locks
lsof ~/projects/agent-comm/data/coordination.db

# Reset permissions
chmod 664 ~/projects/agent-comm/data/coordination.db

5. Message stuck in “leased” state

Cause: Agent crashed during processing without acking.

Fix:

# Nack to return to queue
.venv/bin/python -m agent_comm nack <message-id> <agent>

# Or cleanup expired leases
.venv/bin/python -m agent_comm cleanup

Diagnostic Commands

# View all messages and their states
.venv/bin/python -m agent_comm stats

# Check specific message status
.venv/bin/python -m agent_comm status <message-id>

# List all registered agents
.venv/bin/python -m agent_comm agents

# View SQLite database directly
sqlite3 ~/projects/agent-comm/data/coordination.db ".schema"

Current Limitations

1. Bridge Requires Windows Host

The automated bridge (agent_comm bridge) is designed to run from Windows and call into WSL via wsl -d <instance>. This means:

Cannot run the bridge daemon from inside WSL
Messages require manual forwarding when bridge unavailable
No fully automated polling loop inside WSL

Workaround: Manual message forwarding using openclaw agent --message.

2. No Push Notifications

Currently uses polling model:

Agents must actively poll for messages
No webhook/callback mechanism for instant delivery
Polling interval determines latency

3. Single-Device SQLite

The SQLite transport (coordination.db) is local to one device:

Cross-device requires HTTP relay transport
Relay server must be running on target device
Tailscale/LAN required for connectivity

Available: In-WSL Bridge (Direct Mode)

The direct bridge runs inside WSL and calls openclaw agent directly — no Windows host or WSL wrapper required.

Usage

# Check if bridge target is available
python -m agent_comm bridge nelly --direct \
  --path-setup 'export PATH="$HOME/.local/share/pnpm:/home/linuxbrew/.linuxbrew/bin:$PATH"' \
  --check

# Run bridge daemon (polls and forwards messages)
python -m agent_comm bridge nelly --direct \
  --path-setup 'export PATH="$HOME/.local/share/pnpm:/home/linuxbrew/.linuxbrew/bin:$PATH"' \
  --env GOG_KEYRING_PASSWORD=your-keyring-password \
  --poll-interval 5

# Single poll cycle
python -m agent_comm bridge nelly --direct --path-setup '...' --once

Python API

from agent_comm.bridges import OpenClawDirectBridge
from agent_comm.bridges.openclaw_direct_bridge import DirectBridgeConfig

config = DirectBridgeConfig(
    agent_id="nelly",
    openclaw_agent="main",
    path_setup='export PATH="$HOME/.local/share/pnpm:/home/linuxbrew/.linuxbrew/bin:$PATH"',
    env_vars={"GOG_KEYRING_PASSWORD": "your-keyring-password"},
    timeout_seconds=600,
)
bridge = OpenClawDirectBridge(config)

# Check availability
if bridge.is_available():
    result = bridge.forward(message)

Benefits

Eliminates Windows dependency for bridge
Can run as systemd user service inside WSL
Enables fully automated message delivery

Future Enhancements

1. Webhook Integration

Add webhook support for real-time delivery:

Gateway calls webhook URL when message arrives
Coding Agent hosts lightweight webhook receiver
Eliminates polling latency

3. Systemd Service

Package bridge as systemd user service:

[Unit]
Description=agent-comm bridge for OpenClaw
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/user/projects/agent-comm
ExecStart=/home/user/projects/agent-comm/.venv/bin/python -m agent_comm bridge my-assistant --direct
Restart=always

[Install]
WantedBy=default.target

Reference

Environment Variables

Variable	Purpose	Default
`AGENT_COMM_DB_PATH`	SQLite database path	`./data/coordination.db`
`AGENT_COMM_PROJECT_ROOT`	Project root for registry/config	agent-comm repo root
`AGENT_COMM_TRANSPORT`	Transport backend (sqlite\|file)	`sqlite`
`AGENT_COMM_TTL_HOURS`	Default message TTL in hours	`24`
`AGENT_COMM_LEASE_SECONDS`	Default lease duration in seconds	`60`

CLI Quick Reference

Command	Description
`register <name>`	Register an agent
`send <from> <to> <body>`	Send a message
`poll <agent>`	Poll for messages
`ack <msg-id> <agent>`	Acknowledge message
`nack <msg-id> <agent>`	Negative acknowledge
`status <msg-id>`	Check delivery status
`agents`	List registered agents
`stats`	View spool statistics
`cleanup`	Remove expired messages
`bridge <agent>`	Run bridge daemon
`relay start`	Start HTTP relay server

Project Files

Path	Purpose
`~/projects/agent-comm/`	Project root
`agent_comm/`	Core library
`agent_comm_mcp/`	MCP server
`data/coordination.db`	Message spool
`.venv/`	Python virtual environment
`tests/`	Test suite (224 tests)

README.md — Project overview and quick start
docs/manual/ — Full user manual
CHANGELOG.md — Version history
CLAUDE.md — Coding Agent project guidelines

Human Setup Guide (Quick Reference)

For humans setting up Coding Agent to communicate with an OpenClaw agent:

1. Clone & Install

wsl -d <your-wsl-instance>
cd ~/projects
git clone https://github.com/fbratten/agentspool.git
cd agent-comm
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Register Agents

python -m agent_comm register my-gateway-agent -c "chat,tools" -d wsl
python -m agent_comm register coding-agent -c "code,bash" -d windows

3. Test Communication

# From Coding Agent (via WSL)
python -m agent_comm send coding-agent my-gateway-agent "Hello!" -s "Test"

# Check delivery
python -m agent_comm poll my-gateway-agent

4. Forward to OpenClaw

# Manual forwarding (until automated bridge supports in-WSL mode)
openclaw agent --message "Hello!" --json

That’s it! Bidirectional messaging is now enabled.

Part of the agentspool project — Inter-agent communication for LLM-powered AI entities

Coding Agent ↔ OpenClaw Agent Integration Guide

Table of Contents

Overview

The Problem

The Solution

Architecture

Key Components

Prerequisites

System Requirements

Software Dependencies

Required Access

Installation

Step 1: Clone the Repository

Step 2: Create Virtual Environment

Step 3: Verify Installation

Agent Registration

Register the OpenClaw Agent

Register Coding Agent

Verify Registration

Message Flow

MessageV2 Protocol

Delivery States

CLI Commands

Send a Message

Poll for Messages

Acknowledge a Message

View Spool Statistics

OpenClaw Bridge Integration

How the Bridge Works

Bridge Command

Current Limitation

Manual Message Forwarding

Coding Agent Integration Patterns

Pattern 1: Direct CLI (Simplest)

Pattern 2: Shell Wrapper Script

Pattern 3: Coding Agent Skill

Poll for Responses

End-to-End Walkthrough

Setup

Step 1: Coding Agent Sends Task

Step 2: Gateway Agent Polls and Processes

Step 3: Gateway Agent Sends Response

Step 4: Coding Agent Receives Response

Step 5: Acknowledge Messages

Troubleshooting

Common Issues

1. “Command not found: agent_comm”

2. “No agents registered”

3. “wsl command not found” (Bridge Error)

4. “Permission denied” accessing coordination.db

5. Message stuck in “leased” state

Diagnostic Commands

Current Limitations

1. Bridge Requires Windows Host

2. No Push Notifications

3. Single-Device SQLite

Available: In-WSL Bridge (Direct Mode)

Usage

Python API

Benefits

Future Enhancements

1. Webhook Integration

3. Systemd Service

Reference

Environment Variables

CLI Quick Reference

Project Files

Related Documentation

Human Setup Guide (Quick Reference)

1. Clone & Install

2. Register Agents

3. Test Communication

4. Forward to OpenClaw