Claw Connector

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

clawhub install claw-bond

Then install Python dependencies (once):

pip3 install PyNaCl noiseprotocol websockets

Manual install:

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:

# 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 
Propose a task
python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py propose 
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:

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/:

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 | python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py connect | Connect with a peer using their token | | /claw-diplomat propose | python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py propose | 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 done\|overdue\|partial | python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py checkin done | Report a commitment's status | | /claw-diplomat cancel | python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py cancel | 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 | python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py handoff | Hand off completed work and context to a peer | | /claw-diplomat retry-commit | python3 ~/.openclaw/workspace/skills/claw-bond/negotiate.py retry-commit | 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 
 — Connect with a peer
  /claw-diplomat propose     — Start a negotiation
  /claw-diplomat status            — See your commitments
  /claw-diplomat checkin       — 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":"","relay":"","relay_token":"rt_...","nat_hint":"","issued_at":"","expires_at":""} 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 address.
Your local key is ready, but peers won't be able to connect until the relay is available.
Try again in a few minutes, or set up your own relay:
  DIPLOMAT_RELAY_URL=wss://your-relay.example.com:443
If you just want to connect on the same local network, that's fine — run /claw-diplomat generate-address again when you have internet access.

Flow B: Connect to Peer (/claw-diplomat connect )

Steps: 1. Decode Base64url → parse JSON; verify v==1, all required fields; check expires_at > now() 2. Search peers.json for matching pubkey; if found: reconnect; if alias changed: warn 3. Show: Connecting to {peer_alias}'s agent... 4. Relay connect + Noise_XX handshake (9-step sequence per CONNECTION_ARCHITECTURE.md §5) 5. Show: Verifying {peer_alias}'s identity... ✓ 6. Save/update peers.json entry

Success:

✅ You're connected to {peer_alias}'s agent.
You can now propose tasks: /claw-diplomat propose {peer_alias}
Or wait for them to propose to you.

Token expired:

This address has expired (it was valid until {expires_at_local}).
Ask {peer_alias_or_"your contact"} to run /claw-diplomat generate-address and share their new address.

Noise key mismatch:

⛔ Something doesn't look right.
The agent that responded has a different identity than the address token specified. This could mean:
  • {peer_alias} generated a new key and you have an old token (most likely)
  • Someone is intercepting the connection (unlikely but possible)
To be safe, ask {peer_alias} to share a fresh Diplomat Address and connect again.
This connection has been closed.

Flow C: Propose a Task (/claw-diplomat propose )

Steps: 1. Look up peer in peers.json — if not found: "I don't have a connection to {alias}. Run /claw-diplomat connect

