The Operator Vault Setup Guide

OpenClaw Setup Guide:
Configuration Walkthrough

Configure once, automate forever.

You've installed OpenClaw. Now let's configure it properly. We've made every mistake so you don't have to. Here are our recommendations for every workspace file, channel connection, and security setting.

Not installed yet? Start with the installation guide.

>_Start the $19 Workshop

Know what goes where

Workspace file map.

In our experience, the biggest source of confusion is mixing up two directories. The config directory stores credentials and settings. The workspace stores your agent's memory and instructions. We recommend keeping them strictly separate.

~/.openclaw/
~/.openclaw/
Config, credentials, sessions (not workspace)
openclaw.json
Gateway configuration (JSON5)
credentials/
OAuth tokens, API keys
agents/
Per-agent session data
main/sessions/
JSONL transcripts
skills/
Managed/installed skills
~/.openclaw/workspace/
Your agent's "brain" (the workspace)
AGENTS.md
Operating instructions, memory rules
SOUL.md
Persona, tone, boundaries
USER.md
Who you are, how to address you
IDENTITY.md
Agent name, vibe, emoji
TOOLS.md
Notes about local tools and conventions
HEARTBEAT.md
Periodic task checklist (optional)
BOOTSTRAP.md
One-time first-run ritual (auto-deleted)
MEMORY.md
Curated long-term memory (optional)
memory/
Daily logs (YYYY-MM-DD.md)
skills/
Workspace-specific skills

The workspace core

The 5 files that matter most.

These files are injected into every agent session. Based on our testing, getting these five right is the difference between a helpful assistant and one that forgets everything by tomorrow.

AGENTS.md

Operating instructions

This is the rulebook. It tells the agent how to behave, how to use memory, when to speak in groups, and what safety boundaries to respect. Loaded at the start of every session.

AGENTS.md
## Every Session
Before doing anything else:
1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md (today + yesterday)
4. If in MAIN SESSION: Also read MEMORY.md

Don't ask permission. Just do it.

Common mistake: Putting credentials or API keys here. This file is injected into the model context. Keep secrets in ~/.openclaw/.env instead.

SOUL.md

Personality and boundaries

Defines who the agent is. Its tone, communication style, and hard limits. Think of it as a character sheet. The agent reads this every session to maintain consistent personality.

SOUL.md
# Soul
I'm a pragmatic assistant. Direct but not rude.
I prefer concise answers. I ask before taking
destructive actions. I never share personal data
in group chats.

Common mistake: Making it too long. SOUL.md is injected into every session. Keep it under 500 words to avoid burning tokens on personality text.

USER.md

Context about you

Tells the agent who you are, how to address you, what timezone you are in, and any preferences. This keeps the agent from asking basic questions every session.

USER.md
# User
Name: Kevin
Timezone: America/Denver
Prefers: Direct answers, no fluff
Address me as: Kevin (never "user")

Common mistake: Forgetting to set your timezone. Without it, the agent cannot schedule reminders or interpret time references correctly.

IDENTITY.md

Agent name and vibe

Created during the bootstrap ritual. Contains the agent's chosen name, emoji identity, and personality vibe. Updated during the first-run Q&A.

IDENTITY.md
# Identity
Name: Claw
Emoji: 🦞
Vibe: Helpful and slightly nerdy

Common mistake: Manually editing this before the bootstrap runs. Let the agent fill it in during first boot. Edit it afterward if you want changes.

HEARTBEAT.md

Periodic task checklist

When heartbeats are enabled, the agent reads this file every 30 minutes (configurable). Add a short checklist of things to monitor. Leave it empty or with only comments to skip heartbeat API calls and save tokens.

HEARTBEAT.md
# Heartbeat Tasks
# Keep this short to limit token burn.
- Check for urgent emails
- Check calendar for events in next 2 hours
- If nothing needs attention: HEARTBEAT_OK

Common mistake: Making it too verbose. Every heartbeat costs an API call. A 10-line checklist is fine. A 200-line manifesto will burn your budget.

Configuration mistakes are the #1 reason people get stuck. The workshop walks you through every file in the workspace, with real examples and explanations for each setting. Start the $19 workshop

Connect a channel

First channel setup.

Channels let you message your agent from Telegram, WhatsApp, or Discord instead of the browser. We recommend starting with Telegram (it takes about two minutes), then adding others once you are comfortable.

  1. Message @BotFather on Telegram and create a new bot
  2. Copy the bot token BotFather gives you
  3. Run the command below to add the channel
  4. Message your bot to verify it responds
$ openclaw channels add --channel telegram --token "YOUR_BOT_TOKEN"

Telegram is the easiest channel to set up. No phone number required, no QR scanning. Just a bot token.

Setting up channels can take a full afternoon if you're starting from scratch. The $19 workshop covers WhatsApp, Telegram, and Discord setup in under 15 minutes. Learn more

Do not skip this

The security checklist.

You are giving an AI agent access to run commands on your machine. We treat these six items as non-negotiable. Complete them before exposing your agent to any channel. In our experience, skipping even one of these leads to problems down the road.

Set allowFrom on WhatsAppCritical

Never run WhatsApp open-to-the-world. Restrict to your phone number. Without this, anyone who messages the assistant number gets full agent access.

Use a gateway auth tokenCritical

If you bind the Gateway to a non-loopback address (for VPS or remote access), set OPENCLAW_GATEWAY_TOKEN. Without it, any local process can connect to your agent.

