Skip to content

02 Getting Started

Jump to bottom
Nikolay Vyahhi edited this page Feb 19, 2026 · 3 revisions

Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

Purpose and Scope

This page provides a high-level overview of the ZeroClaw setup process, from prerequisites through your first agent interaction. It serves as the entry point for new users who want to understand the overall flow before diving into specific setup steps.

For detailed installation instructions including platform-specific requirements, see Installation. For a complete walkthrough of the configuration wizard, see Onboarding Wizard. For examples of common usage patterns after setup, see First Steps.

Prerequisites Overview

ZeroClaw is a native Rust application distributed as a single binary. The only hard requirement is the Rust toolchain for compilation. Optional dependencies depend on your deployment mode:

Component Required For Details
Rust toolchain (1.70+) Compilation rustc, cargo via rustup
Build essentials Compilation MSVC (Windows), build-essential (Linux), Xcode CLI (macOS)
Docker Docker runtime mode Only needed if runtime.kind = "docker"
Git Development builds For cloning the repository

Windows-specific: Requires Visual Studio Build Tools with "Desktop development with C++" workload.

Memory requirements: Release builds compile with codegen-units=1 for compatibility with 1GB RAM devices (e.g., Raspberry Pi 3). For faster builds on powerful machines, use cargo build --profile release-fast.

Sources: README.md:99-166, Cargo.toml:161-172

Getting Started Flow

flowchart TD
    Start["User starts ZeroClaw setup"]
    
    CheckRust{"Rust toolchain<br/>installed?"}
    InstallRust["Install Rust via rustup<br/>(rustup.rs)"]
    
    CloneRepo["Clone zeroclaw repo<br/>or download release binary"]
    
    BootstrapChoice{"Setup mode?"}
    QuickPath["Quick: bootstrap.sh<br/>(automated)"]
    ManualPath["Manual: cargo build"]
    
    BuildBinary["cargo build --release --locked"]
    InstallBinary["cargo install --path . --force"]
    
    OnboardChoice{"Configuration?"}
    QuickOnboard["zeroclaw onboard<br/>--api-key sk-..."]
    InteractiveOnboard["zeroclaw onboard<br/>--interactive"]
    ChannelsOnly["zeroclaw onboard<br/>--channels-only"]
    
    ConfigCreated["Config written to<br/>~/.zeroclaw/config.toml"]
    
    FirstInteraction["Test: zeroclaw agent<br/>-m 'Hello, ZeroClaw!'"]
    
    Success["Setup complete"]
    
    Start --> CheckRust
    CheckRust -->|No| InstallRust
    CheckRust -->|Yes| CloneRepo
    InstallRust --> CloneRepo
    
    CloneRepo --> BootstrapChoice
    BootstrapChoice -->|Automated| QuickPath
    BootstrapChoice -->|Manual| ManualPath
    
    QuickPath --> OnboardChoice
    ManualPath --> BuildBinary
    BuildBinary --> InstallBinary
    InstallBinary --> OnboardChoice
    
    OnboardChoice -->|Quick setup| QuickOnboard
    OnboardChoice -->|Full wizard| InteractiveOnboard
    OnboardChoice -->|Repair channels| ChannelsOnly
    
    QuickOnboard --> ConfigCreated
    InteractiveOnboard --> ConfigCreated
    ChannelsOnly --> ConfigCreated
    
    ConfigCreated --> FirstInteraction
    FirstInteraction --> Success
Loading

Getting Started Flow Diagram

Sources: README.md:169-252, bootstrap.sh:1-6, src/onboard/wizard.rs:61-196

Installation Paths

ZeroClaw supports three installation methods, each suited to different scenarios:

Bootstrap Script (Recommended)

The bootstrap script automates dependency installation, Rust setup, compilation, and optional onboarding:

# Clone and bootstrap locally (recommended for security review)
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh

# Optional: Install system dependencies and Rust
./bootstrap.sh --install-system-deps --install-rust

# Optional: Run onboarding in same flow
./bootstrap.sh --onboard --api-key "sk-..." --provider openrouter

The bootstrap script delegates to scripts/bootstrap.sh and supports toolchain initialization on fresh machines.

Sources: README.md:173-192, bootstrap.sh:1-6

Manual Cargo Build

