Getting Started with OpenClaw: A Beginner's Guide (Free)

#Your First AI Agent in 30 Minutes

Setting up OpenClaw for the first time can feel intimidating if you have never worked with self-hosted software before. This guide strips away the complexity and walks you through the essentials — from installation to your first real conversation with your AI agent.

By the end of this guide, you will have a working OpenClaw agent running on your machine, connected to an LLM provider, and reachable through at least one messaging channel.

#Prerequisites

Before you begin, make sure you have:

• A computer that can stay on. This can be a Mac Mini, a Linux server, an old laptop, a Raspberry Pi 4/5, or even a Windows machine running WSL2. OpenClaw needs to run continuously to function as an always-on agent.
• Node.js 20 or later. OpenClaw is built on Node.js. You can check your version by running node --version in your terminal.
• An API key from at least one LLM provider. You will need a key from Anthropic (Claude), OpenAI (GPT), or Google (Gemini). If you do not have one yet, we cover this below.
• Basic comfort with the terminal. You will need to run a few commands, but nothing complex.

#Step 1: Install Node.js

If you do not already have Node.js installed, the easiest method is to use a version manager. This lets you install and switch between Node.js versions without system-level conflicts.

#macOS and Linux

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
# Restart your terminal, then install Node.js 20
nvm install 20
nvm use 20
# Verify the installation
node --version

#Windows

On Windows, the recommended approach is to use WSL2 (Windows Subsystem for Linux) and then follow the Linux instructions above. OpenClaw runs best in a Linux environment.

# Install WSL2 from PowerShell (admin)
wsl --install
# After reboot, open your Linux distribution and install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

#Step 2: Install OpenClaw

With Node.js in place, installing OpenClaw is a single command:

# Install OpenClaw globally
npm install -g openclaw
# Verify the installation
openclaw --version

You should see the version number printed to your terminal. If you get a permissions error on macOS or Linux, prefix the install command with sudo or configure npm to use a different global directory.

#Step 3: Initialize Your Agent

Now create your first agent configuration. OpenClaw provides an interactive setup wizard that walks you through the basics:

# Guided setup: inference first, then the rest of the config
openclaw onboard

The wizard will ask you several questions:

1. Agent name: Give your agent a name. This is how it identifies itself in conversations.
2. LLM provider: Choose your primary provider (Anthropic, OpenAI, or Google).
3. API key: Paste your API key when prompted.
4. Model: Select the specific model to use (the wizard suggests sensible defaults).
5. Messaging channel: Choose at least one channel to connect (Telegram is the easiest for beginners).

After completing the wizard, OpenClaw generates a configuration directory with the following structure:

~/.openclaw/
  openclaw.json        # Main configuration file, in JSON5
  workspace/           # Agent workspace
    SOUL.md            # Agent personality and instructions
    memory/            # Persistent memory storage
  skills/              # Installed skills
  logs/                # Agent logs

#Step 4: Get Your API Key

If you skipped the API key step in the wizard, or if you need to set one up from scratch, here is the quick version for each provider.

#Anthropic (Claude) — Recommended

Anthropic's Claude models are the most popular choice in the OpenClaw community, thanks to their strong instruction-following and nuanced responses.

1. Go to console.anthropic.com and create an account
2. Add a payment method under Settings > Billing
3. Set a spending limit under Settings > Limits (start with $20-50)
4. Generate an API key under Settings > API Keys
5. Copy the key and add it to your OpenClaw config

#OpenAI (GPT)

1. Go to platform.openai.com and create an account
2. Add billing information under Settings > Billing
3. Generate an API key under API Keys
4. Copy the key and add it to your config

#Google (Gemini)

1. Go to aistudio.google.com and sign in
2. Click Get API Key to generate a key
3. Copy the key and add it to your config

Once you have your key, keep it out of the config file. OpenClaw reads env vars from the parent process plus a .env in the current working directory and ~/.openclaw/.env as a global fallback, and neither file overrides an existing variable. For a single personal machine, the global file is the simplest home for the key:

# ~/.openclaw/.env
ANTHROPIC_API_KEY=sk-ant-your-key-here

The config file then only names the model. OpenClaw reads an optional JSON5 config from ~/.openclaw/openclaw.json, and JSON5 allows comments and trailing commas. A model ref of the form provider/model picks the provider and the model together:

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-5" },
    },
  },
}

#Step 5: Connect a Messaging Channel

