Set Up AI Personas in OpenClaw: The Complete Configuration Guide

Prerequisites and Gateway Check

Before configuring any persona, confirm your OpenClaw gateway is running. Open a terminal and check port 18789:

curl http://localhost:18789/status

You should see a JSON response with "status": "ok" and the current OpenClaw version. If the gateway is not responding, restart it with openclaw start and verify Node.js 20+ is installed.²

If you are running OpenClaw for the first time, follow the Beginner Setup Guide first, then return here for persona configuration.

Choose Your Messaging Channel

OpenClaw personas communicate through messaging channels. The two primary options are Telegram and WhatsApp, though Discord is also supported.

Telegram is the recommended starting channel because it supports bot tokens, has no rate limits on messages, and allows multiple bot accounts. Create a bot through @BotFather and save the token for your AGENTS.md configuration.

WhatsApp works well for client-facing agents but requires a dedicated phone number. Use a secondary number rather than your personal one to avoid conflicts with your existing WhatsApp account.⁵

Configure SOUL.md

SOUL.md is the identity file that defines who your persona is. It controls personality, tone, expertise domains, response style, and behavioral guardrails. Every workspace needs one.⁴

A production SOUL.md should be between 30 and 80 lines. Shorter files lack enough context for consistent behavior. Longer files waste tokens on every message and can confuse the model.⁸

Here is a minimal SOUL.md template:

# Identity
You are Atlas, an AI chief of staff for a startup founder.

# Personality
- Direct and concise — no filler language
- Proactive: surface problems before they are asked about
- Professional but not formal

# Expertise
- Calendar management and scheduling
- Email triage and prioritization
- Task tracking and delegation

# Boundaries
- Never send emails without explicit approval
- Never share confidential information outside approved channels
- Always confirm before modifying calendar events

"A vague SOUL.md is worse than no SOUL.md at all." — Sawyer Ruhl, ComputerTech⁶

The most common mistake is writing vague identity lines like "You are a helpful assistant." Instead, specify the role, the audience, and the domain. Pre-built personas from the Remote OpenClaw marketplace come with production-tested SOUL.md files that have been refined across hundreds of deployments.¹

Set Up AGENTS.md

AGENTS.md defines the technical configuration for each agent instance: which LLM model to use, which channel to connect to, which skills to enable, and which API keys to reference.⁶

# Agent: Atlas
model: anthropic/claude-sonnet-4-20250514
channel: telegram
bot_token: ${TELEGRAM_BOT_TOKEN}
skills:
  - calendar-sync
  - email-triage
  - task-tracker
memory: persistent
approval_required: true

You can define multiple agents in a single AGENTS.md file. Each agent block starts with # Agent: Name and contains its own model, channel, and skill configuration.

For the LLM model, you have several options: Anthropic Claude for best reasoning quality, OpenAI GPT-4 for broad tool support, DeepSeek for cost-effective operation, or any model available through OpenRouter.

"Configuration mistakes are the #1 reason people get stuck." — Kevin Jeppesen, The Operator Vault⁷

Configure HEARTBEAT.md

HEARTBEAT.md defines scheduled background tasks that run automatically. The default cycle is every 30 minutes, though you can adjust the interval for specific tasks.⁹

# Heartbeat Configuration
interval: 30m

## Tasks
- Check Gmail for unread messages tagged "urgent"
- Scan Google Calendar for meetings in the next 2 hours
- Update task board with any overdue items
- Send daily briefing at 8:00 AM local time

Each heartbeat cycle should consume fewer than 1,000 tokens. If your heartbeat regularly exceeds that, split it into multiple focused tasks or increase the interval. Check the status with:

curl http://localhost:18789/heartbeat/status

A healthy response shows "status": "HEARTBEAT_OK" with the last run timestamp and token count.¹⁰

Set API Keys

OpenClaw needs API keys for the LLM provider and any integrated services. Store them in your environment file, never in workspace files:

# .env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
TELEGRAM_BOT_TOKEN=123456:ABC...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

For cost monitoring, set a spending cap in your LLM provider dashboard. A single persona with 30-minute heartbeats typically costs $15-30 per month in API usage.

Test Your Agents

Before connecting an agent to a production channel, test it in isolation. Send a direct message on Telegram or WhatsApp and verify:

• The agent responds in character (matching SOUL.md personality)
• Skills trigger correctly when invoked
• Boundaries are respected (the agent refuses out-of-scope requests)
• Memory persists across messages
• Heartbeat tasks execute on schedule

"Test each agent in isolation before binding it to a live channel." — OpenClawVPS³

Common issues during testing include: the agent ignoring SOUL.md boundaries (usually caused by a SOUL.md that is too short), heartbeats not firing (check cron permissions), and skills returning errors (verify API keys are set in .env).

Browse the ClawHub skill library for pre-built integrations that have already been tested across thousands of deployments.

Cost Optimization

Persona API costs can be reduced by 50-70% with proper configuration.¹¹ The biggest cost drivers are:

• SOUL.md length: Every message includes the full SOUL.md in context. Keep it under 80 lines.
• Heartbeat frequency: 30-minute cycles are sufficient for most use cases. Avoid 5-minute intervals unless the task demands it.
• Model selection: Use DeepSeek or OpenRouter budget models for simple tasks, and reserve Claude or GPT-4 for complex reasoning.
• Memory pruning: Configure memory retention windows to avoid accumulating stale context.

For a deeper dive, read the OpenClaw API Cost Optimization Guide.

Managed Hosting Options

If you prefer to skip manual configuration, several managed hosting providers offer pre-configured OpenClaw deployments starting at $19/month.³ These include server provisioning, automatic updates, and pre-installed skills.

Remote OpenClaw publishes 200+ free guides and offers production-tested AI personas in the marketplace that include complete SOUL.md, AGENTS.md, and HEARTBEAT.md configurations. Each persona has been refined over hundreds of deployments and ships with a setup checklist.

Compare hosting options in the Managed OpenClaw Services Compared guide, or join the Skool community to ask questions before choosing.