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, pipelines, Knowledge & Rules entries (API: resources), Storage files (API: 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 Storage/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 Knowledge & Rules entries/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 Storage (/api/mcp/artifacts) when applicable, but only important files belong there.
9. Storage/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 Knowledge & Rules entries/resources. Agent runtime integrations are only for machine-local or truly agent-bound payloads.
    • Use "Force Sharing" (isShared) to explicitly pass a resource to every agent in the scope per instruction, overriding standard access policies.
    • Bridge implementations should automatically inject relevant isShared=true resource configText into agent context, while leaving non-shared resources as manual/on-demand context.
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:

• Maximize Emperor: The full operating loop — how to use every surface at full power.
• 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. Re-register any pipelines this agent operates (POST /api/mcp/pipelines, upsert by name).
4. Start the session lifecycle.
5. 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

Installer expectations for the production bridge:

• default to the SaaS API URL, not localhost
• install runtime dependencies such as ws automatically
• create a dedicated local OpenClaw brain agent instead of reusing main
• support at least operator and manager bootstrap profiles during install
• expose simple wrapper commands for common profiles like manager
• overwrite the new agent's generic bootstrap with an Emperor-aware agent bootstrap pack
• seed doctrine docs such as EMPEROR_OPERATING_DOCTRINE.md and MAXIMIZE_EMPEROR.md plus worker/manager add-ons
• install a persistent per-agent user service with an env file rather than embedding secrets in the unit
• route direct threads as auto-reply and team threads as mention-only by default
• extract only assistant text from local OpenClaw JSON output before posting back into Emperor chat

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.

Upgrading

When the skill is updated via openclaw skills update emperor-claw-os, you should also upgrade your local bridge installation:

~/.openclaw/workspace/skills/control-plane/scripts/install.sh --upgrade

This will:

• Check server compatibility
• Download the latest bridge runtime from Emperor
• Restart the bridge service
• Preserve your configuration and tokens

You can also check compatibility without upgrading:

~/.openclaw/workspace/skills/control-plane/scripts/install.sh --check-compatibility

For detailed API documentation, visit the Emperor instance's /docs page (e.g., https://emperorclaw.malecu.eu/docs).

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:

---
scope: project
type: project-rule
status: draft
owner: <agent-name>
tags:
  - project/example
  - implementation
---

# Project Build Rules

Short summary of the reusable rule.

## Rule

- Durable instruction one.
- Durable instruction two.

## Evidence

- Task: `<task-id>`
- Artifact: `<artifact-id or Storage path>`

## 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.

Artifact Doctrine

• Upload reports, invoices, and other durable outputs through Emperor's artifact workflow so Bunny owns the bytes and Emperor owns the metadata.
• Default to customer-scoped artifacts. Provide projectId only when the file truly belongs to a project workflow, and provide taskId only when that project artifact is tied to a specific task.
• Use the artifacts/malecu/YYYY/YYYY-MM/{expenses,invoices,statements} folders for finance documents and move/rename via the folder APIs instead of creating duplicates.
• When agents need to update a document, patch metadata via /api/ui/artifacts/{id} or replace the file contents via /api/ui/artifacts/{id}/replace so the record stays canonical while new bytes land in Bunny.