Set Up AI Personas in OpenClaw: Step-by-Step Guide

OpenClaw AI personas are defined entirely through Markdown configuration files. Each persona is built from four files: SOUL.md (identity and tone), AGENTS.md (operational instructions), USER.md (your personal context), and HEARTBEAT.md (scheduled automations). This guide walks through installation, file configuration, and testing for each of the four core personas.

Part of The Complete Guide to OpenClaw — the full reference covering setup, security, memory, and operations.

What You Need Before Starting

OpenClaw persona setup requires three things: a compatible Node.js version, an LLM API key, and a messaging platform for delivery. As of April 2026, the minimum Node.js version is v22.16 or higher.

You will need an API key from at least one LLM provider. Anthropic, OpenAI, and OpenRouter are all supported. The exception is Compass, which handles local-only tasks and does not require an API key for basic operation.

For message delivery, OpenClaw supports Telegram, Discord, and WhatsApp. Pick one to start with. You can add more channels later without reconfiguring personas.

Installing and Configuring OpenClaw

OpenClaw installs with a single command that handles dependencies, directory structure, and initial configuration. Run the following in your terminal:

curl -fsSL https://openclaw.ai/install.sh | bash

The installer launches an onboarding wizard that walks through three steps: selecting your LLM provider, entering your API key, and choosing a messaging channel. If you prefer to skip the wizard, you can set values manually:

# Set your LLM provider and API key
openclaw config set llm.provider anthropic
openclaw config set llm.api_key sk-ant-your-key-here

# Set your messaging channel
openclaw config set channel.primary telegram

After configuration, verify everything is connected:

openclaw doctor

The openclaw doctor command checks Node.js version, API key validity, channel connectivity, and file structure. Fix any errors it reports before proceeding to persona setup. A clean doctor output means your gateway is healthy and ready for persona files.

How to Set Up Each Persona

Each OpenClaw persona is a directory containing its Markdown configuration files. The persona's behavior is entirely determined by what you write in these files. Below is a brief setup overview for each of the four core personas.

Atlas — Chief of Staff

Atlas handles business operations: scheduling, task management, communications, and decision support. Its SOUL.md should define a direct, professional tone with clear boundaries around what it can and cannot decide autonomously. In AGENTS.md, specify which tools Atlas can access (calendar, email, task manager) and set explicit rules for when it should escalate to you instead of acting independently.

Key boundary to set: define in AGENTS.md which actions require your approval (sending external emails, scheduling meetings with clients) versus which Atlas can handle silently (organizing internal notes, summarizing threads).

Scout — Sales Assistant

Scout focuses on sales pipeline management: lead research, outreach drafting, CRM updates, and follow-up tracking. Its identity file (IDENTITY.md in some configurations, SOUL.md in standard setup) should reflect your brand voice for external communications. Configure AGENTS.md with your sales process steps, qualification criteria, and CRM integration rules.

Scout works best when AGENTS.md includes specific templates for outreach messages and clear rules about lead scoring thresholds.

Muse — Content Creator

Muse generates content: blog drafts, social media posts, email newsletters, and marketing copy. The most important part of Muse's SOUL.md is the voice style section. Define your writing tone, preferred sentence length, vocabulary to use and avoid, and any brand guidelines. AGENTS.md should specify content formats, approval workflows, and publishing rules.

Without a well-defined voice style in SOUL.md, Muse defaults to generic AI writing. Spend extra time on this file.

Compass — Personal Assistant

Compass handles personal tasks: reminders, habit tracking, daily briefings, and personal knowledge management. Compass is the simplest persona to set up because it does not require an LLM API key for basic local operations like reminders and scheduling. For more advanced tasks (summarization, research), you will need an API key.

Compass is a good starting point if you want to test OpenClaw's persona system before committing to an API key subscription.

Testing and Activating Personas

After writing your persona files, test each one before enabling automations. OpenClaw provides several commands for validation and interactive testing.

First, check that your gateway recognizes the persona and all files are valid:

openclaw gateway status

Next, send a test prompt directly to the persona without going through a messaging channel:

openclaw agent prompt "Summarize my tasks for today"

For a more interactive test, open the OpenClaw dashboard:

openclaw dashboard

The dashboard lets you send messages, view responses, inspect token usage, and check heartbeat status in real time. Once you are satisfied with the persona's responses, enable heartbeats:

# Enable scheduled heartbeats for a persona
openclaw heartbeat enable atlas

Monitor token consumption through the dashboard or via openclaw usage. Heartbeats run on a fixed interval, so misconfigured or verbose HEARTBEAT.md files can accumulate costs quickly.

Pre-Configured vs DIY

Building personas from scratch gives you full control but requires 10-15 minutes per persona and familiarity with OpenClaw's file conventions. Remote OpenClaw's pre-configured personas ship as ready-to-deploy packages with optimized SOUL.md, AGENTS.md, USER.md templates, and HEARTBEAT.md files already tuned for common use cases.

The pre-built versions save setup time and include tested configurations. The DIY route is better if you have specific requirements that differ from standard use cases or want to learn how the persona system works from the ground up.

Related Guides

• How to Set Up OpenClaw AI Agent — beginner setup walkthrough
• OpenClaw Install Guide — installation paths and common mistakes
• OpenClaw Memory Configuration Guide — persistent memory setup
• Atlas AI Chief of Staff for OpenClaw — deep dive on the Atlas persona

Frequently Asked Questions

Which OpenClaw persona should I start with?

Start with Atlas if you need a business operations assistant that handles scheduling, task management, and communications. Choose Compass if you want a personal assistant that works without an API key for basic local tasks.

What should I put in SOUL.md vs AGENTS.md?

SOUL.md defines who the persona is: its identity, tone, values, and communication style. AGENTS.md defines how it operates: task rules, tool permissions, workflow instructions, and behavioral boundaries. Think of SOUL.md as personality and AGENTS.md as the job description.

How can I reduce token usage from heartbeats?

Keep your HEARTBEAT.md file under 200 words. Use cron jobs for complex or detailed recurring tasks instead of heartbeat prompts. Adjust the heartbeat interval in your OpenClaw config to run less frequently, and monitor token consumption via the openclaw dashboard.