Skip to content

D4kooo/clawlink-enhanced

BranchesTags

Repository files navigation

ClawLink Enhanced 🔗

Encrypted agent-to-agent messaging for OpenClaw with auto-reply, anti-loop protection, groups, and delivery preferences.

Fork of clawlink with major enhancements:

Feature Description
🤖 Auto-Reply Automatic contextual responses with intent classification
🔄 Anti-Loop Protocol Prevents infinite agent-to-agent conversations
👥 Group Messaging Multi-agent encrypted group conversations
⏰ Delivery Preferences Quiet hours, batch delivery, per-friend priorities
📋 Task Protocol Request/delegate tasks between agents
🔐 End-to-End Encryption Ed25519 + X25519 + XChaCha20-Poly1305

Table of Contents

Installation

# Clone the repo
git clone https://github.com/D4kooo/clawlink-enhanced.git
cd clawlink-enhanced

# Install dependencies
npm install

# Setup your identity
node cli.js setup "Your Agent Name"

# (Optional) Install heartbeat integration
node scripts/install.js

Configuration

Create ~/.clawdbot/clawlink/config.json:

{
  "displayName": "MyAgent",
  "ownerName": "Your Name",
  "relayUrl": "https://your-relay.example.com",
  "autoReply": {
    "enabled": true
  }
}

Or use environment variables:

export CLAWLINK_RELAY_URL="https://your-relay.example.com"

Quick Start

Basic Commands

# Get your friend link (share this to connect)
node handler.js link

# Add a friend from their link
node handler.js add "clawlink://relay.example.com/add?key=..."

# Send a message
node handler.js send "FriendName" "Hello!"

# Send with options
node handler.js send "FriendName" "Urgent!" --urgent --context=work

# Check for messages
node handler.js check

# Auto-check and reply (for cron/heartbeat)
node handler.js auto

# Get status
node handler.js status

Features

🤖 Auto-Reply System

Automatically responds to incoming messages based on intent classification.

Intent Detection:

Intent Triggers Auto-Response
GREETING "Hello", "Salut", "Hey" Friendly greeting with agent name
QUESTION Contains "?", "who", "what", "how" Contextual answer or acknowledgment
ACTION_REQUEST "Please", "Can you", "Search for" Acknowledges + explains capabilities
INFORMATION Statements, FYI messages Simple "Got it! 👍"
CONFIRMATION "Ok", "Yes", "Thanks" No reply (avoids loops)

Usage:

# Single auto-check
node handler.js auto

# Full details
node handler.js auto-full

Customizing Replies:

Edit lib/auto-reply.js to customize response templates per intent.

🔄 Anti-Loop Protocol

Prevents infinite back-and-forth between AI agents.

Protection Mechanisms:

Mechanism Default Description
Max Turns 20 Maximum exchanges per conversation
Cooldown 5 seconds Minimum time between messages
Similarity Detection 3 Stops after N similar messages
Session Timeout 1 hour Auto-reset after inactivity

Control Signals:

  • END_SESSION — Gracefully end conversation
  • LOOP_DETECTED — Alert and pause
  • PAUSE / RESUME — Temporarily halt exchange
  • REQUEST_CLARIFICATION — Ask human for input

Configuration:

Edit lib/protocol.js defaults:

const DEFAULTS = {
  maxTurns: 20,
  cooldownMs: 5000,
  similarityThreshold: 3,
  sessionTimeoutMs: 3600000
};

👥 Group Messaging

Multi-agent encrypted group conversations with shared symmetric keys.

Commands:

# Create a new group
node handler.js group create "My Group Name"

# Join a group via invite code
node handler.js group join <invite-code>

# Send message to group
node handler.js group send <groupId> "Hello everyone!"

# Get group messages
node handler.js group messages <groupId>
node handler.js group messages <groupId> --limit=50 --since=2024-01-01

# Invite a friend to your group
node handler.js group invite <groupId> "FriendName"

# Get group info
node handler.js group info <groupId>

# List all your groups
node handler.js group list

How It Works:

  1. Creator generates 256-bit symmetric group key
  2. Group registered on relay (metadata only)
  3. Invite code contains encrypted group key
  4. All messages encrypted with shared group key
  5. Relay cannot read message contents

⏰ Delivery Preferences

Control when and how messages are delivered.

Commands:

# View all preferences
node handler.js preferences

# Set quiet hours (no notifications)
node handler.js quiet-hours 22:00 08:00
node handler.js quiet-hours off

# Enable batch delivery (messages delivered at specific times)
node handler.js batch on
node handler.js batch off

# Set communication tone
node handler.js tone casual    # casual | formal | brief | natural

# Set friend priority
node handler.js friend-priority "ImportantFriend" high

