ClawBridge

ClawBridge lets OpenClaw agents on different machines talk to each other.

You can use it in two ways:

• Simple mode: connect two or more machines and let agents ping, check status, and exchange messages.
• Advanced mode: run it as an operator-managed A2A service with permissions, TLS, and optional OpenClaw gateway bridging.

Pick Your Path

I want the easiest setup

Start here: docs/QUICKSTART_SIMPLE.md

This path is for people who want a working connection between machines with the fewest decisions.

I want to run it publicly or in production

Start here: docs/OPERATOR_GUIDE.md

This path is for operators managing domains, TLS, permissions, deploys, and incident recovery.

I want bridge/API details

Start here:

• docs/BRIDGE_SETUP.md
• docs/API_REFERENCE.md

I am an AI agent installing this repo for a user

Start here: docs/AGENT_INSTALL.md

What Success Looks Like

Two machines running OpenClaw can expose selected skills to each other over A2A.

graph LR
    A["OpenClaw on Laptop"] -->|"ping / chat / status"| B["ClawBridge on VPS"]
    B -->|"A2A response"| A

Loading

For most users, the first milestone is simple:

1. Install ClawBridge on machine A.
2. Install ClawBridge on machine B.
3. Run setup on both.
4. Start both servers.
5. Run npm run ping.

If that works, you have a real multi-machine agent link.

Why It Matters

graph TD
    A["Without ClawBridge"] --> A1["SSH into another box"]
    A --> A2["Copy context manually"]
    A --> A3["Write glue scripts"]

    B["With ClawBridge"] --> B1["Call peer skills directly"]
    B --> B2["Reuse specialized agents"]
    B --> B3["Control exposure with policy"]

    style A fill:#fee2e2,stroke:#b91c1c
    style B fill:#dcfce7,stroke:#15803d

Loading

Core Capabilities

• ping: check peer connectivity
• get_status: inspect a peer's available skills and uptime
• chat: send to local targets or run a session-first @agent turn on another peer
• broadcast: fan a message out to multiple peers
• openclaw_*: optionally expose a tightly controlled subset of OpenClaw gateway tools

For session-first direct @agent delivery on Telegram, Discord, and WhatsApp, the receiving node needs an existing local DM/session with that user so OpenClaw exposes a provider-bound session ClawBridge can reuse. When that session-first turn runs, the receiving node now delivers the local agent reply on its own provider session and also returns structured output to the caller.

Quick Install

git clone https://github.com/paprini/clawbridge.git
cd clawbridge
npm install
npm run setup
npm run verify
npm start

If you are not sure what to do next, go to docs/QUICKSTART_SIMPLE.md.

Versioning

ClawBridge now uses package.json as the single source of truth for the installed software version.

Users can see the installed version in:

• npm run status
• node src/cli.js version
• GET /status
• GET /health
• get_status
• the A2A agent card

Release flow:

npm run release:patch
git push origin main --follow-tags

Available commands:

• npm run release:patch
• npm run release:minor
• npm run release:major

Each release command runs the full test suite and npm run verify before creating the version commit and tag. Pushing the tag triggers the GitHub Release workflow to publish a real GitHub Release page.

Install a specific release tag:

git clone --branch v0.2.0 --depth 1 https://github.com/paprini/clawbridge.git

Use:

• patch for fixes
• minor for backward-compatible features
• major for breaking changes

See CHANGELOG.md for release notes and docs/RELEASING.md for the maintainer release checklist.

Documentation

• docs/README.md: documentation map by audience
• docs/QUICKSTART_SIMPLE.md: shortest human path to first success
• docs/USER_GUIDE.md: concept + usage guide for normal users
• docs/SETUP.md: setup tool reference
• docs/OPERATOR_GUIDE.md: deploy and operations path
• docs/PUBLIC_QUICKSTART.md: fastest public HTTPS deployment
• docs/BRIDGE_SETUP.md: advanced bridge configuration
• docs/API_REFERENCE.md: endpoints, payloads, config schema
• docs/DIAGRAMS.md: reusable marketing and architecture diagrams
• docs/RELEASING.md: maintainer release process

Product Positioning

ClawBridge should feel simple at first use and rigorous in advanced operation.

That means:

• simple users should see a short, linear path
• advanced users should get exact controls and protocol detail
• those two styles should stay separated