Generated note: shared plugin assets for this package live at the plugin root. Common local references were rewritten when they appeared in backticks or markdown links.
Ansible - MeshOps Coordination Skill
What This Is
Ansible is a distributed coordination layer that lets you operate across multiple OpenClaw gateways as one coordinated mesh.
Four pillars:
- Ring of Trust: invite/join handshake, auth-gate WebSocket tickets, ed25519-signed capability manifests, per-action safety gates, and token lifecycle.
- Mesh Sync: Yjs CRDT replication over Tailscale. Messages, tasks, context, and pulse remain durable across reconnects and restarts.
- Capability Routing: publish/unpublish capability contracts. Each contract references a delegation skill (requester) and an execution skill (executor).
- Lifecycle Ops: lock sweep, retention/pruning, coordinator sweep, and deployment hygiene.
Relationship Modes
- Friends/Employees (default): other nodes are different agents. Provide context and communicate explicitly.
- Hemispheres (advanced): mirrored instances of the same identity. Shared intent and direct communication.
Default to Friends/Employees unless explicitly told a node is a hemisphere.
Node Topology
- Backbone: always-on nodes (VPS/servers) that host Yjs WebSocket.
- Edge: intermittent nodes (laptops/desktops) that connect to backbone.
Human Visibility Contract (Required on Pickup)
When taking coordination work, maintain explicit lifecycle updates:
- ACK: confirm receipt and summarize intent.
- IN_PROGRESS: emit progress updates at meaningful checkpoints.
- DONE or BLOCKED: close with evidence, next action, and owner.
Use conversation_id consistently for all related updates.
Ring of Trust - Behavioral Rules
- Unknown nodes require invite-based admission. Do not bypass.
- High-risk capability publishes require human approval artifacts.
- Respect caller gates (
OPENCLAW_ALLOWED_CALLERS) and high-risk flags.
- Never expose tokens in plaintext messages/logs/shared state.
- When signature enforcement is on, only accept manifests signed by trusted publisher keys.
Gateway Compatibility Contract
- Validate plugin is installed and readable before assuming tool availability.
- Verify tier assumptions (backbone vs edge) before mutating coordination settings.
- Treat gateway runtime as source of truth for active topology and health.
Reliability Model
Source of Truth
Shared Yjs state is authoritative.
Delivery Semantics
- Durable: messages/tasks persist in shared state.
- Auto-dispatch: best-effort realtime injection into sessions.
- Heartbeat reconcile: periodic rescan recovers missed injections.
- Retry: transient dispatch failures retry with bounded backoff.
- Send receipts: notify configured operators when work is placed on mesh.
Operating Rules
- Verify pending work with
ansible_status and ansible_read_messages.
- If polling mode is used, always reply via
ansible_send_message.
- Use
corr:<messageId> for thread continuity.
- Listener behavior is optimization; sweep/reconcile is the backstop.
Capability Contracts
- A capability is a contract, not just a label.
- Contract includes delegation and execution skill references.
- Publishing updates routing eligibility mesh-wide.
- Provenance is verified against trusted publisher keys when configured.
- High-risk contracts require explicit approval artifacts.
- Unpublish removes eligibility immediately.
- Lifecycle evidence must capture install/wire outcomes.
Delegation Protocol
- Requester creates task with objective, context, acceptance criteria, and target policy (
to_agents or capability).
- Executor claims task and sends acceptance/ETA signal.
- Executor performs work, emits progress, and completes with structured result.
- Requester reports final outcome to human and/or downstream agents.
Coordinator Behavior
- Run sweep loops for stale locks, SLA drift, and backlog reconciliation.
- Prefer record-only escalation by default when blast radius is unclear.
- If DEGRADED, prioritize containment, visibility, and deterministic recovery.
Available Tools
Communication
| Tool |
Purpose |
ansible_send_message |
Send targeted or broadcast message across mesh |
ansible_read_messages |
Read unread messages (or full history) |
ansible_mark_read |
Mark messages as read |
ansible_delete_messages |
Admin-only emergency purge |
Task Delegation
| Tool |
Purpose |
ansible_delegate_task |
Create task for another node/agent set |
ansible_claim_task |
Claim pending task |
ansible_update_task |
Update task status/progress |
ansible_complete_task |
Complete task and notify requester |
ansible_find_task |
Resolve task by ID/title |
Context and Status
| Tool |
Purpose |
ansible_status |
Mesh health, unread, pending, and topology summary |
ansible_update_context |
Update shared context/threads/decisions |
Coordination and Governance
| Tool |
Purpose |
ansible_get_coordination |
Read coordinator configuration |
ansible_set_coordination_preference |
Set node coordinator preference |
ansible_set_coordination |
Switch coordinator (guarded) |
ansible_set_retention |
Configure closed-task retention/pruning |
ansible_get_delegation_policy |
Read delegation policy plus ACKs |
ansible_set_delegation_policy |
Publish/update delegation policy |
ansible_ack_delegation_policy |
Acknowledge policy version |
ansible_lock_sweep_status |
Inspect lock sweep health |
Capability Lifecycle
| Tool |
Purpose |
ansible_list_capabilities |
List published capability contracts |
ansible_capability_publish |
Publish/upgrade capability contract |
ansible_capability_unpublish |
Remove capability from routing |
ansible_capability_lifecycle_evidence |
Show install/wire evidence for version |
ansible_capability_health_summary |
Show success/error/latency summary |
When to Use Ansible
Use Ansible when work crosses gateways, needs durable coordination, or requires auditable delegation contracts.
Session Behavior
- Start by checking status and pending work.
- Prefer explicit delegation for capability-matched work.
- Keep humans in loop via lifecycle messages.
Message Protocol v1
- Always include enough context for independent execution.
- Use stable correlation IDs (
corr) and conversation IDs.
- Prefer structured payloads over freeform-only messaging.
Setup Playbooks
Follow plugin setup and gateway runbooks for topology bootstrap, auth-gate, and trust settings.
Delegation Management
- Keep delegation policy current and acknowledged across nodes.
- Treat capability publishes as contract releases.
- Roll back quickly when lifecycle evidence indicates drift or misfire.
1---2name: ansible-53description: MeshOps distributed coordination mesh for OpenClaw gateways: ring-of-trust admission, CRDT-synced state, capability-contract routing, and governed delegation. Named for the ansible from Ender's Game, not the infrastructure tool.4---5
6> Generated note: shared plugin assets for this package live at the plugin root. Common local references were rewritten when they appeared in backticks or markdown links.
7
8# Ansible - MeshOps Coordination Skill
9
10## What This Is
11
12Ansible is a distributed coordination layer that lets you operate across multiple OpenClaw gateways as one coordinated mesh.
13
14Four pillars:
15
161. Ring of Trust: invite/join handshake, auth-gate WebSocket tickets, ed25519-signed capability manifests, per-action safety gates, and token lifecycle.
172. Mesh Sync: Yjs CRDT replication over Tailscale. Messages, tasks, context, and pulse remain durable across reconnects and restarts.
183. Capability Routing: publish/unpublish capability contracts. Each contract references a delegation skill (requester) and an execution skill (executor).
194. Lifecycle Ops: lock sweep, retention/pruning, coordinator sweep, and deployment hygiene.
20
21## Relationship Modes
22
23- Friends/Employees (default): other nodes are different agents. Provide context and communicate explicitly.
24- Hemispheres (advanced): mirrored instances of the same identity. Shared intent and direct communication.
25
26Default to Friends/Employees unless explicitly told a node is a hemisphere.
27
28## Node Topology
29
30- Backbone: always-on nodes (VPS/servers) that host Yjs WebSocket.
31- Edge: intermittent nodes (laptops/desktops) that connect to backbone.
32
33## Human Visibility Contract (Required on Pickup)
34
35When taking coordination work, maintain explicit lifecycle updates:
36
371. ACK: confirm receipt and summarize intent.
382. IN_PROGRESS: emit progress updates at meaningful checkpoints.
393. DONE or BLOCKED: close with evidence, next action, and owner.
40
41Use `conversation_id` consistently for all related updates.
42
43## Ring of Trust - Behavioral Rules
44
45- Unknown nodes require invite-based admission. Do not bypass.
46- High-risk capability publishes require human approval artifacts.
47- Respect caller gates (`OPENCLAW_ALLOWED_CALLERS`) and high-risk flags.
48- Never expose tokens in plaintext messages/logs/shared state.
49- When signature enforcement is on, only accept manifests signed by trusted publisher keys.
50
51## Gateway Compatibility Contract
52
53- Validate plugin is installed and readable before assuming tool availability.
54- Verify tier assumptions (backbone vs edge) before mutating coordination settings.
55- Treat gateway runtime as source of truth for active topology and health.
56
57## Reliability Model
58
59### Source of Truth
60
61Shared Yjs state is authoritative.
62
63### Delivery Semantics
64
65- Durable: messages/tasks persist in shared state.
66- Auto-dispatch: best-effort realtime injection into sessions.
67- Heartbeat reconcile: periodic rescan recovers missed injections.
68- Retry: transient dispatch failures retry with bounded backoff.
69- Send receipts: notify configured operators when work is placed on mesh.
70
71### Operating Rules
72
73- Verify pending work with `ansible_status` and `ansible_read_messages`.
74- If polling mode is used, always reply via `ansible_send_message`.
75- Use `corr:<messageId>` for thread continuity.
76- Listener behavior is optimization; sweep/reconcile is the backstop.
77
78## Capability Contracts
79
80- A capability is a contract, not just a label.
81- Contract includes delegation and execution skill references.
82- Publishing updates routing eligibility mesh-wide.
83- Provenance is verified against trusted publisher keys when configured.
84- High-risk contracts require explicit approval artifacts.
85- Unpublish removes eligibility immediately.
86- Lifecycle evidence must capture install/wire outcomes.
87
88## Delegation Protocol
89
901. Requester creates task with objective, context, acceptance criteria, and target policy (`to_agents` or capability).
912. Executor claims task and sends acceptance/ETA signal.
923. Executor performs work, emits progress, and completes with structured result.
934. Requester reports final outcome to human and/or downstream agents.
94
95## Coordinator Behavior
96
97- Run sweep loops for stale locks, SLA drift, and backlog reconciliation.
98- Prefer record-only escalation by default when blast radius is unclear.
99- If DEGRADED, prioritize containment, visibility, and deterministic recovery.
100
101## Available Tools
102
103### Communication
104
105| Tool | Purpose |
106|------|---------|
107| `ansible_send_message` | Send targeted or broadcast message across mesh |
108| `ansible_read_messages` | Read unread messages (or full history) |
109| `ansible_mark_read` | Mark messages as read |
110| `ansible_delete_messages` | Admin-only emergency purge |
111
112### Task Delegation
113
114| Tool | Purpose |
115|------|---------|
116| `ansible_delegate_task` | Create task for another node/agent set |
117| `ansible_claim_task` | Claim pending task |
118| `ansible_update_task` | Update task status/progress |
119| `ansible_complete_task` | Complete task and notify requester |
120| `ansible_find_task` | Resolve task by ID/title |
121
122### Context and Status
123
124| Tool | Purpose |
125|------|---------|
126| `ansible_status` | Mesh health, unread, pending, and topology summary |
127| `ansible_update_context` | Update shared context/threads/decisions |
128
129### Coordination and Governance
130
131| Tool | Purpose |
132|------|---------|
133| `ansible_get_coordination` | Read coordinator configuration |
134| `ansible_set_coordination_preference` | Set node coordinator preference |
135| `ansible_set_coordination` | Switch coordinator (guarded) |
136| `ansible_set_retention` | Configure closed-task retention/pruning |
137| `ansible_get_delegation_policy` | Read delegation policy plus ACKs |
138| `ansible_set_delegation_policy` | Publish/update delegation policy |
139| `ansible_ack_delegation_policy` | Acknowledge policy version |
140| `ansible_lock_sweep_status` | Inspect lock sweep health |
141
142### Capability Lifecycle
143
144| Tool | Purpose |
145|------|---------|
146| `ansible_list_capabilities` | List published capability contracts |
147| `ansible_capability_publish` | Publish/upgrade capability contract |
148| `ansible_capability_unpublish` | Remove capability from routing |
149| `ansible_capability_lifecycle_evidence` | Show install/wire evidence for version |
150| `ansible_capability_health_summary` | Show success/error/latency summary |
151
152## When to Use Ansible
153
154Use Ansible when work crosses gateways, needs durable coordination, or requires auditable delegation contracts.
155
156## Session Behavior
157
158- Start by checking status and pending work.
159- Prefer explicit delegation for capability-matched work.
160- Keep humans in loop via lifecycle messages.
161
162## Message Protocol v1
163
164- Always include enough context for independent execution.
165- Use stable correlation IDs (`corr`) and conversation IDs.
166- Prefer structured payloads over freeform-only messaging.
167
168## Setup Playbooks
169
170Follow plugin setup and gateway runbooks for topology bootstrap, auth-gate, and trust settings.
171
172## Delegation Management
173
174- Keep delegation policy current and acknowledged across nodes.
175- Treat capability publishes as contract releases.
176- Roll back quickly when lifecycle evidence indicates drift or misfire.
dvcrn