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:

Permission	What	Why
CLI Exec	~/.pilot/bin/pilotctl	All agent operations go through this binary
File Write	~/.pilot/inbox/	Context snapshots and incoming messages land here
File Write	~/.pilot/received/	Received files from peer agents
File Read	~/.pilot/inbox/	Reading snapshots for context restoration
File Read	~/.pilot/received/	Reading transferred files
Network	Local Unix socket	Daemon communication (localhost only)
Network	UDP tunnels (encrypted)	Agent-to-agent communication (AES-256-GCM)
Script Exec	~/.pilot/context-snapshot.sh	Context snapshot helper script
Script Exec	~/.pilot/pilot-publish.sh	Event publishing helper script
Process	Daemon lifecycle	Start/stop/status of the pilotctl daemon

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

Tool	Purpose	Required?
Pilot Protocol	Core daemon + CLI (pilotctl)	✅ Required
OpenClaw	Skill host + Agent orchestration	✅ Required

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"
}

Field	Description	Default
pilotctl_path	Path to the pilotctl binary	~/.pilot/bin/pilotctl
daemon_start_script	Script to start the daemon	~/.pilot/start-local.sh
snapshot_script	Context snapshot helper script	~/.pilot/context-snapshot.sh
publish_script	Event publish helper script	~/.pilot/pilot-publish.sh
inbox_path	Directory for incoming messages/snapshots	~/.pilot/inbox/
received_path	Directory for received files	~/.pilot/received/
agent_hostname	This agent's hostname on the Pilot network	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

Operation	Multi-node Command	Single-node Alternative
Publish event	pilotctl publish keke-agent topic --data ...	~/.pilot/pilot-publish.sh topic '{"key":"val"}'
Send to inbox	pilotctl send-message keke-agent --data ...	Write file directly to ~/.pilot/inbox/
Context snapshot	pilotctl send-message ...	~/.pilot/context-snapshot.sh
Read inbox	pilotctl inbox → read ~/.pilot/inbox/	Same (read directory directly)
Check status	pilotctl info	✅ Works normally
Set tags	pilotctl set-tags ...	✅ Works normally

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

Topic	Trigger	Data Schema
context.snapshot	Session end / manual save	{session_id, summary, key_decisions}
context.overflow	Token usage > 80%	{token_count, threshold}
context.compaction	Compaction triggered	{before_tokens, after_tokens}
model.switch	Model changed	{from, to, reason}
model.error	Model failure	{model, error, fallback}
task.start	Task initiated	{task, type, model}
task.complete	Task finished	{task, result_summary}
task.error	Task failed	{task, error, retry}
intel.ingested	Information ingested	{source, title, category, value}
error.alert	Error notification	{type, details, action}
agent.spawn	Sub-agent created	{hostname, purpose, model}
agent.exit	Sub-agent exited	{hostname, reason, result}

---

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:

Tag	Meaning	Best Fit Agent
orchestrator	Scheduling & dispatch	OpenClaw primary agent
deep-reasoning	Deep reasoning tasks	Antigravity (Opus)
code-gen	Code generation	Codex (Sonnet)
local-inference	Local model inference	LM Studio (Qwen)
fast	Fast responses	Flash Lite instances
chinese	Chinese language tasks	Qwen / Chinese-optimized models

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

Problem	Diagnostic Command	Solution
Daemon not running	pilotctl daemon status	~/.pilot/start-local.sh
Registry unreachable	pilotctl info (check peers)	Verify rendezvous server is running
Messages not sending	pilotctl connections	Check trust state with target
Inbox overflowing	pilotctl inbox	pilotctl inbox --clear