Getting Started with Clawdbot: A Complete Onboarding Guide with Ollama
Clawdbot is an open-source AI assistant that runs on your infrastructure. Unlike cloud-only assistants, it keeps your data local, works across multiple messaging platforms (WhatsApp, Telegram, Discord, Signal), and gives you full control over which AI models power your conversations.
This guide walks you through setting up Clawdbot for the first time and configuring it to use Ollama as your local model provider — keeping everything on your machine while maintaining access to powerful AI capabilities.
What You’ll Need
• macOS, Linux, or Windows (WSL recommended for Windows)
• Node.js 20+ and npm
• Ollama installed locally
• A reasonably powerful machine (16GB+ RAM recommended; GPU optional but helpful)
Step 1: Install Clawdbot
The quickest way to get started is via npm:
npm install -g clawdbot
Or use the installer script:
curl -fsSL https://clawd.bot/install | bash
Verify the installation:
clawdbot --version
Step 2: Run the Onboarding Wizard
Clawdbot includes an interactive wizard that sets up your configuration and agent workspace:
clawdbot onboard
You’ll be guided through:
• Gateway setup: The daemon that connects to messaging platforms • Authentication: Generate or provide a gateway token • Workspace creation: Where your agent’s files, memory, and configuration live For a minimal setup, use the quickstart flow:
clawdbot onboard --flow quickstart
This auto-generates everything needed to start chatting immediately.
Step 3: Install and Configure Ollama
Before connecting Clawdbot, ensure Ollama is running with a suitable model:
Install Ollama (macOS/Linux)
curl -fsSL https://ollama.com/install.sh | sh
Pull a capable model (Mistral, Llama 3.1, or similar)
ollama pull mistral:latest
Start the Ollama server (if not already running)
ollama serve
By default, Ollama runs on http://127.0.0.1:11434 and exposes an OpenAI-compatible API.
Step 4: Configure Clawdbot to Use Ollama
Edit your Clawdbot configuration file (located at ~/.clawdbot/moltbot.json or your workspace):
{
"agents": {
"defaults": {
"model": {
"primary": "ollama/mistral:latest"
},
"models": {
"ollama/mistral:latest": {
"alias": "Mistral Local"
}
}
}
},
"models": {
"mode": "merge",
"providers": {
"ollama": {
"baseUrl": "http://127.0.0.1:11434/v1",
"apiKey": "ollama",
"api": "openai-responses",
"models": [
{
"id": "mistral:latest",
"name": "Mistral Local",
"reasoning": false,
"input": ["text"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 32000,
"maxTokens": 4096
}
]
}
}
}
}
Key configuration points:
• baseUrl : Ollama’s OpenAI-compatible endpoint (default: http://127.0.0.1:11434/v1 )
• api : Use “openai-responses” for cleaner output handling
• contextWindow : Set based on your model’s actual limits
• mode: “merge” : Allows fallback to cloud providers if Ollama becomes unavailable
Besides, Ollama also provides a specific command to set it up:
- ollama launch clawdbot — Configures Clawdbot to use Ollama AND starts the gateway in one step
- ollama launch clawdbot --config — Just configures without launching
Step 5: Connect a Messaging Channel
WhatsApp (Recommended for Mobile Access)
clawdbot gateway start --channel whatsapp
A QR code will appear. Scan it with WhatsApp on your phone (Linked Devices → Link a Device). Your personal WhatsApp account now messages with your local AI.
Telegram Bot
Create a bot via @BotFather, then:
clawdbot gateway start --channel telegram --token YOUR_BOT_TOKEN
Discord
Create a bot in the Discord Developer Portal, enable Message Content Intent, and:
clawdbot gateway start --channel discord --token YOUR_BOT_TOKEN
Step 6: Verify Everything Works
1. Check gateway status:
clawdbot gateway status
2. Test model connectivity:
curl http://127.0.0.1:11434/v1/models
3. Send a test message via your connected channel. You should see responses powered by your local Ollama model.
Pro Tips for Local Model Usage
Hybrid Setup: Local Primary, Cloud Fallback
Keep cloud models as backups for when Ollama is offline or overwhelmed:
{
"agents": {
"defaults": {
"model": {
"primary": "ollama/mistral:latest",
"fallbacks": ["anthropic/claude-sonnet-4", "openai/gpt-4o-mini"]
}
}
}
}
Performance Optimization
• Keep models loaded: Ollama unloads models after a timeout. For faster responses, set OLLAMA_KEEP_ALIVE=24h when running ollama serve.
• Context management: Lower contextWindow if you experience slowdowns. Start with 8K-16K tokens.
• Quantization: Use q4_K_M or q5_K_M quantized models for good quality with lower memory usage.
Security Considerations
Local models bypass cloud safety filters. To mitigate risks:
• Keep agent capabilities narrow (limit tool access via capabilities config)
• Enable session compaction to prevent context window attacks
• Review the agent’s SOUL.md to define appropriate boundaries
Troubleshooting
“Connection refused” to Ollama • Solution: Verify ollama serve is running and listening on the correct port
Gateway won’t start • Solution: Check clawdbot doctor for diagnostic output
Slow responses • Solution: Use a smaller model, enable GPU acceleration, or reduce contextWindow
Model not found • Solution: Ensure you’ve run ollama pull modelname and the model ID matches in config
No messages received • Solution: Verify channel token/QR code and check clawdbot gateway logs
Next Steps
• Customize your agent: Edit files in your workspace ( ~/clawd by default) to shape personality and capabilities
• Add skills: Run clawdbot skills to browse installable capabilities like weather, web search, or home automation
• Explore the dashboard: Run clawdbot dashboard for a web-based control interface
• Set up cron jobs: Use clawdbot cron for scheduled tasks and proactive notifications
Resources:
• Ollama Clawdbot Integration
Enjoy your fully private, locally-powered AI assistant! 🤖
Comments