Complete setup guide for Clawdbot including installation, configuration, and development workflows.

Storage Locations

Clawdbot separates configuration from the installation:

Location	Purpose
`~/.clawdbot/workspace`	Your workspace files
`~/.clawdbot/clawdbot.json`	Main configuration
`~/.clawdbot/credentials/`	Authentication tokens

This separation allows easy updates without breaking personal configurations.

Prerequisites

Node.js >= 22
pnpm (recommended) or npm
Docker (optional, for containerized setup)

Installation Methods

Quick Install (Recommended)

curl -fsSL https://clawd.bot/install.sh | bash

Via npm

npm i -g clawdbot
clawdbot setup

Via pnpm

pnpm add -g clawdbot
clawdbot setup

Workflows

Stable Workflow (macOS App)

For most users, the macOS app provides the easiest experience:

Install - Download and launch Clawdbot.app
Onboard - Complete the setup wizard
Permissions - Grant required system access
Gateway Mode - Ensure Gateway is in Local mode
Channels - Link communication channels (WhatsApp, Telegram, etc.)
Verify - Run clawdbot health to confirm setup

Development Workflow

For contributors and advanced users:

# Clone the repository
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

# Install dependencies
pnpm install

# Start development Gateway with hot reload
pnpm gateway:watch

Configure the macOS app to Local connection mode. The app attaches to the running Gateway on the configured port (default: ws://127.0.0.1:18789).

Credential Storage

Type	Location
WhatsApp	`~/.clawdbot/credentials/whatsapp/<accountId>/creds.json`
Telegram	`~/.clawdbot/credentials/telegram/`
Sessions	`~/.clawdbot/agents/<agentId>/sessions/`
OAuth	`~/.clawdbot/credentials/oauth.json`
Logs	`/tmp/clawdbot/`

Platform Notes

macOS

The app manages the Gateway automatically via LaunchAgent.

Linux

Uses systemd user service. Enable lingering to prevent service shutdown on logout:

sudo loginctl enable-linger $USER

Windows (WSL2)

Run Clawdbot inside WSL2 with a Linux distribution. The setup is identical to Linux.

Update Strategy

Keep personal content in ~/.clawdbot/ directories separate from the installation:

# Update via npm
npm update -g clawdbot

# Or pull latest source
cd clawdbot
git pull
pnpm install

Your workspace and configuration remain intact across updates.

Health Check

Verify your installation:

clawdbot health

Expected output:

Gateway status: Running
Port: 18789
Channels: Connected
Agent: Ready

Troubleshooting

Gateway Won't Start

Check if port 18789 is in use: lsof -i :18789
Review logs: cat /tmp/clawdbot/gateway.log
Reset configuration: clawdbot configure --reset

Channel Connection Issues

Re-authenticate: clawdbot channels login
Check credentials: ls ~/.clawdbot/credentials/
Verify allowlist: Check clawdbot.json

Next Steps

Onboarding Wizard - Guided setup
Pairing - Access control
Personal Assistant - Build your assistant

Setup Guide