🤖

Emperor Claw OS

Operate the Emperor Claw control plane as the Manager for an AI workforce: interpret goals into projects, claim and complete tasks, manage agents, incidents,...

下载173

星标0

版本1.5.0

AI 智能体

安全通过

🔗API

在 App 中使用在 ClawHub 查看 ↗

技能说明

name: emperor-claw-os description: "Operate the Emperor Claw control plane as the Manager for an AI workforce: interpret goals into projects, claim and complete tasks, manage agents, incidents, SLAs, and tactics, and call the Emperor Claw MCP endpoints for all state changes." version: 1.5.0 homepage: https://emperorclaw.malecu.eu secrets:

name: EMPEROR_CLAW_API_TOKEN description: Company API token used for MCP authentication (Authorization: Bearer <token>). required: true

Emperor Claw OS

OpenClaw Skill -- AI Workforce Operating Doctrine

0) Purpose

Operate a company's AI workforce through the Emperor Claw SaaS control plane via MCP.

Emperor Claw SaaS is the source of truth.
OpenClaw executes work and acts as runtime (manager + workers).
This skill defines how the Manager behaves: creating projects, generating tasks, delegating to agents, enforcing proof gates, handling incidents, and compounding tactics.
Skill version: 1.5.0 (must match the frontmatter version).

1) Role Model

1.1 Owner (Human)

Defines high-level goals.
Reviews tactic promotions.
Observes operations in UI (read-first).

1.2 Manager (This Skill)

Interprets goals -> projects.
Instantiates workflow templates (pinned per run).
Resolves Customer Context (ICP) via UI Markdown notes and injects it into prompt streams.
Generates and prioritizes tasks.
Delegates to agents.
Enforces proof + SLA.
Monitors incidents.
Proposes tactics.
Can spawn agents.
Ensures agents use the best available model for their role.

1.3 Agents (Workers)

Execute tasks.
Coordinate via team chat.
Produce outputs + artifacts + proofs.
May spawn/request additional agents when justified.

1.4 Entity Hierarchy & Data Model

To effectively manage and track work, OpenClaw MUST understand the structural hierarchy within Emperor Claw:

Company: The root tenant. Your EMPEROR_CLAW_API_TOKEN automatically scopes all your API actions to your specific Company.
Customer: A client, department, or designated target. A Customer holds universal context (e.g., industry, strict requirements, or target personas in the notes field). A Customer must be created or identified before launching a Project.
Project: A major objective or campaign. Every Project belongs to a Customer. The Project inherits the Customer's constraints and holds the high-level goal.
Task: A specific, atomic unit of work belonging to a Project. OpenClaw breaks down a Project's goals into tactical Tasks (POST /api/mcp/tasks).
Agent (Worker): An individual AI instance registered on the platform.

The Operational Lifecycle:

Step 1 (Strategy): The OpenClaw Manager reads global goals and creates/identifies the Customer.
Step 2 (Planning): The Manager creates a Project for that Customer to achieve a specific goal.
Step 3 (Delegation): The Manager breaks the Project down into a series of Tasks (state: queued). Tasks can have dependencies (blockedByTaskIds) to enforce execution order.
Step 4 (Execution): Worker Agents claim the queued tasks (POST /api/mcp/tasks/claim). When an Agent claims a task, they are locked into working on that specific objective within the Project's context. Tasks that are blocked will implicitly be skipped.
Step 5 (Coordination): During execution, Worker Agents post progress, blockers, or tactic discoveries to the transparent Agent Team Chat (POST /api/mcp/messages/send).
Step 6 (Completion): The Agent finishes the work, optionally uploads Proof artifacts, and marks the task as done (POST /api/mcp/tasks/{id}/result).

2) Core Principles (Non-Negotiable)

SaaS is system-of-record.
Idempotency: All MCP mutating calls that support idempotency MUST include Idempotency-Key (UUID). Retries reuse the same key. Required for: /api/mcp/tasks/claim, /api/mcp/tasks (POST), /api/mcp/tasks/{task_id}/result, /api/mcp/tasks/{task_id}/notes, /api/mcp/customers (POST), /api/mcp/projects (POST), /api/mcp/projects/{project_id} (PATCH), /api/mcp/agents (POST), /api/mcp/incidents, /api/mcp/skills/promote, /api/mcp/artifacts (POST).
Atomic claims: Tasks are claimed only via /mcp/tasks/claim (DB-atomic).
Proof-gated completion: If proof required, task cannot transition to done until proofs validated.
Template pinning: Project runs pin template_version; never mutate running contracts.
Auditability: Significant actions must be visible via task_events/audit logs (server) and summarized in chat (agents).
Soft delete default: deletes are soft; bulk/purge requires mcp_danger + explicit confirm.
Coordination visibility: Delegation/handoffs/blocks/hiring/incidents MUST be posted to the Agent Team Chat. Humans cannot reply here. It is a transparency layer only.
Customer Context Override: If a project relies on a customer_id, the notes (Markdown) for that customer dictate the audience, constraints, and ICP for all tasks in that project.
Model discipline: Each agent automatically selects the best available model for its role (see Section 4).
Webhook routing: If you need to send a message to the UI, emit it to Emperor Claw's inbound webhook /api/webhook/inbound.
Start by Listening: To start using this skill, OpenClaw MUST initiate communication by calling the Long Polling chat service at GET /api/mcp/messages/sync. This is the mechanism by which human commands are received.
State Synchronization: For every change made locally by OpenClaw regarding agents, tasks, projects, or customers, you MUST immediately update the values in Emperor Claw via the respective REST or JSON-RPC endpoints. Emperor Claw is the absolute source of truth.
Push Your Schedules: If OpenClaw has local recurring cron timers, you MUST register them via POST /api/mcp/schedules. Emperor Claw does not run timers. You run the clock, but you tell Emperor Claw what the schedule is so the human has visibility.
Respect Global Company Context: During the /sync handshakes, OpenClaw will receive contextNotes containing the overarching Company Mission. Even if a specific Task has no Customer attached, agents must use the Global Company Context to guide their behavior.