For users who prefer explicit control or are developing ZeroClaw:

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
cargo build --release --locked
cargo install --path . --force --locked
export PATH="$HOME/.cargo/bin:$PATH"

This builds the release binary with optimization level z (size), LTO enabled, and debug symbols stripped. The resulting binary is typically 3-9 MB depending on platform and enabled features.

Sources: README.md:194-202, Cargo.toml:161-168

Pre-built Binaries

Release binaries are published for major platforms. Download from GitHub releases and place in your PATH. This skips compilation but requires manual dependency management for channels (e.g., system libraries for Telegram, Discord).

For detailed platform-specific instructions, prerequisite installation, and troubleshooting compilation issues, see Installation.

Configuration Initialization

After installation, ZeroClaw requires initial configuration stored in ~/.zeroclaw/config.toml. The zeroclaw onboard command provides three modes:

Quick Setup (Non-Interactive)

Generates sensible defaults instantly with optional API key injection:

zeroclaw onboard --api-key sk-... --provider openrouter
zeroclaw onboard --api-key sk-... --provider openrouter --memory sqlite

This mode invokes run_quick_setup() which creates:

  • Default workspace at ~/.zeroclaw/workspace
  • Config instance with supervised autonomy, workspace-scoped security, and native runtime
  • Minimal scaffold files (IDENTITY.md, AGENTS.md, etc.)
  • Memory backend selection (defaults to SQLite hybrid search)

Sources: src/onboard/wizard.rs:301-463, README.md:203-205

Interactive Wizard

The full 9-step wizard prompts for provider, channels, tunnel, tools, hardware, and memory configuration:

zeroclaw onboard --interactive

The wizard flow implemented in run_wizard() includes:

  1. Workspace Setup: Directory structure initialization
  2. Provider & API Key: Selection from 28+ built-in providers, model selection with live API fetch or cached preview
  3. Channels: Optional Telegram, Discord, Slack, Matrix, Email, WhatsApp, etc.
  4. Tunnel: Cloudflare, Tailscale, ngrok, or custom
  5. Tool Mode & Security: Composio integration, secret encryption
  6. Hardware: Physical world interaction (GPIO, serial, probe)
  7. Memory Configuration: Backend selection (SQLite, Lucid, Postgres, Markdown, None)
  8. Project Context: Personalization (agent name, timezone, communication style)
  9. Workspace Files: Scaffold OpenClaw format identity files

After completion, the wizard optionally launches channels immediately by setting ZEROCLAW_AUTOSTART_CHANNELS=1 environment variable.

Sources: src/onboard/wizard.rs:61-196

Channels-Only Repair

Reconfigure channel tokens and allowlists without re-running full onboarding:

zeroclaw onboard --channels-only

This mode loads existing Config, re-runs setup_channels() only, saves the updated configuration, and optionally launches channels. Useful for fixing authorization issues or adding new channels.

Sources: src/onboard/wizard.rs:199-255, README.md:435-438

For a complete walkthrough of the wizard steps, configuration options, and troubleshooting common setup issues, see Onboarding Wizard.

Configuration to Code Entity Mapping

flowchart LR
    subgraph "Configuration Space"
        ConfigFile["~/.zeroclaw/config.toml"]
        APIKey["api_key"]
        Provider["default_provider"]
        Model["default_model"]
        MemoryBackend["memory.backend"]
        ChannelsConfig["channels_config.*"]
    end
    
    subgraph "Code Entity Space"
        ConfigStruct["Config struct<br/>(src/config/schema.rs)"]
        ProviderTrait["Provider trait<br/>(src/providers/mod.rs)"]
        CreateProvider["create_resilient_provider()<br/>(src/providers/factory.rs)"]
        MemoryTrait["Memory trait<br/>(src/memory/mod.rs)"]
        ChannelTrait["Channel trait<br/>(src/channels/traits.rs)"]
        ChannelMod["channels/mod.rs"]
    end
    
    subgraph "Runtime Initialization"
        ConfigLoad["Config::load_or_init()"]
        ProviderInit["providers::create_resilient_provider()"]
        MemoryInit["memory::create_backend()"]
        ChannelInit["spawn_supervised_listener()"]
    end
    
    ConfigFile --> ConfigStruct
    APIKey --> ConfigStruct
    Provider --> ConfigStruct
    Model --> ConfigStruct
    MemoryBackend --> ConfigStruct
    ChannelsConfig --> ConfigStruct
    
    ConfigStruct --> ConfigLoad
    
    ConfigLoad --> ProviderInit
    ConfigLoad --> MemoryInit
    ConfigLoad --> ChannelInit
    
    ProviderInit --> CreateProvider
    CreateProvider --> ProviderTrait
    
    MemoryInit --> MemoryTrait
    
    ChannelInit --> ChannelMod
    ChannelMod --> ChannelTrait
