OpenClaw Setup Guide: From Zero to Running Agents

OpenClaw Setup Guide: From Zero to Running Agents

OpenClaw is an open-source agent orchestration framework. It lets you run multiple specialist AI agents, connect them to chat platforms like Discord, and give them persistent memory through a file-based vault.

It has 247k GitHub stars. The docs are still catching up. This guide is what I wish I'd had when I started: a practical walkthrough from install to running system.

What you'll end up with

By the end of this guide, you'll have:

• OpenClaw installed and running locally
• A vault directory where agents store memory and working files
• One agent connected to Discord
• A heartbeat schedule so the agent checks in autonomously
• The basic wiring for adding more agents later

Prerequisites

• A machine running Linux or macOS
• Node.js 18+ installed
• A Discord account with a server you control
• API keys for at least one LLM provider (I use a mix, but one is enough to start)
• Git

Step 1: Install OpenClaw

npm install -g openclaw

Then verify:

openclaw --version

If that works, move on.

Step 2: Initialize the gateway

OpenClaw runs a local gateway that coordinates agents, chat connections, and scheduled tasks.

openclaw gateway start

This starts the gateway daemon on ws://127.0.0.1:18789 by default. It runs in the background and auto-restarts.

Check status:

openclaw gateway status

If you see "running," you're good.

Step 3: Set up the vault

The vault is where agents store memory, logs, and working files. Set this up before creating agents. If the agent has nowhere to write, it forgets everything between sessions.

Option A: PARA structure (recommended)

PARA (Projects, Areas, Resources, Archive) is a knowledge management system from Tiago Forte's Building a Second Brain. It gives the agent clean categorical boundaries to reason about, which makes routing and filing much more reliable.

vault/
├── 00-inbox/          # Capture zone
├── 01-projects/       # Active efforts with clear outcomes
├── 02-areas/          # Ongoing responsibilities
├── 03-resources/      # Reference material
├── 04-archive/        # Completed work
├── 05-logs/           # Daily notes, agent activity
└── 02-areas/openclaw/agents/
    ├── harbor/
    ├── forge/
    └── quill/

For the full breakdown of how PARA works inside an agent-operated vault, see PARA in a Live AI Vault.

Option B: Obsidian vault (with wiki-style linking)

If you already use Obsidian, or you prefer a flatter layout, that works too. Obsidian is particularly good as an agent's brain because it handles wiki-style linking, double-bracket links like [[project-name]] that let both you and the agent move between notes by concept, not just folder path.

This is inspired by Andrei Karpathy's approach of using a public wiki-style log with lightweight linking. When your agent can follow the same links you do, context retrieval gets stronger. The agent reads the link graph, not just individual files.

A simple Obsidian structure could look like:

vault/
├── inbox/
├── notes/
├── projects/
├── archive/
├── daily/           # Karpathy-style daily logs
└── agents/

The structure matters less than consistency. Pick something you'll actually maintain. You can always restructure later; the agents adapt if you update their config.

For a deeper dive on using Obsidian as an agent knowledge system, see PARA in a Live AI Vault.

Point OpenClaw at your vault root:

vault:
  path: ~/vault

Step 4: Create your first agent

Each agent is a folder with a few config files. The minimum is:

• AGENTS.md: operational instructions
• SOUL.md: identity and personality
• USER.md: context about the person it serves

Create a workspace:

mkdir -p ~/vault/02-areas/openclaw/agents/harbor
cd ~/vault/02-areas/openclaw/agents/harbor

Write a minimal SOUL.md:

# Harbor

## Identity
- Name: Harbor
- Role: Life admin: handles scheduling, reminders, personal logistics

## Operating Principles
- Prefer action over asking for permission
- Keep messages short
- Escalate when uncertain

Write a minimal AGENTS.md:

# Harbor: Agent Workspace

## Session Startup
1. Read SOUL.md
2. Read USER.md
3. Check daily notes for recent context

## What I Can Do Without Asking
- Check calendar and report upcoming events
- Set reminders
- Organize files within ~/vault

