No history yet

OpenClaw Architecture

The OpenClaw Blueprint

To get started with OpenClaw, you first need to understand its basic structure. Everything happens within a dedicated folder called a workspace. Think of this workspace as the agent's office. It contains the agent's brain, its instructions, and all the files it works on.

At the heart of the workspace is the agent runtime. This is the engine that reads your instructions, processes information, and carries out tasks. The runtime isn't something you'll edit directly. Instead, you'll guide it by changing a few key configuration files that live inside the workspace.

This setup keeps things tidy. The engine is separate from the instructions, making it easy to change an agent's behavior without touching the core code. Let's look at the three files that define your agent.

The Three Core Files

Three simple markdown files control nearly everything your agent does. Understanding their roles is the key to using OpenClaw effectively.

SOUL.md: The Identity USER.md: The Context AGENTS.md: The Team

First is SOUL.md. This file gives the agent its core identity, purpose, and personality. It tells the agent what it is and how it should behave. A well-written soul defines the agent's tone, its core directives, and any constraints it must follow. Think of it as the agent's permanent mission statement.

# SOUL.md

You are a helpful assistant for a software development team.
Your primary goal is to triage new bug reports.

## Personality
- You are professional, concise, and direct.
- You never use emojis.

## Constraints
- You must always ask for reproduction steps if they are missing.
- You will not engage in conversations unrelated to software development.

Next, there's USER.md. This file provides the agent with context about you, the user. It can include your name, role, preferences, or any other information that helps the agent tailor its actions to your specific needs. This file is how the agent knows who it's working for.

# USER.md

## My Info
- Name: Alex
- Role: Lead Developer

## Preferences
- Please summarize reports in a single paragraph.
- My working hours are 9 AM to 5 PM Eastern Time.

Finally, AGENTS.md defines other agents that your main agent can interact with. In a single-agent setup, this file might just define the primary agent itself. But as you build more complex systems, this file becomes a directory, allowing one agent to call upon another with a specific skill.

# AGENTS.md

## @triage
- Description: The primary agent for handling bug reports.
- Soul: ./soul.md

## @docs
- Description: An agent specialized in writing documentation.
- Soul: ./docs_soul.md

How They Work Together

The agent runtime brings these three files to life. It reads SOUL.md to understand its purpose, consults USER.md to know its user, and checks AGENTS.md to learn about its peers. By editing these plain text files, you can direct a powerful AI without writing a single line of code.

FilePurpose
SOUL.mdDefines the agent's core identity and directives.
USER.mdProvides context about the user and their preferences.
AGENTS.mdLists available agents and how to interact with them.

With this structure in mind, you're ready to start putting your first agent to work.