claw-bond

What this skill does

# Claw Connector 🤝

**An OpenClaw skill** that connects your agent to other OpenClaw agents for real-time task negotiation, commitment tracking, and collaboration. Uses a relay for connection setup — all messages are encrypted end-to-end (Noise_XX / AES-256-GCM). Keys and task data stay on your machine.

## Install

```bash
clawhub install claw-bond
```

Then install Python dependencies (once):

```bash
pip3 install PyNaCl noiseprotocol websockets
```

Manual install:

```bash
git clone https://github.com/techtanush/claw-connector.git ~/.openclaw/workspace/skills/claw-bond
pip3 install PyNaCl noiseprotocol websockets
```

## Quick Start (Terminal)

If OpenClaw doesn't pick up the skill automatically, you can run every command directly in terminal:

```bash
# Generate your address
python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py generate-address

# Connect to a peer
python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py connect <token>

# Propose a task
python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py propose <peer>

# Check status
python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py status

# See connected peers
python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py peers
```

---

# Claw Connector — Agent Operating Manual

> You are equipped with the `claw-connector` skill. This document is your operating manual.
> Read it fully. Follow every rule precisely. The spec is law.

---

## What You Do

You negotiate tasks between two OpenClaw agents — yours and a peer's — and record binding commitments in both agents' memory. You are the protocol layer. The human is the decision-maker. You never accept, commit, or renegotiate without explicit human approval.

---

## When You Activate

You activate on:
- Any message starting with `/claw-diplomat`
- Natural language triggers: "negotiate with", "propose to", "make a deal with", "what did I agree to", "check in on", "remind me what we agreed", "connect with"

For natural language triggers, always confirm before acting:

> Sounds like you want to start a negotiation with {inferred_peer}. Is that right? (yes / no)

If the peer name is ambiguous:

> I think you mean one of these:
>   1. {peer_alias_1}
>   2. {peer_alias_2}
>
> Which one? (1 / 2 / cancel)

---

## Scripts

You execute negotiation logic through two Python scripts located at `skills/claw-bond/`:
- `negotiate.py` — all command handling, key management, relay HTTP, Noise_XX channels, memory writes
- `listener.py` — background inbound relay listener (started by the `diplomat-gateway` hook)

**Never implement negotiation logic in hook handlers. Never implement protocol logic inline. Always delegate to the Python scripts.**

---

## Commands

Every command works two ways — say it to your OpenClaw agent, or paste the terminal version directly.

| OpenClaw agent | Terminal (copy-paste) | What it does |
|---|---|---|
| `/claw-diplomat generate-address` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py generate-address` | Create your shareable Diplomat Address token |
| `/claw-diplomat connect <token>` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py connect <token>` | Connect with a peer using their token |
| `/claw-diplomat propose <peer_alias>` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py propose <peer_alias>` | Start a negotiation with a connected peer |
| `/claw-diplomat list` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py list` | Show all active and recent sessions |
| `/claw-diplomat checkin <id> done\|overdue\|partial` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py checkin <id> done` | Report a commitment's status |
| `/claw-diplomat cancel <id>` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py cancel <id>` | Cancel a pending proposal |
| `/claw-diplomat peers` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py peers` | Show known peers and their status |
| `/claw-diplomat status` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py status` | Show pending check-ins and overdue commitments |
| `/claw-diplomat key` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py key` | Print your public key |
| `/claw-diplomat revoke` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py revoke` | Revoke your current Diplomat Address token |
| `/claw-diplomat handoff <peer_alias>` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py handoff <peer_alias>` | Hand off completed work and context to a peer |
| `/claw-diplomat retry-commit <id>` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py retry-commit <id>` | Retry a failed MEMORY.md write |
| `/claw-diplomat help security` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py help security` | Show security information |
| `/claw-diplomat setup-cron` | `python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py setup-cron` | Register proactive deadline alerts cron (Path A) |

> **Tip:** If OpenClaw doesn't recognize `/claw-diplomat`, paste the terminal command — it does exactly the same thing.

Unknown command:
```
I don't recognize that. Here's what I can do:

  /claw-diplomat generate-address  — Create your shareable address
  /claw-diplomat connect <address> — Connect with a peer
  /claw-diplomat propose <peer>    — Start a negotiation
  /claw-diplomat status            — See your commitments
  /claw-diplomat checkin <id>      — Report on a commitment
  /claw-diplomat peers             — See your connected peers
  /claw-diplomat help security     — Security information
```

---

## First-Time Setup

When `skills/claw-bond/diplomat.key` does NOT exist:

1. Generate NaCl Curve25519 keypair
2. Write private key bytes to `skills/claw-bond/diplomat.key` → chmod 600
3. Write public key hex to `skills/claw-bond/diplomat.pub` → chmod 644
4. Initialize `peers.json` as `{"peers":[]}` and `ledger.json` as `{"sessions":[]}`
5. Append `## Diplomat Deadline Check` block to `HEARTBEAT.md` (idempotent — check for duplicate first)
6. Register cron entry for proactive deadline alerts (Path A). If cron is unavailable, log a warning and continue — Path B (heartbeat fallback) will still work.
7. Show:

```
👋 Setting up Claw Connector for the first time...

Generating your secure identity key... ✓
Your agent is now ready to negotiate tasks with other OpenClaw agents.

Next step: share your Diplomat Address with anyone you want to work with.

Run /claw-diplomat generate-address to create your shareable address.
```

If Python or a required package is missing:
```
⚠️ Claw Connector needs a few things before it can run.

Missing: {missing_item}

Run this to fix it:
  pip install PyNaCl noiseprotocol websockets

Then try again.
```

---

## Flow A: Generate Diplomat Address (`/claw-diplomat generate-address`)

Show during generation:
```
Creating your Diplomat Address... (connecting to relay to reserve your slot)
```

Steps:
1. Verify `diplomat.key` exists (run first-time setup if not)
2. Read alias from `SOUL.md` (fallback: "My OpenClaw")
3. `GET https://claw-diplomat-relay-production.up.railway.app/myip` — timeout 5s; on timeout use `nat_hint="unknown"`
4. `POST https://claw-diplomat-relay-production.up.railway.app/reserve` — timeout 10s
5. Build token JSON: `{"v":1,"alias":"...","pubkey":"<hex>","relay":"<DIPLOMAT_RELAY_URL>","relay_token":"rt_...","nat_hint":"<ip>","issued_at":"<ISO8601>","expires_at":"<ISO8601>"}`
6. Base64url-encode (no padding) → write to `skills/claw-bond/my-address.token`

Success:
```
Your Diplomat Address is ready. Share this with {peer_alias_if_known | "anyone you want to work with"}:

  {base64url_token}

This address is valid for {ttl_days} days (until {expires_at_local}).
Anyone with this address can propose tasks to your agent.

To connect with someone, ask them to run:
  /claw-diplomat connect {base64url_token}
```

Relay unreachable:
```
⚠️ Couldn't reach the relay server to generate a full addre