Clawdbot Complete Setup

Complete guide for installing and configuring Clawdbot, a personal AI assistant that runs 24/7 and integrates with messaging channels, Gmail, and browser automation.

Prerequisites

• Node.js ≥22 installed
• npm, pnpm, or bun package manager
• macOS, Linux, or Windows (WSL2 recommended)
• Telegram account (for bot setup)
• Google account (for Gmail integration, optional)
• Composio API key (for Gmail, optional)

Phase 1: Core Installation

Install Clawdbot

npm install -g clawdbot@latest
# or: pnpm add -g clawdbot@latest

Initialize Configuration

clawdbot setup

This creates:

• Config: ~/.clawdbot/clawdbot.json
• Workspace: ~/clawd
• Sessions directory

Configure Gateway

clawdbot config set gateway.mode local
clawdbot config set gateway.bind loopback
clawdbot config set gateway.port 18789

Install Gateway Daemon

clawdbot onboard --install-daemon --non-interactive --accept-risk

This installs the gateway as a background service (LaunchAgent on macOS, systemd on Linux).

Phase 2: Model Configuration

Option A: Google Gemini (Recommended for Cost)

# Set primary model
clawdbot config set agents.defaults.model.primary "google/gemini-3-pro-preview"

# Configure model aliases
clawdbot config set agents.defaults.models."google/gemini-3-pro-preview".alias "gemini"
clawdbot config set agents.defaults.models."google/gemini-3-flash-preview".alias "gemini-flash"

# Add API key
clawdbot config set env.GEMINI_API_KEY "YOUR_GEMINI_API_KEY"

Get API key: https://aistudio.google.com/apikey

Option B: Anthropic Claude

clawdbot config set agents.defaults.model.primary "anthropic/claude-opus-4-5"
# Then configure credentials:
clawdbot models configure

Get API key: https://console.anthropic.com/

Verify Model

clawdbot models list
clawdbot agent --message "Hello" --agent main

Phase 3: Telegram Bot Setup

Create Telegram Bot

1. Open Telegram, search @BotFather
2. Send /newbot
3. Name your bot (e.g., "MyAssistant")
4. Choose username ending in "bot" (e.g., "myassistant_bot")
5. Copy the bot token

Get Your User ID

1. Search @userinfobot or @useridbot on Telegram
2. Start the bot
3. Copy your user ID (numeric)

Configure Telegram Channel

# Add Telegram channel
clawdbot channels add --channel telegram --token "YOUR_BOT_TOKEN"

# Set security (restrict to your user ID)
clawdbot config set channels.telegram.allowFrom '["YOUR_USER_ID"]'
clawdbot config set channels.telegram.dmPolicy "pairing"

Approve Pairing (if needed)

When you first message the bot, you'll get a pairing code. Approve it:

clawdbot pairing approve telegram PAIRING_CODE

Verify Telegram

clawdbot channels status
clawdbot health

Should show: Telegram: ok (@your_bot_name)

Phase 4: Gmail Integration (Composio)

Install Composio SDK

pip3 install composio

Setup Gmail Connection

1. Get Composio API key from https://platform.composio.dev/
2. Connect Gmail account on Composio dashboard
3. Note the connected account ID (starts with ca_)

Create MCP Server

from composio import Composio

composio = Composio(api_key="YOUR_COMPOSIO_API_KEY")

# Create MCP server for Gmail
mcp_server = composio.mcp.create(
    name="clawdbot-gmail-server",
    toolkits=[{"toolkit": "gmail"}],
    allowed_tools=[
        "GMAIL_FETCH_EMAILS",
        "GMAIL_SEND_EMAIL",
        "GMAIL_CREATE_DRAFT",
        "GMAIL_LIST_LABELS",
        "GMAIL_GET_EMAIL"
    ]
)

# Generate user URL
mcp_instance = composio.mcp.generate(
    user_id="clawdbot-user",
    mcp_config_id=mcp_server.id
)

Add Composio to Clawdbot Config

clawdbot config set env.COMPOSIO_API_KEY "YOUR_COMPOSIO_API_KEY"

Alternative: Using gog CLI

# Install gog
brew install steipete/tap/gogcli

# Authorize Gmail
gog auth credentials /path/to/client_secret.json
gog auth add your-email@gmail.com --services gmail

Phase 5: Browser Extension Setup

Install Extension

clawdbot browser extension install

This installs to: ~/.clawdbot/browser/chrome-extension

Load in Chrome

1. Open Chrome → chrome://extensions
2. Enable "Developer mode" (top right)
3. Click "Load unpacked"
4. Select: ~/.clawdbot/browser/chrome-extension
5. Pin the extension to toolbar

Use Extension