Your agent needs at least one messaging channel to communicate through. Telegram is the easiest option for beginners because setup is straightforward and the mobile app is excellent.

#Quick Telegram Setup

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to create a bot
3. BotFather will give you a bot token — copy it
4. Add the token to ~/.openclaw/openclaw.json, or run openclaw channels add --channel telegram --token <bot-token> and let the CLI write it for you:

// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "allowlist",
      allowFrom: ["<YOUR_TELEGRAM_USER_ID>"],
    },
  },
}

#Step 6: Customize Your Agent's Personality

One of OpenClaw's most powerful features is the SOUL.md file. This Markdown document defines your agent's personality, communication style, knowledge areas, and behavioral guidelines. The default SOUL.md is functional, but customizing it transforms your agent from generic to genuinely useful.

Here is a minimal example:

# Soul
You are Atlas, a personal AI assistant.
## Personality
- Direct and concise — no filler or unnecessary pleasantries
- Proactive — suggest next steps and flag potential issues
- Technical — comfortable with code, systems, and complex topics
## Rules
- Always confirm before executing destructive actions
- Keep responses under 200 words unless asked for detail
- Use bullet points for lists of 3 or more items

The LLM reads this file as part of its system prompt for every interaction, so your agent consistently behaves according to your specifications.

#Step 7: Start Your Agent

Everything is configured. Time to bring your agent to life. Run the Gateway in the foreground for this first start, which is the pair of commands the run page gives:

openclaw gateway
openclaw gateway run   # equivalent, explicit form

Save openclaw gateway start for after the next section: that one drives the managed service, and "If no managed service is installed, gateway start prints install hints and exits nonzero."

You should see log output indicating that the Gateway engine has started, your LLM provider is connected, and your messaging channel is active. Open Telegram (or whichever channel you configured) and send your agent a message.

Try something simple first:

"Hey, what can you do?"

Your agent should respond based on its SOUL.md personality and the skills you have enabled.

#Running as a Background Service

For always-on operation, you do not want OpenClaw running in a terminal that closes when you disconnect. OpenClaw installs itself as a system service:

openclaw gateway install

openclaw gateway install installs and starts the service, so your agent comes back on its own after a reboot. If you would rather supervise it with something like pm2, point the supervisor at the foreground form, openclaw gateway, rather than at the managed service, and set OPENCLAW_SUPERVISOR_MODE=external. The docs reserve that variable for when "another process manager owns the Gateway lifecycle", and in that mode "Native service install, start, stop, and uninstall operations are refused".

#Step 8: Test and Explore

Now that your agent is running, try some basic interactions to verify everything works:

1. Test basic conversation: Ask your agent questions to confirm the LLM connection is working.
2. Test memory: Tell your agent your name and a preference. In a later message, ask if it remembers.
3. Check logs: Run openclaw logs to see what is happening behind the scenes.

# View recent agent logs
openclaw logs --tail 50
# Check agent status
openclaw status

#Common First-Time Issues

Agent does not respond to messages: Check that your API key is valid and has billing enabled. Most providers require an active payment method before API calls work.

Telegram bot does not receive messages: Verify you messaged the correct bot and that the bot token in your config matches what BotFather provided. Also confirm your numeric user ID is in the channels.telegram.allowFrom list.

"Model not found" error: Make sure the model name in your config matches an available model from your provider. Model names are case-sensitive and change over time.

High latency in responses: This is usually the LLM provider's response time, not OpenClaw. Smaller models like Claude Haiku or GPT-4.1-mini respond faster if speed is a priority.

#What's Next?

Congratulations — you have a working AI agent. But what you have right now is just the starting point. Here is where to go from here:

• Explore skills: Install community skills from ClawHub to expand your agent's capabilities. Start with web-search and reminder for immediately useful functionality.
• Fine-tune personality: Spend time with your SOUL.md file. The more specific your instructions, the more useful your agent becomes.
• Choose the right model: Read The Best LLM Models for OpenClaw in 2026 to understand the tradeoffs between speed, intelligence, and cost.
• Understand API keys: Check out API Keys Explained to learn how billing works and how to manage costs.
• Go premium: ClawDocx offers in-depth guides on advanced configuration, multi-agent workflows, security hardening, cost optimization, and much more. These guides are written for people who want to get the absolute most out of their OpenClaw setup.

Your agent is live. Now it is time to make it truly yours.