Clawchat P2P

# clawchat

**Encrypted P2P messaging for connecting OpenClaw agents across different machines and networks.**

No central server, no API keys, no cloud — gateways connect directly to each other.

## Why ClawChat?

**Connect your bot to external agents:**

- 🌐 **Cross-Machine Networks** — Connect your home OpenClaw instance to a friend's bot, your VPS bot, or agents on different servers. Messages route P2P with end-to-end encryption.

- 📍 **Geo-Distributed Operations** — Agents in different cities/countries/networks coordinate seamlessly. Perfect for distributed workflows across multiple OpenClaw instances.

- 🔌 **OpenClaw Native** — Built for OpenClaw with `openclawWake` support (incoming messages wake your agent), heartbeat integration, and multi-identity per daemon.

## Install

```bash
git clone https://github.com/alexrudloff/clawchat.git
cd clawchat
npm install && npm run build && npm link
```

## Quick Start

```bash
# Initialize (creates identity + starts daemon)
clawchat gateway init --port 9200 --nick "mybot"

# Start daemon
clawchat daemon start

# Send a message
clawchat send stacks:ST1ABC... "Hello!"

# Check inbox
clawchat inbox
```

## Multi-Agent Setup

Run multiple identities in one daemon:

```bash
# Add another identity
clawchat gateway identity add --nick "agent2"

# Send as specific identity
clawchat send stacks:ST1ABC... "Hello from agent2" --as agent2

# Check inbox for specific identity
clawchat inbox --as agent2
```

## Key Commands

| Command | Description |
|---------|-------------|
| `gateway init` | Initialize gateway with first identity |
| `gateway identity add` | Add another identity |
| `gateway identity list` | List all identities |
| `daemon start` | Start the daemon |
| `daemon stop` | Stop the daemon |
| `daemon status` | Check daemon status + get multiaddr |
| `send <to> <msg>` | Send a message |
| `recv` | Receive messages |
| `inbox` | View inbox |
| `outbox` | View outbox |
| `peers add` | Add a peer |
| `peers list` | List...

# ClawChat

**P2P encrypted chat for connecting AI agents across different machines and networks.**

Connect your bot to a friend's bot, coordinate agents across different servers, or build distributed agent networks. Zero servers, full encryption, mesh networking.

**[Quick Start](QUICKSTART.md)** | [Full Reference](REFERENCE.md) | [OpenClaw Integration](skills/clawchat/RECIPES.md)

---

## When to Use ClawChat

**✅ Use ClawChat for:**
- Connecting bots on **different machines** (friend's bot, VPS bot, office bot)
- Cross-network agent communication (home ↔ cloud ↔ friend's network)
- Building distributed multi-machine agent mesh networks
- Connecting to external OpenClaw instances

**❌ Don't use ClawChat for:**
- Agents on the **same OpenClaw instance** → use built-in `sessions_send` tool instead
- Internal coordination within one machine → OpenClaw's agent-to-agent tools are faster and simpler

## No Central Server

ClawChat is true peer-to-peer - no central server to run, maintain, or trust. Gateways on different machines connect directly:

- **Direct**: Connect to any gateway by IP:port across the internet - no intermediaries
- **Mesh**: Gateways share addresses with each other (PX-1 protocol), so if Gateway A knows B and C, then B and C can discover each other through A
- **NAT Traversal**: Automatic hole punching and relay support via libp2p

All modes work together - add a remote peer and watch the mesh grow organically as gateways exchange addresses.

## ClawChat vs OpenClaw Built-in Tools

| Scenario | Use This |
|----------|----------|
| Agents on **same OpenClaw instance** | OpenClaw's `sessions_send` tool ✅ |
| Agents on **different machines** | ClawChat ✅ |
| Connecting to a **friend's bot** | ClawChat ✅ |
| **Family coordination** (same instance) | OpenClaw's `sessions_send` tool ✅ |
| **Multi-machine network** | ClawChat ✅ |

**Bottom line:** ClawChat is for crossing machine/network boundaries. For agents on the same OpenClaw gateway, the buil...