Agent Swarm Network

Agent Swarm Network — Agent Communication Skill

A unified communication backbone for every AI tool in the OpenClaw ecosystem (OpenClaw / Antigravity / Codex).

Analogy: This network = the Agent's nervous system. OpenClaw = the Agent's brain.

Acknowledgments

This Skill is built on top of Pilot Protocol by @TeoSlayer. Pilot Protocol provides the core daemon, encrypted tunnels, NAT traversal, and peer-to-peer addressing that this Skill leverages. Huge thanks to the Pilot Protocol team for building the Internet of Agents.

Permissions & Privacy

This Skill executes local CLI commands and writes files to the ~/.pilot/ directory. Full transparency:

Privacy Note: All inter-agent traffic is encrypted end-to-end using X25519 key exchange + AES-256-GCM. Agents are private by default and require mutual trust handshake before communication. No data passes through relay servers. The rendezvous registry defaults to localhost (127.0.0.1:9000) — no peer-discovery metadata leaves the machine unless you explicitly change registry_url to a remote address. Snapshots are unencrypted JSON; you must secure the ~/.pilot/ directory (chmod 700).

Prerequisites

Configuration

Edit config.json after installation:

{
  "pilotctl_path": "~/.pilot/bin/pilotctl",
  "daemon_start_script": "~/.pilot/start-local.sh",
  "snapshot_script": "~/.pilot/context-snapshot.sh",
  "publish_script": "~/.pilot/pilot-publish.sh",
  "inbox_path": "~/.pilot/inbox/",
  "received_path": "~/.pilot/received/",
  "agent_hostname": "keke-agent"
}

First-time Setup

1. Install Pilot Protocol securely: We strongly recommend building from source to eliminate supply-chain risk. Clone https://github.com/TeoSlayer/pilotprotocol, audit the source, compile via go build, and place the binary at ~/.pilot/bin/pilotctl.
2. Secure your directories: chmod 700 ~/.pilot
3. Start the daemon: ~/.pilot/start-local.sh
4. Verify: ~/.pilot/bin/pilotctl --json daemon status

Global Rules

1. All pilotctl commands use the full path: ~/.pilot/bin/pilotctl
2. Always append the --json flag for structured output
3. Check the returned status field: ok = success, error = failure
4. On failure, read the hint field for remediation guidance

⚠️ Single-Node Mode (Current State)

Currently running with only one node (keke-agent). Cannot send network messages to self (publish/send-message will return connection_failed).

Single-Node Workarounds

When a second node joins (e.g., VPS or another Mac), network commands will activate automatically.

Capability 1: Context Snapshot & Restore (Highest Priority)

1.1 Save Context Snapshot

When a session ends, compaction triggers, or manual request is made, save critical context:

# Using the snapshot script (works in both single-node and multi-node)
~/.pilot/context-snapshot.sh SESSION_ID "Key summary of current context"

# Or manually write to inbox
echo '{"type":"context_snapshot","session_id":"ID","summary":"Summary"}' > ~/.pilot/inbox/snapshot_$(date +%Y%m%d_%H%M%S).json

1.2 Restore Context

When a new session starts, read the previous session's snapshot:

~/.pilot/bin/pilotctl --json inbox

Returns a messages array sorted by received_at. Read the most recent context_snapshot type message.

1.3 Context Overflow Protocol

When context usage exceeds 80%:

Step 1: Extract critical information from current context
Step 2: Serialize as JSON snapshot
Step 3: pilotctl send-message keke-agent --data "{snapshot}" --type json
Step 4: pilotctl publish keke-agent context.overflow --data "overflow at TOKEN_COUNT tokens"
Step 5: Suggest user starts a new session
Step 6: New session automatically restores from inbox

Capability 2: Event-Driven Collaboration

2.1 Publish Events

When significant events occur, use pilot-publish.sh (automatically handles single-node/multi-node):

# Model switch
~/.pilot/pilot-publish.sh model.switch '{"from":"flash-lite","to":"opus-4.6","reason":"strategic analysis"}'

# Task completion
~/.pilot/pilot-publish.sh task.complete '{"task":"intelligence_ingestion","source":"twitter"}'

# Context compaction
~/.pilot/pilot-publish.sh context.compaction '{"before_tokens":150000,"after_tokens":30000}'

# Error alert
~/.pilot/pilot-publish.sh error.alert '{"type":"model_402","model":"gemini","action":"fallback"}'

# Intelligence ingested
~/.pilot/pilot-publish.sh intel.ingested '{"source":"url","title":"Article Title","category":"infra"}'

2.2 Subscribe to Events

Listen for specific topics (used by sub-agents or external monitors):

# Listen to all events
~/.pilot/bin/pilotctl --json subscribe keke-agent "*" --timeout 60s

