Setup Guide

This is the detailed version. If you just want it working fast, hit up Getting Started instead.

TL;DR

Your stuff lives outside the repo: ~/clawd (workspace) + ~/.clawdbot/moltbot.json (config)
Easiest workflow: Install the macOS app, let it handle the Gateway
Dev workflow: Run Gateway yourself (pnpm gateway:watch), macOS app connects in Local mode

What You Need (From Source)

Node 22 or newer
pnpm
Docker (only if you want containers or e2e tests — Docker docs)

Config Strategy (Stay Update-Safe)

Want full customization without update headaches? Keep it separate:

Config: ~/.clawdbot/moltbot.json (JSON/JSON5-ish)
Workspace: ~/clawd (skills, prompts, memories—make it a private git repo if you’re smart)

Bootstrap once:


moltbot setup

If you’re in the repo without a global install:


pnpm moltbot setup

Stable Workflow (macOS App First)

Install Moltbot.app (menu bar app)
Launch it — uses the bundled Gateway
Connect — uses Unix socket by default (zero network exposure)

The app handles Gateway lifecycle. You just… use it.

Dev Workflow (Gateway Watch Mode)

Want live reload? Run Gateway yourself:


pnpm gateway:watch

Then:

macOS app → Local mode (connects to your running Gateway)
Or hit the Control UI directly: http://127.0.0.1:18789/

Config File Breakdown

Lives at ~/.clawdbot/moltbot.json. Here’s what’s in there:

Gateway Settings


{
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "your-secret-token"
    }
  }
}

Channel Config


{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"
    },
    "telegram": {
      "token": "your-bot-token"
    }
  }
}

Agent Routing


{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/clawd",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

Full config reference: Configuration docs

Common Setups

Single User, Max Security


{
  "gateway": {
    "bind": "loopback",
    "auth": { "mode": "token", "token": "long-random-string" }
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "groups": { "*": { "requireMention": true } }
    }
  }
}

Multi-User (Family/Team)


{
  "session": {
    "dmScope": "per-channel-peer"
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+1234567890", "+0987654321"]
    }
  }
}

Remote Gateway (Tailscale)


moltbot gateway --bind tailnet --token your-secret-token

Config:


{
  "gateway": {
    "bind": "tailnet",
    "auth": { "mode": "token", "token": "your-secret-token" }
  }
}

Workspace Setup

Your workspace is where skills, prompts, and agent state live. Default: ~/clawd


cd ~/clawd
git init  # Track your customization

Add skills, templates, memories—whatever you need. Keep it in git so you don’t lose your setup.

Auth Profiles

Located at: ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json

Stores:

API keys (Anthropic, OpenAI, etc.)
OAuth tokens (Claude Pro, Codex)

Security tip: Permissions should be 600 (user-only read/write).

Troubleshooting

Gateway won’t start


moltbot doctor

This checks everything and offers fixes.

Channels not connecting


moltbot channels list

Shows channel status + any errors.

Need logs?


moltbot logs
# or
tail -f /tmp/moltbot/moltbot-$(date +%Y-%m-%d).log

Next Steps

Need help? Discord community or GitHub issues .