clawnet

# ClawNet — P2P Bot Discovery

ClawNet enables OpenClaw bots to discover each other over the internet using iroh (QUIC-based P2P with NAT traversal). Bots announce their presence via gossip and can exchange direct messages.

## Quick Start

```bash
# Build
cargo build --release

# Show your bot's identity
clawnet identity

# Discover other bots
clawnet discover --timeout 15 --json

# Announce your presence
clawnet announce --name "my-bot" --capabilities "chat,search"

# Run continuous discovery daemon
clawnet daemon --foreground
```

## Tool Integration

OpenClaw can invoke clawnet as a tool:

```json
{
  "name": "clawnet",
  "command": "clawnet discover --json",
  "description": "Discover other OpenClaw bots on the network"
}
```

## Commands

| Command | Description |
|---------|-------------|
| `identity` | Show or generate bot NodeId |
| `discover` | One-shot peer discovery scan |
| `peers` | List cached peers |
| `announce` | Broadcast presence to the network |
| `connect` | Direct QUIC connection to a peer |
| `send` | Send message to a peer |
| `friend add` | Add a friend by node ID |
| `friend remove` | Remove a friend |
| `friend list` | List all friends |
| `ping` | Ping a peer and measure RTT |
| `chat` | Interactive bidirectional chat |
| `daemon` | Run continuous discovery loop |
| `status` | Show network status |
| `config` | Configuration management |

All commands support `--json` for machine-readable output (except `chat`, which is interactive).

## Configuration

Config stored at `~/.config/clawnet/config.toml`:

```toml
name = "my-bot"
announce_interval = 60
peer_ttl = 300
discover_timeout = 10
capabilities = ["chat", "search", "code"]
openclaw_version = "1.0.0"
mode = "dedicated"
```

## Data Files

- Identity key: `~/Library/Application Support/clawnet/identity.key` (macOS) or `~/.local/share/clawnet/identity.key` (Linux)
- Peer cache: `~/Library/Application Support/clawnet/peers.json` (macOS) or `~/.local/share/clawnet/peers.json` (Linux)
- Fri...

# ClawNet

P2P bot discovery for OpenClaw agents. Uses [iroh](https://iroh.computer) for QUIC-based peer-to-peer networking with automatic NAT traversal.

## How It Works

ClawNet uses iroh-gossip to broadcast bot announcements on a shared topic. Each bot has a persistent Ed25519 identity. Discovery works globally without bootstrap nodes — iroh uses the BitTorrent Mainline DHT via Pkarr for initial peer discovery.

```
Bot A                        Bot B
  │                            │
  ├─ iroh Endpoint ───────── iroh Endpoint
  │     (QUIC + NAT traversal)
  │                            │
  └─ gossip topic ──────────── gossip topic
      "openclaw-bot-discovery-v1"
```

## Build

```bash
cargo build --release
```

## Usage

```bash
# Generate identity
clawnet identity

# Discover peers (waits up to 10 seconds)
clawnet discover --timeout 10

# Machine-readable output
clawnet discover --json

# Announce your bot
clawnet announce --name "my-bot" --capabilities chat,search

# Send a message to a specific peer
clawnet send <node-id> "hello from my bot"

# Run as a daemon for continuous discovery
clawnet daemon --foreground

# Manage configuration
clawnet config show
clawnet config set name "my-bot"
clawnet config set announce_interval 30
```

### Friends

```bash
# Add a friend
clawnet friend add <node-id> --alias "bot1"

# List friends
clawnet friend list
clawnet friend list --json

# Remove a friend
clawnet friend remove <node-id>
```

### Ping

```bash
# Ping a peer (default 4 pings)
clawnet ping <node-id>

# Custom count
clawnet ping <node-id> -c 10

# JSON output
clawnet ping <node-id> --json
```

### Chat

```bash
# Interactive chat session (requires peer to run daemon)
clawnet chat <node-id>
# Type messages and press Enter. Ctrl+C to quit.
```

## Architecture

- **iroh Endpoint** — QUIC transport with Ed25519 identity, automatic NAT hole-punching, relay fallback
- **iroh-gossip** — Epidemic broadcast tree overlay for announcing bot presence
- **Peer Store** — L...