Loading

Configuration to Runtime Mapping

This diagram shows how TOML configuration keys map to Rust code structures and initialization paths. The Config::load_or_init() method reads config.toml, deserializes it into the Config struct, then the provider factory, memory subsystem, and channel supervisor consume those fields to instantiate concrete implementations of the respective traits.

Sources: src/config/schema.rs:48-144, src/channels/mod.rs:101-123, src/channels/traits.rs

First Agent Interaction

After onboarding completes successfully, verify the setup with a simple agent query:

# Single-turn conversation
zeroclaw agent -m "Hello, ZeroClaw!"

# Interactive mode (multi-turn)
zeroclaw agent

# Check system status
zeroclaw status

Expected Output

💬 User: Hello, ZeroClaw!
⏳ Processing message...
🤖 Reply (342ms): Hello! I'm ZeroClaw, your AI assistant. How can I help you today?

The agent command flow:

  1. Loads Config from ~/.zeroclaw/config.toml
  2. Initializes Provider via create_resilient_provider() with configured credentials and reliability settings
  3. Builds system prompt from workspace files (IDENTITY.md, AGENTS.md, etc.) via build_system_prompt()
  4. Creates tool registry from enabled tools
  5. Invokes run_tool_call_loop() which sends messages to LLM and processes tool calls
  6. Returns final response after tool execution completes or max iterations reached

Sources: src/channels/mod.rs:556-814, src/channels/mod.rs:888-1037

Common First-Run Issues

Issue Symptom Solution
Missing API key Error: Provider requires API key Set api_key in config.toml or OPENROUTER_API_KEY env var
Network timeout Error: Connection timeout after 30s Check internet connection, firewall rules, or use local provider (Ollama)
Invalid model Error: Model not found Verify model ID with zeroclaw models list --provider openrouter
Memory backend failure Error: Failed to open SQLite database Check workspace permissions, disk space, or switch to memory.backend = "none"

For detailed troubleshooting steps, see Troubleshooting in the documentation.

Workspace Structure

After initialization, the workspace directory (~/.zeroclaw/workspace by default) contains:

~/.zeroclaw/
├── config.toml              # Main configuration file
├── active_workspace.toml    # Current workspace marker
├── .secret_key              # ChaCha20Poly1305 encryption key (if secrets.encrypt=true)
├── auth-profiles.json       # OAuth tokens (if using subscription auth)
└── workspace/
    ├── IDENTITY.md          # Agent identity and persona
    ├── AGENTS.md            # Behavior guidelines
    ├── SOUL.md              # Core personality and values
    ├── USER.md              # User context and preferences
    ├── TOOLS.md             # Available tools documentation
    ├── MEMORY.md            # Curated long-term memory
    ├── BOOTSTRAP.md         # First-run ritual (optional)
    ├── memory/              # Daily memory files (if backend supports)
    ├── skills/              # Skill manifests and instructions
    └── state/               # Runtime state (models cache, cron jobs, etc.)

The workspace files use the OpenClaw format by default. To use AIEOS JSON format, set identity.format = "aieos" in config.toml.

Sources: src/channels/mod.rs:846-1027, src/config/schema.rs:48-58

Next Steps

Once basic setup is verified, common next steps include:

Enable Channels

Start the daemon to activate messaging platform integrations:

# Launch all configured channels
zeroclaw daemon

# Or start gateway only (HTTP webhook server)
zeroclaw gateway  # binds to 127.0.0.1:3000 by default

Channel configuration requires platform-specific tokens and allowlists. See Channel Implementations for setup instructions.

Configure Security

Review and adjust the default security policy:

[autonomy]
level = "supervised"        # "readonly" | "supervised" | "full"
workspace_only = true       # Restrict file operations to workspace
allowed_commands = ["git", "npm", "cargo"]
forbidden_paths = ["/etc", "/root", "/proc", "/sys"]

