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

CODEBLOCK0

Field	Description	Default
INLINECODE14	Path to the pilotctl binary	INLINECODE15
INLINECODE16

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. 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: INLINECODE31
3. Start the daemon: INLINECODE32
4. Verify: INLINECODE33

---

Global Rules

1. 1. All pilotctl commands use the full path: INLINECODE35
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	INLINECODE43	INLINECODE44
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:

CODEBLOCK1

1.2 Restore Context

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

CODEBLOCK2

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

CODEBLOCK3

---

Capability 2: Event-Driven Collaboration

2.1 Publish Events

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

CODEBLOCK4

2.2 Subscribe to Events

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

CODEBLOCK5

2.3 Standard Event Topics

Topic	Trigger	Data Schema
INLINECODE57	Session end / manual save	INLINECODE58
INLINECODE59

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

CODEBLOCK6

3.2 Spawning Sub-Agents

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

CODEBLOCK7

3.3 Collecting Sub-Agent Results

CODEBLOCK8

---

Capability 4: Task Routing

4.1 Route by Tags

Assign capability tags to different agents:

CODEBLOCK9

Tag conventions:

Tag	Meaning	Best Fit Agent
INLINECODE81	Scheduling & dispatch	OpenClaw primary agent
INLINECODE82

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

CODEBLOCK10

---

Capability 5: Model Dispatch Notifications

5.1 Publish Model Switch Events

Every model switch gets logged to the event stream:

CODEBLOCK11

5.2 Model Fallback Chain

On model failure, automatically publish degradation events:

CODEBLOCK12

---

Capability 6: File Transfer

6.1 Send File

CODEBLOCK13

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

6.2 View Received Files

CODEBLOCK14

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

CODEBLOCK15

7.2 Performance Testing

CODEBLOCK16

---

Capability 8: Gateway IP Bridging

8.1 Map Agent to Local IP

CODEBLOCK17

Once mapped, standard HTTP tools can be used:
CODEBLOCK18

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

CODEBLOCK19

9.2 Event Types

All native daemon events are pushed to the webhook:

• - node.registered / INLINECODE89
• INLINECODE90 / conn.fin / INLINECODE92
• INLINECODE93 / INLINECODE94
• INLINECODE95 / INLINECODE96
• INLINECODE97 / INLINECODE98
• INLINECODE99 / INLINECODE100

---

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	INLINECODE102	INLINECODE103
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 |