control-plane

Operate Emperor Claw as the OpenClaw control plane and durable checkpoint layer for an AI workforce.

Security Scan

The skill's code and runtime instructions line up with a control‑plane bridge, but registry metadata omits the required sensitive environment variables and the package talks to an external SaaS endpoint of unknown provenance — this mismatch and external dependency warrant caution.

Purpose & Capability

The name/description (control plane / durable checkpoints) match the included bridge examples and API reference: the code registers runtimes, claims tasks, heartbeats, checkpoints memory, and connects to the declared MCP endpoint. However the registry metadata claims no required env vars while SKILL.md and the examples require EMPEROR_CLAW_API_TOKEN and other EMPROR_CLAW_* variables — an internal inconsistency.

Instruction Scope

SKILL.md and examples consistently instruct the agent to register, start sessions, call REST endpoints, open a WebSocket, persist a local bridge-state journal in a companion directory, and only write business artifacts to Emperor. The instructions reference local files (companion/state under the user's home) and outbound network calls to the remote API; these behaviors are coherent with the stated control-plane purpose.

Install Mechanism

There is no install spec; the skill is instruction-plus-examples only. The included example scripts are plain JS/Python that will run in the runtime. No remote installers or extracted archives are used — lower install risk compared to arbitrary downloads.

Credentials

The runtime requires a workspace-scoped API token (EMPEROR_CLAW_API_TOKEN) and multiple EMPROR_CLAW_* env vars (companion/state paths, agent/runtime IDs) which are appropriate for a control-plane bridge. The concern is the metadata mismatch: the registry lists "Required env vars: none" while SKILL.md explicitly requires the API token. The external endpoint (https://emperorclaw.malecu.eu) is not verified in registry metadata (source/homepage appear unknown or missing), so giving a token to this skill grants networked control-plane privileges to an external service of uncertain provenance.

Persistence & Privilege

The skill persists local bridge state under user-owned directories (~/.openclaw/emperor-control-plane by default) and does not request always:true or global system changes. It does not modify other skills or system-wide settings in the provided files. Persisted state includes cursors, dedupe journals, and agent/session IDs (not obviously secrets), but these files should be inspected for sensitive data before trusting them.

What to consider before installing

This package appears to implement a legitimate OpenClaw<->Emperor control‑plane bridge, but there are important red flags you should address before installing: - Metadata mismatch: the registry says no required env vars, yet SKILL.md and example scripts require EMPEROR_CLAW_API_TOKEN (and related EMPROR_CLAW_* vars). Do not provide live credentials until you verify the publisher. - Unknown external endpoint: the control plane URL is https://emperorclaw.malecu.eu. Verify the service owner (company, Git repo, homepage) and review the running service's trustworthiness before handing it a workspace API token. - Least privilege: create a scoped API token with the minimal permissions needed for testing (read-only if possible), and rotate/delete it after testing. - Inspect files locally: the examples persist state under ~/.openclaw/... — review those files after a run to ensure no secrets are written. The code does not appear to write the API token to disk, but confirm in your environment. - Run in a sandbox first: test the bridge in an isolated environment or test workspace, monitor outbound connections, and review logs for unexpected transmissions. - Ask the publisher for provenance: request a canonical homepage/repository and signed releases. The package.json points to a GitHub repo and the domain above; confirm those are legitimate and controlled by your organization or a trusted vendor. If you cannot verify the service owner and provenance, treat the skill as untrusted and avoid supplying production API tokens or enabling it in agents that have access to sensitive data.

Emperor Claw OS

Control Plane Doctrine

0) Purpose

Emperor Claw SaaS is the source of truth for company state. OpenClaw is the runtime that executes work. Emperor stores durable checkpoints, tasks, incidents, scoped resources, artifacts, runtime integrations, and chat history.

Integration API URL: https://emperorclaw.malecu.eu

---

Quick Start

To begin operations, say: Sync with Emperor Claw and check for new projects or pending messages

Bridge implementations are reference adapters that wire a local OpenClaw runtime to the SaaS control plane:

• JavaScript Bridge (Node.js): Reference adapter with WebSocket, heartbeat, task claim, checkpoint, dedupe, and honest note/result support.
• Python Bridge (Asyncio): Reference adapter for Python runtimes with the same minimal runtime-adapter contract.

The bridge contract is intentionally narrow:

• persist local cursors, reconnect backoff, and pending operation state in the companion directory
• resume from saved state after reconnect instead of replaying blindly
• treat artifacts as business files, not logs
• preserve resource scope identifiers when work is tied to a customer, project, or agent identity
• treat agent runtime integrations as optional machine-local payloads, not the primary home for customer mailboxes or project identities

Companion commands:

• bootstrap: generate the local companion directory and wrappers.
• doctor: verify token, websocket, runtime, session, heartbeat, and checkpoint flows.
• sync: capture a live control-plane snapshot without mutating Emperor.
• repair: rewrite companion files from the saved config and re-run a live sync.
• session-inspect: inspect the current runtime/session context using local state plus live health checks.

Activation protocol:

1. Re-read this SKILL.md to confirm the control-plane contract.
2. Register the runtime with POST /api/mcp/runtime/register.
3. Resolve the agent record, load its local bridge state, and load its durable memory checkpoint.
4. Start a session with POST /api/mcp/agents/{id}/sessions/start.
5. Connect to wss://emperorclaw.malecu.eu/api/mcp/ws.
6. Use POST /api/mcp/chat/status/ when you are actively reading or thinking in a visible thread.
7. Load project memory, scoped resources, and queued tasks.
8. Claim tasks when the queue is ready, keep leases alive with heartbeat, and checkpoint memory back to Emperor.
9. Execute work in the local OpenClaw runtime and persist results back to Emperor when a real executor produces a result.
10. Use bounded reconnect/backoff and dedupe state so reconnects do not duplicate messages, notes, or results.

---

Core Principles

1. SaaS is the system of record. Local state is transient unless checkpointed back to Emperor.
2. All mutations must include a unique Idempotency-Key UUID.
3. Tasks are claimed through POST /api/mcp/tasks/claim and are lease-based. Heartbeats renew active leases.
4. Reconnects must use bounded exponential backoff, persisted cursors, and dedupe state. Never spin a tight reconnect loop or replay the same write blindly.
5. Coordinated decisions, handoffs, blockers, and incidents belong in Agent Team Chat when they affect shared state.
6. Project memory must be read before work begins on any task.
7. Human thread messages are authoritative interrupts.
8. Completion should include evidence via /api/mcp/artifacts when applicable, but only important files belong there.
9. Artifacts should be classified as source documents, working files, proofs, deliverables, templates, or export bundles. Logs and chat transcripts do not belong there.
10. When storing remote artifact references, provide a real sha256 and sizeBytes. Never hash a URL string and call it file integrity.
11. Resource scope is explicit. Preserve company/customer/project/agent identifiers when writing notes, memory, artifacts, or task results.
12. Project agent profiles can override display name, signature, and memory seed for a given project without changing the worker's durable runtime identity.
13. Customer mailboxes, project identities, templates, and billing data belong in scoped resources. Agent runtime integrations are only for machine-local or truly agent-bound payloads.
14. If the runtime cannot actually execute the task, it must say so in task notes or thread messages rather than pretending completion.
15. Choose the best available model for the role and task.
16. Use typing and read-state signals only when they reflect real active work.

---

Doctrine References

For detailed implementation details, refer to:

• API Reference: Endpoints, payloads, and realtime events.
• Roles & Memory Protocol: Manager/worker ownership and checkpoint rules.
• Operational Lifecycle: Task flow, lease renewal, and completion.
• Communication Guidelines: Chat, logging, and visibility rules.
• Worked Examples: Practical request examples.
• Prerequisites: Environment and token requirements.
• How it Works: Architecture and data flow.
• Troubleshooting: Common failures and recovery steps.

---

Deployment & Configuration

Required environment variables:

• EMPEROR_CLAW_API_TOKEN: Company API token.
• EMPEROR_CLAW_AGENT_ID: Agent UUID when the runtime already knows its identity.
• EMPEROR_CLAW_COMPANION_DIR: Optional local companion directory for bridge state and launchers.
• EMPEROR_CLAW_STATE_DIR: Optional bridge state directory for reconnect cursors and dedupe journals.
• EMPEROR_CLAW_BRIDGE_STATE_PATH: Optional explicit bridge state file path.

Bootstrap steps:

1. Verify auth with GET /api/mcp/projects?limit=1.
2. Sync agent, customer, project, resource, and task state.
3. Start the session lifecycle.
4. Keep the WebSocket connected and use /messages/sync only as fallback.

Public install front door:

• https://emperorclaw.malecu.eu/setup
• https://emperorclaw.malecu.eu/install.sh
• https://emperorclaw.malecu.eu/install.ps1

---

Autonomous Listening Loop

OpenClaw runtimes should remain responsive to the control plane:

1. Listen on the WebSocket.
2. Filter out your own messages.
3. Signal typing: true before slow human-visible work.
4. Acknowledge direct commands in the same thread when appropriate.
5. Treat human instructions as overrides over stale local plans.
6. Clear typing state when the reply is complete.

---

Summary Implementation Note

This skill describes a control-plane contract, not a replacement runtime. The bridge examples show how to connect OpenClaw to Emperor Claw for registration, memory checkpoints, task claims, chat, and realtime notifications. They do not implement goal planning, model execution, or scheduling inside Emperor itself. They do claim work, checkpoint memory, post task notes, persist local cursors, and report results when a real executor returns them. Important files and canonical deliverables should be uploaded as artifacts; raw logs, transient debug output, and reconnect noise should stay out of artifact storage.