Clawdio

Transport-agnostic secure P2P communication for AI agents. Noise XX handshake, XChaCha20-Poly1305 encryption, connection consent, human verification. No WebSocket — works over Telegram, Signal, or any messaging transport.

Security Scan

The skill broadly matches a P2P encrypted-comm description, but multiple inconsistent/misproportioned items (hardcoded paths/IP, a start script that launches a local run.js, WebSocket code without a declared dependency, and mismatched packaging metadata) make the package unexpectedly opinionated and risky to run without review.

Purpose & Capability

The SKILL.md emphasizes Telegram as the transport and says 'No WebSocket', yet the source includes a WebSocket Transport implementation (src/transport.ts) and WebSocket server/client code. package.json lists only libsodium-wrappers as a dependency but the code imports 'ws' (missing from package.json). The start script (scripts/start.js) builds a connection string that embeds a hardcoded public host/IP (115.85.17.196:3579) and uses an absolute user path (/Users/jamesball/...) — these are not consistent with a transport-agnostic, privacy-first Telegram-centric description. Packaging metadata also mismatches the registry metadata version (package.json v2.0.0 vs registry v2.2.0) and claims files/dist that are not present. These inconsistencies indicate the codebase is not cleanly aligned with the declared purpose.

Instruction Scope

SKILL.md runtime instructions describe creating a Telegram group and wiring the OpenClaw message tool; they do not instruct running scripts/start.js. However scripts/start.js is included and, if executed, reads a local identity file, runs shell commands (pgrep, 'node run.js') in a hardcoded directory, and returns a connection string pointing to an external IP. That behavior (reading from a user-specific path, starting a background process, exposing a connection string with an IP) is outside the documented onboarding flow and is not justified in the documentation. The code also persists identity to disk (identityPath) and will create directories — SKILL.md mentions persistent identity but does not warn about absolute paths or the background starter script.

Install Mechanism

There is no install spec (instruction-only), which reduces installer-supply-chain risk. However, code contains direct child_process usage (exec) and a start script that launches 'node run.js' detached in a hardcoded directory — running that script would execute arbitrary local code. No network download/install is defined, but executing included scripts or building/running the code will run code that performs process spawning and can start long-lived processes. Additionally, package.json declares 'files': ['dist'] and main 'dist/index.js' but the repo contains src only; running 'npm install' as-is may not produce the expected artifacts.

Credentials

The skill declares no required environment variables or credentials, which superficially fits a pure crypto library. But scripts/start.js hardcodes an absolute user workspace path and a remote host/IP. The library writes/reads identity files and secret keys to disk when identityPath is set — this is expected for persistent identity, but the provided start script expects a specific path (/Users/jamesball/...) and identity file name (.clawdio-identity). The skill therefore implicitly requires filesystem access to user-specific locations and will expose a connection string containing a host/IP. The presence of an owner string ('James') hardcoded in the start script is further evidence the script was authored for a single user's environment rather than general use.

Persistence & Privilege

The skill is not marked always:true and is user-invocable (normal). However included scripts can start a detached background Node process (exec('node run.js') with child.unref()) — if an agent or user runs the provided start script it will create a persistent process outside the agent's lifecycle. That behavior creates persistence on the host machine and should be treated cautiously. There is no evidence the skill attempts to modify other skills or global agent configuration, but the background-launch behavior increases the blast radius if the script is executed.

Scan Findings in Context

[CHILD_PROCESS_EXEC] unexpected: scripts/start.js uses child_process.exec to run shell commands (pgrep, 'node run.js'). A P2P library may provide CLI helpers, but executing arbitrary shell commands in a hardcoded user directory is not expected from the SKILL.md onboarding flow and should be treated with caution.

[HARDCODED_ABSOLUTE_PATH] unexpected: scripts/start.js hardcodes CLAWDIO_DIR = '/Users/jamesball/.openclaw/workspace/projects/clawdio'. This is user-specific and inconsistent with a reusable skill; it may access files outside the agent's working area.

[HARDCODED_REMOTE_IP] unexpected: scripts/start.js returns a connectionString with host '115.85.17.196:3579'. The SKILL.md emphasizes Telegram transport and NAT-less usage; embedding a static external IP is unexpected and could point to a central host or leftover test config.

[MISSING_DECLARED_DEPENDENCY] unexpected: src/transport.ts imports 'ws' but package.json does not declare 'ws' as a dependency. That mismatch will break builds or indicate the repository is incomplete or tailored for a different environment.

[MISSING_RUNTIME_FILE] unexpected: scripts/start.js attempts to start 'node run.js' in CLAWDIO_DIR, but there is no run.js in the provided file manifest. The starter script appears to assume files exist in a user's workspace, suggesting the script is environment-specific rather than a general-purpose starter.

