OpenClaw Agent Bridge

Send messages to any OpenClaw agent from external scripts, AI agents, or automation pipelines.

---

The Problem

OpenClaw has excellent multi-agent routing between OpenClaw agents. But what if you need to:

• Send a message from Hermes (research agent) to Forge (execution agent)?
• Trigger an agent from a cron job or webhook?
• Have Claude Code or another external tool dispatch a task to an OpenClaw agent?
• Build a CI/CD pipeline that notifies your agent?

There's no built-in way for external processes to talk into the OpenClaw ecosystem.

The Solution

This bridge connects to the OpenClaw gateway via WebSocket, authenticates with Ed25519 device signing (Protocol v3), and sends messages to any registered agent session.

External Agent  →  bridge.py  →  OpenClaw Gateway (WS:18792)  →  Target Agent Session

60-Second Quickstart

git clone https://github.com/dudman1/openclaw-agent-bridge.git
cd openclaw-agent-bridge
pip install -r requirements.txt
python pair.py
python cli.py --session "agent:main:telegram:direct:12345" --text "Hello from bridge"

That is the whole flow:

1. install deps
2. pair once
3. send messages

Install

git clone https://github.com/dudman1/openclaw-agent-bridge.git
cd openclaw-agent-bridge
pip install -r requirements.txt

# optional: editable install for local development
pip install -e .

Pair (one-time)

python pair.py

This registers your device with the OpenClaw gateway. You need the gateway running and access to an already-paired device for approval.

Send Messages

# By session key
python cli.py --session "agent:main:telegram:direct:12345" --text "Hello!"

# JSON output
python cli.py --session "agent:main:telegram:direct:12345" --text "Status: OK" --json

# Real example: Hermes -> Forge
python cli.py --session "agent:main:telegram:direct:1440870889" --text "HERMES: research complete, ready for execution"

from bridge import send_message

result = send_message(
    session_key="agent:main:telegram:direct:12345",
    message="Automated report: all systems nominal",
)

Configuration

Env Var	Default	Description
OPENCLAW_CONFIG_PATH	~/.openclaw/openclaw.json	Gateway config file
OPENCLAW_GATEWAY_PORT	18792	WebSocket port
OPENCLAW_BRIDGE_DIR	~/.openclaw-bridge	Credential storage

Pairing Prerequisites

Pairing requires one of:

1. Same-host auto-detect: the gateway's device identity (~/.openclaw-forge/identity/device.json) and paired devices file (~/.openclaw-forge/devices/paired.json) must be readable by the bridge process.
2. Manual approver: provide both --approver-identity PATH and --approver-token TOKEN from any device that is already paired and has operator scope.

You cannot pair with only the shared gateway token — you need an already-paired device to approve the new one.

Use Cases

• Multi-agent orchestration — Let Hermes push research findings to Forge for execution
• Cron → Agent — Schedule automated messages: 0 9 * * * python cli.py --session ... --text "..."
• Webhook handlers — Build HTTP endpoints that dispatch to agents
• CI/CD notifications — Notify your agent when builds complete or deploys happen
• Cross-platform bridges — Connect agents across different machines via Tailscale/SSH tunnels

Security

• Ed25519 device signing prevents impersonation
• All connections are local loopback only (ws://127.0.0.1) — not TLS, not network-exposed
• Trusted local transport assumption: this bridge assumes the local machine is trusted. Do not expose the gateway port to untrusted networks.
• Private keys stored with chmod 0600

Requirements

• Python 3.10+
• OpenClaw gateway running (any version with Protocol v3 support)
• cryptography, websocket-client packages (pip install -r requirements.txt)
• For pairing: access to the gateway's device identity and paired-devices files (same host), or a pre-authorized approver identity + token

License

MIT