Disable heartbeats until you trust the setupCritical

Heartbeats run the agent autonomously every 30 minutes. Set agents.defaults.heartbeat.every to "0m" in config until you are confident in your agent instructions and safety rules.

Enable sandboxing for non-main sessions

Agent sandboxing runs tool execution inside Docker containers, isolating file and shell access. Set agents.defaults.sandbox.mode to "non-main" so group chats and subagent sessions cannot reach your host filesystem.

Use a dedicated WhatsApp number

If you link your personal WhatsApp, every message to you becomes agent input. Use a separate number dedicated to the assistant.

Review tool policy

By default, the agent can read, write, edit files, and run shell commands. Use tools.sandbox.tools.deny to block tools you do not want exposed (browser, cron, discord, gateway).

Background automation

The heartbeat system.

What it does

Every 30 minutes (default), the Gateway sends the agent a "heartbeat" message. The agent reads HEARTBEAT.md and executes the checklist. Check emails, review calendar events, monitor feeds. If nothing needs attention, it replies HEARTBEAT_OK silently.

Why disable it first

Each heartbeat costs one API call. Until you trust your agent's instructions and tool access, heartbeats can surprise you with unexpected actions. Disable with agents.defaults.heartbeat.every set to "0m" in config.

When to enable it

Once your AGENTS.md, SOUL.md, and security settings are dialed in. Start with a simple checklist (check email, check calendar). Expand as you build confidence.

Example HEARTBEAT.md

HEARTBEAT.md
# Heartbeat Tasks
# Keep this short to limit token burn.

- Check for urgent unread emails
- Check calendar for events in next 2 hours
- If nothing needs attention: HEARTBEAT_OK

How your agent remembers

The memory system.

OpenClaw memory is plain Markdown files in your workspace. No proprietary database, no cloud sync. Just files on disk that you control, back up, and edit. We recommend this approach because it gives you full visibility into what your agent remembers.

Daily logs

memory/YYYY-MM-DD.md

The agent creates one file per day. Append-only log of decisions, context, and important events. On session start, the agent reads today and yesterday automatically.

Long-term memory

MEMORY.md (optional)

Curated facts, preferences, and decisions that matter across weeks and months. Only loaded in the main session (direct chats). Never shared in group contexts for security.

Auto-compaction protection: When a session nears the model's context limit, OpenClaw automatically triggers a silent memory flush before compacting. The agent writes durable notes to disk so critical context survives the compression. This happens behind the scenes with no user intervention required.

Practical paranoia

Back up your brain.

Your workspace is your agent's memory. We strongly recommend putting it in a private git repo. We have seen people lose weeks of agent tuning to an accidental rm command. A simple git init prevents that entirely.

terminal
# Initialize the workspace as a git repo
$ cd ~/.openclaw/workspace
$ git init
$ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
$ git commit -m "Add agent workspace"

# Add a private remote (GitHub CLI)
$ gh repo create openclaw-workspace --private --source . --remote origin --push

# Ongoing updates
$ git add . && git commit -m "Update memory" && git push

Keep the repo private. Your workspace contains personal context, preferences, and memory. Never commit API keys, OAuth tokens, or anything from ~/.openclaw/ (config directory). Add a .gitignore with: .env, *.key, *.pem, **/secrets*

Save yourself the frustration

Common configuration mistakes.

We see these come up constantly. Each one is easy to fix once you know what to look for, and frustrating if you do not.

Mistake

API key not working after adding to openclaw.json

API keys in the config file must be quoted strings. Use: openclaw config set models.providers.anthropic.apiKey '"sk-ant-..."' --json. Or set the ANTHROPIC_API_KEY environment variable instead (recommended).

Mistake

Port 18789 already in use

Another Gateway instance is running. Check with "openclaw gateway status" or "lsof -i :18789". Stop the existing one with "openclaw gateway stop" before starting a new one.

Mistake

Forgetting to save .env after editing

If you use ~/.openclaw/.env for secrets, the Gateway reads it on startup. After editing, restart: openclaw gateway restart. Changes do not apply until restart.

Mistake

Docker sandbox permission denied on workspace files

Sandbox containers run as uid 1000 by default. If your workspace files are owned by a different user, set agents.defaults.sandbox.docker.user to match, or chown the workspace: "sudo chown -R 1000:1000 ~/.openclaw/workspace".

Mistake

WhatsApp QR code expires before scanning

Run "openclaw channels login" and scan within 60 seconds. If it expires, run the command again for a fresh QR. Make sure you are scanning from the assistant phone, not your personal one.

Mistake

Agent replies in all group chats without being mentioned

By default, the agent replies when mentioned in groups. If it is replying to everything, check your group settings. Set channels.whatsapp.groups.requireMention to true in config.

Kevin Jeppesen, Founder of The Operator Vault

Written by

Kevin Jeppesen

Founder, The Operator Vault

Kevin is an early OpenClaw adopter who has saved an estimated 400 to 500 hours through AI automation. He stress-tests new workflows daily, sharing what actually works through step-by-step guides and a security-conscious approach to operating AI with real tools.

Setup FAQ

Questions about configuration.

Get the walkthrough.
Skip the trial and error.

The $19 workshop covers install, security basics, your first run, first workflow, and connecting channels. Real commands, real results.

>_Start the $19 WorkshopDone-For-You Setup