The SecurityPolicy enforces these constraints at tool execution time. See Security Model for details.

Set Up Memory

Enable hybrid search for context-aware responses:

[memory]
backend = "sqlite"
auto_save = true
embedding_provider = "openai"  # or "custom:https://..."
vector_weight = 0.7
keyword_weight = 0.3

The memory system combines vector similarity (cosine) with FTS5 keyword search (BM25). See Memory System for architecture details.

Add Tools

Enable additional capabilities by uncommenting tool configurations:

[browser]
enabled = true
allowed_domains = ["docs.rs", "github.com"]

[composio]
enabled = true
api_key = "cmp_..."  # Access to 200+ OAuth apps

[http_request]
enabled = true
allowed_domains = ["api.example.com"]

For the complete list of available tools and their configuration, see Tools.

For hands-on examples of common workflows (file operations, git commits, cron scheduling, browser automation), see First Steps.

Sources: README.md:492-599, src/config/schema.rs:48-144

Verification Commands

System Health Check

Run diagnostics to verify all subsystems are correctly configured:

# Overall system status
zeroclaw status

# Detailed diagnostics with recommendations
zeroclaw doctor

# Channel-specific health check
zeroclaw channel doctor

The doctor command checks:

  • Configuration validity
  • Provider connectivity and API key
  • Memory backend accessibility
  • Workspace file integrity
  • Channel token validity
  • Tool permissions

Sources: README.md:226-233

Authentication Status

For subscription-based providers (OpenAI Codex, Claude Code):

# Check active auth profiles
zeroclaw auth status

# Refresh expired tokens
zeroclaw auth refresh --provider openai-codex --profile default

Encrypted auth profiles are stored in ~/.zeroclaw/auth-profiles.json with the encryption key at ~/.zeroclaw/.secret_key.

Sources: README.md:255-298

Provider and Model Discovery

List available providers and models:

# List all built-in providers
zeroclaw providers

# List models for a specific provider (requires API key)
zeroclaw models list --provider openrouter

# Refresh model cache
zeroclaw models refresh --provider openrouter

Model lists are cached in workspace/state/models_cache.json with a 12-hour TTL to minimize API calls.

Sources: src/onboard/wizard.rs:53-57, src/channels/mod.rs:70-71

Troubleshooting Common Setup Issues

Compilation Failures

Issue: error: linking with cc failed or out-of-memory during compilation.

Solution:

  • Use cargo build --profile release-fast on machines with 16GB+ RAM for faster builds
  • Or use default cargo build --release which uses codegen-units=1 for low-memory compatibility
  • Install required build tools: Visual Studio Build Tools (Windows), build-essential (Linux), Xcode CLI (macOS)

Sources: Cargo.toml:161-172, README.md:99-166

Configuration Not Found

Issue: Error: Configuration file not found at ~/.zeroclaw/config.toml

Solution: Run zeroclaw onboard to create initial configuration. If using a custom workspace, set ZEROCLAW_WORKSPACE environment variable.

Sources: src/config/schema.rs:48-58

Channel Authorization Failures

Issue: ignoring message from unauthorized user in logs.

Solution:

  1. Check sender identity in warning logs
  2. Add identity to channel allowlist in config.toml
  3. Or run zeroclaw channel bind-telegram <IDENTITY> for quick approval
  4. Or rerun zeroclaw onboard --channels-only to reconfigure

Empty allowlists use deny-by-default policy. Use ["*"] to allow all (testing only).

Sources: README.md:398-438, src/channels/mod.rs:133-144

Memory Backend Initialization Failures

Issue: Error: Failed to open SQLite database: unable to open database file

Solution:

  • Verify workspace directory exists and is writable
  • Check disk space availability
  • If issue persists, switch to memory.backend = "none" temporarily
  • For SQLite lock timeouts, set memory.sqlite_open_timeout_secs = 30

Sources: README.md:346-377

For comprehensive troubleshooting guides including network issues, LLM provider errors, and deployment-specific problems, see the Troubleshooting documentation.

Home

  1. Overview

  2. Getting Started

  3. Core Architecture

  4. Configuration

  5. Providers

  6. Channels

  7. Agent Core

  8. Tools

  9. Memory System

  10. Gateway

  11. Scheduler

  12. Development Guide

  13. Deployment

  14. Maturity Framework

Clone this wiki locally
⚡