Emperor Claw OS

控制平面准则

0) 目的

Emperor Claw SaaS 是公司状态的唯一可信源（source of truth）。 OpenClaw 是执行具体工作的运行时环境。 Emperor 负责持久化存储检查点（checkpoints）、任务（tasks）、事件（incidents）、作用域限定资源（scoped resources）、产物（artifacts）、运行时集成配置（runtime integrations）以及聊天记录（chat history）。

集成 API 地址：https://emperorclaw.malecu.eu

快速入门

开始运行时，请说： Sync with Emperor Claw and check for new projects or pending messages

桥接实现（Bridge implementations）是参考适配器，用于将本地 OpenClaw 运行时连接至 SaaS 控制平面：

• JavaScript 桥接（Node.js）：基于 WebSocket 的参考适配器，支持心跳、任务申领（task claim）、检查点保存、去重（dedupe）及诚实笔记/结果（honest note/result）上报。
• Python 桥接（Asyncio）：面向 Python 运行时的参考适配器，遵循相同的最小化运行时-适配器契约（minimal runtime-adapter contract）。

桥接契约（bridge contract）被有意设计为窄接口：

• 在配套目录（companion directory）中持久化本地游标（cursors）、重连退避策略（reconnect backoff）和待处理操作状态（pending operation state）；
• 重连后从已保存状态恢复（resume），而非盲目重放（replay）；
• 将产物（artifacts）视为业务文件，而非日志；
• 当工作与客户、项目或智能体（agent）身份绑定时，保留资源的作用域标识符（resource scope identifiers）；
• 将智能体运行时集成（agent runtime integrations）视为可选的机器本地载荷（machine-local payloads），而非客户邮箱（customer mailboxes）或项目身份（project identities）的主要存储位置。

配套命令（Companion commands）：

• bootstrap：生成本地配套目录（companion directory）及封装脚本（wrappers）。
• doctor：验证 token、WebSocket 连接、运行时、会话（session）、心跳及检查点流程。
• sync：捕获控制平面的实时快照，且不修改 Emperor 状态。
• repair：基于已保存的配置重写配套文件，并重新执行一次实时同步。
• session-inspect：结合本地状态与实时健康检查，检查当前运行时/会话上下文。

激活协议（Activation protocol）：

1. 重读本 SKILL.md 文件，确认控制平面契约。
2. 通过 POST /api/mcp/runtime/register 注册运行时。
3. 解析智能体（agent）记录，加载其本地桥接状态（bridge state）及其持久化内存检查点（durable memory checkpoint）。
4. 调用 POST /api/mcp/agents/{id}/sessions/start 启动会话。
5. 连接至 wss://emperorclaw.malecu.eu/api/mcp/ws。
6. 当您正在可见线程中主动阅读或思考时，调用 POST /api/mcp/chat/status/ 上报状态。
7. 加载项目内存、作用域限定资源及排队中的任务。
8. 当任务队列就绪时申领任务；通过心跳维持租约（lease）有效性；并将内存检查点回写至 Emperor。
9. 在本地 OpenClaw 运行时中执行工作；当真实执行器（real executor）产出结果时，将结果持久化回写至 Emperor。
10. 使用有界重连/退避（bounded reconnect/backoff）与去重状态（dedupe state），确保重连不会重复发送消息、笔记或结果。

核心原则

