zeroclaw-labs/zeroclaw — Gitpedia

<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" /> <h1 align="center">🦀 ZeroClaw — Personal AI Assistant</h1> You own the agent. You own the data. You own the machine it runs on. <a href="https://github.com/zeroclaw-labs/zeroclaw/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/zeroclaw-labs/zeroclaw/ci.yml?branch=master&label=build" alt="Build Status" /></a> <a href="https://github.com/zeroclaw-labs/zeroclaw/releases/latest"><img src="https://img.shields.io/github/v/release/zeroclaw-labs/zeroclaw?label=release" alt="Latest release" /></a> <a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License" /></a> <a href="https://www.rust-lang.org"><img src="https://img.shields.io/badge/rust-edition%202024-orange?logo=rust" alt="Rust Edition 2024" /></a> <a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a> <a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a> <a href="docs/book/src/introduction.md">Docs</a> · <a href="docs/book/src/philosophy.md">Philosophy</a> · <a href="docs/book/src/getting-started/quick-start.md">Quick start</a> · <a href="docs/book/src/architecture/overview.md">Architecture</a> · <a href="https://discord.com/invite/wDshRVqRjx">Discord</a>

ZeroClaw is an agent runtime — a single Rust binary you configure and run. It talks to LLM providers (Anthropic, OpenAI, Ollama, and ~20 others), reaches the world through 30+ channels (Discord, Telegram, Matrix, email, voice, webhooks, your own CLI), and acts through tools (shell, browser, HTTP, hardware, custom MCP servers). Everything runs on your machine, with your keys, in your workspace.

Read the Philosophy for the four opinions that shape it.

Install

bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash

Or clone and run:

bash
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

The installer asks whether you want a prebuilt binary (fast, ~seconds) or a source build (slower, customisable). Both end the same way — zeroclaw onboard kicks off automatically.

Flags:

./install.sh --prebuilt              # always prebuilt; don't ask
./install.sh --source                # always build from source
./install.sh --minimal               # kernel only (~6.6 MB)
./install.sh --source --features agent-runtime,channel-discord  # custom feature set
./install.sh --skip-onboard          # install only, run `zeroclaw onboard` later
./install.sh --list-features         # print available feature flags

Platform-specific notes: Linux · macOS · Windows · Docker

Quick start

bash
zeroclaw onboard                  # interactive onboard: provider, channels, agents, etc.
zeroclaw agent -a <alias>         # interactive chat using the [agents.<alias>] entry
zeroclaw service install          # register as systemd/launchctl/Windows Service
zeroclaw service start            # run it always-on in the background

Full walkthrough: Quick start — or skip the safety gates with YOLO mode for dev boxes.

What ZeroClaw does

Multi-channel — one agent answering you across every channel you configure. Inbound messages from Discord, Telegram, Matrix, email, webhooks, CLI — all delivered to the same agent loop.
Provider-agnostic — model providers are pluggable. Configure Anthropic, OpenAI, local Ollama, or any OpenAI-compatible endpoint. Fallback chains and routing keep the agent running when a provider flakes.
Security-first, with escape hatches — default autonomy is supervised: medium-risk ops require approval, high-risk blocked. Workspace boundaries, command policy, OS-level sandboxes (Landlock / Bubblewrap / Seatbelt / Docker), and cryptographic tool receipts on every action. YOLO mode exists for trusted dev environments.
Hardware-capable — GPIO / I2C / SPI / USB on Raspberry Pi, STM32, Arduino, and ESP32 via the Peripheral trait. See Hardware.
Gateway + dashboard — HTTP / WebSocket gateway for clients, with a web dashboard for chat, memory browsing, config editing, cron management, and tool inspection.
SOP engine — event-triggered Standard Operating Procedures (MQTT / webhook / cron / peripheral) with approval gates and resumable runs.
ACP — IDE / editor integration via Agent Client Protocol (JSON-RPC 2.0 over stdio).

Configuration

One TOML file at ~/.zeroclaw/config.toml. Pointers:

Provider configuration — the universal [providers.models.<type>.<alias>] schema
Channels overview — per-channel [channels.<type>.<alias>] blocks
Security overview — autonomy, sandboxing, tool receipts
Full config reference — generated from the live schema; every key documented

A V3 config has at minimum four section headers (<type>.<alias> shaped) — a provider entry, an agent that references it, and a risk profile the agent gates against. See Provider Configuration → Minimal working example for the canonical four-section form with inline type/alias commentary.

For standard OpenAI Codex subscription auth, swap the provider entry to:

toml
[providers.models.openai.coding]   # type = openai; alias = coding (you choose)
model = "gpt-5-codex"
wire_api = "responses"
requires_openai_auth = true

…and point your agent at it with model_provider = "openai.coding".

Notes:

Normal OpenAI Codex subscription auth uses stored auth profiles, not an api_key on the provider entry.
Only set api_key / uri on [providers.models.openai.<alias>] when intentionally targeting a custom OpenAI-compatible gateway or endpoint.
If you see provider streaming failed, falling back to non-streaming chat, ZeroClaw retries the same request in non-streaming mode. Check zeroclaw auth status before changing provider config.

Architecture

┌──────────────────────────────────────────────────────────────┐
│            channels       gateway        ACP                 │
│          (30+ adapters)   (REST/WS)    (JSON-RPC)            │
│                        ↓                                     │
│                   ZeroClaw runtime                           │
│         ┌──────────┬──────────┬──────────┐                   │
│         │  agent   │ security │   SOP    │                   │
│         │   loop   │  policy  │  engine  │                   │
│         └──────────┴──────────┴──────────┘                   │
│              ↓          ↓           ↓                        │
│          providers    tools      memory                      │
│         (Anthropic,  (shell,    (SQLite,                     │
│          OpenAI,     browser,    embeddings)                 │
│          Ollama,     HTTP,                                   │
│          ~20 more)   hardware)                               │
└──────────────────────────────────────────────────────────────┘

Full detail with Mermaid diagrams: Architecture overview · Request lifecycle · Crates.

Contributing

Start with how to contribute. Larger changes go through the RFC process. Real-time chat lives on Discord (the best way to reach the team); durable work tracking is on GitHub issues.

Good places to start:

New channel → crates/zeroclaw-channels/
New provider → crates/zeroclaw-providers/
New tool → crates/zeroclaw-tools/
Hardware support → crates/zeroclaw-hardware/
Docs → docs/book/src/

AI-assisted PRs are welcome; see Contribution culture (RFC #5615) for the co-authorship norms.

Security

Do not file public issues for security vulnerabilities. Email security@zeroclaw.dev. See SECURITY.md for the full policy.

Official repository & impersonation notice

This is the only official ZeroClaw repository:

https://github.com/zeroclaw-labs/zeroclaw

Any other repository, organization, domain, or package claiming to be "ZeroClaw" or implying affiliation with ZeroClaw Labs is unauthorized and not affiliated with this project.

License

Dual-licensed: MIT OR Apache 2.0. You may choose either. Contributors automatically grant rights under both — see CLA. The ZeroClaw name and logo are trademarks of ZeroClaw Labs.