How to Use OpenClaw: The Complete Beginner Guide

What Is OpenClaw (And Why Should You Care)

OpenClaw is a CLI-first AI agent framework. Unlike hosted platforms where you drag and drop nodes in a browser, OpenClaw runs directly on your machine. You define agents using simple markdown files, connect them to any LLM (Claude, GPT-4o, Llama, Mistral), and deploy them to messaging platforms like Telegram, Discord, and Slack.

The key difference from other frameworks: OpenClaw agents are configured with a file called SOUL.md. This single markdown file contains your agent's personality, role, instructions, and behavior rules. No Python classes, no YAML configs, no visual node editors. Just a text file that reads like a job description for your AI employee.

OpenClaw is free and open source. The community maintains over 162 agent templates covering roles like SEO analyst, content writer, customer support, DevOps monitor, and more. You can start from a template or build your own from scratch.

Step 1: Install OpenClaw

OpenClaw requires Node.js 18 or later. If you already have Node installed, you can get OpenClaw with a single command. There are three installation methods depending on your preference.

Option A: One-line install script (recommended)

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

This downloads and installs the latest version, adds the openclaw binary to your PATH, and verifies the installation. It works on macOS and Linux.

Option B: Install via npm

npm install -g openclaw

Option C: Install via pnpm

pnpm add -g openclaw

After installation, verify it worked by checking the version:

openclaw --version
# Expected output: openclaw v3.x.x

If you see a version number, you are ready to go. If you get a "command not found" error, make sure your npm global bin directory is in your PATH. Run npm bin -g to find it and add that path to your shell profile.

Step 2: First Run and Initial Setup

The first time you run OpenClaw, it creates a configuration directory at ~/.openclaw/. This is where your agent configurations, sessions, and logs live.

Initialize a new project in any directory:

mkdir my-agents && cd my-agents
openclaw init

This creates the basic folder structure:

my-agents/
  agents/
    assistant/
      SOUL.md        # Your first agent definition
  config.json        # Project-level settings
  skills/            # Shared skill scripts

OpenClaw generates a starter agent called "assistant" with a basic SOUL.md. You can rename it, edit it, or delete it and start fresh. The important thing is that the agents/ directory exists and each subdirectory contains a SOUL.md file.

Step 3: Connect to an LLM Provider

OpenClaw agents need an LLM to think. You can connect to cloud APIs (Claude, OpenAI) or run models locally with Ollama. Here are the three most common setups.

Claude API (Anthropic)

openclaw config set provider anthropic
openclaw config set apiKey sk-ant-your-key-here
openclaw config set model claude-sonnet-4-20250514

Get your API key from console.anthropic.com. Claude is the default recommendation for OpenClaw because of its strong instruction-following and long context window.

OpenAI API

openclaw config set provider openai
openclaw config set apiKey sk-your-openai-key-here
openclaw config set model gpt-4o

Ollama (free local models)

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

# Then configure OpenClaw
openclaw config set provider ollama
openclaw config set model llama3
openclaw config set ollamaHost http://localhost:11434

Ollama runs models entirely on your hardware. No API key, no per-message cost. You need at least 8 GB of RAM for 7B parameter models and 16 GB for 13B models. For the best local experience, use llama3 (8B) or mistral (7B).

Verify your provider connection:

openclaw config get provider
# Expected: anthropic | openai | ollama

Step 4: Create Your First Agent with SOUL.md

Every OpenClaw agent starts with a SOUL.md file. This is where you define who your agent is, what it does, and how it behaves. Think of it as a job description and personality brief combined into one document.

Create a new agent:

mkdir -p agents/writer
touch agents/writer/SOUL.md

Open agents/writer/SOUL.md in your editor and paste the following:

# Writer Agent

## Role
You are a professional content writer. You write clear, concise blog
posts and social media content for tech startups.

## Personality
- Friendly but professional tone
- Short sentences. No filler words.
- Use concrete examples instead of abstract claims

## Rules
1. Always respond in English
2. Never use emojis in blog posts
3. Keep paragraphs under 4 sentences
4. Include a call-to-action at the end of every blog post

## Skills
- Blog post writing (500-2000 words)
- Twitter thread creation
- LinkedIn post drafting
- Email newsletter copywriting

## Context
Company: Acme Corp
Industry: Developer tools
Audience: Software engineers, CTOs, technical founders

That is a complete agent definition. The structure is flexible. You can add any section that makes sense for your use case. The most common sections are Role, Personality, Rules, Skills, and Context. OpenClaw reads the entire file and passes it to the LLM as the system prompt.

Test your agent immediately:

openclaw agent --agent writer --message "Write a 3-tweet thread about shipping fast"

You should see your agent respond within a few seconds, following the personality and rules you defined in SOUL.md.

Step 5: Connect to Messaging Platforms

Running agents from the terminal is useful for testing, but the real power comes when you connect them to messaging platforms. OpenClaw supports Telegram, Discord, and Slack out of the box.

Telegram

Create a bot with @BotFather on Telegram, copy the token, and configure it:

openclaw config set telegram.botToken YOUR_BOT_TOKEN
openclaw config set telegram.allowedChatIds 123456789

# Start the gateway to listen for messages
openclaw gateway start

The allowedChatIds setting restricts which Telegram users can talk to your agent. Get your chat ID by messaging @userinfobot on Telegram.

Discord

openclaw config set discord.botToken YOUR_DISCORD_TOKEN
openclaw config set discord.allowedChannels channel-id-here

openclaw gateway start

Create a Discord bot at discord.com/developers, enable the Message Content intent, and invite it to your server with the bot and applications.commands scopes.