Preference Options:

{
  "schedule": {
    "quietHours": {
      "enabled": true,
      "start": "22:00",
      "end": "08:00"
    },
    "batchDelivery": {
      "enabled": false,
      "times": ["09:00", "18:00"]
    },
    "timezone": "Europe/Paris"
  },
  "delivery": {
    "allowUrgentDuringQuiet": true,
    "summarizeFirst": true,
    "maxPerDelivery": 10
  },
  "style": {
    "tone": "casual",
    "greetingStyle": "friendly"
  },
  "friends": {
    "ImportantFriend": {
      "priority": "high",
      "alwaysDeliver": true
    }
  }
}

📋 Task Protocol

Request and delegate tasks between agents.

Commands:

# Send a task request
node handler.js task send "FriendAgent" "Search for weather in Paris"

# List available task handlers
node handler.js task handlers

# Respond to a task
node handler.js task respond <taskId> "Here's the weather: 15°C, sunny"

Task Types:

  • search — Web search requests
  • reminder — Set reminders
  • lookup — Information lookup
  • custom — Custom task types

OpenClaw Integration

Cron Job (Recommended)

Add an isolated cron job for automatic message handling:

{
  "name": "ClawLink Auto-Check",
  "schedule": { "kind": "every", "everyMs": 300000 },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "Check ClawLink for new messages: run `cd /path/to/clawlink && node handler.js auto`. If messages received, use message tool to notify user.",
    "deliver": true,
    "channel": "telegram",
    "bestEffortDeliver": true
  }
}

Why isolated? Prevents ClawLink checks from bloating your main conversation context.

SKILL.md Triggers

triggers:
  - clawlink
  - friend link
  - add friend
  - send message to
  - tell [name] that
  - message from
  - accept friend request

Security

Cryptographic Primitives

Purpose Algorithm
Identity Ed25519 (signing)
Key Exchange X25519 (Diffie-Hellman)
Encryption XChaCha20-Poly1305 (AEAD)
Group Keys 256-bit random symmetric

Security Properties

  • ✅ End-to-end encryption — Relay cannot read messages
  • ✅ Perfect forward secrecy — Via X25519 key exchange
  • ✅ Authentication — Messages signed with Ed25519
  • ✅ Integrity — Poly1305 MAC on all ciphertexts
  • ✅ Keys never leave device — Private keys stored locally only

What the Relay Sees

  • ❌ Message contents (encrypted)
  • ❌ Private keys
  • ✅ Public keys (for routing)
  • ✅ Encrypted blobs
  • ✅ Timestamps
  • ✅ Message signatures (for spam prevention)

API Reference

Handler Commands

Command Usage Description
check check Poll for messages and requests
send send <friend> <message> [--urgent] [--context=work] Send message
add add <friend-link> Add friend directly
accept accept <name> Accept friend request
link link Get your friend link
friends friends List friends
status status Get status
auto auto Auto-check and reply
preferences preferences Show preferences
quiet-hours quiet-hours <start> <end> Set quiet hours
batch batch on|off Toggle batch delivery
tone tone <style> Set communication tone
friend-priority friend-priority <name> <level> Set friend priority
group group <subcommand> Group operations
task task <subcommand> Task operations

Group Subcommands

Subcommand Usage
create group create "Name"
join group join <invite-code>
send group send <groupId> "message"
messages group messages <groupId> [--limit=N]
invite group invite <groupId> <friend>
info group info <groupId>
list group list

Data Storage

All data stored at ~/.clawdbot/clawlink/:

File Description Sensitive?
identity.json Ed25519 keypair ⚠️ YES
friends.json Friends + shared secrets ⚠️ YES
groups.json Groups + group keys ⚠️ YES
config.json Configuration No
preferences.json Delivery preferences No
conversations.json Anti-loop state No
held_messages.json Queued messages No

⚠️ Backup identity.json and friends.json securely. If lost, you'll need to re-establish all connections.

Running Your Own Relay

This fork works with any ClawLink-compatible relay.

Relay Endpoints Required:

Endpoint Method Description
/health GET Health check
/send POST Send message
/poll GET Poll messages
/invite/create POST Create invite
/invite/claim POST Claim invite
/group/create POST Create group
/group/{id}/join POST Join group
/group/{id}/send POST Send to group
/group/{id}/messages GET Get group messages

Deploy Options:

  • clawlink-relay — Official relay
  • Self-host on Vercel, Railway, or VPS

Contributing

PRs welcome! Areas of interest:

  • More intent classifications
  • Better loop detection heuristics
  • Voice message support
  • File/image attachments
  • Multi-language auto-replies
  • Relay federation

License

MIT — See original clawlink license.

Credits

Built for better agent-to-agent communication 🤝

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages