OpenClaw Setup Guide 2026: Install, Configure & Run Your First Agent

What You'll Build

By the end of this guide, you will have a fully working OpenClaw AI agent running on your local machine. The agent will be able to chat with you through the terminal, use external tools like web browsing and file operations, and complete tasks autonomously based on the instructions you define in a SOUL.md file.

You will go from zero to a running agent in seven steps: install OpenClaw, initialize a project, configure a model provider, customize your agent's SOUL.md, start the gateway, and optionally connect channels like Telegram or Slack. Each step includes the exact commands you need to run, what to expect, and how to troubleshoot if something goes wrong.

This OpenClaw setup guide covers the 2026 version of the framework and reflects the latest CLI commands, configuration format, and supported model providers. If you are upgrading from an older version, the core workflow is the same — but some commands and defaults have changed.

System Requirements

Before you install OpenClaw, make sure your machine meets these requirements. OpenClaw is lightweight and runs on most modern computers, but the language model provider you choose will affect your hardware needs.

Check your current Node.js version by running this command in your terminal:

node --version
# Expected output: v22.x.x or higher

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

Step 1: Install OpenClaw

There are two ways to install OpenClaw. You can run it directly with npx (no global install needed) or install it globally with npm. Both methods give you the same CLI — the difference is whether OpenClaw lives in your global path or is fetched on demand.

npx openclaw

npm install -g openclaw

The npx approach downloads and runs OpenClaw without adding it to your global path. This is ideal for trying it out. The global install adds the openclaw command to your system, so you can run it from any directory without the npx prefix.

After installation, verify that OpenClaw is working by checking the version:

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

If you see a version number, OpenClaw is installed correctly. If you get a "command not found" error, make sure Node.js 22 is active and try reinstalling with npm.

Step 2: Initialize Your Project

The init command scaffolds a new OpenClaw project with a default directory structure, a starter SOUL.md file, and configuration files. Run it in the directory where you want to create your project:

npx openclaw init my-first-agent
cd my-first-agent

This creates a directory called my-first-agent with the following structure:

my-first-agent/
├── SOUL.md              # Your agent's identity and rules
├── agents.md            # Multi-agent registry (optional)
├── config/
│   ├── models.yaml      # Model provider settings
│   ├── channels.yaml    # Channel integrations (Telegram, Slack)
│   └── skills.yaml      # Tool/skill configuration
├── knowledge/           # Files your agent can reference
│   └── README.md
└── sessions/            # Agent conversation history
    └── .gitkeep

The most important file is SOUL.md — this is where you define your agent's personality, role, and rules. The config/ directory holds YAML files for model providers, channels, and skills. The knowledge/ directory is where you can place reference documents that your agent can read during conversations.

Step 3: Configure Your Model Provider

Your agent needs a language model to think and respond. OpenClaw supports three categories of model providers: cloud APIs (Anthropic, OpenAI, Google), and local models via Ollama. Choose the provider that fits your needs, then run the corresponding setup command.

openclaw models auth setup-token --provider anthropic
# Paste your Anthropic API key when prompted

openclaw models auth setup-token --provider openai
# Paste your OpenAI API key when prompted

# First, install Ollama from ollama.com and pull a model:
ollama pull llama3

# Then configure OpenClaw to use Ollama:
openclaw models auth setup-token --provider ollama
# No API key needed — press Enter to skip

After authenticating your provider, set the default model your agents will use. This determines which specific model handles your agent's requests:

# Set default model (pick one):
openclaw config set agents.defaults.model.primary claude-sonnet-4-5
openclaw config set agents.defaults.model.primary gpt-4o
openclaw config set agents.defaults.model.primary llama3

You can change the default model at any time, and you can also assign different models to different agents in a multi-agent setup by editing the agents.md file.

Step 4: Customize Your SOUL.md

The openclaw init command generates a default SOUL.md with a basic agent configuration. Open it in your editor and customize it to match the agent you want to build. The SOUL.md file is the heart of your agent — it controls who the agent is, how it behaves, and what it can do.

Here are the key sections you should customize:

Here is a practical example of a customized SOUL.md for a research assistant agent:

# 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)

For more SOUL.md examples and templates, check out our SOUL.md creation guide or use the interactive SOUL.md generator to build one step by step.

Step 5: 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. Run the following command from your project directory:

openclaw gateway start

On first launch, you will see output similar to 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...

>

The gateway is now running. You can type messages directly in the terminal and your agent will respond based on the SOUL.md configuration you created. The agent has access to the tools you defined in the skills section, and it will follow the rules and personality you specified.

To stop the gateway, press Ctrl+C in the terminal. To restart it (useful after changing your SOUL.md or configuration), run:

openclaw gateway restart

Step 6: Add Channels (Optional)

By default, you interact with your agent through the terminal. But OpenClaw supports connecting your agent to external messaging platforms — called channels — so you can chat with your agent from Telegram, Slack, Discord, or any HTTP client. Channels are optional; your agent works perfectly fine with just the terminal interface.

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

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

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

Step 7: Add Skills (Tools)

Skills are the tools your agent can use to interact with the outside world. Without skills, your agent can only generate text. With skills, it can browse the web, search for information, read and write files, execute code, and call external APIs. OpenClaw includes several built-in skills that you can enable with a single command.

After enabling skills, make sure to reference them in your SOUL.md's Tools section. Agents perform best when you explicitly tell them which tool to use and when. Simply enabling a skill is not enough — the agent needs instructions in its SOUL.md to know when to reach for each tool.

# Enable multiple skills at once:
openclaw skills enable browser search files

# List all enabled skills:
openclaw skills list

Troubleshooting

If you run into issues during setup, check these common problems and their solutions. Most issues are related to Node.js versions, API key configuration, or port conflicts.

If you are still stuck, clear the session cache and restart fresh. This resets any corrupted state without affecting your SOUL.md or configuration:

# Clear session cache:
rm -rf ~/.openclaw/agents/*/sessions/sessions.json

# Restart the gateway:
openclaw gateway restart

Next Steps

You now have a working OpenClaw agent running on your machine. From here, there are several directions you can take to expand your setup:

Frequently Asked Questions