ZeroClaw
Rust-based autonomous AI assistant infrastructure. Runtime OS for agentic workflows — deploy anywhere, swap anything. Runs on <5MB RAM, <10ms startup, ~8.8MB binary.
When to Use
- Setting up ZeroClaw from scratch (install, bootstrap, onboard)
- Authoring or debugging
config.toml (providers, channels, memory, security)
- Binding channels (Matrix, Discord, Slack, IRC, webhooks)
- Troubleshooting CLI errors, auth failures, or daemon issues
- Migrating from OpenClaw or other agent frameworks
- Deploying via Docker, native binary, or webhook gateway
When NOT to Use
- Other agent frameworks (LangChain, AutoGPT) — different architecture
- General Rust development unrelated to ZeroClaw
Quick Reference
| Command |
Purpose |
zeroclaw onboard --interactive |
First-time setup wizard |
zeroclaw agent -m "msg" |
Single message |
zeroclaw agent |
Interactive REPL |
zeroclaw daemon |
Full autonomous runtime + channels |
zeroclaw gateway |
Webhook server (default :42617) |
zeroclaw status |
Check daemon & config |
zeroclaw doctor |
System diagnostics |
zeroclaw channel doctor |
Channel health check |
zeroclaw channel bind-telegram <id> |
Bind Telegram chat |
zeroclaw providers |
List available providers |
zeroclaw auth login --provider <p> --device-code |
OAuth login |
zeroclaw auth setup-token --provider <p> |
Token auth |
zeroclaw service install |
Install as system service |
zeroclaw migrate openclaw --dry-run |
Preview migration |
zeroclaw completions <shell> |
Shell completions |
Installation
# Homebrew
brew install zeroclaw
# Bootstrap (local clone)
git clone https://github.com/zeroclaw-labs/zeroclaw.git && cd zeroclaw && ./bootstrap.sh
# Remote bootstrap
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash
# From source
cargo build --release --locked && cargo install --path . --force --locked
# Pre-built binaries: GitHub Releases (Linux x86_64/aarch64/armv7, macOS, Windows)
# Bootstrap flags: --prefer-prebuilt, --prebuilt-only, --docker
Build requirements: 2GB+ RAM+swap, 6GB+ disk. Runtime: <5MB.
Configuration
Edit ~/.zeroclaw/config.toml. Core sections:
[providers]
# OpenAI, Anthropic, OpenRouter, Google, Mistral, xAI, DeepSeek, 70+ more
# Set via env: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
[memory]
backend = "sqlite" # "postgres", "markdown", "lucid", "none"
# Built-in vector search (BLOBs + cosine similarity) + FTS5 keyword search
# No external vector DB needed — hybrid merge of vector + BM25
[runtime]
kind = "native" # "docker" for sandboxed execution
[channels]
# CLI, Telegram, Discord, Slack, Matrix, Signal, IRC, Email, iMessage,
# WhatsApp, Mattermost, Lark, DingTalk, QQ, Linq, Nostr, Webhook
[security]
# allowlists, pairing, rate_limits, filesystem_scoping
[autonomy]
level = "full" # "supervised" (default) or "full"
max_actions_per_hour = 999999 # ⚠️ MUST be > 0 or daemon silently fails
max_cost_per_day_cents = 999999 # same
require_approval_for_medium_risk = false
block_high_risk_commands = false
Architecture
Trait-driven — every subsystem is swappable:
| Layer |
Swappable Options |
| Providers |
OpenAI, Anthropic, OpenRouter, Google, custom endpoints |
| Channels |
18+ (CLI, Telegram, Discord, Slack, Matrix, etc.) |
| Memory |
SQLite (default), PostgreSQL, Markdown, Lucid, none |
| Tools |
Shell, file ops, Git, HTTP, screenshots, browser |
| Runtime |
Native, Docker sandbox |
Authentication
OPENAI_API_KEY=sk-... zeroclaw agent # env var
zeroclaw auth login --provider openai-codex --device-code # OAuth device flow
zeroclaw auth paste-token --provider anthropic --profile default # token paste
Profiles stored encrypted at ~/.zeroclaw/auth-profiles.json (key: ~/.zeroclaw/.secret_key). Manage with auth use, auth status, auth refresh (see Quick Reference).
WARNING (Feb 2026): Claude Code OAuth tokens (Free/Pro/Max) are restricted to Claude Code/Claude.ai only. Do NOT use them via ZeroClaw — violates Anthropic ToS.
Memory System
Built-in full-stack search engine (no external vector DB):
- Vector: Embeddings as BLOBs in SQLite, cosine similarity
- Keyword: FTS5 virtual tables, BM25 scoring
- Hybrid: Weighted merge of vector + keyword results
- Embeddings: OpenAI, custom URL, or noop
- Chunking: Line-based markdown with heading preservation
- Cache: SQLite LRU embedding cache
- Reindex: Atomic FTS5 rebuild + missing vector re-embedding
The agent manages memory automatically via built-in tools.
Common Patterns
Deploy as daemon with Telegram
zeroclaw onboard --interactive # configure provider + channel
zeroclaw channel bind-telegram 123456 # bind chat ID
zeroclaw daemon # start autonomous runtime
Webhook gateway
zeroclaw gateway --port 8080 # or --port 0 for random
Docker sandbox
# config.toml
[runtime]
kind = "docker"
Migration from OpenClaw
zeroclaw migrate openclaw --dry-run # preview changes
zeroclaw migrate openclaw # execute migration
Troubleshooting
| Issue |
Fix |
| Build OOM |
Use --prefer-prebuilt or add swap (need 2GB+) |
| Channel not responding |
zeroclaw channel doctor |
| Auth expired |
zeroclaw auth refresh --provider <p> |
| Config issues |
zeroclaw doctor |
| Gateway unreachable |
Check port binding, firewall, pairing config |
| Memory search poor |
Check embedding provider config, run reindex |
| Config schema JSON parse fails |
zeroclaw config schema mixes INFO log lines with JSON — save to file and strip the log line first |
| Config changes not applied |
zeroclaw service restart (or zeroclaw service stop && zeroclaw service start) then zeroclaw doctor |
Common Mistakes
| Mistake |
Fix |
| Editing config while daemon is running |
Stop daemon first: zeroclaw daemon stop |
| Missing provider API key in config |
Set via zeroclaw auth add <provider> or env var |
| Using file paths in channel webhooks |
Use full URLs with protocol (https://...) |
Skipping zeroclaw onboard |
Required for initial profile + provider setup |
| Running without memory backend configured |
Defaults work but set explicit backend for production |
Security
Supports gateway pairing, Docker sandboxing, allowlists (tools/files/channels), rate limiting, filesystem scoping, and encrypted secrets at rest.
1---2name: zeroclaw3description: Use when building, configuring, deploying, or troubleshooting ZeroClaw AI agent infrastructure — including provider setup, channel binding, memory backends, config.toml authoring, CLI usage, Docker/native runtime, and migration from other agent frameworks4---56# ZeroClaw78Rust-based autonomous AI assistant infrastructure. Runtime OS for agentic workflows — deploy anywhere, swap anything. Runs on <5MB RAM, <10ms startup, ~8.8MB binary.910- Repo: https://github.com/zeroclaw-labs/zeroclaw11- Docs: https://github.com/zeroclaw-labs/zeroclaw/blob/main/docs/README.md1213## When to Use1415- Setting up ZeroClaw from scratch (install, bootstrap, onboard)16- Authoring or debugging `config.toml` (providers, channels, memory, security)17- Binding channels (Matrix, Discord, Slack, IRC, webhooks)18- Troubleshooting CLI errors, auth failures, or daemon issues19- Migrating from OpenClaw or other agent frameworks20- Deploying via Docker, native binary, or webhook gateway2122## When NOT to Use2324- Other agent frameworks (LangChain, AutoGPT) — different architecture25- General Rust development unrelated to ZeroClaw2627## Quick Reference2829| Command | Purpose |30|---------|---------|31| `zeroclaw onboard --interactive` | First-time setup wizard |32| `zeroclaw agent -m "msg"` | Single message |33| `zeroclaw agent` | Interactive REPL |34| `zeroclaw daemon` | Full autonomous runtime + channels |35| `zeroclaw gateway` | Webhook server (default :42617) |36| `zeroclaw status` | Check daemon & config |37| `zeroclaw doctor` | System diagnostics |38| `zeroclaw channel doctor` | Channel health check |39| `zeroclaw channel bind-telegram <id>` | Bind Telegram chat |40| `zeroclaw providers` | List available providers |41| `zeroclaw auth login --provider <p> --device-code` | OAuth login |42| `zeroclaw auth setup-token --provider <p>` | Token auth |43| `zeroclaw service install` | Install as system service |44| `zeroclaw migrate openclaw --dry-run` | Preview migration |45| `zeroclaw completions <shell>` | Shell completions |4647## Installation4849```bash50# Homebrew51brew install zeroclaw5253# Bootstrap (local clone)54git clone https://github.com/zeroclaw-labs/zeroclaw.git && cd zeroclaw && ./bootstrap.sh5556# Remote bootstrap57curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash5859# From source60cargo build --release --locked && cargo install --path . --force --locked6162# Pre-built binaries: GitHub Releases (Linux x86_64/aarch64/armv7, macOS, Windows)63# Bootstrap flags: --prefer-prebuilt, --prebuilt-only, --docker64```6566**Build requirements:** 2GB+ RAM+swap, 6GB+ disk. Runtime: <5MB.6768## Configuration6970Edit `~/.zeroclaw/config.toml`. Core sections:7172```toml73[providers]74# OpenAI, Anthropic, OpenRouter, Google, Mistral, xAI, DeepSeek, 70+ more75# Set via env: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.7677[memory]78backend = "sqlite" # "postgres", "markdown", "lucid", "none"79# Built-in vector search (BLOBs + cosine similarity) + FTS5 keyword search80# No external vector DB needed — hybrid merge of vector + BM258182[runtime]83kind = "native" # "docker" for sandboxed execution8485[channels]86# CLI, Telegram, Discord, Slack, Matrix, Signal, IRC, Email, iMessage,87# WhatsApp, Mattermost, Lark, DingTalk, QQ, Linq, Nostr, Webhook8889[security]90# allowlists, pairing, rate_limits, filesystem_scoping9192[autonomy]93level = "full" # "supervised" (default) or "full"94max_actions_per_hour = 999999 # ⚠️ MUST be > 0 or daemon silently fails95max_cost_per_day_cents = 999999 # same96require_approval_for_medium_risk = false97block_high_risk_commands = false98```99100101## Architecture102103**Trait-driven — every subsystem is swappable:**104105| Layer | Swappable Options |106|-------|-------------------|107| **Providers** | OpenAI, Anthropic, OpenRouter, Google, custom endpoints |108| **Channels** | 18+ (CLI, Telegram, Discord, Slack, Matrix, etc.) |109| **Memory** | SQLite (default), PostgreSQL, Markdown, Lucid, none |110| **Tools** | Shell, file ops, Git, HTTP, screenshots, browser |111| **Runtime** | Native, Docker sandbox |112113## Authentication114115```bash116OPENAI_API_KEY=sk-... zeroclaw agent # env var117zeroclaw auth login --provider openai-codex --device-code # OAuth device flow118zeroclaw auth paste-token --provider anthropic --profile default # token paste119```120121Profiles stored encrypted at `~/.zeroclaw/auth-profiles.json` (key: `~/.zeroclaw/.secret_key`). Manage with `auth use`, `auth status`, `auth refresh` (see Quick Reference).122123**WARNING (Feb 2026):** Claude Code OAuth tokens (Free/Pro/Max) are restricted to Claude Code/Claude.ai only. Do NOT use them via ZeroClaw — violates Anthropic ToS.124125## Memory System126127Built-in full-stack search engine (no external vector DB):128129- **Vector**: Embeddings as BLOBs in SQLite, cosine similarity130- **Keyword**: FTS5 virtual tables, BM25 scoring131- **Hybrid**: Weighted merge of vector + keyword results132- **Embeddings**: OpenAI, custom URL, or noop133- **Chunking**: Line-based markdown with heading preservation134- **Cache**: SQLite LRU embedding cache135- **Reindex**: Atomic FTS5 rebuild + missing vector re-embedding136137The agent manages memory automatically via built-in tools.138139## Common Patterns140141### Deploy as daemon with Telegram142```bash143zeroclaw onboard --interactive # configure provider + channel144zeroclaw channel bind-telegram 123456 # bind chat ID145zeroclaw daemon # start autonomous runtime146```147148### Webhook gateway149```bash150zeroclaw gateway --port 8080 # or --port 0 for random151```152153### Docker sandbox154```toml155# config.toml156[runtime]157kind = "docker"158```159160### Migration from OpenClaw161```bash162zeroclaw migrate openclaw --dry-run # preview changes163zeroclaw migrate openclaw # execute migration164```165166## Troubleshooting167168| Issue | Fix |169|-------|-----|170| Build OOM | Use `--prefer-prebuilt` or add swap (need 2GB+) |171| Channel not responding | `zeroclaw channel doctor` |172| Auth expired | `zeroclaw auth refresh --provider <p>` |173| Config issues | `zeroclaw doctor` |174| Gateway unreachable | Check port binding, firewall, pairing config |175| Memory search poor | Check embedding provider config, run reindex |176| Config schema JSON parse fails | `zeroclaw config schema` mixes INFO log lines with JSON — save to file and strip the log line first |177| Config changes not applied | `zeroclaw service restart` (or `zeroclaw service stop && zeroclaw service start`) then `zeroclaw doctor` |178179## Common Mistakes180181| Mistake | Fix |182|---------|-----|183| Editing config while daemon is running | Stop daemon first: `zeroclaw daemon stop` |184| Missing provider API key in config | Set via `zeroclaw auth add <provider>` or env var |185| Using file paths in channel webhooks | Use full URLs with protocol (`https://...`) |186| Skipping `zeroclaw onboard` | Required for initial profile + provider setup |187| Running without memory backend configured | Defaults work but set explicit backend for production |188189## Security190191Supports gateway pairing, Docker sandboxing, allowlists (tools/files/channels), rate limiting, filesystem scoping, and encrypted secrets at rest.
Lu1sDV