Zeroclaw

ZeroClaw — Complete Reference Skill

Comprehensive operational knowledge for ZeroClaw, the fast, small, fully autonomous AI assistant infrastructure built in Rust. Source: https://github.com/zeroclaw-labs/zeroclaw | Version: 0.1.1 | Last updated: 2026-02-21

What Is ZeroClaw

• Language: 100% Rust, single binary (~3.4-8.8MB release)
• Memory: <5MB RAM at runtime
• Startup: <10ms cold start
• Platforms: ARM, x86, RISC-V — runs on $10 hardware
• Architecture: Trait-driven, everything is swappable (providers, channels, tools, memory, tunnels, security)
• Config: ~/.zeroclaw/config.toml (TOML format)
• Workspace: ~/.zeroclaw/workspace/ (SOUL.md, AGENTS.md, IDENTITY.md, USER.md, MEMORY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md)
• Identity: ZeroClaw introduces itself as ZeroClaw, never as ChatGPT/Claude/etc.

Installation

# Option A: Clone + build
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw && ./bootstrap.sh

# Option B: Remote one-liner
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash

# Fresh machine (install Rust + system deps)
./bootstrap.sh --install-system-deps --install-rust

# Quick onboard after install
zeroclaw onboard --api-key "your-api-key" --provider openrouter

Updating ZeroClaw

# Fastest: prebuilt binary (no compile)
git clone https://github.com/zeroclaw-labs/zeroclaw.git /tmp/zeroclaw-update
cd /tmp/zeroclaw-update && bash scripts/bootstrap.sh --prefer-prebuilt
rm -rf /tmp/zeroclaw-update

# With browser-native feature (requires compile)
git clone https://github.com/zeroclaw-labs/zeroclaw.git /tmp/zeroclaw-update
cd /tmp/zeroclaw-update && cargo install --path . --force --locked --features browser-native
rm -rf /tmp/zeroclaw-update

# Verify
zeroclaw --version

Note: There is no built-in zeroclaw update command. Re-running bootstrap.sh --prefer-prebuilt from a fresh clone is the quickest path. The prebuilt binary does not include browser-native — you must build from source with --features browser-native if you need the rust_native browser backend.

CLI Reference (All Commands)

Top-Level

Service Management (launchd/systemd)

zeroclaw service install      # Install for auto-start
zeroclaw service start        # Start service
zeroclaw service stop         # Stop service
zeroclaw service status       # Check status
zeroclaw service uninstall    # Remove service

Channel Management

zeroclaw channel list                      # List all channels + status
zeroclaw channel start                     # Start all configured channels
zeroclaw channel doctor                    # Health check channels
zeroclaw channel add <type> <json>         # Add channel (type + JSON config)
zeroclaw channel remove <name>             # Remove channel
zeroclaw channel bind-telegram <IDENTITY>  # Add Telegram user to allowlist

Note: channel add/remove is not a full config mutator yet — prefer editing ~/.zeroclaw/config.toml directly or using zeroclaw onboard.

Cron / Scheduling

zeroclaw cron list                              # List tasks
zeroclaw cron add "<cron-expr>" "<command>"      # Add recurring task
zeroclaw cron add --tz America/New_York "..."    # With timezone
zeroclaw cron add-at <rfc3339> "<command>"       # One-shot at timestamp
zeroclaw cron add-every <ms> "<command>"         # Fixed interval
zeroclaw cron once <delay> "<command>"           # One-shot delayed (e.g. "30m", "2h")
zeroclaw cron remove <id>
zeroclaw cron pause <id>
zeroclaw cron resume <id>

Models & Providers

zeroclaw providers                          # List all 30 providers
zeroclaw models refresh                     # Refresh model catalogs
zeroclaw models refresh --provider <ID>     # Refresh specific provider
zeroclaw models refresh --force             # Force refresh

Skills

zeroclaw skills list                        # List installed skills
zeroclaw skills install <source>            # Install from GitHub URL or local path
zeroclaw skills remove <name>               # Remove skill

Integrations

zeroclaw integrations info <name>           # Show integration details
# Examples: Telegram, Discord, Slack, iMessage, Matrix, Signal, WhatsApp, Email, DingTalk, Ollama

Auth

