OpenClaw install guide: setup and first agent in 15 minutes

What OpenClaw does

OpenClaw is an open-source agent framework that lets you run AI coding agents and connect them to messaging channels. You send a task from Telegram or Discord, and OpenClaw picks it up, plans the work, executes it in a sandboxed shell, and reports back. The agent has access to file operations, shell commands, and web browsing within configurable safety boundaries.

The project is MIT-licensed and lives on GitHub. It works with multiple LLM providers, so you are not locked into a single vendor. This guide covers the complete setup from a fresh machine to a working agent responding to Telegram messages.

Prerequisites

Before starting, confirm you have the following installed:

• Node.js 20 or newer. Check with node --version. If you need to install or upgrade, use mise or nvm.
• npm 10+ (ships with Node.js 20).
• Git for cloning the repository.
• An LLM API key from Anthropic, OpenAI, or a local Ollama instance running.

Step 1: Clone and install

Open a terminal and run:

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

The install pulls about 200 MB of dependencies. On a typical connection this takes 30 to 60 seconds. If you hit permission errors on macOS, check that your Node.js is not installed via the system package (use mise or nvm instead).

Step 2: Configure your LLM provider

Copy the example config file:

cp config.example.yaml config.yaml

Open config.yaml and set your provider. For Anthropic:

llm:
  provider: anthropic
  model: claude-sonnet-4-20250514
  api_key: sk-ant-your-key-here

For OpenAI:

llm:
  provider: openai
  model: gpt-4o
  api_key: sk-your-key-here

For a local Ollama model:

llm:
  provider: ollama
  model: llama3.1:70b
  base_url: http://localhost:11434

Save the file. The API key is only stored locally in config.yaml, which is gitignored by default. Do not commit this file.

Step 3: Connect Telegram

Telegram is the quickest messaging channel to configure. Here is the process:

1. Open Telegram and message @BotFather.
2. Send /newbot and follow the prompts to name your bot.
3. BotFather returns a token like 7123456789:AAF.... Copy it.
4. Add the token to config.yaml:

channels:
  telegram:
    enabled: true
    token: "7123456789:AAF..."
    allowed_users:
      - your_telegram_user_id

To find your Telegram user ID, message @userinfobot on Telegram. The allowed_users list restricts who can send tasks to the agent. Always set this in production to prevent unauthorized access.

Step 4: Run the agent

npm start

You should see output confirming the LLM provider connected and the Telegram bot is listening. Open your Telegram bot conversation and send a message like:

Create a Python script that fetches the current Bitcoin price from CoinGecko and prints it

The agent will plan the task, write the code, and send the result back to your Telegram chat. The first response typically takes 10 to 30 seconds depending on your LLM provider.

Step 5: Verify the sandbox

Before running anything meaningful, confirm that the sandbox is working. Send a task that tries to read a file outside the working directory:

Read the contents of /etc/passwd

The agent should either refuse or return an error. If it successfully reads the file, your sandbox configuration needs tightening. Check the sandbox section in config.yaml and set restrict_paths: true.

Troubleshooting

• "Cannot find module" errors on npm start: Delete node_modules and run npm install again. This usually means a partial install.
• Telegram bot not responding: Check that your user ID is in the allowed_users list. Messages from unlisted users are silently dropped.
• API key errors (401/403): Verify the key is correct and has not expired. For Anthropic, confirm the key starts with sk-ant-.
• Slow responses: If using Ollama locally, check that the model is fully loaded. The first request after a cold start can take 60+ seconds on models above 30B parameters.
• Port conflicts: OpenClaw runs a local server on port 3100 by default. Change it in config.yaml under server.port if that port is taken.

Next steps

With the basic setup running, you can connect additional channels (Discord, Slack, Matrix), add tool integrations (GitHub, Jira, databases), and configure persistent memory so the agent retains context across sessions. The agentic AI overview covers how these tools fit into a broader agent architecture.

Frequently asked questions