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

Task Delegation

Context and Status

Coordination and Governance

Capability Lifecycle

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.