OpenClaw: Complete Guide to Local AI Assistant
OpenClaw is an open-source AI assistant that lives on your machine and integrates with your communication channels. Mascot β lobster π¦. Key feature: data never leaves your box, only LLM API calls go out.
1. Architecture & Philosophy
- Core: Rust (fast, safe, cross-platform)
- Plugins: TypeScript / Python (easy to extend)
- LLM Adapters: OpenAI, Anthropic, Ollama, llama.cpp, LM Studio, vLLM, OpenRouter
- Transports: Telegram, WhatsApp (Baileys), Discord, Slack, Matrix, local CLI, web UI
- Tools: filesystem, calendar, browser (Playwright), terminal, Git, Docker, SQL, HTTP client
Repository: github.com/openclaw/openclaw (394k β )
2. Quick Start (5 minutes)
Prerequisites
- Rust 1.75+ (
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh) - Node.js 20+ (for plugins and web UI)
- Git
- Optional: Ollama (
curl -fsSL https://ollama.ai/install.sh | sh) for local models
Installation
git clone https://github.com/openclaw/openclaw
cd openclaw
./install.sh # installs deps, configures, builds
# First run β interactive setup wizard
openclaw
The wizard asks:
- LLM Provider β OpenAI / Anthropic / Ollama / OpenRouter / Custom
- Model β gpt-4o, claude-3.5-sonnet, llama3.1, nemotron, etc.
- Messengers β Telegram Bot Token, WhatsApp (QR), Discord Bot Token, Slack App
- Permissions β which folders/files the agent can read/write
- Tools β which to enable (files, browser, terminal, calendar)
3. LLM Provider Setup
OpenAI / Anthropic / OpenRouter
# In wizard select provider, paste API key
# OpenRouter gives access to 100+ models with one key
# Free models: pick ones with :free suffix
Local Models via Ollama (Recommended for Privacy)
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
# Pull models
ollama pull llama3.1:8b # fast, smart
ollama pull nemotron3:8b # great for coding
ollama pull qwen2.5:7b # good multilingual
ollama pull codellama:7b # code-specialized
In OpenClaw wizard select "Ollama" β pick model from list.
llama.cpp (Even Faster on CPU)
# OpenClaw supports llama.cpp directly
# Point to .gguf file in settings
4. Messenger Setup
Telegram Bot
- Create bot at @BotFather β
/newbot - Copy token
- In OpenClaw wizard: select Telegram β paste token
- Done! Message bot /start
WhatsApp (via Baileys)
- In wizard select WhatsApp
- Scan QR code in terminal with phone
- Session saves automatically
Discord Bot
- Create app at Discord Developer Portal
- Bot β Reset Token β copy
- Enable Privileged Gateway Intents (Message Content, Server Members)
- Invite to server (OAuth2 β bot + applications.commands)
- In wizard: Discord β token
Slack App
- Create App at api.slack.com/apps
- OAuth & Permissions β Bot Token Scopes: chat:write, channels:read, groups:read, im:read, mpim:read
- Install to Workspace
- In wizard: Slack β Bot User OAuth Token
5. Tools β What the Lobster Can Do
| Tool | What It Does | Example |
|---|---|---|
| Filesystem | Read/write/search files | "Find all TODOs in project", "Create README.md" |
| Terminal | Execute shell commands | "Run tests", "git status", "docker ps" |
| Browser | Playwright automation | "Open GitHub PR #42 and summarize", "Screenshot page" |
| Calendar | Google Cal / CalDAV / local | "What's tomorrow?", "Create meeting at 3PM" |
| Git | Git operations | "Create branch feature/x", "Commit with message..." |
| Docker | Container management | "Restart postgres", "Logs of api container" |
| SQL | Database queries | "Show last 10 users" |
| HTTP | REST/GraphQL requests | "Call weather API for Moscow" |
Tools enabled/disabled in wizard or ~/.config/openclaw/tools.toml.
6. Skills β Procedural Memory
Skills in OpenClaw are Markdown files with YAML frontmatter (like Hermes), loaded on trigger.
# ~/.config/openclaw/skills/my-deploy.md
---
name: my-deploy
description: "Use when user wants to deploy to production. Runs full pipeline."
tools: [Terminal, Git, HTTP]
---
Deploy procedure:
1. Run tests: npm run test
2. Build: npm run build
3. Check bundle size
4. Deploy: npm run deploy
5. Verify: curl https://myapp.com/health
6. Notify in Telegram: "Deploy done!"
Rollback on failure:
- git revert HEAD
- npm run deploy
- Notify: "Rollback done"
Place file in ~/.config/openclaw/skills/ β agent picks it up automatically.
7. Advanced Configuration
Main config: ~/.config/openclaw/config.toml
[agent]
name = "Claw"
personality = "helpful, concise, slightly sarcastic"
language = "en"
[llm]
provider = "ollama"
model = "llama3.1:8b"
temperature = 0.3
max_tokens = 4096
[tools]
filesystem = { enabled = true, allowed_paths = ["/home/user/projects", "/home/user/docs"] }
terminal = { enabled = true, allow_sudo = false }
browser = { enabled = true, headless = true }
calendar = { enabled = true, provider = "google", credentials = "/path/to/creds.json" }
[memory]
type = "sqlite"
path = "~/.config/openclaw/memory.db"
retention_days = 365
[privacy]
telemetry = false
local_only = true # blocks external calls except LLM
8. Comparison: OpenClaw vs Hermes vs Claude Code
| Feature | OpenClaw | Hermes Agent | Claude Code |
|---|---|---|---|
| Runs on | Local (your PC/server) | Local (Python) | Local (Node/Rust CLI) |
| Messengers | β WhatsApp, Telegram, Discord, Slack | β Telegram (built-in) | β Terminal only |
| Customization | TS/Python plugins, TOML config | Skills (Markdown+YAML) | Subagents, hooks, slash-cmds |
| Tools | Files, terminal, browser, calendar, Git, Docker, SQL | Browser, terminal, search, GitHub | Files, terminal, bash, MCP |
| Memory | SQLite (long-term) + context | SQLite (skills + facts) | CLAUDE.md + context |
| Privacy | Maximum (local-only mode) | High | Depends on settings |
| Coding | Via tools (terminal, LSP) | Via skills | Native code work |
| Learning curve | Medium (setup wizard) | Low (pip install) | Low (npm install) |
| Best for | Personal assistant in messengers, life automation | Task orchestration in chat, skills | Code work in repo, CI/CD |
9. Common Issues & Fixes
- No reply in Telegram β check token, webhook (long polling), logs:
openclaw logs - Ollama model not found β
ollama list, verify exact name in config - WhatsApp QR won't scan β restart
openclaw, Baileys sometimes glitches - Permission denied on files β add paths to
config.tomlβtools.filesystem.allowed_paths - High memory usage β use smaller models (qwen2.5:3b, phi3:mini)
10. Useful Links
- Repository: github.com/openclaw/openclaw
- Documentation: docs.openclaw.dev
- Discord Community: discord.gg/openclaw
- Releases: GitHub Releases
- Skill Examples: examples/skills
- Plugins: plugins/
First Run Checklist
git clone && ./install.sh && openclaw- Pick LLM: Ollama (local) or OpenRouter (cloud)
- Connect at least 1 messenger (Telegram easiest)
- Enable tools: Filesystem + Terminal (baseline)
- Create 1-2 skills for your routines
- Test: "Claw, what's in my calendar tomorrow?"