Slack

openclaw config set slack.botToken xoxb-YOUR-SLACK-TOKEN
openclaw config set slack.signingSecret YOUR_SIGNING_SECRET
openclaw config set slack.appToken xapp-YOUR-APP-TOKEN

openclaw gateway start

Slack requires a Socket Mode app. Create one at api.slack.com/apps, enable Socket Mode, and subscribe to the message.im and app_mention events.

The gateway process handles all incoming messages from all connected platforms. It routes each message to the correct agent based on your configuration, gets the response from the LLM, and sends it back to the platform. Keep it running with:

# Run in background
openclaw gateway start --daemon

# Check status
openclaw gateway status

# View logs
openclaw gateway logs

Step 6: Add Skills to Your Agent

Skills give your agent the ability to do things beyond just generating text. A skill is a script (JavaScript or Python) that your agent can call to interact with external services, read files, make API calls, or run calculations.

Create a skill in your agent's directory:

mkdir -p agents/writer/skills
touch agents/writer/skills/word-count.cjs

Write the skill script:

// agents/writer/skills/word-count.cjs
// Skill: Count words in a given text
// Input: { text: string }
// Output: { count: number }

module.exports = async function wordCount({ text }) {
  const count = text.trim().split(/\s+/).length;
  return { count };
};

Then reference it in your SOUL.md by adding a Skills section:

## Available Tools
- word-count: Counts words in a given text. Use this before submitting
  any blog post to verify it meets the minimum word count requirement.

OpenClaw automatically discovers skill files in the agent's skills/ directory. The agent can invoke them during a conversation when it determines a tool call is appropriate. You can also create shared skills in the project-level skills/ directory that all agents can access.

Some popular community skills include web scraping, Google search, file I/O, database queries, email sending, and calendar integration. Check the OpenClaw GitHub repository for a curated list of community-maintained skills.

Essential Commands for Daily Use

Once your agents are set up, here are the commands you will use every day:

# Talk to an agent directly
openclaw agent --agent writer --message "Draft a changelog for v2.1"

# Start the gateway (serves all messaging platforms)
openclaw gateway start

# Run gateway as a background daemon
openclaw gateway start --daemon

# Restart the gateway after config changes
openclaw gateway restart

# Check which agents are registered
openclaw agents list

# View an agent's current configuration
openclaw agent info --agent writer

# Check gateway health and connected platforms
openclaw gateway status

# View recent conversation logs
openclaw gateway logs --tail 50

# Clear agent session history (fresh start)
openclaw agent clear --agent writer

# Update all config values at once
openclaw config set model claude-sonnet-4-20250514

The two most important commands to remember are openclaw agent --agent [NAME] --message "..." for direct interaction and openclaw gateway start for running the messaging bridge. Everything else is configuration and debugging.

Common First-Time Mistakes (And How to Fix Them)

After helping hundreds of users get started with OpenClaw, these are the issues that come up most often:

1. "API key not found" error. You set the key but misspelled the config field. Run openclaw config get apiKey to verify it is stored correctly. The field name is case-sensitive.

2. Agent not responding on Telegram. Three things to check: is the gateway running (openclaw gateway status), is your chat ID in the allowedChatIds list, and did you start the conversation by sending /start to the bot first.

3. Ollama model running but agent returns empty responses. Make sure the ollamaHost config points to the right address. If Ollama runs on the same machine, it should be http://localhost:11434. Also verify the model name matches exactly what Ollama shows when you run ollama list.

4. SOUL.md changes not taking effect. The gateway caches agent definitions. After editing a SOUL.md file, restart the gateway with openclaw gateway restart. For direct CLI messages, changes take effect immediately.

5. "Permission denied" when running skills. Skill scripts need to be executable. Run chmod +x agents/[AGENT]/skills/[SCRIPT].cjs to fix this. On macOS, you may also need to allow the script in System Settings if Gatekeeper blocks it.

6. Gateway crashes after a few hours. This is usually a memory issue from long conversation histories. Clear old sessions with openclaw agent clear --agent [NAME] or set a maximum session length in your config. For production deployments, use the --daemon flag which includes automatic restart on crash.

Next Steps: Multi-Agent Systems and Automation

Once you are comfortable with a single agent, OpenClaw really shines when you start building multi-agent teams. The AGENTS.md file lets you define how agents delegate tasks to each other, share context, and collaborate on complex workflows.

A common setup is a three-agent team: a project manager agent that receives requests and breaks them into tasks, a specialist agent that does the actual work (writing, coding, analysis), and a reviewer agent that checks the output before it is sent back.

my-agents/
  agents/
    orion/          # PM agent - routes tasks
      SOUL.md
    echo/           # Writer agent - creates content
      SOUL.md
    radar/          # SEO agent - reviews and optimizes
      SOUL.md
  AGENTS.md         # Team orchestration rules

Your AGENTS.md might look like this:

# Agent Team Configuration

## Routing
- Content requests go to Echo
- SEO analysis requests go to Radar
- Everything else goes to Orion for triage

## Delegation Rules
- Orion can delegate to Echo and Radar
- Echo can request reviews from Radar
- Radar reports findings back to Orion

For automation, you can trigger agents on a schedule using cron jobs, webhooks, or external scripts. A popular pattern is running a morning report agent that checks analytics, summarizes overnight events, and sends a digest to Telegram at 8 AM every day.

# Example cron job: daily morning report at 8 AM
0 8 * * * openclaw agent --agent radar --message "Generate today's SEO report"

The full multi-agent and automation setup is covered in our dedicated guides. For now, focus on getting your first agent working smoothly, and expand from there.