Zeroclaw

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.

• Repo: https://github.com/zeroclaw-labs/zeroclaw
• Docs: https://github.com/zeroclaw-labs/zeroclaw/blob/main/docs/README.md

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.