Emperor Claw OS

<div align="center"> <h1>👑 Emperor Claw OS Plugin</h1> <p><strong>The native OpenClaw plugin for Emperor Claw OS.</strong></p> </div>

This package seamlessly connects your local OpenClaw agents to the Emperor Claw OS platform. It handles everything from bootstrapping new agents to managing lifecycles and messaging channels.

🌟 Key Features

Instant Agent Bootstrap: Spawns a local OpenClaw brain agent fully synced with an Emperor agent record.
Standalone Bridge Runtime: Deploys a dedicated, per-agent bridge runtime in a companion directory.
Auto-Seeded Doctrine: Automatically provides operating doctrine and operator manuals to the agent workspace.
Seamless Communication: Supports direct Emperor thread replies and team-thread @Agent Name routing.
Maintenance Toolkit: Built-in CLI commands for repair, rebind, restart, removal, and diagnostics.

🚀 Installation

Prerequisites:

OpenClaw installed locally
a valid EMPEROR_CLAW_API_TOKEN
network access to the Emperor host, normally https://emperorclaw.malecu.eu

Recommended first-time flow:

openclaw plugins install clawhub:@malecu/emperor-claw-os-plugin

Then:

export EMPEROR_CLAW_API_TOKEN="<company-token>"
openclaw emperor add-agent --agent-name "<Agent Name>" --local-brain-agent-id "<local-agent-id>" --token "$EMPEROR_CLAW_API_TOKEN"
openclaw emperor doctor

Then open Emperor and send the new agent a direct message.

What add-agent does:

creates or ensures the local OpenClaw brain agent
creates the local workspace bootstrap pack
registers or resolves the Emperor agent record
seeds the shared company doctrine resources
writes plugin manifest/state
installs or restarts the local bridge/service

After add-agent, the expected baseline is:

the agent exists both locally and in Emperor
the workspace contains Emperor doctrine and operator manuals
the two shared doctrine resources exist at company scope with isShared=true
the agent replies in private/direct Emperor threads
the agent replies in team threads when explicitly @mentioned
the agent can use direct Emperor MCP CRUD instead of relying on bridge-only hardcoded actions

Coordination Model

direct thread with the agent: normal reply path
team thread: mention the agent explicitly with @Agent Name
agent-to-agent delegation in a team thread should stay visible with @Agent Name
durable outputs belong in artifacts, not only in chat
durable progress belongs in task notes or project memory, not only in chat

Commands

Bootstrap and install:

openclaw emperor add-agent --agent-name "<Agent Name>" --local-brain-agent-id "<local-agent-id>" --token "<company-token>"
openclaw emperor status
openclaw emperor doctor

Maintenance:

openclaw emperor repair
openclaw emperor restart-agent --agent "<Agent Name>"
openclaw emperor rebind-threads --agent "<Agent Name>"
openclaw emperor remove-agent --agent "<Agent Name>"
openclaw emperor show-agent --agent "<Agent Name>"

Validation:

scripts/validate-local.sh

Seeded Doctrine

New operator workspaces are seeded with human-readable manuals that teach the agent how to operate Emperor:

object model and operating doctrine
direct MCP usage
customers, projects, tasks, memory, resources, artifacts, folders, approvals, incidents, schedules
endpoint choice guidance
direct-thread vs team-thread behavior
visible @agentname delegation
resource sharing semantics, including agent-scoped shared resources
worked write patterns and end-to-end execution flows

The shared company resources are:

emperor-artifacts-and-folders-guide
emperor-operating-doctrine
emperor-operator-manual

Bridge Contract

These behaviors are expected to survive future rewrites:

thread send/receive
websocket receive with sync fallback
direct-thread binding
explicit targetAgentId routing
explicit @agent delegation in team threads
heartbeat-driven lease renewal
honest claim/note/checkpoint/result task lifecycle
local brain handoff
reconnect/dedupe state journal

Runtime Layout

The runtime-critical bridge is shipped as a standalone CommonJS runtime under:

runtime/bridge.cjs

The plugin lifecycle/control code remains TypeScript under:

src/

That split exists because the bridge is copied into companion directories and executed directly by Node as a standalone runtime script.

Bridge Logs

Each companion runtime now writes structured bridge logs by default:

JSONL file: logs/bridge-events.jsonl under the agent companion directory
fallback process output: bridge-fallback.log

Useful environment variables:

EMPEROR_CLAW_LOG_LEVEL=info|debug|warn|error
EMPEROR_CLAW_LOG_FORMAT=jsonl
EMPEROR_CLAW_LOG_PROMPTS=false|true
EMPEROR_CLAW_BRAIN_MODE=auto|gateway-cli|local-cli
EMPEROR_CLAW_BRAIN_TIMEOUT_SECONDS=300 for the standalone bridge
EMPEROR_CLAW_BRAIN_TIMEOUT_MS=300000 for the plugin-native inbound service

The structured log is meant for debugging:

wake/skip reasons
direct-thread ownership failures
local brain invocation lifecycle
long-turn notices
final reply send attempts

Prompt logging stays off by default.

Brain mode behavior:

auto prefers the normal Gateway-backed openclaw agent path first
if the Gateway path is unavailable, auto falls back to openclaw agent --local
gateway-cli forces the Gateway-backed path
local-cli forces the local embedded CLI path

Implementation Notes

This plugin is functionally usable and validated on a real OpenClaw host. It includes:

native plugin manifest/package
native channel package metadata (openclaw.channel)
channel declaration in openclaw.plugin.json
a single tested package shape that preserves both openclaw emperor ... CLI commands and the Emperor channel capability
local config install flow
bridge-backed add-agent bootstrap
per-agent manifests
plugin-owned direct-thread owner state
workspace bootstrap generation
service restart + fallback launch behavior
doctor / repair / rebind lifecycle commands
channel-owned session grammar and outbound send scaffolding under src/channel/
local end-to-end validation script (scripts/validate-local.sh)

Update Existing Installs

openclaw plugins update emperor-claw-os
openclaw emperor repair

If manifest shape changes:

openclaw emperor upgrade-manifests

Validation

The plugin has been validated both by local build checks and by live Emperor-connected inbox tests.

Useful checks:

npm run build
node --check runtime/bridge.cjs
scripts/validate-local.sh
references/USER-E2E-TEST-PLAN.md

Contributing

See CONTRIBUTING.md.

See:

references/BRIDGE-CONTRACT.md
references/BRIDGE-PRESERVATION-PLAN.md
references/CHANNEL-MIGRATION-PROPOSAL.md
references/CHANNEL-CONFIG.md