Complete OpenClaw Setup Guide (Mac, Linux & Windows)

Why OpenClaw Is Worth Setting Up

Prerequisites

OpenClaw is a Node.js application, so the main thing you need is a modern version of Node installed. You'll also need an API key from at least one AI provider — Anthropic (Claude) and OpenAI (GPT-4) are the most popular choices. If you're cost-conscious, Google Gemini Flash is an excellent low-cost option for background tasks like heartbeats and cron summaries.

Installation

OpenClaw is distributed as a global npm package. Installing it globally makes the openclaw command available system-wide, so you can run it from any directory. This is the only installation method currently supported — unlike some tools, OpenClaw is designed to run as a persistent daemon on your machine rather than inside a specific project directory.

npm install -g openclaw@latest

This installs OpenClaw globally. The package includes the CLI, the gateway server, and all built-in skills. Wait for the installation to complete — typically 1–2 minutes on a normal connection. You'll see npm download and link several dependencies; this is expected.

Once installation finishes, verify it worked by checking the version number. If the command is found and prints a version, you're ready for configuration:

openclaw --version

You should see the version number (e.g., 2026.3.8). If you get "command not found", try restarting your terminal or check that your npm global bin directory is on your PATH.

Initial Configuration

The fastest way to get configured is the built-in onboarding wizard. It walks you through provider selection, API key entry, workspace creation, and daemon setup — all in one interactive flow. Your API key is stored locally in ~/.openclaw/config/ and is never transmitted anywhere outside your chosen provider's API.

openclaw onboard --install-daemon

The --install-daemon flag registers OpenClaw as a system service so it starts automatically at login — highly recommended for automation use cases. The wizard will guide you through these four steps:

1. 1Choosing your primary AI provider (Anthropic, OpenAI, Google)
2. 2Entering your API key (stored locally, never sent anywhere else)
3. 3Setting up your workspace directory (~/.openclaw/workspace/)
4. 4Installing as a background daemon (auto-starts on boot)

If you prefer to configure manually — for example, to set up dual models (one fast, one capable) or to configure multiple providers — edit the config file directly. The heartbeat model handles background tasks like cron summaries and is worth pointing at a cheaper model such as Gemini Flash to reduce costs. See our cost calculator to estimate your monthly spend across different model configurations.

{
  "model": {
    "default": "anthropic/claude-sonnet-4-6",
    "heartbeat": "google/gemini-flash-lite"
  },
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-YOUR_KEY_HERE"
    }
  }
}

First Run & Testing

The OpenClaw gateway is the core server process that routes messages, executes tools, and manages channel connections. You need it running before any other functionality works. Start it with:

openclaw gateway start

The gateway binds to port 18789 by default and exposes a local HTTP interface for message routing and management. You should see a confirmation line appear within a few seconds. If you installed the daemon, this starts automatically at login — but for your first run you'll start it manually to watch the output.

Look for: ✓ Gateway ready on http://localhost:18789

Once the gateway is running, send a test message directly from the CLI to verify your API key and model are working correctly. This bypasses any channel configuration and tests the core AI layer in isolation:

openclaw send --message "Hello, OpenClaw! What's today's date?"

Connecting Telegram

Telegram is the recommended channel for OpenClaw — it's fast, reliable, free, and works perfectly as a mobile interface to your agent. The integration uses a Telegram Bot token, which you get by talking to @BotFather — Telegram's official bot-creation service. The whole process takes about 3 minutes.

openclaw channel add telegram

The command will prompt you to open Telegram and message @BotFather. Send it /newbot, choose a name and username for your bot, and BotFather will reply with a token that looks like 1234567890:ABC-DEF1234.... Paste that token into the CLI prompt and OpenClaw will handle the rest — registering the webhook, configuring your user ID as an allowed sender, and starting to listen for messages.

After setup, open Telegram, find your new bot, and send it a message. You should get a reply within a second or two. If it takes longer, check that the gateway is still running and that your bot token is correct in the config.

Other Channels

You can connect additional channels alongside Telegram. Each one adds a new input/output surface for your agent:

Your First Automation: Morning Brief

Now that your agent is running and connected to Telegram, let's set up a real automation. A morning brief is the perfect first cron job — it demonstrates how OpenClaw can pull together multiple data sources (weather, calendar, news) and push a formatted summary to you every morning, completely automatically.

OpenClaw uses standard cron syntax for scheduled tasks. Create a file called CRONS.md in your workspace directory. Each cron entry specifies a schedule and a prompt that your agent will execute at that time:

# Morning Brief
schedule: 0 7 * * 1-5
prompt: >
  Good morning! Please prepare my daily brief:
  1. Today's weather for Belgrade
  2. Any calendar events today (check Google Calendar)
  3. Top 3 crypto prices (BTC, ETH, SOL)
  4. Any unread emails flagged as important
  Send the brief to my Telegram channel.

This cron runs at 7:00am on weekdays (Monday–Friday). The agent will execute the prompt, gather the requested data using its built-in tools, format a clean summary, and send it to your Telegram — all without you doing anything. For a more detailed walkthrough of morning brief customization options, see the Automated Morning Routine guide.

After saving the file, reload your workspace so OpenClaw picks up the new cron:

openclaw workspace reload

Setting Up Your Workspace

The workspace directory is where you define your agent's personality, memory, and behavior. Think of it as the agent's brain — a set of plain Markdown files that OpenClaw reads on startup and injects into every conversation as context. This is what makes your agent feel like your agent rather than a generic chatbot.

~/.openclaw/workspace/
├── SOUL.md      # Agent personality & behavior rules
├── USER.md      # About you: timezone, style, goals
├── MEMORY.md    # Persistent facts your agent should know
├── AGENTS.md    # Agent topology (single or multi-agent)
└── CRONS.md     # Scheduled automations (cron jobs)

The most impactful files to set up first are USER.md and SOUL.md. USER.md tells your agent your timezone, communication style, and goals — so it can format responses appropriately and understand your context without you re-explaining it each time. SOUL.md defines the agent's personality, name, and rules.

See the Memory System guide for details on each file and how LCM (Lossless Context Management) keeps memory across long sessions.

Troubleshooting

Most issues during initial setup fall into a few predictable categories. Here are the most common errors and how to fix them. If none of these solve your problem, check the logs with openclaw gateway logs --tail — the output usually points directly at the issue.

Next Steps

Congratulations — you have a working AI agent. But this is just the foundation. OpenClaw's real power comes from the 20-phase setup covered in the full OpenClaw Guide, which walks through advanced topics like multi-agent architectures, custom skills, Tailscale remote access, and production-grade security hardening. In the meantime, these posts cover the most useful next steps: