Openclaw Skill Ansible

Operate and secure mesh workflows across gateways, including plugin bootstrap, invite/join auth handshake, resilient routing, capability contract lifecycle,...

Security Scan

The skill's files and runtime instructions broadly match its MeshOps purpose, but there are inconsistencies and several powerful, potentially risky operations (deploying archives, running commands, automatic capability registration/auto-claiming) gated by environment variables — the gating and registry metadata are inconsistent and need review before install.

Purpose & Capability

The name/description (MeshOps control-plane) aligns with the included docs, SKILL.md, and scripts: they implement ring-of-trust, CRDT sync, capability routing, and lifecycle ops. The presence of scripts to install plugins, deploy skills, run commands, and collect logs is coherent with an operator/mesh-control skill. However, the skill manifest shown earlier (registry summary) reported no required env vars/binaries while metadata.yaml inside the package lists several required env vars and binaries (OPENCLAW_* gates, openclaw, jq, curl, tar, sha tools, git). This mismatch is an incoherence to resolve.

Instruction Scope

SKILL.md instructs agents to perform broad dispatcher behaviors (auto-register capabilities on load, auto-claim tasks at each reasoning step, write routing metadata into shared Yjs state). Those instructions give loaded agents autonomous authority to discover and claim work across a mesh. The runtime action scripts also read environment gates, write to filesystem locations (/opt/openclaw/skills, /var/lib/openclaw/artifacts), download artifacts from arbitrary HTTPS URLs (deploy-skill), and run CLI tooling. While many of these actions are gated, the SKILL.md's automatic/implicit side-effects (capability registration on load, automated claiming) expand the agent's scope significantly and deserve operator review.

Install Mechanism

There is no package-install spec embedded (instruction-only at registry level) and code files are shipped in the skill bundle. The scripts themselves call external network via openclaw plugins install and curl (for deploy-skill) — but those are invoked at runtime and are gated. No opaque downloads from personal IPs or shorteners; deploy-skill requires HTTPS and SHA256 verification. This is acceptable but still risky in practice because extracting remote archives into /opt is high-impact.

Credentials

Declared envs in metadata.yaml (OPENCLAW_ALLOWED_CALLERS, OPENCLAW_ALLOW_HIGH_RISK, OPENCLAW_ALLOW_RUN_CMD, OPENCLAW_ALLOW_DEPLOY_SKILL, OPENCLAW_RUN_CMD_ALLOWLIST, OPENCLAW_ARTIFACT_ROOT) map to the skill's gating design and are not secret credentials, which is proportionate. But the registry summary reported no required envs (contradiction). Also, required envs control powerful actions: if gates are enabled (OPENCLAW_ALLOW_RUN_CMD=1, OPENCLAW_ALLOW_DEPLOY_SKILL=1, OPENCLAW_ALLOW_HIGH_RISK=1) and caller allowlist permits a caller, the skill can download and extract archives and run commands (even though run-cmd has an allowlist, deploy-skill downloads arbitrary artifact URLs). This makes correct gate configuration critical.

Persistence & Privilege

always:false and disable-model-invocation:false (normal). The skill's documented behavior includes side-effects on agent startup (capability registration) and automatic claiming at each reasoning step; those are functional choices but increase the blast radius because agents with the skill become eligible executors and can be auto-invoked. Combined with the deploy-skill/run-cmd scripts, this raises risk if gating env-vars or allowlists are misconfigured. The skill does not request system-wide config modification beyond installing skills or writing to /opt when operator-invoked.

What to consider before installing

This skill is purpose-aligned for a MeshOps control plane, but review these before installing: - Resolve the manifest mismatch: the registry summary says "no required env vars/bins" but metadata.yaml inside the package lists several gates and binaries. Confirm the marketplace metadata matches the packaged metadata. - Treat the gating env vars (OPENCLAW_ALLOW_HIGH_RISK, OPENCLAW_ALLOW_RUN_CMD, OPENCLAW_ALLOW_DEPLOY_SKILL) as safety interlocks — ensure they default to disabled (0) and are only enabled deliberately for vetted tasks. - Confirm OPENCLAW_ALLOWED_CALLERS is set to a small trusted allowlist. If mis-set, remote callers could trigger deploy/run operations. - Audit the deploy-skill workflow: it downloads HTTPS artifacts and extracts them to /opt/openclaw/skills. Although it requires a sha256 and https, validate the artifact sources and verify the SHA before enabling deployment in production. - Review automatic behavior in SKILL.md: the design requires skills to auto-register capabilities and for executors to auto-claim tasks at reasoning start. If you do not want agents to autonomously claim/execute mesh tasks, do not load this skill into agents that must remain passive. - Test in an isolated environment first: verify preflight, allowlists, artifact root behavior, and that run-cmd only permits the exact commands you expect. If you want, I can list the exact lines/scripts that perform downloads, extractions, command execution, and automatic registration to make your audit easier.

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:

1. Ring of Trust: invite/join handshake, auth-gate WebSocket tickets, ed25519-signed capability manifests, per-action safety gates, and token lifecycle.
2. Mesh Sync: Yjs CRDT replication over Tailscale. Messages, tasks, context, and pulse remain durable across reconnects and restarts.
3. Capability Routing: publish/unpublish capability contracts. Each contract references a delegation skill (requester) and an execution skill (executor).
4. 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:

1. ACK: confirm receipt and summarize intent.
2. IN_PROGRESS: emit progress updates at meaningful checkpoints.
3. 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

1. Requester creates task with objective, context, acceptance criteria, and target policy (to_agents or capability).
2. Executor claims task and sends acceptance/ETA signal.
3. Executor performs work, emits progress, and completes with structured result.
4. 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.