MagicAssist
Back to Blog
OpenClawTutorial

How to Get Started with OpenClaw (Step-by-Step Tutorial)

February 18, 2026•1 min read
How to Get Started with OpenClaw (Step-by-Step Tutorial)

In short:

Get a quick AI-generated summary of this article to save time and grasp the key points instantly.

Summarize full blog with:

How to Get Started with OpenClaw (Step-by-Step Tutorial)

Published: February 2026 | Reading time: ~8 minutes

Getting OpenClaw running for the first time takes less than 30 minutes if you know what to expect. This guide walks through every step: prerequisites, installation, first configuration, and setting up your first agent so you can verify things are actually working.

If you want a conceptual overview before diving in, start with What is OpenClaw? and come back here when you are ready to install.

Prerequisites

Before you install anything, make sure your environment meets these requirements. Skipping this step is the most common reason first-time setups fail.

System Requirements

  • Operating system: Linux, macOS, or Windows (WSL2 recommended for Windows users)
  • Node.js: v18 or higher
  • npm: v9 or higher
  • RAM: At least 2 GB free
  • Disk space: 500 MB minimum for the base install

Check your Node.js version before you proceed:

node --version
npm --version

If Node is not installed or is below v18, install it via nvm or the official Node.js installer. The nvm route is cleaner because it lets you switch versions later without touching your system install.

API Keys and Accounts

OpenClaw connects to language model providers and communication platforms. You will need at least one of the following before your agent can do anything useful.

Language model provider (pick one to start):

  • Anthropic API key (Claude models)
  • OpenAI API key (GPT models)

Communication channel (optional but recommended for testing):

  • A Telegram bot token (easiest to set up, takes under 5 minutes)
  • Or a Discord bot token if your team lives in Discord

You do not need all of these on day one. A single API key and a Telegram bot token is enough to complete this tutorial.

Installing OpenClaw

OpenClaw is installed via npm. The install command below will pull down the CLI globally so you can run it from any directory.

npm install -g openclaw

Once it finishes, confirm the install worked:

openclaw --version

You should see a version string printed to your terminal. If you get a “command not found” error, your npm global bin directory is probably not in your PATH. The fix depends on your shell:

# For bash/zsh, add this to ~/.bashrc or ~/.zshrc:
export PATH="$(npm root -g)/../bin:$PATH"

# Then reload your shell config:
source ~/.bashrc

After sorting PATH, run openclaw --version again. If it still fails, check the official OpenClaw documentation for platform-specific troubleshooting.

First Configuration

Initialize Your Workspace

OpenClaw uses a workspace directory to store your agent configurations, memory files, and logs. Run the init command to create it:

openclaw init

By default, this creates a workspace at ~/.openclaw/workspace. You can specify a custom path if you prefer:

openclaw init --workspace /path/to/your/workspace

The init command will walk you through a short interactive setup. It will ask for a workspace name and whether you want to create a default agent configuration. Answer yes to both for now.

Add Your API Key

Open the configuration file at ~/.openclaw/config.json in any text editor. You will see a section for providers:

{
  "providers": {
    "anthropic": {
      "apiKey": "YOUR_ANTHROPIC_KEY_HERE"
    }
  }
}

Replace the placeholder with your actual API key and save the file. Do not commit this file to version control. Add config.json to your .gitignore if you plan to manage your workspace in git.

Connect a Communication Channel

This step is optional for a basic test, but connecting Telegram now makes it much easier to verify your agent is responding correctly.

To create a Telegram bot:

  1. Open Telegram and search for @BotFather
  2. Send /newbot and follow the prompts
  3. Copy the token BotFather gives you

Then add the token to your config:

{
  "channels": {
    "telegram": {
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN"
    }
  }
}

For Discord setup, the process is similar but requires creating an application in the Discord Developer Portal and generating a bot token from there. The OpenClaw docs have a dedicated page for Discord configuration if you need it.

Setting Up Your First Agent

Create the Agent File

Every agent in OpenClaw is defined by a configuration file inside your workspace. Navigate to your workspace and create an agent directory:

mkdir -p ~/.openclaw/workspace/agents/my-first-agent

Create a file called agent.json inside that directory:

{
  "name": "my-first-agent",
  "description": "A basic agent for testing OpenClaw setup.",
  "model": "claude-3-5-sonnet-20241022",
  "provider": "anthropic",
  "channels": ["telegram"],
  "systemPrompt": "You are a helpful assistant. Answer questions clearly and concisely."
}

