OpenClaw Setup Wizard

OpenClaw (formerly Clawdbot and Moltbot) is an open-source personal AI assistant that answers you on Telegram, WhatsApp, Discord, Slack or iMessage. Its setup comes down to one config file, ~/.openclaw/openclaw.json. Pick your options below to get a config that passes OpenClaw's strict validation, a .env for your keys, and the exact commands to run.

Step 1: Your setup

Get a ANTHROPIC_API_KEY
Chat apps
Who can DM your assistant?

Your numeric Telegram user IDs, separated by commas.

Ready. This combination passes openclaw config validate.

Step 2: Your config and keys

openclaw.json

// ~/.openclaw/openclaw.json
// Keys live in ~/.openclaw/.env; ${VAR} values are read from there.
{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "anthropic/claude-sonnet-5-5"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "pairing"
    }
  }
}

.env

# ~/.openclaw/.env  (keep this file private: chmod 600)
OPENCLAW_GATEWAY_TOKEN=generating...
ANTHROPIC_API_KEY=paste-your-key-here
TELEGRAM_BOT_TOKEN=paste-your-token-here

The gateway token is made in your browser and never leaves it; nothing on this page is sent anywhere. Replace each paste-your-... value with your real key, and rename the download to .env inside ~/.openclaw.

Step 3: Run these commands

  1. 1

    Install OpenClaw without the onboarding wizard

    The installer adds Node.js 24 or 26 if you need it. Skipping onboarding keeps it from writing its own config over yours.

    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
    openclaw --version
  2. 2

    Save the two files

    Save the config as ~/.openclaw/openclaw.json and the secrets as .env in the same folder, then fill in your real keys.

    mkdir -p ~/.openclaw && cd ~/.openclaw
    nano openclaw.json
    nano .env && chmod 600 .env
  3. 3

    Check the config

    Strict validation: any unknown key stops the Gateway from starting. Fix what it reports before you go on.

    openclaw config validate
    openclaw doctor
  4. 4

    Start the Gateway as a background service

    Runs as a LaunchAgent.

    openclaw gateway install
    openclaw gateway start
    openclaw gateway status
  5. 5

    Message your bot, then approve yourself

    Your first DM gets an 8-character pairing code that expires in an hour. Approve it once per channel.

    openclaw pairing approve telegram <CODE>
  6. 6

    Open the dashboard

    Opens the Control UI at http://127.0.0.1:18789 with a one-time login link.

    openclaw dashboard

Before you start

  • Node.js 24.16+ or 26.1+ (26 is recommended). Node 22, 23 and 25 are not supported; the installer adds a supported version if needed.
  • An API key for your model provider, or Ollama running locally.
  • A bot token for each chat app: @BotFather for Telegram, the Developer Portal for Discord (turn on Message Content Intent), a Socket Mode app for Slack.
  • Port 18789 free on this machine. Check with openclaw gateway status --deep if something else is using it.
  • Keys go only in ~/.openclaw/.env, never in openclaw.json, so you can share or back up the config safely.

Common setup errors

Gateway start blocked: set gateway.mode=local

A hand-written config needs gateway: { mode: "local" }. The config from this wizard always includes it. You can also re-run openclaw onboard --mode local.

Invalid config, or the Gateway exits with code 78

OpenClaw rejects unknown keys. Run openclaw config validate to see the bad path, then openclaw doctor --fix to migrate old keys such as agents.list or heartbeat.

EADDRINUSE or another gateway instance is already listening

An old Gateway or a second service holds port 18789. Run openclaw gateway status --deep, remove the duplicate, or change gateway.port, then openclaw gateway restart.

Dashboard says unauthorized or AUTH_TOKEN_MISMATCH

Run openclaw dashboard for a fresh one-time login link, or openclaw gateway auth-token --show to see the token the Gateway is using.

The bot ignores my first message

With pairing on, your first DM returns an 8-character code instead of an answer. Approve it with openclaw pairing approve <channel> <CODE> within an hour.

Telegram bot is silent in groups

Telegram privacy mode hides group messages. Send /setprivacy to @BotFather and pick Disable (or make the bot an admin), then remove and re-add the bot to the group.

Discord bot sees no server messages

Turn on Message Content Intent under Bot in the Discord Developer Portal, then restart the Gateway.

WhatsApp keeps logging out

Back up ~/.openclaw/credentials/whatsapp, run openclaw channels logout --channel whatsapp, then openclaw channels login --channel whatsapp and scan the QR again.

Every config combination was checked with openclaw config validate on OpenClaw 2026.11.4 on November 17, 2026. Sources: Install, Configuration, Configuration examples, Gateway settings, Pairing, Multi-agent. Not affiliated with the OpenClaw project.

OpenClaw setup FAQ

Is it hard to set up OpenClaw?

No. One install command and a short config get most people chatting in 5 to 15 minutes. Telegram is the fastest channel because it only needs a bot token. WhatsApp needs a QR scan, and iMessage needs a Mac with Full Disk Access.

What is the command to start OpenClaw?

Run openclaw gateway to start it in the foreground, or openclaw gateway install and then openclaw gateway start to run it as a background service. openclaw dashboard opens the web UI at http://127.0.0.1:18789, and openclaw on its own opens the terminal UI.

Where is the OpenClaw config file?

It is ~/.openclaw/openclaw.json, written in JSON5, so comments and trailing commas are fine. Set OPENCLAW_CONFIG_PATH to use another file. The Gateway watches the file and reloads it when you save.

Where do I put my API keys?

Put them in ~/.openclaw/.env, for example ANTHROPIC_API_KEY=... or TELEGRAM_BOT_TOKEN=..., and refer to them in the config as ${TELEGRAM_BOT_TOKEN}. That keeps secrets out of openclaw.json.

Can OpenClaw have multiple agents?

Yes. One Gateway can run several isolated agents, each with its own workspace and memory. List them under agents.entries, set agents.ownership to "explicit", and route chats to them with bindings, or run openclaw agents add <id>.

What happened to heartbeat settings?

Heartbeat keys were removed from the config. Scheduled check-ins are now automations you create with openclaw automations add, for example a daily briefing at 8:00. openclaw doctor --fix moves old heartbeat settings for you.

Related free tools

Skip the setup: run OpenClaw managed on NitroClaw

NitroClaw hosts a dedicated OpenClaw assistant for you, with updates, uptime and channel connections handled. No server, Node.js or config file needed.

Explore NitroClaw