Understanding OpenClaw's Agent OS Skill: Persistent Multi‑Agent Orchestration

What the Agent OS Skill Does in OpenClaw

OpenClaw is a framework that lets developers compose autonomous agents to
solve real‑world problems. One of its most powerful building blocks is the
Agent OS skill, found at skills/skills/cryptocana/agent-os/SKILL.md in
the official repository. This skill transforms a collection of stateless
workers into a coordinated, memory‑enabled operating system for agents. Below
is a detailed walk‑through of its core capabilities, architecture, and
practical usage.

Persistent Agent Memory

The defining feature of Agent OS is that each agent retains a personal memory
across sessions. Whenever an agent finishes a task, it writes two JSON files
to the data/ folder: [agent-id]-memory.json and [agent-id]-state.json.
The memory file stores lessons learned, success rates, and a historical log of
every task the agent has attempted. The state file captures the agent’s
current task, progress percentage, and any blockers. Because this data lives
on disk, shutting down the process or restarting the machine does not erase an
agent’s experience. When the system boots again, Agent OS reloads these files,
giving each worker instant access to its past performance.

This persistence solves a common problem in LLM‑based agents: the need to
re‑inject the same context over and over, which wastes tokens and increases
cost. By keeping a compact summary of what worked and what did not, agents can
make better decisions without repeatedly prompting the model with large blocks
of text.

Task Decomposition and Smart Routing

Agent OS includes a TaskRouter component that turns high‑level goals into
concrete, executable steps. When you call runProject(goal, taskTypes), the
router first breaks the goal into a sequence of task types—for example,
turning “Build a feature” into planning → design → development → testing.
Each task type is matched against the list of registered agents and their
declared capabilities.

The matcher uses a simple fitness score: an agent receives a point for each
capability it shares with the task type. The agent with the highest score is
assigned the task. If multiple agents tie, the router prefers the one with the
best historical success rate stored in memory. This ensures that work is
routed to the most suitable worker while still allowing less‑experienced
agents to gain experience on simpler tasks.

Execution Tracking and Live Progress

Once tasks are assigned, the Executor runs them sequentially (with plans
for parallel DAG execution in future releases). As each task proceeds, the
executor calls the agent’s updateProgress(percentage, message) method, which
updates the agent’s state file and, if a dashboard is enabled, pushes the
information to a live HTML UI.

The dashboard (ui/dashboard.html) provides a real‑time kanban‑style board
showing every agent’s current task, completion percentage, and any active
blockers. This visibility makes it easy for humans to intervene when an agent
stalls, and it gives developers a clear audit trail of what happened during a
run.

State Persistence and Project Resumability

Beyond per‑agent memory, Agent OS persists the entire project state in
[project-id]-project.json. This file contains the ordered list of tasks,
each task’s status (pending, in‑progress, completed, blocked), and any output
produced so far. If the process crashes after completing five of twelve tasks,
a subsequent call to runProject with the same project ID will load the
project file, skip the already‑finished tasks, and resume at task six.

This feature is invaluable for long‑running workflows such as multi‑day
research projects, iterative software development, or any scenario where you
cannot guarantee uninterrupted uptime. It also enables checkpoint‑based
debugging: you can inspect the project file after each step to verify
intermediate results.

Core Components Overview

• Agent class (core/agent.js) – Encapsulates memory, state, capabilities, and methods like startTask, completeTask, recordError, and learnLesson.
• TaskRouter class (core/task-router.js) – Implements goal decomposition, capability matching, dependency tracking, and utilities such as getNextTask and canExecuteTask.
• Executor class (core/executor.js) – Drives the sequential execution loop, handles errors, and persists state after each task.
• AgentOS class (core/index.js) – The public façade that exposes registration, initialization, project execution, and status querying methods.

API Reference at a Glance

Using Agent OS in a Node.js project is straightforward:

