OpenClaw Setup Guide: From Zero to AI Assistant

Quick Answer: OpenClaw setup takes 10-15 minutes. You need Node.js >=22, an AI provider API key (Anthropic, OpenAI, or OpenRouter), and optionally a messaging app like WhatsApp or Telegram. Run npm install -g openclaw@latest and follow the onboard wizard to get started.

This guide walks you through installing OpenClaw from scratch, connecting an AI model provider, and optionally linking your favorite messaging apps (WhatsApp, Telegram, Discord, Slack, Lark/Feishu, iMessage) -- all in one session.

For AI Agents: This guide is designed so that any AI coding assistant can follow it step-by-step to help a user install and configure OpenClaw. Each phase includes the exact commands to run and the information to collect from the user.

What Do You Need Before Starting?

Before you begin the installation, make sure you have:

• Node.js >= 22 (check with node --version)
• npm (bundled with Node.js)
• A supported OS: macOS, Linux, or Windows (WSL2)

If Node.js is not installed:

# macOS (Homebrew)
brew install node

# macOS / Linux (fnm)
curl -fsSL https://fnm.vercel.app/install | bash && fnm install 22

# Or download from https://nodejs.org

How to Install OpenClaw?

First, install OpenClaw globally via npm:

npm install -g openclaw@latest

Next, verify the installation:

openclaw --version

Troubleshooting: If you get a permission error, try sudo npm install -g openclaw@latest. If openclaw is not found after install, add npm's global bin to your PATH:

Which AI Provider Should You Choose?

OpenClaw supports many AI providers out of the box. Here's a quick comparison:

For AI Agents: Before proceeding, ask the user the following questions in order:

If the user wants to skip this step entirely, that's fine -- they can configure the API key later by editing ~/.openclaw/openclaw.json. Proceed to the next section and use the interactive onboard wizard instead.

How to Get Your API Key Step-by-Step?

If you're not sure what an API key is or how to get one, don't worry. An API key is a secret string used to authenticate your requests -- think of it like a password. Each AI provider has its own dashboard where you can sign up, create a key, and copy it.

Anthropic (Claude)

1. Open https://console.anthropic.com and sign up or log in
2. Navigate to Settings > API Keys in the left sidebar (or go directly to https://console.anthropic.com/settings/keys)
3. Click Create Key and give it a name (e.g. "openclaw")
4. Copy the generated key (starts with sk-ant-) -- the key is only shown once, so save it immediately
5. Note: New accounts may need to add a payment method on the Billing page before the key can be used

OpenAI (GPT)

1. Open https://platform.openai.com/api-keys and sign up or log in
2. Click Create new secret key and give it a name (e.g. "openclaw")
3. Copy the generated key (starts with sk-) -- the key is only shown once, so save it immediately
4. Note: You may need to add a payment method at https://platform.openai.com/settings/organization/billing/overview before the key can be used

OpenRouter (Multi-Provider)

1. Open https://openrouter.ai/keys and sign up or log in
2. Click Create Key and give it a name (e.g. "openclaw")
3. Copy the generated key (starts with sk-or-) -- the key is only shown once, so save it immediately
4. Add credits at https://openrouter.ai/credits if needed

Don't have an API key right now? You can leave it blank during the onboard step below and add it later by editing ~/.openclaw/openclaw.json manually. See the Full Configuration Example section for details.

How to Run the Initial Setup?

OpenClaw provides a one-command setup. Replace the placeholder with your actual API key.

Anthropic:

openclaw onboard --install-daemon --anthropic-api-key "sk-ant-your-key-here"

OpenAI:

openclaw onboard --install-daemon --openai-api-key "sk-your-key-here"

OpenRouter:

openclaw onboard --install-daemon --auth-choice apiKey --token-provider openrouter --token "sk-or-your-key-here"

This command will:

1. Configure authentication with your chosen provider
2. Set up the gateway (local access on port 18789)
3. Install the background daemon service
4. Perform a health check

Troubleshooting: If the non-interactive command fails, run openclaw onboard --install-daemon and follow the interactive prompts. Select your provider, paste your API key, and accept defaults for everything else.

How to Choose Your Default Model?

The default model is what OpenClaw uses for new conversations. Edit ~/.openclaw/openclaw.json:

Anthropic Models

{
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" }
    }
  }
}

OpenAI Models

{
  "agents": {
    "defaults": {
      "model": { "primary": "openai/gpt-5.2" }
    }
  }
}

OpenRouter Models

Format: openrouter/<provider>/<model>

{
  "agents": {
    "defaults": {
      "model": { "primary": "openrouter/anthropic/claude-sonnet-4-6" }
    }
  }
}

What Recommended Settings Should You Add?

Add these to your ~/.openclaw/openclaw.json for a better experience:

{
  "agents": {
    "defaults": {
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 }
    }
  },
  "messages": { "ackReactionScope": "group-mentions" },
  "commands": { "native": "auto", "nativeSkills": "auto" },
  "skills": { "install": { "nodeManager": "npm" } }
}

How to Secure Your OpenClaw Installation?

Make sure your gateway is locked down. These should already be set by the onboard wizard, but double-check in ~/.openclaw/openclaw.json:

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": { "mode": "token" },
    "nodes": {
      "denyCommands": [
        "camera.snap", "camera.clip", "screen.record",
        "calendar.add", "contacts.add", "reminders.add"
      ]
    }
  }
}

Key security rules:

• Always bind to loopback (127.0.0.1). Never expose the gateway to 0.0.0.0.
• Keep token auth enabled. The gateway auth token is a password.
• Deny sensitive commands to prevent the agent from accessing your camera, calendar, or contacts without explicit permission.

How to Connect Messaging Apps? (Optional)

