OpenMOSS Documentation

OpenMOSS is an "AI Company Operating System" designed to enable multiple AI Agents to operate autonomously. It acts as a middleware between orchestration systems like OpenClaw or Claude Code and the underlying AI models.

Instead of a single agent attempting a task and failing when it hits an error, OpenMOSS organizes agents into a structured company hierarchy with specialized roles (Planner, Executor, Reviewer, and Patrol) to ensure self-organization, self-repair, and closed-loop quality control.

The Task Planner must establish a standardized directory structure for all tasks and sub-tasks to ensure execution Agents can access them immediately:

{Public Working Directory}/tasks/{TaskName}_{ShortID}/
                     └── {SubTaskName}_{ShortID}/

Naming Rules:

• Replace spaces and special characters with underscores (_).
• The Short ID must be the first 6 characters of the Task/Sub-task ID.
• Directories must be created at the time the task is initialized.

{公共工作目录}/tasks/{任务名称}_{任务短ID}/
                     └── {子任务名称}_{子任务短ID}/

OpenMOSS uses a layered prompt directory structure to manage agent behaviors. You can customize these to create specialized agents for your specific use case.

• prompts/templates/: Contains base role templates (e.g., task-planner.md, executor.md) used when creating agents via the WebUI.
• prompts/agents/: Contains examples of how to combine base templates with specialized capability definitions (e.g., executor-backend.md for backend developers).
• prompts/role/: Contains executor role specialization examples that define specific responsibilities (e.g., ai-xiaowu-executor.md). Customize these for your specific domain.
• prompts/tool/: Contains prompts related to tool usage, such as agent-onboarding.md.

OpenClaw manages context through different session types:

• Private chat: Operates as one independent context (session window).
• Group chat: Operates as a separate independent context that is not synced with private chats.
• Cron wake-up: Triggers a completely fresh context.

Operational Tip: If a main agent becomes blocked while performing a task and you cannot interact with it, instruct it to create a temporary sub-agent to handle that specific task. This allows you to continue communicating with the main agent independently.

To create a long-term automated workflow (e.g., a daily news site), define the task with type: recurring. A recurring task consists of a sequence of subtasks with dependencies. For example, a content pipeline might follow the pattern: Subtask 1 (Collection) -> Subtask 2 (Creation) -> Subtask 3 (Publishing).

When the Planner detects that all subtasks in a round are done, it automatically creates a new round of the same task type. Ensure that subtask descriptions explicitly state dependencies and the file paths of the deliverables required from previous steps.

OpenMOSS utilizes four specialized roles modeled after human organizational structures to manage task lifecycles:

Sub-tasks are the smallest unit of work that these roles interact with.

Agents are managed by the OpenClaw cron scheduler. Each time an agent is 'woken up', it starts with a fresh context. The standard lifecycle for an agent is:

1. Read global rules: Understand behavior standards.
2. Check reflection logs: Review past mistakes to avoid repetition.
3. View score rankings: Monitor performance metrics.
4. Work per role: Perform specific tasks (Plan, Execute, Review, or Patrol).
5. Submit results: Update task status via the API.
6. Write logs: Record actions taken.
7. Sleep: Wait for the next scheduled wake-up.

OpenMOSS acts as a coordination middleware for multiple AI agents. Instead of agents communicating directly (which is unreliable), they interact asynchronously through the OpenMOSS middleware.

The Workflow:

1. Wake-up: Agents are triggered by a scheduler (e.g., OpenClaw's cron) with a completely fresh context.
2. Status Check: Agents call the OpenMOSS API to check assigned tasks, acceptance criteria, and previous submissions/reviews.
3. Execution: Agents perform role-specific actions.
4. Persistence: Agents write deliverables, logs, and scores back to the OpenMOSS database.
5. Sleep: Agents wait for the next scheduled wake-up.

This mechanism ensures 100% agent uptime because all state is persisted in the database, preventing progress loss if a conversation session terminates.

The Context Router (formerly context-router) manages conversation history in multi-turn dialogues and concurrent tool/model usage. It prevents context overflow and task interference by routing context based on specific identifiers.

Key Abstractions

• thread_id: The session dimension (e.g., user, tenant, or session).
• task_id: The task dimension. Multiple tasks can exist within a single thread.
• caller_id: An identifier for the caller (model, tool, or service), which can be stored in meta.
• mode: The context strategy:
  • stateless: No context is provided.
  • auto: Context is only provided if continuation patterns (e.g., "continue", "that", "this") are detected.
  • always: Context is always provided.
• snapshot: A persisted context snapshot containing a summary and recent_messages.