Configuration Wizard

The wizard (moltbot onboard) is the easiest way to get Moltbot running. It’s interactive, handles the boring stuff, and gets you to a working bot fast.

What It Does


moltbot onboard --install-daemon

You’ll answer some questions, it’ll:

Set up your gateway
Configure auth (OAuth or API keys)
Connect your channels
Install a background service (optional)
Generate security defaults

Takes like 5-10 minutes if you have your tokens ready.

The Questions

1. Gateway Mode

Local or remote?

Local: Gateway runs on this machine (most common)
Remote: Gateway runs somewhere else (VPS, homelab, whatever)

Pick local unless you know you need remote.

2. Authentication

OAuth or API keys?

OAuth — Easier. Uses your existing Claude Pro/Codex subscription
API keys — More flexible. Pay-as-you-go

For Anthropic, API keys work better. For OpenAI Codex, OAuth is smoother.

Already have Claude Code? Run claude setup-token first—wizard will find it.

3. Model Provider

Pick your AI backend:

Anthropic (Claude)
OpenAI (Codex)
Local models (Ollama)
Others

You can change this later in config.

4. Channels

What do you want to connect?

WhatsApp — QR login (wizard handles it)
Telegram — Need a bot token (BotFather )
Discord — Bot token + app ID
iMessage — macOS only
More — Mattermost, Slack, Signal, etc.

You can skip channels here and add them later.

5. Security Defaults

The wizard sets up safe defaults:

DM policy: pairing (strangers need approval)
Groups: Mention-only
Gateway auth: Token-based (auto-generated)

You can tighten/loosen this in config later.

6. Background Service

Install as a system service?

Yes (recommended): Gateway starts on boot, runs in background
No: You run it manually when needed

Mac uses launchd, Linux/WSL2 uses systemd.

7. Workspace Setup

Where do you want your agent’s workspace?

Default: ~/clawd

This is where skills, prompts, and agent state live. The wizard can bootstrap it for you.

After the Wizard

Your config file is at ~/.clawdbot/moltbot.json.

Check if it’s running:


moltbot status

Should show:

Gateway: ✓
Model: ✓
Channels: ✓

Wizard Flags

Want to skip interactive mode?


moltbot onboard --install-daemon --non-interactive

Set stuff via env:


MOLTBOT_GATEWAY_PORT=18789 \
ANTHROPIC_API_KEY=your-key \
moltbot onboard --install-daemon --non-interactive

Common Post-Wizard Tasks

Add more channels


moltbot configure --section channels

Change model provider


moltbot configure --section providers

Update gateway auth


moltbot doctor --generate-gateway-token

Re-run wizard


moltbot onboard --reset

Clears previous wizard state and starts fresh.

Troubleshooting

Wizard crashes or hangs


moltbot doctor

Service didn’t install

Manual install:


moltbot install-daemon

Can’t find your CLI

The wizard should’ve added it to PATH. If not:


export PATH="$HOME/.moltbot/bin:$PATH"

Add that to your .bashrc or .zshrc.

What Gets Created

After running the wizard:


~/.clawdbot/
├── moltbot.json           # Main config
├── credentials/           # Channel creds
│   └── whatsapp/
├── agents/                # Agent state
│   └── main/
│       ├── agent/
│       └── sessions/
└── ...

~/clawd/                   # Workspace (optional)
├── skills/
├── templates/
└── ...

Next Steps

Still stuck? Ask on Discord .