# Emperor Claw Os > Operate Emperor Claw as the OpenClaw control plane and durable checkpoint layer for an AI workforce. - Skill: `emperorclaw/emperor-claw-os` (Agent Skill, multi-file: 31 files) - Install (CLI): `npx skillmds@latest add emperorclaw/emperor-claw-os` - Raw SKILL.md: https://api.skillmd.com/api/skills/emperorclaw/emperor-claw-os/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: emperorclaw (https://skillmd.com/u/emperorclaw) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/emperorclaw/emperor-claw-os --- # 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)](./examples/bridge.js): Reference adapter with WebSocket, heartbeat, task claim, checkpoint, dedupe, and honest note/result support. - [Python Bridge (Asyncio)](./examples/bridge.py): 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](./references/api.md): Endpoints, payloads, and realtime events. - [Roles & Memory Protocol](./references/roles.md): Manager/worker ownership and checkpoint rules. - [Operational Lifecycle](./references/lifecycle.md): Task flow, lease renewal, and completion. - [Communication Guidelines](./references/guidelines.md): Chat, logging, and visibility rules. - [Worked Examples](./references/examples.md): Practical request examples. - [Prerequisites](./references/PREREQUISITES.md): Environment and token requirements. - [How it Works](./references/HOW-IT-WORKS.md): Architecture and data flow. - [Troubleshooting](./references/TROUBLESHOOTING.md): 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. ## Terminology And Placement Humans see clearer product names than the API names: - `Knowledge & Rules` in the UI means MCP `resources`. - `Storage` in the UI means MCP `artifacts` and folders. Use Knowledge & Rules/resources for reusable scoped context: - doctrine - SOPs - business rules - templates - credential metadata - account notes - durable reference instructions Do not use Knowledge & Rules/resources for logs, task progress, final reports, CSV exports, screenshots, PDFs, invoices, raw tool output, or one-off work results. Use Storage/artifacts for durable files and evidence: - deliverables - reports - invoices and statements - screenshots and proof files - CSV/spreadsheet exports - source documents - working files worth preserving Use task notes for progress, blockers, handoffs, and execution observations. Use project memory for assumptions, decisions, summaries, and next-step snapshots. If a human says "Storage", use artifact endpoints. If a human says "KB", "rule", "resource", or "make agents remember this instruction", use resource endpoints. ## Company Brain Note Protocol Knowledge & Rules works like a shared Obsidian-style company vault. Create durable notes, not chat logs. When creating or proposing a Knowledge & Rules entry: 1. Pick the smallest correct scope: `company`, `customer`, `project`, or `agent`. 2. Use a short human title that can be linked as `[[Title]]`. 3. Add frontmatter properties for `scope`, `type`, `status`, `owner`, and `tags`. 4. Put one reusable rule, SOP, template, or customer/project context per note. 5. Link related notes with `[[wikilinks]]`. 6. Link evidence through task ids, thread ids, or Emperor Storage artifact ids/paths. 7. Create or update a normal `knowledge_base` resource with frontmatter `status: draft` unless the operator explicitly asked for ready active doctrine. Template: ```markdown --- scope: project type: project-rule status: draft owner: tags: - project/example - implementation --- # Project Build Rules Short summary of the reusable rule. ## Rule - Durable instruction one. - Durable instruction two. ## Evidence - Task: `` - Artifact: `` ## Related - [[Company Operating Doctrine]] ``` Do not fake folder paths in titles like `Client / Project / Rule`. Emperor places notes in the vault tree by resource scope. Use tags for retrieval and `[[wikilinks]]` for graph relationships. Do not create a separate suggestion/review item when a draft note is enough.