1. Open the tab you want to control (e.g., Gmail)
2. Click the Clawdbot extension icon
3. Badge shows "ON" when attached
4. Bot can now control that tab

Browser Status

clawdbot browser status

Should show:

• profile: chrome
• enabled: true
• controlUrl: http://127.0.0.1:18791
• cdpUrl: http://127.0.0.1:18792

Phase 6: Verification & Testing

Check System Status

clawdbot status
clawdbot health
clawdbot doctor

Test Telegram Bot

Message your bot on Telegram:

• "Hello, are you working?"
• "check my last 10 emails"
• "what can you do?"

Test Gmail Access

With browser extension attached to Gmail tab:

• "check my last 10 emails"
• "show me unread emails"
• "which emails need a response?"

Common Issues & Fixes

Gateway Won't Start

Error: hooks.enabled requires hooks.token

Fix: Disable hooks if not using webhooks:

clawdbot config set hooks.enabled false
clawdbot gateway restart

Telegram Not Responding

Check:

1. Gateway is running: clawdbot health
2. Bot token is correct: clawdbot channels status
3. User ID is in allowlist: clawdbot config get channels.telegram.allowFrom
4. Pairing was approved: Check ~/.clawdbot/credentials/telegram-pairing.json

Fix: Restart gateway and verify config:

clawdbot gateway restart
clawdbot channels status

Browser Extension Shows "!"

Error: Extension badge shows "!" (relay not reachable)

Fix:

1. Ensure gateway is running: clawdbot health
2. Check browser status: clawdbot browser status
3. Verify relay is running (auto-started by gateway on port 18792)

Model Not Responding

Check:

1. API key is set: clawdbot config get env.GEMINI_API_KEY (or ANTHROPIC_API_KEY)
2. Model is configured: clawdbot models list
3. Test directly: clawdbot agent --message "test" --agent main

Fix: Verify API key and restart gateway:

clawdbot config set env.GEMINI_API_KEY "YOUR_KEY"
clawdbot gateway restart

Gmail Not Accessible

Check:

1. Composio account is connected: Check Composio dashboard
2. MCP server is created: Verify in Composio dashboard
3. Browser extension is attached: Badge shows "ON" on Gmail tab

Fix: Re-attach extension to Gmail tab and verify connection

Configuration Files

• Main config: ~/.clawdbot/clawdbot.json
• Workspace: ~/clawd/
• Credentials: ~/.clawdbot/credentials/
• Logs: ~/.clawdbot/logs/gateway.log

Useful Commands

# Status and health
clawdbot status
clawdbot health
clawdbot doctor

# Gateway control
clawdbot gateway restart
clawdbot gateway status

# Channel management
clawdbot channels status
clawdbot channels list

# Agent interaction
clawdbot agent --message "Your message" --agent main

# Browser control
clawdbot browser status
clawdbot browser extension path

# Configuration
clawdbot config get <key>
clawdbot config set <key> <value>

# Logs
clawdbot logs --follow
tail -f ~/.clawdbot/logs/gateway.log

Security Best Practices

1. Telegram Security:

   • Always set allowFrom with your user ID
   • Use dmPolicy: "pairing" for additional security
   • Run clawdbot doctor to check for security issues

2. Browser Extension:

   • Only attach when needed
   • Detach when done
   • Consider using a dedicated Chrome profile

3. API Keys:

   • Store in config (encrypted by system keyring)
   • Never commit to git
   • Rotate if compromised

4. Gateway:

   • Keep on loopback (127.0.0.1) for local use
   • Use Tailscale Serve/Funnel for remote access
   • Require token authentication

Next Steps After Setup

1. Test basic functionality: Message bot on Telegram
2. Connect Gmail: Set up Composio or gog CLI
3. Install browser extension: For web automation
4. Add more channels: WhatsApp, Slack, Discord
5. Configure skills: Install additional capabilities
6. Set up automation: Cron jobs, webhooks

Resources

• Documentation: https://docs.clawd.bot
• Getting Started: https://docs.clawd.bot/start/getting-started
• Configuration Reference: https://docs.clawd.bot/gateway/configuration
• Troubleshooting: https://docs.clawd.bot/help/troubleshooting
• GitHub: https://github.com/clawdbot/clawdbot

Quick Setup Checklist

• Clawdbot installed globally
• Gateway daemon installed and running
• Model configured (Gemini or Claude) with API key
• Telegram bot created and configured
• User ID added to allowlist
• Pairing approved (if required)
• Gmail connected (Composio or gog)
• Browser extension installed and loaded in Chrome
• Extension attached to Gmail tab (badge shows "ON")
• Test messages working on Telegram
• Gmail access tested and working