Moltbot Configuration Reference

This guide covers all configuration options for Moltbot, including config files, credentials, and environment variables.

Configuration Files

Main Config: ~/.clawdbot/moltbot.json

This is your primary configuration file. It uses JSON5 format (allows comments and trailing commas).

{
  // Workspace for skills, prompts, memories
  "workspace": "~/clawd",

  // Default AI model
  "defaultModel": "claude-sonnet-4-20250514",

  // Gateway settings
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1"
  },

  // Channel configurations
  "channels": {
    "telegram": {
      "enabled": true,
      "tokenFile": "~/.clawdbot/credentials/telegram-token"
    },
    "discord": {
      "enabled": true
    },
    "whatsapp": {
      "enabled": true
    },
    "slack": {
      "enabled": false
    }
  },

  // Agent settings
  "agent": {
    "name": "Moltbot",
    "systemPrompt": "You are a helpful assistant."
  }
}

Creating the Config

The config file is created automatically when you run:

moltbot setup

Or create it manually:

mkdir -p ~/.clawdbot
cat > ~/.clawdbot/moltbot.json << 'EOF'
{
  "workspace": "~/clawd",
  "defaultModel": "claude-sonnet-4-20250514"
}
EOF

Workspace: ~/clawd

Your workspace contains customizations that persist across updates:

~/clawd/
├── skills/           # Custom skills
│   └── my-skill.js
├── prompts/          # Custom prompts
│   └── system.md
├── memories/         # Conversation memories
│   └── <agentId>/
└── config/           # Additional config
    └── models.json

Recommendation: Make your workspace a private git repo for backup and versioning:

cd ~/clawd
git init
git remote add origin git@github.com:yourname/clawd-private.git

Credential Storage

Credential Locations

Credential	Location
WhatsApp session	`~/.clawdbot/credentials/whatsapp/<accountId>/creds.json`
Telegram bot token	`~/.clawdbot/credentials/telegram-token`
Discord bot token	Config/env (`DISCORD_BOT_TOKEN`)
Slack tokens	Config/env (`SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`)
Channel allowlists	`~/.clawdbot/credentials/<channel>-allowFrom.json`
Model auth profiles	`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`

Auth Profiles

For AI model authentication, create ~/.clawdbot/agents/{agentId}/agent/auth-profiles.json:

{
  "anthropic": {
    "apiKey": "sk-ant-..."
  },
  "openai": {
    "apiKey": "sk-..."
  }
}

Or use environment variables (preferred for security).

Environment Variables

Environment variables override config file settings.

Core Settings

Variable	Environment variables override config file settings.	Default
`NODE_ENV`	Environment mode	`development`
`LOG_LEVEL`	Logging verbosity	`info`
`GATEWAY_PORT`	Gateway WebSocket port	`18789`
`GATEWAY_HOST`	Gateway bind address	`127.0.0.1`

AI Provider Keys

Variable	Environment variables override config file settings.
`ANTHROPIC_API_KEY`	Anthropic (Claude) API key
`OPENAI_API_KEY`	OpenAI API key
`GOOGLE_API_KEY`	Google AI API key

Channel Tokens

Variable	Environment variables override config file settings.
`TELEGRAM_BOT_TOKEN`	Telegram bot token
`DISCORD_BOT_TOKEN`	Discord bot token
`DISCORD_APPLICATION_ID`	Discord application ID
`SLACK_BOT_TOKEN`	Slack bot OAuth token
`SLACK_APP_TOKEN`	Slack app-level token

Example .env File

# Environment
NODE_ENV=production
LOG_LEVEL=info

# Gateway
GATEWAY_PORT=18789

# AI Providers
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-...

# Channels
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHI...
DISCORD_BOT_TOKEN=MTIzNDU2Nzg5...
DISCORD_APPLICATION_ID=123456789012345678

Security: Never commit .env files to version control. Add .env to your .gitignore.

Gateway Configuration

Port Settings

Default WebSocket: ws://127.0.0.1:18789

Change via config:

{
  "gateway": {
    "port": 18790,
    "host": "0.0.0.0"
  }
}

Or environment:

GATEWAY_PORT=18790 moltbot gateway

Important: Keep the macOS app, CLI, and Gateway all using the same port!

Gateway Flags

When running the Gateway directly:

# Specify port
moltbot gateway --port 18790

# Specify config file
moltbot gateway --config /path/to/config.json

# Debug mode
DEBUG=moltbot:* moltbot gateway

Channel Configuration

{
  "channels": {
    "telegram": {
      "enabled": true,
      "tokenFile": "~/.clawdbot/credentials/telegram-token",
      "replyToMode": "thread",
      "allowedChats": [123456789, -987654321]
    }
  }
}

Discord

{
  "channels": {
    "discord": {
      "enabled": true,
      "replyToMode": "thread",
      "allowedGuilds": ["123456789"],
      "allowedChannels": ["987654321"]
    }
  }
}

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": "~/.clawdbot/credentials/whatsapp-allowFrom.json"
    }
  }
}

Allowlist file format:

{
  "numbers": ["+1234567890"],
  "groups": ["Family Group"]
}

Slack

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "allowedChannels": ["C123456"]
    }
  }
}

Agent Configuration

{
  "agent": {
    "name": "Moltbot",
    "systemPrompt": "You are a helpful AI assistant.",
    "defaultModel": "claude-sonnet-4-20250514",
    "maxTokens": 4096,
    "temperature": 0.7
  }
}

Option	Description	Default
`name`	Agent display name	`Moltbot`
`systemPrompt`	Base system prompt	Built-in
`defaultModel`	AI model to use	`claude-sonnet-4-20250514`
`maxTokens`	Max response tokens	`4096`
`temperature`	Response randomness	`0.7`

State and Logs

Session Storage

Active sessions are stored at:

~/.clawdbot/agents/<agentId>/sessions/

Log Files

Logs are written to:

/tmp/moltbot/
├── gateway.log
├── error.log
└── <channel>.log

Or view via journalctl (Linux):

journalctl --user -u moltbot -f

Configuration Precedence

Settings are loaded in this order (later overrides earlier):

Built-in defaults
~/.clawdbot/moltbot.json
Environment variables
Command-line flags

Validating Configuration

Check your config for errors:

moltbot config validate

View effective config:

moltbot config show

Backup Recommendations

What to back up:

Path	Contains	Priority
`~/.clawdbot/moltbot.json`	Main config	High
`~/.clawdbot/credentials/`	All credentials	High
`~/clawd/`	Workspace	High
`~/.clawdbot/agents/`	Sessions, memories	Medium

Simple backup script:

#!/bin/bash
tar -czf moltbot-backup-$(date +%Y%m%d).tar.gz \
  ~/.clawdbot \
  ~/clawd

Next Steps

Channel Integration

Connect messaging platforms

View guide

Security Guide

Protect your credentials

View guide

Gateway Runbook

Advanced Gateway operations

View guide

Moltbot Configuration Reference

Configuration Files

Main Config: ~/.clawdbot/moltbot.json

Creating the Config

Workspace: ~/clawd

Credential Storage

Credential Locations

Auth Profiles

Environment Variables

Core Settings

AI Provider Keys

Channel Tokens

Example .env File

Gateway Configuration

Port Settings

Gateway Flags

Channel Configuration

Telegram

Discord

WhatsApp

Slack

Agent Configuration

State and Logs

Session Storage

Log Files

Configuration Precedence

Validating Configuration

Backup Recommendations

Next Steps

Channel Integration

Security Guide

Gateway Runbook

Related