How to Install OpenClaw: Step-by-Step Setup Guide

Introduction

Getting OpenClaw up and running is more involved than installing a mobile app, but far less daunting than it might initially seem. The process takes most people between 30 minutes and 2 hours on their first attempt, depending on familiarity with the command line and API setup. Once running, the agent operates entirely autonomously — meaning setup time is a one-time cost that pays dividends every day afterward.

This guide assumes you're starting from zero. No prior Node.js experience required. No prior messaging bot experience required. Just a computer, an internet connection, and an API key from at least one LLM provider. Let's build your first autonomous AI agent.

Prerequisites

Before you touch any code, make sure you have the following ready:

• Node.js 20 or later: OpenClaw is a Node.js application. Install it from nodejs.org. Verify installation with node --version in your terminal.
• Git: You'll clone the repository from GitHub. Git comes pre-installed on most Macs and Linux systems. Windows users can install it from git-scm.com.
• An LLM API key: At minimum, you need one. The most popular choices are OpenAI (platform.openai.com) and Anthropic (console.anthropic.com). Alternatively, install Ollama to run local models without any API key at all.
• A messaging platform bot token: Telegram is the easiest to start with. You'll see creating a Telegram bot below. WhatsApp, Slack, and Discord are also supported but require additional setup steps.
• A machine to run it on: Your laptop works for testing. For 24/7 operation, you'll want a dedicated machine — a Mac Mini, a Raspberry Pi 5, or a cheap cloud VPS. More on hardware choices in a separate guide.

Security note before we begin: never share your API keys with anyone. Never commit them to a public repository. Never include them in screenshots you post publicly. These keys represent money and access.

Clone & Install

Open your terminal and run the following commands:

git clone https://github.com/openclaw-foundation/openclaw.git
cd openclaw
npm install

The npm install command downloads all of OpenClaw's dependencies. Depending on your internet connection, this takes one to three minutes. You'll see a progress bar and eventually a confirmation message.

Next, create your configuration file. OpenClaw uses a YAML file for configuration. The repository includes a template:

cp config.example.yaml config.yaml

Open config.yaml in your text editor of choice. This is where all your settings live. Take a moment to read through it — the file is well commented and reading it gives you a mental model of how OpenClaw is structured before you start the service.

Configuring API Keys

Locate the llm section in your config.yaml. You'll see slots for multiple providers. Configure at least one:

llm:
  default_provider: openai
  providers:
    openai:
      api_key: "sk-your-key-here"
      model: "gpt-4o"
    anthropic:
      api_key: "sk-ant-your-key-here"
      model: "claude-opus-4"

A few important practices here. First, prefer environment variables over hardcoded keys in the YAML file. Instead of writing your key directly, you can reference an environment variable: api_key: "${OPENAI_API_KEY}". Set the variable in your shell profile or in a .env file (add .env to your .gitignore immediately).

Second, set spending limits on your API accounts. Both OpenAI and Anthropic allow you to set monthly spending caps from their dashboards. OpenClaw agents can consume tokens at a surprising rate, especially during initial setup when you're testing extensively. A $20 monthly cap during testing is a sensible safeguard against runaway costs.

If you want to use a local model instead, install Ollama, download a model with ollama pull llama3.2, and configure the provider section accordingly. Local models have no API costs but require adequate hardware — at minimum, 8GB of RAM for smaller models, 16GB or more for capable ones.

Connecting a Messaging App

Telegram is the fastest and most reliable channel to start with. Here's how to create a Telegram bot:

1. Open Telegram and search for @BotFather — the official bot for creating bots.
2. Send the command /newbot.
3. BotFather will ask for a name (the display name) and a username (must end in "bot"). Choose anything you like.
4. BotFather will send you an API token — a long string like 123456789:AAHdfkjhsdkjfhskdjfhskdjfh. Copy it.

Now add your Telegram token to config.yaml:

channels:
  telegram:
    enabled: true
    bot_token: "123456789:AAHdfkjhsdkjfhskdjfhskdjfh"
    allowed_user_ids:
      - 987654321

To find your own Telegram user ID, message @userinfobot on Telegram — it will reply with your numeric user ID. Add this to the allowed_user_ids list. This is an important security measure: it restricts your agent to only responding to your Telegram account. Without this, anyone who discovers your bot's username could send it commands.

Your First Run

With configuration complete, start OpenClaw:

npm start

You should see the service start, channels initialize, and a message confirming the agent is running. Now open Telegram and send your bot a message — start with something simple like "Hello, are you there?" Within a few seconds, you should receive a response from your AI agent.

Try a few more interactions to confirm everything is working:

• "What's today's date and time?" — tests basic LLM connectivity
• "What can you do?" — asks the agent to describe its available Skills
• "Remember that my name is [your name] and I work in [your industry]" — tests the memory system

If all three work, your installation is complete and functional. Congratulations — you have a running AI agent.

Running with Docker

For production use, running OpenClaw in Docker is strongly recommended. Docker provides isolation, makes the service easier to manage, and gives you a consistent deployment regardless of what else is running on the host machine.

OpenClaw ships with a Dockerfile and a docker-compose.yml for easy getting it running. First, edit your environment variables in a .env file. Then launch:

docker-compose up -d

The -d flag runs the container in detached mode — it keeps running in the background even after you close the terminal. Check that it's running with docker-compose ps and view logs with docker-compose logs -f.

For added security, configure the Docker volume mounts in docker-compose.yml to give the container access only to the directories it needs — typically the OpenClaw config directory and the memory files directory. Do not mount your entire home directory or system root.

Common Troubleshooting Tips

A few issues come up repeatedly in the community that are worth knowing about:

The agent doesn't respond on Telegram. First verify that the bot token is correct (regenerate it via BotFather if unsure). Then check that your user ID is in the allowed list. Finally, confirm that outbound HTTPS traffic to api.telegram.org isn't blocked by a firewall.

API errors or "rate limit exceeded" messages. This usually means your API key is invalid, hasn't been funded, or you've hit a rate limit. Check your provider's dashboard. For OpenAI, ensure you have a payment method attached and available credit.

"Cannot find module" errors on startup. Run npm install again. Sometimes installing on one OS and running on another (or after a git pull that updated dependencies) leaves the node_modules directory out of sync.

High memory or CPU usage. This is usually caused by an overly aggressive heartbeat schedule or a runaway agent loop. Increase the heartbeat interval in config, or add circuit-breaker limits to the agent's allowed actions.

Telegram messages not delivering. If the agent is sending messages but they're not arriving, check that you haven't accidentally blocked the bot on Telegram. Delete the conversation and start a new chat with the bot.

Wrapping Up

Setting up OpenClaw takes more effort than downloading an app. But you now have something genuinely different: a persistent AI agent running on your own hardware, communicating through your existing messaging apps, with full access to your configured Skills and growing memory. That one-time setup investment is the foundation for months or years of autonomous AI assistance.

Explore the HEARTBEAT.md configuration next — that's where you tell your agent what to do proactively, and where OpenClaw's real value begins to reveal itself.