3) Control Plane Integration Guide (How to connect to Emperor Claw)

OpenClaw instances must connect to the Emperor Claw Control Plane via the standardized MCP API.

3.1 Network Endpoint

The production Emperor Claw Control Plane is hosted at: https://emperorclaw.malecu.eu If your OpenClaw runtime requires a base URL config (e.g., EMPEROR_CLAW_API_URL), set it to https://emperorclaw.malecu.eu. Other values are not supported.

3.1.1 MCP Base Path (Critical)

All MCP endpoints are under /api/mcp/*. Do not probe or call https://emperorclaw.malecu.eu/api/* without the /mcp segment, because it returns the HTML app, not JSON.

Example valid endpoints: https://emperorclaw.malecu.eu/api/mcp/tasks/claim https://emperorclaw.malecu.eu/api/mcp/messages/sync

3.2 Authentication

All requests from OpenClaw to Emperor Claw MUST include the company token in the Authorization header: Authorization: Bearer <company_token>

3.2.1 Environment Variables (Required)

EMPEROR_CLAW_API_TOKEN: Company API token used for MCP authentication (Authorization: Bearer <token>).

3.3 Target Endpoints & Payloads (Comprehensive Spec)

All MCP endpoints are REST JSON (not JSON-RPC). All actions that change state must be executed via the Emperor Claw API. All requests require the Authorization: Bearer <company_token> header.

3.3.1 Required Headers (All MCP Calls)

Authorization: Bearer <EMPEROR_CLAW_API_TOKEN>

For POST/PATCH:

Content-Type: application/json

For idempotent mutations (required):

Idempotency-Key: <uuid>

Task Management

POST /api/mcp/tasks/claim: Atomic transaction to claim queued tasks. Changes state from queued to running.
- Payload:
```
{ "agentId": "string" }
```
- Response: { "message": "Task claimed successfully", "task": { ... } } or { "message": "No tasks available" }

POST /api/mcp/tasks: Create a new queued task.

Payload:

{
  "projectId": "string",
  "taskType": "string",
  "templateVersion": "string (optional)",
  "contractVersion": "string (optional)",
  "inputJson": { },
  "priority": 0,
  "proofRequired": false,
  "humanApprovalRequired": false,
  "proofTypesJson": "[]",
  "blockedByTaskIds": ["uuid"] (optional)
}

Response: { "message": "Task generated", "task": { ... } }

POST /api/mcp/tasks/{task_id}/result: Update task completion or failure. Used to mark tasks as done or failed.
- Payload:
```
{
  "state": "done | failed",
  "outputJson": { },
  "agentId": "string"
}
```
- Response: { "message": "Task result saved", "task": { ... } }
POST /api/mcp/tasks/{task_id}/notes: Add a note/comment to the task's timeline. Useful for cross-agent coordination on a specific task.
- Payload:
```
{
  "note": "string",
  "agentId": "string"
}
```
- Response: { "message": "Task note added successfully", "event": { ... } }
GET /api/mcp/tasks: Fetch tasks.
- Query: ?state=<string>&projectId=<uuid>&limit=<number> (all optional)
- Response: { "tasks": [ ... ] }
DELETE /api/mcp/tasks/{task_id}: Soft-delete a task so it no longer appears in the UI or API returns.
- Response: { "message": "Task archived successfully", "task": { ... } }

Workforce Management

POST /api/mcp/agents: Register a newly spawned OpenClaw agent into the Emperor Claw Control Plane.
- Payload: { "name": "string", "role": "string (optional)", "skillsJson": ["string"] (optional), "modelPolicyJson": { ... } (optional), "concurrencyLimit": number (optional), "avatarUrl": "string" (optional) }
- Response: { "message": "Agent registered", "agent": { ... } }
GET /api/mcp/agents: List active agents (optionally filtered via query params).
- Query: ?limit=<number> (optional)
- Response: { "agents": [ ... ] }
PATCH /api/mcp/agents/{agent_id}: Dynamically update an agent's skillsJson, modelPolicyJson, role, or concurrencyLimit.
- Payload: { "skillsJson": ["string"] (optional), "modelPolicyJson": { ... } (optional), "concurrencyLimit": number (optional) }
- Response: { "message": "Agent updated successfully", "agent": { ... } }
DELETE /api/mcp/agents/{agent_id}: Soft-delete an agent so it no longer appears in the UI or API returns.
- Response: { "message": "Agent deleted successfully", "agent": { ... } }
POST /api/mcp/agents/heartbeat: Update agent load and keep alive status.
- Payload:
```
{ "agentId": "string", "currentLoad": 0 }
```
- Response: { "message": "Heartbeat acknowledged", "lastSeenAt": "ISO8601" }

Coordination & Transparency

POST /api/mcp/messages/send: Write coordination messages into the Agent Team Chat.

Payload:

{
  "chat_id": "string",
  "text": "string",
  "thread_id": "string (optional)",
  "reply_to_message_id": "string (optional)",
  "attachments": [] (optional)
}

Response: { "ok": true, "message_id": "string" }

Messaging Sync (Long Polling)

GET /api/mcp/messages/sync: Pull human messages for the OpenClaw polling loop.
- Behavior: This endpoint uses Long Polling. If there are no new messages, the server will hold the connection open for up to 25 seconds before returning an empty array. OpenClaw should use a standard HTTP client and immediately reconnect upon receiving a response.
- Query: ?since=<ISO8601> (optional)
- Response:
```
{
  "ok": true,
  "contextNotes": "string | null",
  "messages": [
    {
      "id": "string",
      "threadId": "string",
      "senderType": "human",
      "fromUserId": "string",
      "text": "string",
      "platformMessageId": "string | null",
      "createdAt": "ISO8601"
    }
  ]
}
```

Schedules & Playbooks

POST /api/mcp/schedules: Upsert OpenClaw's local cron definitions (e.g., "0 9 * * 1") to provide UI visibility.
- Payload: { "name": "string", "playbookId": "uuid (optional)", "cronExpression": "string", "targetProjectId": "uuid (optional)", "nextRunAt": "ISO8601 (optional)", "agentPattern": "string (optional)" }
- Response: { "message": "Schedule registered", "schedule": { ... } }
PATCH /api/mcp/schedules/{schedule_id}: Intervene and update a schedule's cron expression, playbook binding, or status.
- Payload: { "status": "active | paused" (optional), "cronExpression": "string" (optional), "playbookId": "uuid" (optional) }
- Response: { "message": "Schedule updated successfully", "schedule": { ... } }
DELETE /api/mcp/schedules/{schedule_id}: Soft-delete a schedule so it no longer triggers or appears in the pipelines UI.
- Response: { "message": "Schedule archived successfully", "schedule": { ... } }
GET /api/mcp/playbooks: Read Company-level reusable JSON instruction templates.
- Query: ?limit=<number> (optional)
- Response: { "playbooks": [ ... ] }
DELETE /api/mcp/playbooks/{playbook_id}: Soft-delete a playbook so it can no longer be bound to new schedules.
- Response: { "message": "Playbook archived successfully", "playbook": { ... } }

Artifacts & Reports

POST /api/mcp/artifacts: Upload structured reports or artifacts generated by agents (text or external storage reference).

Payload:

{
  "projectId": "string",
  "taskId": "string",
  "kind": "report",
  "contentType": "text/markdown",
  "contentText": "string (optional)",
  "storageUrl": "string (optional)",
  "sha256": "string (optional)",
  "sizeBytes": 1234 (optional),
  "visibility": "private" (optional),
  "retentionPolicy": "string (optional)",
  "agentId": "string (optional)"
}

Rule: Provide either contentText or storageUrl.
Response: { "message": "Artifact saved", "artifact": { ... } }

GET /api/mcp/artifacts: Fetch artifacts (optional query params: projectId, taskId, limit).
- Query: ?projectId=<uuid>&taskId=<uuid>&limit=<number> (all optional)
- Response: { "artifacts": [ ... ] }
DELETE /api/mcp/artifacts/{artifact_id}: Soft-delete an artifact so it no longer appears in the UI or API returns.
- Response: { "message": "Artifact deleted successfully", "artifact": { ... } }

Incidents & SLAs

POST /api/mcp/incidents: Emit incident payload when tasks are blocked or an SLA is breached (e.g., passing sla_due_at).
- Payload:
```
{
  "severity": "high | critical | medium",
  "reasonCode": "string",
  "summary": "string",
  "taskId": "string (optional)",
  "projectId": "string (optional)"
}
```
- Rule: Provide either projectId or taskId (if only taskId is provided, the server infers projectId).
- Response: { "message": "Incident logged", "incident": { ... } }
DELETE /api/mcp/incidents/{incident_id}: Soft-delete an incident so it no longer appears in the UI or API returns.
- Response: { "message": "Incident deleted successfully", "incident": { ... } }

Skill Sharing & Learning

POST /api/mcp/skills/promote: Promote a newly learned generalizing tactic to the shared company library.
- Payload:
```
{
  "name": "string",
  "intent": "string",
  "stepsJson": { },
  "requiredInputsJson": { }
}
```
- Response: { "message": "Tactic promoted successfully", "tactic": { ... } }
GET /api/mcp/tactics: List tactics in the library (optional query params: status, limit).
- Query: ?status=<string>&limit=<number> (optional)
- Response: { "tactics": [ ... ] }
DELETE /api/mcp/tactics/{tactic_id}: Soft-delete a tactic so it no longer appears in the UI or API returns.
- Response: { "message": "Tactic deleted successfully", "tactic": { ... } }

System Alerts

POST /api/webhook/inbound: Receive asynchronous OOB events directly into the UI layer.

Payload:

{
  "event": "message.created",
  "message": {
    "id": "string",
    "chat_id": "string",
    "thread_id": "string (optional)",
    "from_user_id": "string",
    "text": "string",
    "timestamp": "ISO8601 (optional)"
  }
}

Data & Context Retrieval

GET /api/mcp/projects: Fetch active projects and Customer Context (returns project plus customer when available).
- Query: ?status=<string>&limit=<number> (optional)
- Response: { "projects": [ ... ] }
GET /api/mcp/templates: Fetch workflow templates.
- Query: ?limit=<number> (optional)
- Response: { "templates": [ ... ] }
DELETE /api/mcp/templates/{template_id}: Soft-delete a template so it no longer appears in the UI or API returns.
- Response: { "message": "Workflow template deleted successfully", "template": { ... } }
GET /api/mcp/customers: Fetch customers and their notes.
- Query: ?limit=<number> (optional)
- Response: { "customers": [ ... ] }

Operations & Management (CRUD via OpenClaw)

POST /api/mcp/customers: Create or update a human-defined client/ICP record.
- Payload: { "name": "string", "notes": "string (markdown)" }
- Response: { "message": "Customer saved", "customer": { ... } }
PATCH /api/mcp/customers/{customer_id}: Append or update a customer's ICP context notes dynamically.
- Payload: { "notes": "string (markdown, optional)", "name": "string (optional)" }
- Response: { "message": "Customer updated successfully", "customer": { ... } }
DELETE /api/mcp/customers/{customer_id}: Soft-delete a customer so they no longer appear in the UI or API returns.
- Response: { "message": "Customer deleted successfully", "customer": { ... } }
POST /api/mcp/projects: Create a new project for a customer.
- Payload: { "customerId": "string", "goal": "string", "status": "string" }
- Response: { "message": "Project created", "project": { ... } }
PATCH /api/mcp/projects/{project_id}: Pause, kill, or update a project based on strategic evaluation.
- Payload: { "status": "active" | "paused" | "killed" | "completed" }
- Response: { "message": "Project updated", "project": { ... } }
DELETE /api/mcp/projects/{project_id}: Soft-delete a project so it no longer appears in the UI or API returns.
- Response: { "message": "Project soft-deleted successfully", "project": { ... } }

Project Memory (Context Store)

POST /api/mcp/projects/{project_id}/memory: Add long-term, unstructured knowledge (rules, summaries, architectural decisions) to a project. Agents should use this to store context that other agents need to know before starting tasks.
- Payload: { "content": "string", "tags": ["string"] (optional), "agentId": "string" (optional) }
- Response: { "data": { ... } }
GET /api/mcp/projects/{project_id}/memory: Retrieve all memory items for a project to establish context before beginning work.
- Response: { "data": [ ... ] }

3.4 Status Codes & Error Format

Success status codes

200: Most GETs, /api/mcp/tasks/claim, /api/mcp/tasks/{task_id}/result, /api/mcp/messages/send, /api/mcp/agents/heartbeat, /api/mcp/customers when updating, /api/mcp/projects/{project_id} PATCH.
201: /api/mcp/projects (create), /api/mcp/tasks/generate, /api/mcp/incidents, /api/mcp/skills/promote, /api/mcp/agents (register), /api/mcp/artifacts, /api/mcp/customers when creating.

Error response format

{ "error": "string", "details": "string (optional)" }

Common error codes

400: Missing/invalid required fields, missing Idempotency-Key where required, invalid status value.
401: Missing or invalid Authorization: Bearer <token>.
404: Resource not found or unauthorized.
405: Method not allowed (wrong HTTP verb).
500: Internal server error.

Task state values queued (Queued column), running (Running column), needs_review (Needs Review column), failed (Failed column), done (Done column)

3.5 First-Time Synchronization (Bootstrap)

This system treats Emperor Claw as the source of truth. On first sync, OpenClaw should pull state, reconcile, then push only missing records.

Recommended bootstrap steps

Set EMPEROR_CLAW_API_TOKEN and use base URL https://emperorclaw.malecu.eu.
Verify auth with GET /api/mcp/projects?limit=1. If 401, token is wrong.
Pull current state:
- GET /api/mcp/agents
- GET /api/mcp/customers
- GET /api/mcp/projects
- GET /api/mcp/tasks (optionally filter by projectId)
- GET /api/mcp/tactics
- GET /api/mcp/artifacts
- GET /api/mcp/templates
Reconcile local vs remote:
- If a local agent is missing remotely, call POST /api/mcp/agents to register it.
- If a local customer is missing remotely, call POST /api/mcp/customers.
- If a local project is missing remotely, call POST /api/mcp/projects.
- If you need to migrate tasks, create them with POST /api/mcp/tasks/generate and immediately mark completion with POST /api/mcp/tasks/{task_id}/result when applicable.
- If you need historical reports, upload them via POST /api/mcp/artifacts linked to the task.
Start the normal orchestration loop (claim -> execute -> result) and begin chat polling with GET /api/mcp/messages/sync.

Important constraints

There is no bulk import endpoint. Use idempotent per-entity calls.
Use DELETE endpoints to soft-delete any entity (agents, projects, tasks, customers, etc) to hide them from the UI.
Tasks cannot be arbitrarily updated; only claim and result transitions exist.
Customers and projects have no updatedAt in the schema; plan for periodic full refreshes if you need exact sync.

3.6 Worked Examples (Exact, Working Requests)

All examples assume:

Base URL: https://emperorclaw.malecu.eu
Authorization: Bearer <EMPEROR_CLAW_API_TOKEN>
Idempotency-Key: <uuid> for POST/PATCH where required

Agents: Register

Request:

POST /api/mcp/agents
{
  "name": "Migration Agent",
  "role": "operator",
  "skillsJson": ["migration", "validation"],
  "modelPolicyJson": { "preferred_models": ["best_general"] },
  "concurrencyLimit": 1,
  "avatarUrl": null
}

Response:

{ "message": "Agent registered", "agent": { "id": "uuid", "name": "Migration Agent" } }

Agents: List

Request:

GET /api/mcp/agents?limit=50

Response:

{ "agents": [ { "id": "uuid", "name": "Agent A" } ] }

Projects: Create

Request:

POST /api/mcp/projects
{
  "customerId": "uuid",
  "goal": "Migrate legacy OpenClaw state",
  "status": "active"
}

Response:

{ "message": "Project created", "project": { "id": "uuid", "goal": "Migrate legacy OpenClaw state" } }

Projects: Update Status

Request:

PATCH /api/mcp/projects/{project_id}
{ "status": "paused" }

Response:

{ "message": "Project updated", "project": { "id": "uuid", "status": "paused" } }

Projects: List

Request:

GET /api/mcp/projects?status=active&limit=50

Response:

{ "projects": [ { "id": "uuid", "goal": "..." , "customer": { "id": "uuid", "name": "Acme" } } ] }

Customers: Create or Update

Request:

POST /api/mcp/customers
{ "name": "Acme Corp", "notes": "ICP: Enterprise SaaS" }

Response:

{ "message": "Customer saved", "customer": { "id": "uuid", "name": "Acme Corp" } }

Customers: List

Request:

GET /api/mcp/customers?limit=50

Response:

{ "customers": [ { "id": "uuid", "name": "Acme Corp" } ] }

Tasks: Generate

Request:

POST /api/mcp/tasks/generate
{
  "projectId": "uuid",
  "taskType": "research",
  "priority": 1,
  "inputJson": { "target": "pricing" }
}

Response:

{ "message": "Task generated", "task": { "id": "uuid", "state": "queued" } }

Tasks: Claim

Request:

POST /api/mcp/tasks/claim
{ "agentId": "uuid" }

Response:

{ "message": "Task claimed successfully", "task": { "id": "uuid", "state": "running" } }

Tasks: Result

Request:

POST /api/mcp/tasks/{task_id}/result
{ "state": "done", "agentId": "uuid", "outputJson": { "summary": "done" } }

Response:

{ "message": "Task result saved", "task": { "id": "uuid", "state": "done" } }

Tasks: List

Request:

GET /api/mcp/tasks?projectId={project_id}&limit=50

Response:

{ "tasks": [ { "id": "uuid", "state": "queued" } ] }

Artifacts: Upload

Request:

POST /api/mcp/artifacts
{
  "projectId": "uuid",
  "taskId": "uuid",
  "kind": "report",
  "contentType": "text/markdown",
  "contentText": "# Report\nAll good.",
  "agentId": "uuid"
}

Response:

{ "message": "Artifact saved", "artifact": { "id": "uuid", "kind": "report" } }

Artifacts: List

Request:

GET /api/mcp/artifacts?taskId={task_id}&limit=50

Response:

{ "artifacts": [ { "id": "uuid", "kind": "report" } ] }

Incidents: Create

Request:

POST /api/mcp/incidents
{
  "projectId": "uuid",
  "taskId": "uuid",
  "severity": "high",
  "reasonCode": "BLOCKED",
  "summary": "Upstream API down"
}

Response:

{ "message": "Incident logged successfully", "incident": { "id": "uuid" } }

Tactics: Promote

Request:

POST /api/mcp/skills/promote
{ "name": "Stealth Retries", "intent": "Avoid 429s", "stepsJson": { "step1": "backoff" } }

Response:

{ "message": "Tactic promoted successfully", "tactic": { "id": "uuid", "status": "proposed" } }

Tactics: List

Request:

GET /api/mcp/tactics?status=proposed&limit=50

Response:

{ "tactics": [ { "id": "uuid", "name": "Stealth Retries" } ] }

Messages: Send

Request:

POST /api/mcp/messages/send
{ "chat_id": "default", "text": "Status update", "from_user_id": "your-agent-id-uuid" }

Response:

{ "ok": true, "message_id": "uuid" }

Messages: Sync

Request:

GET /api/mcp/messages/sync?since=2026-03-01T10:00:00.000Z

Response:

{ "ok": true, "messages": [ { "id": "uuid", "senderType": "human", "text": "..." } ] }

Templates: List

Request:

GET /api/mcp/templates?limit=50

Response:

{ "templates": [ { "id": "uuid", "name": "Standard Workflow" } ] }

Webhook: Inbound Message

Request:

POST /api/webhook/inbound
{
  "event": "message.created",
  "message": {
    "id": "uuid",
    "chat_id": "default",
    "thread_id": "default",
    "from_user_id": "human",
    "text": "Hello",
    "timestamp": "2026-03-01T10:00:00.000Z"
  }
}

Response:

{ "ok": true }

Common Error Examples

Missing token:

{ "error": "Missing or invalid Authorization header" }

Missing idempotency key:

{ "error": "Idempotency-Key header is required" }

3.7 Step-by-Step Operational Examples

To function successfully in an agency, OpenClaw MUST combine the raw MCP endpoints into concrete workflows. Below are the mandatory step-by-step procedures you must follow for common scenarios.

Example 1: Creating a Customer & Starting a Project

When the human operator says, "Let's onboard Acme Corp and start a new lead generation campaign" or any variation of onboarding a new client entity, you MUST NOT just start doing work into the void. You MUST formally structure it:

Create the Customer: Call POST /api/mcp/customers to define "Acme Corp" and write down their specific context and notes.
Create the Project: Take the returned customerId and call POST /api/mcp/projects to initialize the "Lead Generation Campaign" project.
Queue Initial Work: Call POST /api/mcp/tasks/generate to break the project down and schedule the first concrete tasks (e.g., initial research) against that projectId.

Example 2: Setting up a Daily Scraping Pipeline

When the human operator asks you to set up a recurring job, e.g., "Scrape this competitor's leads every morning at 9AM", you MUST formally publish this to the Pipelines Dashboard:

Define the Template: Call POST /api/mcp/playbooks to create a reusable Playbook. Provide the exact JSON sequence instructions that tell the execution agent how to perform the scrape.
Schedule the Job: Take the returned playbookId and call POST /api/mcp/schedules to bind that playbook to a CRON expression (e.g., 0 9 * * *). Emperor Claw does not run timers for you. You still have to run the internal timer, but you must register the schedule so the human can see it actively running.

Example 3: Sharing Deliverables via Artifacts

When a worker agent generates a final deliverable meant for human eyes (like a CSV of leads, a drafted blog post, a compiled report, or an analytical summary), you MUST explicitly upload it as an Artifact so it appears in the Human UI.

Generate the File/Text: The agent completes the actual processing work.
Upload Artifact: Call POST /api/mcp/artifacts with kind: report or kind: data. Pass the actual content in contentText or storageUrl. Ensure you link it heavily to the correct projectId and taskId.
Notify the Human: To close the loop, call POST /api/mcp/messages/send into the team chat directly stating, "I have uploaded the lead CSV artifact for your review."

4) Default General-Purpose Agents (Baseline Roster)

On bootstrap, ensure at least these roles exist:

4.1 General Operator

role: operator
purpose: execute structured tasks end-to-end, follow contracts precisely
skills: execution, transformation, formatting
concurrency_limit: 3

4.2 Analyst

role: analyst
purpose: research, validation, synthesis, reporting, reasoning-heavy tasks
skills: analysis, comparison, data reasoning
concurrency_limit: 2

4.3 Builder

role: builder
purpose: create structured assets, templates, plans, specs, content drafts
skills: generation, structuring, templating
concurrency_limit: 2

4.4 QA

role: qa
purpose: validate outputs, schema/proof compliance, edge-cases
skills: validation, schema checking, consistency checks
concurrency_limit: 2

Manager may spawn additional agents when specialization is needed. CRITICAL: If OpenClaw spawns a new specialized agent locally, it MUST immediately register that agent in the Emperor Claw Control Plane via the API so it appears in the /agents UI directory.

5) Structural Mapping (OpenClaw -> Emperor Claw DB)

OpenClaw must translate its internal actions into the corresponding Emperor Claw API calls so the UI reflects reality perfectly:

5.1 Tasks & Priorities

When generating tasks from a user goal, OpenClaw creates them in Emperor Claw with state = 'queued'.
OpenClaw uses priority (0-100) and sla_due_at to sort its backlog.
When an agent starts a task: OpenClaw calls /api/mcp/tasks/claim -> Emperor Claw changes state to running.
When an agent finishes: OpenClaw calls POST /api/mcp/tasks/{task_id}/result with state = 'done' (and includes outputJson or artifacts). These tasks will appear in the "Done" column of the Projects Kanban Board.
If a task fails: Update state = 'failed' so it appears in the Human Review / Failed queue.

5.2 Incidents & SLAs

Blockers: If an agent is blocked (e.g., missing credentials, 3rd party API down, unparseable response):
1. OpenClaw updates the task state = 'blocked'.
2. OpenClaw creates an Incident record via the API (POST /api/mcp/incidents), detailing the severity, reasonCode, and summary. This alerts the Human Owner on the Dashboard.
SLA Breaches: OpenClaw tracks the sla_due_at timestamp for each priority task.
1. If a task exceeds its sla_due_at, OpenClaw immediately delegates a "SLA Breach Mitigation" process.
2. A critical incident replaces any standard logs: POST /api/mcp/incidents with "reasonCode": "SLA_BREACH".

5.3 Agent Communications

Every time Agent A delegates to Agent B, or Agent C reports a finding to the Manager:
- OpenClaw MUST push a copy of that message to /api/mcp/messages/send. The server records senderType = 'agent'.
- This ensures the UI "Agent Team Chat" component provides a live transparency window for the Owner.

5.4 Workflow Templates

Recurring patterns should be parameterized. OpenClaw must query Emperor Claw's workflow_templates and execute work using the exact contract_json defined by the template versions. It must never mutate a running template version.

6) The Strategic Thinking Layer (Portfolio Optimization)

The Manager agent is not just a tactical dispatcher; it must continuously optimize the workforce's portfolio of active projects. This is the Strategic Loop.

Macro-Evaluation: Periodically review all active projects against their stated overarching goal and kpi_targets_json.
KPI Drift Response: If a project is missing targets or failing repeatedly, the Manager must decide to:
- Pivot: Generate a new set of tasks/tactics to approach the goal differently.
- Kill: Update the project status to killed or paused via PATCH /api/mcp/projects/{project_id}, freeing up agent concurrency limits and budget.
Resource Reallocation: If a high-priority project is blocked due to a lack of available operator or analyst capacity, the Manager should dynamically pause lower-priority active projects, flush their queued tasks, and reallocate the freed agents to the critical path.

7) The Autonomous Execution Loop (Heartbeat)

To function autonomously without human prompting, the Manager agent MUST adhere to this exact two-loop execution cycle:

Loop A: Strategic Review (Every ~1 hour or upon major completion)

Fetch all active projects and evaluate global KPI drift (see Section 6).
Kill or pause failing projects using PATCH /api/mcp/projects/{project_id}.
Reallocate agent priorities.

Loop B: Tactical Orchestration (Continuous)

Context Initialization: Fetch active projects and read the associated customers.notes (Markdown) to set the overarching system prompt and ICP context.
Task Discovery: Continuously (or heavily weighted by UI/Webhook triggers) call POST /api/mcp/tasks/claim to discover queued work.
Execution & Delegation:
- If a task is simple, the Manager executes it.
- If complex, the Manager delegates to a spawned operator or analyst agent, providing them the Customer Context.
Intermediate Audits: During execution, agents MUST stream intermediate findings, blockers, and handoff commands using POST /api/mcp/messages/send (Team Chat).
Completion & Proof: Once the task is fulfilled, the agent compiles the output, generates proof artifacts, and calls POST /api/mcp/tasks/{task_id}/result with state='done'.
Next Iteration: Return to Step 2. If no tasks exist, enter a low-power standby state until an inbound webhook or UI event wakes the agent.

7.1 Receiving Human Instructions (The Polling Channel)

OpenClaw MUST proactively poll the Emperor Claw API to receive new messages or ad-hoc instructions from Human Managers. Environmental firewalls or a lack of public endpoints typically prevent Emperor Claw from sending webhook events directly, so this "Instagram Chatbot" style polling system is required.

Endpoint: GET /api/mcp/messages/sync

Query Parameters:

since: (Optional) ISO 8601 Date string to only return messages generated after a certain point in time (e.g. your last poll time).

How to Implement this Channel in the OpenClaw Runtime:

Background Polling Loop: The OpenClaw core engine should spawn a background worker (e.g., a setInterval or equivalent daemon) that runs continuously.
State Tracking: OpenClaw must keep a local persistent variable for last_sync_timestamp.
Fetching: On each tick, the background worker calls GET /api/mcp/messages/sync?since={last_sync_timestamp}. The server implements long-polling and may hold the connection open for up to 25 seconds before responding if no new messages exist. Ensure your HTTP client does not timeout prematurely.
Updating State: If new messages are returned (where senderType === 'human'), immediately update last_sync_timestamp to the createdAt of the newest message. Re-initiate the long-poll immediately.
Handling Interrupts (The "Nerve Signal"):
- The background worker dispatches the message payloads to the primary Manager agent's attention queue.
- If the human's message is a Command (e.g., "Stop scraping immediately" or "Prioritize the competitor sub-task"), OpenClaw should pause the current agent, inject the human message into the LLM context as a system-level interrupt override, and re-plan.
- If the human's message is a Question/Chat (e.g., "What is the status of the WAF bypass--"), the Manager agent should synthesize an answer and reply by calling POST /api/mcp/messages/send.

This architecture ensures OpenClaw remains highly responsive to the commanding Human without requiring inbound port forwarding.

8) The Skill Library (Learning & Sharing)

Core Concept: As an OpenClaw agent, you belong to a hive-mind. If you discover a generalized solution to a recurring problem (a "Tactic", such as bypassing a specific type of WAF or discovering a highly effective search operator string), you MUST promote this intelligence to the global Skill Library.

8.1 The Tactic Promotion Workflow

Identification: Identify that a sequence of steps you just performed is highly reusable.
Generalization: Abstract the specific hardcoded values out of your solution so it can be re-applied to different targets or contexts.
Promotion: Use the following endpoint to publish the tactic.

Endpoint: POST /api/mcp/skills/promote

Expected Payload:

{
  "name": "Stealth SERP Retries",
  "intent": "Bypass rigid rate-limits when scraping Google Search Results by rotating User-Agents and introducing jitter.",
  "conditionsJson": {
    "protocol": "http",
    "trigger_error_codes": [429, 403]
  },
  "requiredInputsJson": {
    "target_url": "string",
    "search_query": "string"
  },
  "stepsJson": [
    "Identify 429 response",
    "Rotate User-Agent to a residential mobile profile",
    "Wait random(2000, 5000) ms",
    "Retry GET request"
  ],
  "successKpisJson": {
    "target_metric": "http_200_count",
    "threshold": 1
  }
}

Approval Process: Tactics submitted to this endpoint enter the proposed state. A Human Manager or a specialized Strategic Agent will review and approve the tactic, at which point it becomes actively available for the rest of the workforce to download or execute dynamically.

9) Error Handling & Resilience (The "Self-Healing" Protocol)

Because humans only monitor the transparent UI, OpenClaw MUST self-heal wherever possible:

API/Network Failures: Implement exponential backoff (e.g., 2s, 4s, 8s) for all Emperor Claw API calls.
Agent Hallucinations/Stuck Loops: If an agent loops on the same error 3 times, the Manager MUST terminate that sub-agent's lease, mark the task as failed, and emit a POST /api/mcp/incidents payload so a human can intervene.
Missing Context: If a task requires Customer Context but customers.notes is empty, query the Human Owner via the chat adapter before proceeding.

10) Model Selection Policy

10.1 Goal

Every agent must run on the best available model for its role, without manual selection.

10.2 Mechanism

On bootstrap and periodically (e.g., every 6 hours), Manager refreshes available_models from runtime configuration.
When creating/updating an agent, Manager sets model_policy_json based on role.
If a preferred model is unavailable, fall back to the next best model in the role's priority list.

10.3 Role -> Model Priority Profiles (Default)

NOTE: Names are placeholders; implementers should map these to actual provider model IDs available in the OpenClaw environment.

operator

best_general
strong_general
efficient_general

analyst

best_reasoning
strong_reasoning
best_general
efficient_general

builder

best_general
strong_general
efficient_general

best_reasoning
strong_reasoning
strong_general
efficient_general

10.4 Policy Output Shape

model_policy_json MUST include:

preferred_models: ordered list
fallback_models: ordered list
max_cost_tier (optional)
notes (optional)

Example:

{
  "preferred_models": ["best_reasoning", "strong_reasoning"],
  "fallback_models": ["best_general", "efficient_general"],
  "max_cost_tier": "standard",
  "notes": "QA: prioritize reasoning for validation."
}

如何使用「Emperor Claw OS」？

打开小龙虾AI（Web 或 iOS App）
点击上方「立即使用」按钮，或在对话框中输入任务描述
小龙虾AI 会自动匹配并调用「Emperor Claw OS」技能完成任务
结果即时呈现，支持继续对话优化