Getting Started with the OpenClaw Agent Runtime

I have spent way too much time wrestling with AI agents that forget who they are or where they are supposed to work. It is a common headache: you spend hours fine-tuning a persona only for the agent to lose its “soul” because the context management is messy. I want my agent to have a consistent memory and a clear workspace without me having to babysit the configuration every day.

OpenClaw handles this through a dedicated agent runtime. It gives your agent a specific home and a set of instructions that stick.

What You’ll Need

• OpenClaw installed on your system.
• A designated Workspace directory for your agent.
• A basic configuration file (usually ~/.openclaw/openclaw.json).

Quick Start

Setting up your agent runtime takes about five minutes if you follow this path.

1. Initialize your workspace

The agent needs a single directory to live in. This is its only working directory for tools and context. I recommend using the setup command to get your config and files ready:

openclaw setup

This creates ~/.openclaw/openclaw.json and prepares your workspace files.

2. Configure your model

In your config, you need to point to a model using the provider/model format. If you use a provider like OpenRouter, include that prefix.

{
  "agents": {
    "defaults": {
      "model": "openrouter/moonshotai/kimi-k2",
      "workspace": "/your/path/to/workspace"
    }
  }
}

3. Define the Agent’s “Soul”

Inside your workspace, you will find several Markdown files. OpenClaw injects these into the agent context on the first turn of a session.

• SOUL.md: Define the persona, tone, and boundaries.
• AGENTS.md: Write down operating instructions and long-term memory.
• USER.md: Tell the agent who you are and how you like to be addressed.
• IDENTITY.md: Give your agent a name and a vibe.

4. Verify Built-in Tools

Your agent arrives with core tools for reading, editing, and executing code. While TOOLS.md exists in your workspace, it does not create tools. Use it to give the agent guidance on how you want those tools used.

Troubleshooting

The agent says a file is missing If you delete one of the required files like USER.md, OpenClaw does not crash. It injects a “missing file” marker. Running openclaw setup again will restore the default template.

Bootstrap rituals are not running The BOOTSTRAP.md file is for one-time first-run rituals. It only appears in a brand new workspace. Once the ritual is complete, the file is deleted. If you want to prevent this file from ever being created, add this to your config:

{ "agent": { "skipBootstrap": true } }

Large files are getting cut off OpenClaw keeps prompts lean. If your bootstrap files are too large, the runtime trims them and adds a truncation marker. You can still read the full file manually, but the agent only sees the truncated version in its immediate context.

Messages are getting skipped in Steer mode If your queue mode is set to steer, I should warn you that inbound messages can interrupt the agent. If you send a message while the agent is running tools, it skips the remaining tools in that turn to process your new input. You will see an error: “Skipped due to queued user message.”

If you need help with a specific configuration or a weird error, check out the AI Setup Assistant.

What’s Next

• Group Chats — Learn how to bring your agent into multi-user conversations.
• Agent Workspace — Deep dive into the full workspace layout and backup strategies.
• Gateway configuration — Fine-tune your skill gating and sandbox settings.
• Streaming + chunking — Adjust how the agent sends text blocks back to you.