zeroclaw auth login --provider <ID>         # OAuth login (e.g. openai-codex)
zeroclaw auth login --provider <ID> --device-code  # Device code flow
zeroclaw auth paste-token                   # Paste auth token (Anthropic)
zeroclaw auth setup-token                   # Alias for paste-token
zeroclaw auth refresh                       # Refresh OAuth token
zeroclaw auth logout                        # Remove auth profile
zeroclaw auth use --provider <ID>           # Set active profile
zeroclaw auth list                          # List profiles
zeroclaw auth status                        # Show token expiry info

Hardware & Peripherals

zeroclaw hardware discover                  # Enumerate USB devices (VID/PID)
zeroclaw hardware introspect <path>         # Introspect device
zeroclaw hardware info [--chip <name>]      # Chip info via probe-rs

zeroclaw peripheral list                    # List configured boards
zeroclaw peripheral add <board> <path>      # Add board (e.g. nucleo-f401re /dev/ttyACM0)
zeroclaw peripheral flash [--port <port>]   # Flash Arduino firmware
zeroclaw peripheral setup-uno-q             # Setup Arduino Uno Q Bridge
zeroclaw peripheral flash-nucleo            # Flash Nucleo-F401RE firmware

Migration

zeroclaw migrate openclaw [--source <path>] [--dry-run]  # Import from OpenClaw

Supported Providers (30 total)

Custom Provider Setup

# OpenAI-compatible
default_provider = "custom:https://your-api.com"
api_key = "your-api-key"
default_model = "your-model"

# Anthropic-compatible
default_provider = "anthropic-custom:https://your-api.com"
api_key = "your-api-key"
default_model = "your-model"

Channels (14 supported)

Channel Matrix

Deny-by-Default Allowlist Rules

• [] (empty) = deny all
• ["*"] = allow all (not recommended for production)
• ["123456789", "username"] = exact match only

Telegram Setup

[channels_config.telegram]
bot_token = "your-bot-token"
allowed_users = []

# 1. Get bot token from @BotFather on Telegram
# 2. Add config above to ~/.zeroclaw/config.toml
# 3. Bind your user:
zeroclaw channel bind-telegram <USER_ID_OR_USERNAME>
# 4. Start:
zeroclaw daemon

