OpenClaw Setup Guide: From Install to First Agent in 5 Minutes

What is OpenClaw?

OpenClaw is an open source AI agent framework that lets you build, configure, and deploy autonomous AI agents on your own machine. You define an agent's identity, personality, and rules in a simple markdown file called SOUL.md. The agent then runs locally, connects to language models like Claude, GPT-4o, or Ollama, and can interact with you through the terminal, Telegram, Slack, Discord, or a REST API.

OpenClaw was formerly known as Clawdbot and Moltbot. The project was renamed and open-sourced in late 2025. If you used either of those earlier versions, the core concepts are the same, but the CLI commands and configuration format have been updated. This guide covers the current 2026 version.

What makes OpenClaw different from other agent frameworks is its simplicity. There is no Python environment to manage, no complex YAML pipelines to write, and no web dashboard required. Everything runs from the terminal with a handful of commands. Your agent's entire configuration lives in a single SOUL.md file that you can version control, share, and deploy anywhere.

Prerequisites

Before you start, make sure you have these two things ready:

# Check your Node.js version
node --version
# Expected: v22.x.x or higher

# If you need to install or upgrade:
nvm install 22
nvm use 22

Step 1: Install OpenClaw

You can install OpenClaw two ways. The npx approach downloads and runs it on demand without a global install. The npm approach adds the openclaw command permanently to your system path. Both give you the same CLI.

npx openclaw

npm install -g openclaw

curl -fsSL https://get.openclaw.dev | sh

After installation, verify it works:

openclaw --version
# Output: openclaw v2.x.x

If you see a version number, you are good to go. If you get a "command not found" error, make sure Node.js 22 is active and try the npm install again.

Step 2: Run Onboarding

OpenClaw includes an interactive onboarding wizard that walks you through the initial setup. It creates your project directory, configures your model provider, and scaffolds a starter agent. Run it from the directory where you want your project:

openclaw onboard

The onboarding wizard will ask you to:

After onboarding completes, you will have a project structure like this:

my-agent-project/
├── SOUL.md              # Your agent's identity and rules
├── agents.md            # Multi-agent registry (optional)
├── config/
│   ├── models.yaml      # Model provider settings
│   ├── channels.yaml    # Channel integrations
│   └── skills.yaml      # Tool/skill configuration
├── knowledge/           # Reference docs for your agent
│   └── README.md
└── sessions/            # Conversation history
    └── .gitkeep

Step 3: Configure Your First Agent - Create SOUL.md

The SOUL.md file is the heart of your agent. It defines who the agent is, how it communicates, what rules it follows, and which tools it can use. The onboarding wizard creates a basic one for you, but you should customize it for your specific use case.

Open the SOUL.md file in your editor and structure it with these key sections:

Here is a complete example of a SOUL.md for a research assistant:

# ResearchAssistant

## Role
You are a research specialist. You gather
information from the web, summarize findings,
and produce structured research briefs with
sources cited.

## Personality
- Tone: Neutral, academic
- Style: Structured, evidence-based
- Always cite sources with URLs
- Present both sides of any argument

## Rules
- ALWAYS respond in English
- ALWAYS include source URLs
- Target 500-1,000 words per research brief
- NEVER fabricate data or statistics
- Include a confidence score (High/Medium/Low)
  for each finding

## Tools - USE THEM
- Use Browser to read web pages and articles
- Use Search to find relevant sources
- Use Files to save research briefs locally

## Output Format
- Title
- Executive Summary (3-5 sentences)
- Key Findings (bulleted)
- Detailed Analysis (H2 sections)
- Sources (numbered list with URLs)

After editing your SOUL.md, register the agent with OpenClaw:

# Register the agent (from your project directory)
openclaw agents add my-agent --workspace . --non-interactive

# Verify it was registered
openclaw agents list

Step 4: Start the Gateway

The gateway is OpenClaw's runtime engine. It loads your SOUL.md, connects to your model provider, and starts listening for messages on port 18789. Start it from your project directory:

openclaw gateway start

You should see output like this:

[OpenClaw] Loading SOUL.md...
[OpenClaw] Agent: ResearchAssistant
[OpenClaw] Model: claude-sonnet-4-5 (Anthropic)
[OpenClaw] Skills: browser, search, files
[OpenClaw] Gateway running on port 18789
[OpenClaw] Type a message to start chatting...

>

Your agent is now live. Type a message directly in the terminal and it will respond based on your SOUL.md configuration. The gateway also exposes a web interface at http://localhost:18789 and a REST API for programmatic access.

To stop the gateway, press Ctrl+C. To restart it after making changes to your SOUL.md or configuration:

openclaw gateway restart

Step 5: Connect to Telegram, Slack, or Discord

By default, you interact with your agent through the terminal. OpenClaw also supports connecting your agent to messaging platforms so you can chat from your phone or workspace. Channels are optional. Your agent works perfectly fine with just the terminal.

openclaw config set channels.telegram.bottoken YOUR_BOT_TOKEN
openclaw gateway restart

openclaw config set channels.slack.bottoken xoxb-YOUR-BOT-TOKEN
openclaw config set channels.slack.apptoken xapp-YOUR-APP-TOKEN
openclaw gateway restart

openclaw config set channels.discord.bottoken YOUR_DISCORD_BOT_TOKEN
openclaw gateway restart

You can also interact with your agent through the REST API, which is useful for integrating with custom applications:

curl -X POST http://localhost:18789/api/message \
  -H "Content-Type: application/json" \
  -d '{"message": "Research the latest AI trends"}'

Step 6: Test Your Agent

With the gateway running, you can test your agent in three ways. Pick whichever is most convenient for your workflow.

openclaw agent --agent my-agent --message "What can you help me with?"

When testing, pay attention to how well the agent follows your SOUL.md rules. If the responses are off, edit the SOUL.md, then restart the gateway with openclaw gateway restart. The gateway does not hot-reload configuration changes, so a restart is required after every SOUL.md edit.

Common Setup Issues and Fixes

Most OpenClaw setup issues fall into three categories: Node.js version problems, API key errors, and port conflicts. Here are the most common issues and how to fix them.

If none of these fix your issue, try a full reset. This clears all session data and restarts the gateway cleanly:

# Clear all session data
rm -rf ~/.openclaw/agents/*/sessions/sessions.json

# Restart the gateway
openclaw gateway restart

Quick Reference: All 6 Steps

Here is the complete setup flow in one code block. Copy and run these commands in order:

# Step 1: Install OpenClaw
npm install -g openclaw

# Step 2: Run onboarding
openclaw onboard

# Step 3: Edit your SOUL.md
# (open SOUL.md in your editor and customize)

# Step 4: Start the gateway
openclaw gateway start

# Step 5: Connect a channel (optional)
openclaw config set channels.telegram.bottoken YOUR_TOKEN
openclaw gateway restart

# Step 6: Test your agent
openclaw agent --agent my-agent --message "Hello, what can you do?"

Frequently Asked Questions