This is the minimum viable agent configuration. The systemPrompt field is where you define the agent’s behavior and personality. Keep it simple for now.

Write a Basic Soul File

OpenClaw agents can optionally use a SOUL.md file to define their personality and working style in natural language. This is separate from the JSON config and gets included in the agent’s context at startup.

Create ~/.openclaw/workspace/agents/my-first-agent/SOUL.md:

## Who I Am

I am a test agent for verifying the OpenClaw setup. My job is to confirm
that messages are being received and responses are being sent correctly.

## How I Work

I respond to every message with a short, clear reply. I do not take on
complex tasks during testing.

This step is optional but gets you into good habits early. When you build more sophisticated agents, a well-written SOUL.md is worth the effort.

Testing That Everything Works

Start the OpenClaw Gateway

The gateway is the background service that manages your agents, handles incoming messages, and routes tasks. Start it with:

openclaw gateway start

You should see output confirming the gateway is running and which agents are loaded. Check the status at any time with:

openclaw gateway status

Send a Test Message

If you connected Telegram, open the Telegram app and find the bot you created. Send it any message, something like “hello” or “are you there?” Within a few seconds, you should receive a response.

If the bot does not respond after 30 seconds, check the gateway logs:

openclaw gateway logs --tail 50

Look for error lines near the bottom. Common issues are a malformed API key, a Telegram token with an extra space, or a model name that does not match the provider’s API.

Verify Without a Channel

If you skipped the channel setup, you can test the agent directly from the CLI:

openclaw chat --agent my-first-agent

This opens an interactive chat session in your terminal. Type a message, press enter, and the agent should respond. This is useful for quick checks before wiring up channels.

Common First-Timer Mistakes

A few issues come up repeatedly when people set up OpenClaw for the first time. Knowing them in advance saves a lot of time.

Mistake 1: Using the Wrong Node Version

OpenClaw requires Node v18+. If you installed OpenClaw with an older Node version and then upgraded Node, you may need to reinstall OpenClaw to pick up the correct binary. Run npm install -g openclaw again after upgrading Node.

Mistake 2: Putting Secrets in the Wrong File

The config.json file holds your API keys. Your agent.json and SOUL.md files do not need keys and should be safe to share or commit. Keep secrets in config.json only, and treat that file as private.

Mistake 3: Starting Agents Before the Gateway

Individual agents do not run on their own. The gateway is the coordinator. Always start the gateway first with openclaw gateway start, then let it load your agents automatically. Trying to invoke an agent directly without the gateway running will result in a timeout.

Mistake 4: Overly Complex System Prompts Early On

It is tempting to write a detailed, multi-page system prompt for your first agent. Resist this. Start with three to five clear sentences, test the behavior, and add complexity only when you know the basics are working. Debugging a sophisticated agent is much harder when you do not know whether your setup itself is solid.

Mistake 5: Ignoring the Logs

OpenClaw writes detailed logs for every message, tool call, and error. When something does not work, the logs almost always tell you why. Make openclaw gateway logs your first stop for troubleshooting, not your last.

What’s Next?

You now have a working OpenClaw setup with at least one agent running. From here, the natural next step is learning how to manage multiple agents, monitor their activity, and handle more complex configurations.

The OpenClaw Dashboard Guide covers the built-in web UI where you can see agent status, message history, and resource usage at a glance. It is worth bookmarking once you move past the single-agent stage.

For teams running several agents across different projects or clients, the overhead of managing each one individually adds up fast. That is where Mission Control (MC Pro) comes in. It gives you a single interface for monitoring, configuring, and deploying multiple agents without touching config files directly.

A Note on Scale

OpenClaw handles single-agent setups well out of the box. However, as your use cases grow, you will likely want a layer of orchestration on top of the raw OpenClaw configuration, particularly for task routing, agent handoffs, and audit logging.

MagicAssist is built on top of OpenClaw and handles this orchestration layer for you. It is designed for teams that want the power of OpenClaw without spending engineering time on the infrastructure around it. If you are evaluating whether that makes sense for your situation, the MagicAssist free trial lets you connect your existing OpenClaw workspace and see the difference firsthand.

This tutorial covers OpenClaw as of February 2026. Installation steps and configuration formats may change in future releases. Always check the official OpenClaw documentation for the most current instructions.

Share this article

Found this helpful? Share it with your network.

Get early access

MagicAssist is launching soon. Join the waitlist to be first in line when we open up.