Running Clawdbot in Docker on macOS

2026-01-26

Clawdbot is a personal AI assistant that connects to your messaging apps — WhatsApp, Telegram, Discord, and more. Instead of installing Node.js and dependencies directly on your Mac, you can run it in a Docker container. This keeps your system clean and makes the setup reproducible.

In this post, we’ll get Clawdbot running in Docker on macOS in about 10 minutes.

Prerequisites

You need Docker Desktop installed on your Mac. If you don’t have it yet, download it from:

https://www.docker.com/products/docker-desktop

After installation, make sure Docker is running. You should see the whale icon in your menu bar.

New to Docker? Check out my previous posts on Docker basics for a gentle introduction.

Quick Start

Clawdbot provides an official Docker image. Pull and run it with a single command:

docker run -it --name clawdbot \
  -v ~/.clawdbot:/root/.clawdbot \
  -v ~/clawd:/root/clawd \
  -p 18789:18789 \
  ghcr.io/clawdbot/clawdbot:latest \
  clawdbot onboard

Let’s break this down:

Flag	Purpose
`-it`	Interactive mode with terminal
`--name clawdbot`	Name the container for easy reference
`-v ~/.clawdbot:/root/.clawdbot`	Persist config and credentials
`-v ~/clawd:/root/clawd`	Persist the agent workspace
`-p 18789:18789`	Expose the Gateway port

The onboard command starts an interactive wizard that guides you through the initial setup.

The Onboarding Wizard

When you run the command above, the wizard will ask you a few questions:

Model Provider — Choose Anthropic (Claude) or OpenAI
Authentication — API key or OAuth login
Channels — Which messaging apps to connect (WhatsApp, Telegram, etc.)
Workspace — Where to store agent memory and files

For WhatsApp, you’ll scan a QR code. For Telegram, you’ll need a bot token from @BotFather.

Follow the prompts, and the wizard handles the rest.

Running the Gateway

After onboarding, start the Gateway:

docker run -d --name clawdbot-gateway \
  -v ~/.clawdbot:/root/.clawdbot \
  -v ~/clawd:/root/clawd \
  -p 18789:18789 \
  --restart unless-stopped \
  ghcr.io/clawdbot/clawdbot:latest \
  clawdbot gateway

The -d flag runs it in the background. The --restart unless-stopped ensures it survives reboots.

Check if it’s running:

docker logs clawdbot-gateway

You should see output indicating the Gateway is listening on port 18789.

Verify the Setup

Open a new terminal and run:

docker exec clawdbot-gateway clawdbot status

This shows the current status of your Clawdbot instance, including connected channels and active sessions.

Sending Your First Message

With the Gateway running, send a message to your connected channel (WhatsApp, Telegram, etc.). Clawdbot should respond.

If you’re using WhatsApp, the first message from a new contact will trigger a pairing request. Approve it with:

docker exec clawdbot-gateway clawdbot pairing list whatsapp
docker exec clawdbot-gateway clawdbot pairing approve whatsapp <code>

Using Docker Compose

For a cleaner setup, create a docker-compose.yml:

version: '3.8'

services:
  clawdbot:
    image: ghcr.io/clawdbot/clawdbot:latest
    container_name: clawdbot
    command: clawdbot gateway
    volumes:
      - ~/.clawdbot:/root/.clawdbot
      - ~/clawd:/root/clawd
    ports:
      - "18789:18789"
    restart: unless-stopped

Then start with:

docker compose up -d

And stop with:

docker compose down

Updating Clawdbot

To update to the latest version:

docker compose pull
docker compose up -d

Or without Compose:

docker pull ghcr.io/clawdbot/clawdbot:latest
docker stop clawdbot-gateway
docker rm clawdbot-gateway
# Run the docker run command again

Troubleshooting

Container won’t start?

Check the logs:

docker logs clawdbot-gateway

WhatsApp disconnected?

Re-authenticate:

docker exec -it clawdbot-gateway clawdbot channels login

Port already in use?

Change the port mapping:

-p 18790:18789

What’s Next?

With Clawdbot running in Docker, you have a personal AI assistant that:

Responds to your messages on WhatsApp, Telegram, Discord
Remembers context across conversations
Can search the web, manage files, and run commands
Stays running 24/7 on your Mac

For more advanced setups — like connecting multiple channels or adding custom skills — check the official documentation:

https://docs.clawd.bot

Resources

If you have questions or run into issues, leave a comment or reach out on the Clawdbot Discord.