You can chat with OpenClaw through the terminal (openclaw tui), but connecting a messaging app lets you talk to it from your phone anytime.

How to Connect WhatsApp?

WhatsApp is the most popular option. OpenClaw connects via QR code pairing (same as WhatsApp Web).

Step 1: Add to ~/.openclaw/openclaw.json:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["+your-phone-number"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+your-phone-number"]
    }
  }
}

Step 2: Restart the daemon and link your phone:

openclaw daemon restart
openclaw channels login --channel whatsapp

Step 3: Open WhatsApp on your phone > Settings > Linked Devices > Link a Device > scan the QR code.

Step 4: Approve the pairing:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Best practice: Use a dedicated WhatsApp number, not your personal one.

How to Connect Telegram?

Telegram is the fastest channel to set up -- you just need a bot token.

Step 1: Open Telegram and message @BotFather

Step 2: Send /newbot and follow the prompts to name your bot

Step 3: Copy the bot token that BotFather gives you

Step 4: Add to ~/.openclaw/openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-bot-token-here",
      "dmPolicy": "pairing"
    }
  }
}

Step 5: Restart and approve:

openclaw daemon restart

Send any message to your bot in Telegram, then:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

How to Connect Discord?

Step 1: Go to https://discord.com/developers/applications

Step 2: Click New Application, give it a name

Step 3: In the sidebar click Bot > Reset Token > copy the token

Step 4: On the Bot page, enable Message Content Intent

Step 5: In the sidebar click OAuth2 > URL Generator:

• Check the bot scope
• Check permissions: Send Messages, Read Message History, Add Reactions, Attach Files, Embed Links

Step 6: Copy the generated URL, open it in your browser, and add the bot to your server

Step 7: Add to ~/.openclaw/openclaw.json:

{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "your-bot-token-here",
      "dmPolicy": "pairing"
    }
  }
}

Step 8: Restart and verify:

openclaw daemon restart
openclaw channels status --probe

Best practice: Create a private Discord server with channels like #coding, #research for isolated agent sessions.

How to Connect Slack?

Step 1: Go to https://api.slack.com/apps > Create New App > From scratch

Step 2: Name the app and select your workspace

Step 3: Go to Socket Mode, enable it, generate an App Token (starts with xapp-) -- copy it

Step 4: Go to OAuth & Permissions, add bot scopes: chat:write, channels:history, im:history, app_mention

Step 5: Click Install to Workspace and authorize

Step 6: Copy the Bot User OAuth Token (starts with xoxb-)

Step 7: Go to Event Subscriptions, enable, subscribe to: message.im, app_mention

Step 8: Add to ~/.openclaw/openclaw.json:

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-your-bot-token",
      "appToken": "xapp-your-app-token",
      "dmPolicy": "pairing"
    }
  }
}

Step 9: Restart and verify:

openclaw daemon restart
openclaw channels status --probe

How to Connect Lark / Feishu?

Step 1: Go to the developer console:

• Lark: https://open.larksuite.com
• Feishu: https://open.feishu.cn

Step 2: Create a Custom App

Step 3: In the credentials page, copy the App ID (starts with cli_) and App Secret

Step 4: Add to ~/.openclaw/openclaw.json:

{
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "lark",
      "accounts": {
        "main": {
          "appId": "cli_your-app-id",
          "appSecret": "your-app-secret"
        }
      }
    }
  }
}

For Feishu (instead of Lark), change "domain" to "feishu".

Step 5: Restart and verify:

openclaw daemon restart
openclaw channels status --probe

How to Connect iMessage? (macOS Only)

Step 1: Install the CLI tool:

brew install steipete/tap/imsg

Step 2: Grant permissions:

• Open System Settings > Privacy & Security > Full Disk Access and enable it for Terminal
• Allow Automation access for Messages when prompted

Step 3: Add to ~/.openclaw/openclaw.json:

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/usr/local/bin/imsg",
      "dbPath": "/Users/YOUR_USERNAME/Library/Messages/chat.db"
    }
  }
}

Step 4: Restart:

openclaw daemon restart

What Are the Channel Access Control Options?

All channels share these access control options:

How to Verify Everything Works?

Restart the daemon and check that your models are available:

openclaw daemon restart
sleep 3
openclaw models list

You should see your provider's models listed (e.g. anthropic/claude-sonnet-4-6).

Check connected channels:

openclaw channels status --probe

How to Start Using OpenClaw?

Terminal Chat

openclaw tui

Web Dashboard

openclaw dashboard

Then open http://127.0.0.1:18789 in your browser.

Useful Commands

Full Configuration Example

Here's a complete ~/.openclaw/openclaw.json using Anthropic with WhatsApp and Telegram:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-key-here"
  },
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" },
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 }
    }
  },
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["+1234567890"]
    },
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-your-bot-token",
      "dmPolicy": "pairing"
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": { "mode": "token" },
    "nodes": {
      "denyCommands": [
        "camera.snap", "camera.clip", "screen.record",
        "calendar.add", "contacts.add", "reminders.add"
      ]
    }
  },
  "messages": { "ackReactionScope": "group-mentions" },
  "commands": { "native": "auto", "nativeSkills": "auto" },
  "skills": { "install": { "nodeManager": "npm" } }
}

What If Something Goes Wrong?

Quick Reference Links

• Official docs: https://docs.openclaw.ai
• GitHub: https://github.com/openclaw/openclaw
• Anthropic Console: https://console.anthropic.com
• OpenAI Platform: https://platform.openai.com
• OpenRouter: https://openrouter.ai
• Discord Developer Portal: https://discord.com/developers/applications
• Slack API: https://api.slack.com/apps
• Lark Developer: https://open.larksuite.com
• Feishu Developer: https://open.feishu.cn