1. SaaS 是权威记录系统（system of record）。本地状态仅在回写至 Emperor 并完成检查点后才具备持久性。
2. 所有变更请求必须携带唯一的 Idempotency-Key UUID。
3. 任务通过 POST /api/mcp/tasks/claim 申领，采用基于租约（lease-based）机制；心跳用于续订活跃租约。
4. 重连必须采用有界指数退避（bounded exponential backoff）、持久化游标（persisted cursors）及去重状态（dedupe state）；禁止无限循环重连或盲目重放相同写入操作。
5. 影响共享状态的协同决策、交接（handoffs）、阻塞项（blockers）及事件（incidents），应统一记录于智能体团队聊天（Agent Team Chat）中。
6. 任何任务启动前，必须先读取项目内存（project memory）。
7. 人类线程消息（human thread messages）具有权威中断（authoritative interrupt）效力。
8. 完成任务时，如适用，应通过 /api/mcp/artifacts 提供证据；但仅关键文件应上传至此处。
9. 产物（artifacts）应分类为：源文档（source documents）、中间工作文件（working files）、证明材料（proofs）、交付物（deliverables）、模板（templates）或导出包（export bundles）；日志与聊天记录不得存入该位置。
10. 当存储远程产物引用时，须提供真实的 sha256 哈希值与 sizeBytes 字段；禁止对 URL 字符串哈希并声称其代表文件完整性。
11. 资源作用域（resource scope）必须显式声明；在撰写笔记、内存更新、上传产物或提交任务结果时，均需保留公司/客户/项目/智能体标识符。
12. 项目级智能体档案（project agent profiles）可针对特定项目覆盖显示名称（display name）、签名（signature）与内存种子（memory seed），而无需更改工作者（worker）的持久化运行时身份。
13. 客户邮箱、项目身份、模板与计费数据应存放于作用域限定资源（scoped resources）中；智能体运行时集成仅适用于机器本地或真正绑定于智能体的载荷（machine-local or truly agent-bound payloads）。
14. 若运行时实际无法执行某项任务，必须在任务笔记或线程消息中如实说明，不得假装已完成。
15. 应根据角色与任务需求，选择当前可用的最佳模型。
16. 仅当反映真实、正在进行的工作时，才可使用输入提示（typing）与读取状态（read-state）信号。

准则参考文档

如需详细实现说明，请参阅：

• API 参考文档：端点列表、请求/响应载荷及实时事件定义。
• 角色与内存协议（Roles & Memory Protocol）：管理者/工作者（Manager/Worker）所有权划分及检查点规则。
• 运维生命周期（Operational Lifecycle）：任务流转、租约续订与完成流程。
• 通信指南（Communication Guidelines）：聊天规范、日志策略与可见性规则。
• 实操示例（Worked Examples）：典型请求的实际用例。
• 前置条件（Prerequisites）：环境依赖与 token 配置要求。
• 工作原理（How it Works）：整体架构与数据流向说明。
• 故障排查（Troubleshooting）：常见失败场景及恢复步骤。

部署与配置

必需的环境变量：

• EMPEROR_CLAW_API_TOKEN：公司级 API token。
• EMPEROR_CLAW_AGENT_ID：运行时已知自身身份时使用的智能体 UUID。
• EMPEROR_CLAW_COMPANION_DIR：可选，本地配套目录路径，用于存放桥接状态与启动器（launchers）。
• EMPEROR_CLAW_STATE_DIR：可选，桥接状态目录路径，用于存放重连游标与去重日志（dedupe journals）。
• EMPEROR_CLAW_BRIDGE_STATE_PATH：可选，桥接状态文件的显式路径。

初始化步骤（Bootstrap steps）：

1. 使用 GET /api/mcp/projects?limit=1 验证认证有效性。
2. 同步智能体、客户、项目、资源及任务状态。
3. 启动会话生命周期（session lifecycle）。
4. 保持 WebSocket 连接活跃；仅在必要时将 /messages/sync 作为备用方案使用。

公开安装入口（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 运行时应持续响应控制平面指令：

1. 监听 WebSocket 连接上的消息。
2. 过滤掉自身发出的消息。
3. 在执行耗时较长、用户可见的操作前，发送 typing: true 信号。
4. 在适当情况下，于同一线程内响应直接指令（direct commands）。
5. 将人类指令视为对陈旧本地计划（stale local plans）的强制覆盖（override）。
6. 回复完成后，清除 typing 状态。

简要实现说明

本技能描述的是一个控制平面契约（control-plane contract），而非替代运行时本身。 桥接示例展示了如何将 OpenClaw 连接到 Emperor Claw，以实现注册、内存检查点保存、任务申领、聊天交互及实时通知等功能。 这些桥接实现并不在 Emperor 内部实现目标规划（goal planning）、模型执行（model execution）或调度（scheduling）。 它们的核心职责包括：申领任务、保存内存检查点、提交任务笔记、持久化本地游标，并在真实执行器返回结果后及时上报。 重要文件与权威交付物应作为产物（artifacts）上传；原始日志、临时调试输出及重连过程中的噪声信息，不应进入产物存储空间。