## What Always Needs Approval
- Sending external messages
- Making purchases
- Deleting files

Write a minimal USER.md:

# About My Human
- Name: (your name)
- Timezone: (your timezone)
- Prefers direct answers, not lengthy explanations

An agent is just markdown files in a directory. OpenClaw reads them at session start. You can edit any of these files and the agent picks up changes on the next session.

Step 5: Connect to Discord

This is where most people get stuck. The Discord integration requires creating a bot application.

Create a Discord bot

1. Go to the Discord Developer Portal
2. Click "New Application" → give it a name
3. Go to "Bot" → click "Add Bot"
4. Copy the bot token (you'll need it)
5. Enable "Message Content Intent" under Privileged Gateway Intents

Invite the bot to your server

Use this URL format (replace CLIENT_ID with your app's client ID from the General Information page):

https://discord.com/api/oauth2/authorize?client_id=CLIENT_ID&permissions=8&scope=bot

Configure OpenClaw

In your OpenClaw config (usually ~/.openclaw/config.yaml or set via openclaw config), add the Discord provider:

providers:
  discord:
    token: YOUR_BOT_TOKEN_HERE

Then restart the gateway:

openclaw gateway restart

If the bot appears online in your Discord server, the connection is working.

Channel mapping

Create a channel for each agent (e.g. #harbor, #forge, #quill). When a message is sent in that channel, OpenClaw routes it to the matching agent.

You can configure this in the agent's config or let OpenClaw auto-discover channels by name.

Step 6: Enable heartbeat

Heartbeat is how agents check in autonomously. Instead of waiting for a message, the agent gets polled on a schedule and can do useful work proactively.

Create a HEARTBEAT.md in the agent's workspace:

# Harbor Heartbeat

## Checks
- [ ] Any upcoming calendar events in the next 2 hours?
- [ ] Any unread emails that look urgent?
- [ ] Any inbox items older than 24 hours?

## Rules
- Do at most 2 checks per cycle
- If nothing needs attention, reply HEARTBEAT_OK
- Don't send messages between 23:00 and 07:00 unless urgent

Then configure the heartbeat schedule. In OpenClaw config:

heartbeat:
  intervalMinutes: 30

Now every 30 minutes, the agent gets a heartbeat prompt, reads HEARTBEAT.md, and acts on what it finds.

Step 7: Add your second agent

Once the first agent is running, adding more is mostly copy and change.

1. Create a new agent folder (e.g. ~/vault/02-areas/openclaw/agents/quill/)
2. Write SOUL.md, AGENTS.md, USER.md for the new role
3. Create a Discord channel matching the agent name
4. Restart the gateway

Each agent gets its own context, its own memory, and its own channel. No cross-contamination.

Mistakes I made (so you don't have to)

Starting with one monolith agent

I tried to make one agent handle everything. Context got messy fast. Split by domain early. Even two agents is better than one blob.

Not setting up the vault before connecting chat

If the agent has nowhere to write memory, it forgets everything between sessions. Set up the vault structure first.

Over-automating before the structure was stable

I wired up cron jobs, webhooks, and automated pipelines before the basic daily workflow was reliable. The automations broke, and debugging was harder because the foundation wasn't solid.

Get one agent doing useful daily work first. Then add automation.

Skipping HEARTBEAT.md

Without heartbeat, the agent only works when you message it. That's a chatbot. Heartbeat is what makes the agent proactive.

What to do next

Once the basics are running:

• Read PARA in a Live AI Vault if you want to go deeper on vault structure
• Read why specialist agents beat one big chat before adding more roles
• Set up daily notes in 05-logs/daily/ for session continuity
• Connect a second LLM provider so you can route different tasks to different models

The key principle

OpenClaw is a coordination layer between agents, memory, and chat.

The system works because the pieces are simple: markdown files, git, chat channels, scheduled prompts. Each piece does one thing. The combination does something useful.

Start small. Get one agent doing real work. Then expand.

Read next: Building an AI Second Brain With OpenClaw and PARA in a Live AI Vault.