# Listen only to model switches
~/.pilot/bin/pilotctl --json subscribe keke-agent model.switch --count 1

# Listen for error alerts
~/.pilot/bin/pilotctl --json subscribe keke-agent error.* --timeout 300s

2.3 Standard Event Topics

Capability 3: Sub-Agent Management

3.1 Naming Convention

Primary agent:    keke-agent
Sub-agents:       keke-sub-{purpose}  (e.g., keke-sub-code, keke-sub-writer)
Nested sub:       keke-sub-{purpose}-{n}

3.2 Spawning Sub-Agents

When OpenClaw needs to create a sub-agent for overflow tasks:

# Publish agent spawn event
~/.pilot/bin/pilotctl --json publish keke-agent agent.spawn \
  --data '{"hostname":"keke-sub-code","purpose":"code refactoring","model":"sonnet-4.6"}'

3.3 Collecting Sub-Agent Results

# Sub-agent sends results via Data Exchange
~/.pilot/bin/pilotctl --json send-message keke-agent \
  --data '{"type":"sub_agent_result","from":"keke-sub-code","result":"refactoring complete","files_changed":3}' \
  --type json

# Primary agent checks results
~/.pilot/bin/pilotctl --json inbox

Capability 4: Task Routing

4.1 Route by Tags

Assign capability tags to different agents:

# Tag self
~/.pilot/bin/pilotctl --json set-tags orchestrator chinese fast

Tag conventions:

4.2 Find the Best Agent

~/.pilot/bin/pilotctl --json peers --search "code-gen"

Capability 5: Model Dispatch Notifications

5.1 Publish Model Switch Events

Every model switch gets logged to the event stream:

~/.pilot/bin/pilotctl --json publish keke-agent model.switch \
  --data '{"from":"CURRENT_MODEL","to":"NEW_MODEL","reason":"reason","timestamp":"ISO8601"}'

5.2 Model Fallback Chain

On model failure, automatically publish degradation events:

~/.pilot/bin/pilotctl --json publish keke-agent model.error \
  --data '{"model":"gemini-3-flash","error":"402 quota exceeded","fallback":"minimax-m2.5"}'

Capability 6: File Transfer

6.1 Send File

~/.pilot/bin/pilotctl --json send-file keke-agent /path/to/file

Files are saved to ~/.pilot/received/.

6.2 View Received Files

~/.pilot/bin/pilotctl --json received

6.3 Use Cases

• Transfer context snapshot files
• Transfer code diffs
• Transfer analysis reports
• Share configuration across agents

Capability 7: Network Diagnostics

7.1 Health Checks

# Daemon status
~/.pilot/bin/pilotctl --json daemon status

# Agent info
~/.pilot/bin/pilotctl --json info

# Connection list
~/.pilot/bin/pilotctl --json connections

# Peer list
~/.pilot/bin/pilotctl --json peers

7.2 Performance Testing

# Ping latency
~/.pilot/bin/pilotctl --json ping keke-agent --count 3

# Throughput benchmark
~/.pilot/bin/pilotctl --json bench keke-agent 1

Capability 8: Gateway IP Bridging

8.1 Map Agent to Local IP

# Gateway bridging on user-space ports (>1024) does NOT require root/sudo.
~/.pilot/bin/pilotctl gateway start --ports 1234,8080 0:0000.0000.0001

Once mapped, standard HTTP tools can be used:

curl http://10.4.0.1:1234/v1/chat/completions  # Like calling LM Studio directly

8.2 Use Cases

• Expose LM Studio through Gateway as a Pilot address
• Unify all model endpoints under one entry point
• Access agent services with standard HTTP tools

Capability 9: Webhook Real-time Monitoring

9.1 Set Up Webhook

~/.pilot/bin/pilotctl --json set-webhook http://localhost:8080/pilot-events

9.2 Event Types

All native daemon events are pushed to the webhook:

• node.registered / node.reregistered
• conn.established / conn.fin / conn.rst
• handshake.received / handshake.approved
• message.received / file.received
• pubsub.published / pubsub.subscribed
• security.syn_rate_limited / security.nonce_replay

Standing Orders (Automation Rules)

Rule 1: Snapshot Before Session End

Automatically execute a context snapshot (Capability 1.1) before every session ends.

Rule 2: Critical Events Must Be Published

The following events must always be published to the Event Stream:

• Model switches
• Intelligence ingestion completions
• Task completions/failures
• Context compactions
• Error alerts

Rule 3: Auto-Restore on New Session

On every new session start, check pilotctl inbox for the latest snapshot and restore context.

Rule 4: Daemon Heartbeat

Check daemon status every 30 minutes. Auto-restart on failure.

Troubleshooting