1. Install via ClawHub: clawhub install nova/agent-os
2. Require the main class:
3. const { AgentOS } = require('agent-os');
4. Create an instance, optionally passing a project ID:
5. const os = new AgentOS('my‑project');
6. Register agents with unique IDs, display names, and capability arrays:
7. os.registerAgent('research', '🔍 Research', ['research', 'planning']);
8. os.registerAgent('design', '🎨 Design', ['design', 'planning']);
9. os.registerAgent('dev', '💻 Development', ['development']);
10. Initialize the system (loads existing state from disk):
11. await os.initialize();
12. Run a project by supplying a goal string and an ordered list of task types:
13. const result = await os.runProject('Build a feature', ['planning', 'design', 'development']);
14. Retrieve progress or full status via os.getStatus() or os.getAgentStatus(agentId).

The returned result object contains a progress field (0‑100) and an array
of per‑task outputs, making it easy to log or forward to other systems.

Example Workflow: Research → Design → Development

The repository includes an illustrative example at examples/research-
project.js. Running npm start in that folder produces output similar to:

Registered 3 agents
📋 Task Plan: 12 tasks
🚀 Starting execution...
✅ [Task 1] Complete
✅ [Task 2] Complete
...
📊 PROJECT COMPLETE - 100% progress

In this scenario:

• The research agent gathers requirements, creates a specification, and records lessons about ambiguous user stories.
• The design agent receives the spec, produces wireframes, and updates its memory with UI patterns that received positive feedback.
• The development agent implements the features, logs any bugs, and updates its success rate for each component type.
• All three agents write their memory and state after every step, so if you stop after the design phase and restart later, the development agent will pick up exactly where it left off, without needing to re‑read the spec.

Roadmap: What’s Coming in v0.2+

The Agent OS skill is actively evolving. Planned enhancements include:

• An HTTP server that serves the live dashboard remotely, enabling team‑wide monitoring.
• Parallel task execution using a directed‑acyclic‑graph (DAG) solver to run independent tasks concurrently.
• A capability‑learning system that automatically adjusts agent scores based on outcomes, reducing the need for manual capability tuning.
• Improved smart routing that factors in current workload, estimated duration, and historical variance.
• Failure recovery with exponential back‑off and retry logic for transient errors.
• Token‑usage tracking per agent to help optimize cost.
• Human checkpoints for high‑risk outputs, allowing a reviewer to approve or request revisions before proceeding.

Philosophical Underpinnings

Agent OS embodies the idea that agents should remember what they learn.
Traditional agent frameworks treat each invocation as a blank slate, forcing
developers to repeatedly inject context, which not only inflates token costs
but also prevents agents from benefitting from experience. By contrast, Agent
OS treats memory as a first‑class citizen:

• Remember – Agents retain a compact history, eliminating redundant context resets.
• Learn – Success rates and lessons improve over time, yielding better task allocations.
• Coordinate – Shared project state prevents duplicate work and clarifies dependencies.
• Cost less – Smaller prompts mean lower API usage and faster responses.

Getting Started

To try Agent OS today:

1. Clone the OpenClaw skills repository: git clone https://github.com/openclaw/skills.git
2. Navigate to skills/skills/cryptocana/agent-os.
3. Run npm install to fetch dependencies.
4. Start the example: npm run example or node examples/research-project.js.
5. Observe the live dashboard at http://localhost:3000/ui/dashboard.html (if the server feature is enabled) or inspect the generated JSON files in the data/ folder.

Because the skill is MIT‑licensed, you are free to adapt it for commercial or
research projects. The modular design lets you replace the storage layer
(e.g., swap JSON files for a database) or extend the TaskRouter with
domain‑specific templates without touching the core orchestration logic.

Conclusion

The Agent OS skill equips OpenClaw with a persistent, multi‑agent operating
system that transforms fleeting, stateless workers into knowledgeable,
cooperative teammates. By providing durable memory, intelligent task routing,
real‑time progress tracking, and seamless project resumability, it addresses
the most common pain points in LLM‑driven automation: context waste,
duplicated effort, and fragile workflows. Whether you are building a simple
research assistant or a complex software‑development pipeline, Agent OS offers
the foundation needed to create agents that not only execute tasks but also
get better at them over time.

Skill can be found at:
os/SKILL.md>