[PACKAGING_MISMATCH] unexpected: package.json lists 'dist' as the shipped files and main 'dist/index.js', but the package includes src/*.ts and no dist directory. Registry metadata lists version 2.2.0 while package.json is 2.0.0 — indicates inconsistent packaging or an incomplete source snapshot.

What to consider before installing

This package implements a plausible Noise+XChaCha20 P2P library, but the shipped artefacts include several red flags: a start script tailored to a single user's filesystem that spawns detached processes and embeds an external IP; WebSocket transport code while documentation says 'No WebSocket' and the 'ws' dependency is missing; packaging/version mismatches and a reference to a run.js that is not included. Do not run scripts/start.js or any included script unreviewed. If you want to use this skill: (1) ask the author for the canonical source/homepage and a release build (dist) that matches the registry version, (2) inspect run.js (which is not included) before running anything, (3) fix or remove hardcoded absolute paths and host/IPs, (4) run the code in a sandbox/container and avoid exposing private identity files to external hosts, (5) prefer building from source only after adding missing dependencies (or use a vetted package from a known origin). If you cannot verify the origin and contents, treat it as untrusted — the background-start behavior and hardcoded host/IP increase risk of unintended persistent network connections or data exposure.

Secure peer-to-peer communication for AI agents using Telegram as transport. Create a "Clawdio Hub" group, add your bot, and you're ready to connect with other agents securely. Agents perform Noise XX handshake over Telegram, then communicate via encrypted channels.

When to Use

• Secure agent-to-agent communication via Telegram
• Task delegation between agents on different machines
• Distributed AI workflows requiring encrypted P2P messaging
• Cross-platform agent coordination without port forwarding

Why Telegram

• ✅ Always online — No port forwarding, NAT, or server setup
• ✅ Reliable delivery — Messages queue when peers offline
• ✅ Universal access — Works from anywhere with internet
• ✅ Battle-tested — Handles billions of messages daily
• ✅ OpenClaw integration — Simple message tool for send/receive
• ✅ Offline resilience — Messages delivered when peer comes back online

Quick Onboarding

First Time Setup (Your Agent)

1. Install Clawdio: clawhub install clawdiocomms
2. Create a Telegram group called "Clawdio Hub"
3. Add your OpenClaw bot to the group
4. Send your agent the group ID (or agent auto-detects it)
5. Your agent generates your identity and you're ready

Connecting to a Peer

1. Share your public key with your friend
2. Your friend does the same setup on their end
3. Your friend shares their public key + their Clawdio Hub group ID with you
4. Your agent creates a topic/thread in your Clawdio Hub for this peer (e.g. "James <> Alex")
5. Connection request sent — friend's agent asks for consent
6. Friend approves
7. Noise XX handshake happens over Telegram messages in the dedicated topics
8. You're connected — encrypted comms flowing

Human Verification (Optional but Recommended)

1. Meet in person
2. Both run: compare 6-word verification codes
3. If they match, mark as human-verified

Technical Setup

cd projects/clawdio && npm install && npx tsc

Quick Start

const { Clawdio } = require('./projects/clawdio/dist/index.js');

// Create two nodes
const alice = await Clawdio.create({ autoAccept: true });
const bob = await Clawdio.create({ autoAccept: true });

// Wire transport (agents decide HOW to send)
alice.onSend((peerId, msg) => bob.receive(alice.publicKey, msg));
bob.onSend((peerId, msg) => alice.receive(bob.publicKey, msg));

// Connect (Noise XX handshake)
const aliceId = await bob.connect(alice.publicKey);

// Send messages
await bob.send(aliceId, { task: "What's the weather?" });
alice.onMessage((msg, from) => console.log(msg.task));

Using with Telegram (via OpenClaw)

const node = await Clawdio.create({ owner: 'James' });

// Send via Telegram
node.onSend((peerId, base64Message) => {
  // Use OpenClaw's message tool to send to peer's Telegram
  sendTelegramMessage(peerId, base64Message);
});

// When receiving a Telegram message from peer:
node.receive(peerId, base64EncodedMessage);

Connection Consent

Unknown inbound peers require explicit consent:

node.on('connectionRequest', (req) => {
  console.log(`Peer: ${req.id}, Fingerprint: ${req.fingerprint}`);
  node.acceptPeer(req.id);  // or node.rejectPeer(req.id)
});

Human Verification

const code = node.getVerificationCode(peerId); // "torch lemon onyx prism jade index"
// Compare codes in person, then:
node.verifyPeer(peerId);

Persistent Identity

const node = await Clawdio.create({ identityPath: '.clawdio-identity.json' });

API Reference

Method	Description
Clawdio.create(opts)	Create and initialize a node
node.onSend(handler)	Register send handler (transport layer)
node.receive(from, b64)	Feed incoming message from transport
node.connect(peerId)	Initiate Noise XX handshake
node.send(peerId, msg)	Send encrypted message
node.onMessage(handler)	Listen for decrypted messages
node.acceptPeer(id)	Accept pending connection
node.rejectPeer(id)	Reject pending connection
node.getVerificationCode(id)	Get 6-word verification code
node.verifyPeer(id)	Mark peer as human-verified
node.getPeerTrust(id)	Get trust level
node.getFingerprint(id)	Emoji fingerprint
node.getPeerStatus(id)	alive/stale/down
node.stop()	Shutdown

Security Properties

• Forward secrecy (ephemeral X25519 keys)
• Mutual authentication (Noise XX)
• Replay protection (monotonic counters)
• XChaCha20-Poly1305 AEAD encryption
• Connection consent for inbound peers
• Human verification via 6-word codes

Dependencies

Single production dependency: libsodium-wrappers.