Important: Telegram uses long-polling — no inbound port or public IP required. Only one poller per bot token allowed (don't run multiple daemons).

Discord Setup

1. Go to https://discord.com/developers/applications
2. Create app, enable Bot, copy token
3. Enable MESSAGE CONTENT intent
4. Run zeroclaw onboard

Slack Setup

1. Go to https://api.slack.com/apps
2. Create app, add Bot Token Scopes, install
3. Run zeroclaw onboard

Mattermost Setup

[channels_config.mattermost]
url = "https://mm.your-domain.com"
bot_token = "your-bot-access-token"
channel_id = "your-channel-id"
allowed_users = ["user-id-1"]
thread_replies = true
mention_only = true

WhatsApp Setup

[channels_config.whatsapp]
access_token = "your-access-token"
phone_number_id = "your-phone-number-id"
verify_token = "your-verify-token"
allowed_numbers = ["+1234567890"]

WhatsApp requires a public URL (webhook) — use a tunnel (Tailscale/ngrok/Cloudflare).

Signal Setup

[channels_config.signal]
http_url = "http://127.0.0.1:8686"
account = "+1234567890"
allowed_from = ["+1987654321"]
ignore_attachments = true
ignore_stories = true

Lark Setup

[channels_config.lark]
app_id = "your-app-id"
app_secret = "your-app-secret"
allowed_users = ["your-user-id"]
receive_mode = "websocket"   # or "webhook"

In-Chat Commands (Telegram/Discord)

While channel server is running, users can execute:

• /models — show available providers
• /models <provider> — switch provider (sender-scoped)
• /model — show current model
• /model <model-id> — switch model (sender-scoped)

Switching clears that sender's conversation history to avoid cross-model contamination.

Config Reference (~/.zeroclaw/config.toml)

Core

Gateway

Memory

Autonomy / Security

Agent

Browser Control

HTTP Requests

Other Notable Sections

• [runtime] — native or docker sandbox
• [reliability] — provider retries, backoff, fallback
• [scheduler] — task scheduling (max 64 tasks, 4 concurrent)
• [heartbeat] — periodic check-ins (disabled by default)
• [cron] — cron scheduling
• [tunnel] — provider: none, tailscale, ngrok, cloudflare
• [composio] — Composio integration (250+ app integrations)
• [secrets] — encrypted secrets
• [web_search] — DuckDuckGo by default
• [proxy] — HTTP proxy support
• [cost] — daily/monthly limits, per-model pricing
• [peripherals] — hardware boards

Browser Control Setup

Browser Backends

auto detection priority order: rust_native (if compiled + WebDriver reachable) -> agent_browser (if CLI installed) -> computer_use (if sidecar reachable). Falls back with helpful error if nothing is available.

Prebuilt binary note: The prebuilt binary from bootstrap.sh --prefer-prebuilt does not include browser-native. If you set backend = "rust_native" with the prebuilt binary, the agent will report the feature isn't enabled. You must build from source: cargo install --path . --force --locked --features browser-native.

Browser Actions (17 total)

Standard actions (all backends):

Computer-use only actions (6 extra — OS-level, not DOM):

Using computer-use actions on a non-computer-use backend returns a backend-specific error.

Backend Comparison (Tested)

Recommendation for AI-driven automation: Use agent_browser. The accessibility tree snapshot with @ref handles is essential — it lets the agent "see" page structure and target specific elements (e.g. @e12) rather than guessing CSS selectors. Use rust_native only for zero-Node deployments or simple scraping where you already know the selectors. Use computer_use when you need OS-level control beyond the browser DOM.

Recommended Setup: agent_browser with Visible Chrome Window

This gives you a visible Chrome window that pops up on your desktop (like OpenClaw) — you can watch the AI browse, log into sites, and the profile persists cookies/sessions.

Step 1: Install agent-browser

npm install -g agent-browser
# Verify:
agent-browser --version

Step 2: Configure agent-browser for headed mode

Create ~/.agent-browser/config.json:

{
  "headed": true,
  "profile": "~/.agent-browser/profile",
  "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}

CRITICAL: The executablePath is required for headed (visible) mode. By default, agent-browser uses Playwright's bundled Chromium (~/Library/Caches/ms-playwright/chromium-*/) which ignores the headed flag and always runs headless. Pointing to your real Google Chrome install fixes this.

Common Chrome paths:

• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Linux: /usr/bin/google-chrome or /usr/bin/chromium
• Windows: C:\Program Files\Google\Chrome\Application\chrome.exe

The profile path gives you persistent cookies/logins across sessions.

Step 3: Configure ZeroClaw

In ~/.zeroclaw/config.toml:

[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"

Step 4: Start daemon with headed env var (belt and suspenders)

AGENT_BROWSER_HEADED=true zeroclaw daemon

Or for service install, export the env var in your shell profile first.

agent-browser CLI Reference

agent-browser open <url>              # Navigate to URL
agent-browser click <selector>        # Click element
agent-browser type <sel> <text>       # Type into element
agent-browser fill <sel> <text>       # Clear and fill
agent-browser screenshot [path]       # Take screenshot
agent-browser snapshot                # Accessibility tree with @refs (for AI)
agent-browser eval <js>               # Run JavaScript
agent-browser close                   # Close browser
agent-browser --headed open <url>     # Force visible window
agent-browser --session <name> ...    # Isolated session
agent-browser --profile <path> ...    # Persistent browser profile

agent-browser Environment Variables

Browser Security Model

• All URLs pass through validate_url() which enforces allowed_domains
• file:// scheme is blocked (prevents local file exfiltration)
• Private/reserved IP ranges are rejected
• For computer_use: coordinate validation, endpoint must be localhost unless allow_remote_endpoint = true

Troubleshooting Browser

Full Autonomy Setup (Max Power Mode)

To unlock all capabilities and remove all restrictions:

Config (~/.zeroclaw/config.toml)

[autonomy]
level = "full"
workspace_only = false
allowed_commands = ["*"]
forbidden_paths = []
max_actions_per_hour = 200
max_cost_per_day_cents = 5000
require_approval_for_medium_risk = false
block_high_risk_commands = false
auto_approve = [
    "shell",
    "file_read",
    "file_write",
    "memory_store",
    "memory_recall",
    "memory_forget",
]
always_ask = []

[agent]
compact_context = false
max_tool_iterations = 50
max_history_messages = 200
parallel_tools = true
tool_dispatcher = "auto"

[scheduler]
enabled = true
max_tasks = 128
max_concurrent = 8

[heartbeat]
enabled = true
interval_minutes = 30

[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"

[http_request]
enabled = true
allowed_domains = ["*"]
max_response_size = 10485760
timeout_secs = 30

[composio]
enabled = true
entity_id = "default"

[web_search]
enabled = true
provider = "duckduckgo"
max_results = 5
timeout_secs = 15

External Dependencies for Full Power

# Browser control (visible Chrome window)
npm install -g agent-browser

# agent-browser config (~/.agent-browser/config.json)
{
  "headed": true,
  "profile": "~/.agent-browser/profile",
  "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}

# Start daemon with headed browser
AGENT_BROWSER_HEADED=true zeroclaw daemon

What Each Setting Unlocks

Security Warning

Full autonomy mode removes all guardrails. The agent can:

• Run any command on your system
• Read/write any file
• Browse any website with your Chrome profile (cookies, logins)
• Make HTTP requests to any domain
• Execute shell commands without approval

Only use this on trusted, personal machines. For shared/production use, keep supervised mode with explicit allowlists.

Operations Runbook

Runtime Modes

Operator Checklist

zeroclaw status          # Check config
zeroclaw doctor          # Run diagnostics
zeroclaw channel doctor  # Check channel health
zeroclaw daemon          # Start runtime

Safe Config Change Flow

1. Backup ~/.zeroclaw/config.toml
2. Apply one logical change
3. Run zeroclaw doctor
4. Restart daemon/service
5. Verify with status + channel doctor

Logs

• macOS/Windows: ~/.zeroclaw/logs/daemon.stdout.log, daemon.stderr.log
• Linux systemd: journalctl --user -u zeroclaw.service -f

Network Deployment

Telegram/Discord/Slack (No Port Needed)

These use long-polling — outbound only. Works behind NAT, on RPi, in home labs.

zeroclaw daemon --host 127.0.0.1 --port 3000

Webhook Channels (WhatsApp, etc.)

Need a public URL. Options:

• [tunnel] provider = "tailscale" — Tailscale Funnel
• [tunnel] provider = "ngrok" — ngrok tunnel
• Cloudflare Tunnel

LAN Access

[gateway]
host = "0.0.0.0"
allow_public_bind = true

Hardware Peripherals

Supported Boards

Adding a Board

zeroclaw peripheral add nucleo-f401re /dev/ttyACM0

Or in config:

[peripherals]
enabled = true
datasheet_dir = "docs/datasheets"

[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200

Two Operation Modes

1. Edge-Native: ZeroClaw runs directly on device (ESP32, RPi) with local GPIO/I2C/SPI
2. Host-Mediated: ZeroClaw on host (Mac/Linux) connects to device via USB/J-Link for development/debugging

Troubleshooting Quick Reference

Diagnostic Commands

zeroclaw --version
zeroclaw status
zeroclaw doctor
zeroclaw channel doctor
zeroclaw channel list

Workspace Files

Memory System

• Daily notes: memory/YYYY-MM-DD.md — raw logs (on-demand via tools)
• Long-term: MEMORY.md — curated, auto-injected each session
• Tools: memory_store, memory_recall, memory_forget

Security Model

• Deny-by-default channel allowlists
• Gateway pairing required by default
• Public bind disabled by default
• Workspace-scoped filesystem access
• Command allowlist for shell execution
• Rate limiting (actions/hour, cost/day)
• Encrypted secrets storage
• Pluggable sandboxing (Landlock, Firejail, Bubblewrap, Docker — feature-gated)
• Audit logging (proposal/roadmap — HMAC-signed tamper-evident logs)

LangGraph / Python Integration

zeroclaw-tools Python package provides LangGraph-based tool calling for consistent behavior with any OpenAI-compatible provider:

pip install zeroclaw-tools

from zeroclaw_tools import create_agent, shell, file_read, file_write
agent = create_agent(tools=[shell, file_read, file_write], model="glm-5", api_key="your-api-key", base_url="your-base-url")

Open Skills Integration

ZeroClaw integrates with Open Skills (https://github.com/besoeasy/open-skills) — pre-built execution playbooks that reduce token usage by 95-98%.

Skills are synced to ~/.zeroclaw/workspace/skills/ and installed via:

zeroclaw skills install <github-url-or-local-path>

Key Design Principles

1. Zero overhead — <5MB RAM, <10ms startup, ~3.4MB binary
2. Zero compromise — full security without sacrificing performance
3. 100% Rust — single binary, no runtime dependencies
4. 100% Agnostic — swap providers, channels, tools, memory, tunnels at will
5. Trait-driven — every subsystem is a trait, making everything pluggable
6. Secure by default — pairing, scoping, allowlists, encrypted secrets