What will you take on? (describe your tasks)
> {user types their tasks}
What are you asking {peer_alias} to do?
> {user types peer's tasks}
What's the deadline? (e.g. "Friday 5pm" or "2026-03-27 17:00")
> {user types deadline}
Check-in time? (optional — leave blank to use the deadline)
> {user types or presses Enter}

Here's what you're proposing to {peer_alias}:
  You'll do: {my_tasks_formatted}
  They'll do: {peer_tasks_formatted}
  Deadline: {deadline_local}
  {check_in_line_if_set}
Send this proposal? (yes / no)

Couldn't reach the relay right now. Your proposal has been saved and I'll retry the next time you open your agent.
To retry now: /claw-diplomat propose {peer_alias}

↩️  {peer_alias} has a counter-proposal:
  They'll do: {peer_new_my_tasks}
  You'll do: {peer_new_your_tasks}
  Deadline: {peer_new_deadline_local}
  (Changes from your original: {diff_summary})
What do you want to do?
  [accept]  — Agree to these terms
  [counter] — Propose different terms
  [reject]  — Decline and end the negotiation

What changes do you want to make?
Your tasks (currently: {current_my_tasks}):
> {user types or presses Enter to keep}
Their tasks (currently: {current_peer_tasks}):
> {user types or presses Enter to keep}
Deadline (currently: {current_deadline_local}):
> {user types or presses Enter to keep}
Sending counter-proposal to {peer_alias}...

✅ Deal locked in with {peer_alias}.
  You'll do: {my_tasks_formatted}
  They'll do: {peer_tasks_formatted}
  Deadline: {deadline_local}
I've logged this in your memory. I'll remind you before the deadline.

⚠️ I accepted the deal but couldn't write it to your memory.
Error: {error_message}
Please check your disk space and file permissions, then run:
/claw-diplomat retry-commit {session_id_short}
Your commitment is safely recorded in the skill's ledger (ledger.json) until this is resolved.

You already have 20 active commitments logged. Complete or cancel one before taking on another.
To see your current commitments: /claw-diplomat status

✅ Marked complete. {peer_alias}'s agent has been notified.
Great work.

Noted. I've logged this as partially complete.
Want to renegotiate the remaining tasks with {peer_alias}? (yes / no)

Logged as overdue. {peer_alias}'s agent has been notified.
You can renegotiate when you're ready: /claw-diplomat propose {peer_alias}

Logged as overdue. Opening a renegotiation with {peer_alias}...

📨 {peer_alias}'s agent is proposing a task split:
  They'll handle: {peer_my_tasks}
  They want you to handle: {your_tasks}
  Deadline: {deadline_local}
  Check-in: {checkin_local}
Any changes, or should I accept?

I'll accept {peer_alias}'s proposal. Once I send this, it becomes a logged commitment for both of you. Confirm? (yes / no)

Got it. I'll send {peer_alias}'s agent a counter-proposal:
  You'll handle: {your_tasks} — unchanged
  They'll handle: {peer_tasks} — unchanged
  Deadline: {deadline_local} — unchanged
  Check-in: {new_checkin_local}  ← changed
Should I send that? (yes / no)

I'll decline {peer_alias}'s proposal and close this negotiation. Confirm? (yes / no)

📨 An agent you haven't connected with before wants to propose something.
  Agent key: {pubkey_short} (from {peer_ip})
Do you want to add them as a peer to see what they're proposing?
  yes — I'll add them as "{suggested_alias}" and show you the full proposal
  no  — I'll decline and close the connection

⚠️ {peer_alias} missed their check-in.
  Their tasks: {peer_tasks_summary}
  Was due: {deadline_local}
They haven't reported their status yet. You can:
  • Wait — they may just be running late
  • Renegotiate: /claw-diplomat propose {peer_alias}
  • Log it officially: /claw-diplomat checkin {session_id_short} overdue

Lost connection to {peer_alias} mid-negotiation. No deal was recorded.
Your last proposed terms are saved. I'll try to reconnect the next time you open your agent.

Your connected peers:
  {peer_alias_1}  ·  last seen {relative_time_1}  ·  {connection_status_1}
  {peer_alias_2}  ·  last seen {relative_time_2}  ·  {connection_status_2}
{n} peer{s} total. To add a new peer: /claw-diplomat connect 

You haven't connected with anyone yet.
Share your address to get started: /claw-diplomat generate-address

claw-connector status:
Active commitments ({n}):
  {per_commitment_one_liner}
Pending proposals ({n}):
  {per_proposal_one_liner}
Overdue ({n}):
  {per_overdue_one_liner}
{nothing_to_show_message_if_all_zero}

All clear — no active commitments or pending proposals.

*/15 * * * * python3 {skill_dir}/cron_deadline_check.py >> {skill_dir}/cron.log 2>&1

⏰ Heads up — {my_tasks} is due in {hours} hours and {peer_alias} hasn't confirmed completion yet. Want me to check in with their agent?

Diplomat Deadline Check
On every heartbeat: scan ## Diplomat Commitments in MEMORY.md. For any entry marked [ACTIVE] where the Due date has passed, reply with the alias and ID. For any entry where Due is within 2 hours, flag as upcoming.