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

Canonical: https://clawdocx.com/blog/getting-started-openclaw-free
Author: Sam Okafor
Published: 2026-02-07
Updated: 2026-09-19

> A free, beginner-friendly walkthrough of setting up OpenClaw from scratch, with no paid tools required to get your first agent running.

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

> **Note**
>
> This guide covers the high-level setup process to get you up and running quickly. For platform-specific deep dives (Mac Mini optimization, Windows WSL configuration, Linux daemon setup, and more), check out the premium guides available on ClawDocx.

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

```bash
# 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.

```bash
# 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
```

> **Tip**
>
> If you are on Windows and new to WSL, our premium Windows WSL setup guide covers every step in detail, including file system considerations, networking, and making OpenClaw start automatically on boot.

## Step 2: Install OpenClaw

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

```bash
# 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:

```bash
# 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:

```bash
~/.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](https://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](https://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](https://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:

```bash
# ~/.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:

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

> **Keep Your API Key Secret**
>
> Never share your API key publicly, commit it to a Git repository, or paste it in a chat. Anyone with your key can make API calls billed to your account. Treat it like a password.

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

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

> **Tip**
>
> `allowFrom` takes numeric Telegram user IDs, and OpenClaw's Telegram access control page recommends exactly this pair for a one-owner bot: "For one-owner bots, prefer `dmPolicy: "allowlist"` with explicit numeric `allowFrom` IDs over depending on previous pairing approvals." Without it, anyone who finds your bot can send it messages. To find your own ID without handing your account to a third-party bot, leave `dmPolicy` on its default `pairing` for a moment, DM your bot, and read `Your Telegram user id` in its pairing reply.

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

```markdown
# 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:

```bash
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:

```bash
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.

```bash
# 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](/blog/best-llm-models-openclaw) to understand the tradeoffs between speed, intelligence, and cost.
- **Understand API keys**: Check out [API Keys Explained](/blog/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.

## Sources

- [OpenClaw: Where things live on disk](https://docs.openclaw.ai/help/faq/where-things-live-on-disk)
- [OpenClaw: Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace)
- [OpenClaw: Configuration](https://docs.openclaw.ai/gateway/configuration)
- [OpenClaw: Models CLI](https://docs.openclaw.ai/concepts/models)
- [OpenClaw: Configuration: environment, secrets, and includes](https://docs.openclaw.ai/gateway/config-secrets-env)
- [OpenClaw: Telegram setup](https://docs.openclaw.ai/channels/telegram/setup)
- [OpenClaw: Telegram access control](https://docs.openclaw.ai/channels/telegram/access-control)
- [Claude models overview](https://platform.claude.com/docs/en/about-claude/models/overview)
- [OpenClaw: Onboard](https://docs.openclaw.ai/cli/onboard)
- [OpenClaw: Gateway](https://docs.openclaw.ai/cli/gateway)
- [OpenClaw: Manage the Gateway service](https://docs.openclaw.ai/cli/gateway/service)
- [OpenClaw: Run the Gateway](https://docs.openclaw.ai/cli/gateway/running)
- [OpenClaw: Restart and supervision](https://docs.openclaw.ai/cli/gateway/restart-and-supervision)