ZeroClaw Architecture and Runtime

1. The workspace shape

The official architecture docs describe ZeroClaw as a layered Rust workspace. At the center sits the runtime, and around it are the pluggable surfaces that talk to the outside world.

The most useful way to read the codebase is:

Area	Purpose
zeroclaw-runtime	Agent loop, security enforcement, SOP engine, scheduling, coordination
zeroclaw-config	TOML schema, secrets handling, autonomy settings, workspace resolution
zeroclaw-api	Public trait contracts such as ModelProvider, Channel, and Tool
zeroclaw-providers	Model-provider clients, retries, routing
zeroclaw-channels	Messaging and ingress integrations
zeroclaw-tools	Built-in callable agent capabilities
zeroclaw-gateway	HTTP, WebSocket, dashboard, webhook ingress
zeroclaw-memory	Memory and retrieval
zerocode	Terminal UI

That structure reflects an important design choice: ZeroClaw wants the runtime core to depend on traits and registries, not on hard-coded platform implementations.

2. The three primary extension points

The v0.8.1 architecture guide explicitly calls out three trait-based extension points:

• ModelProvider
• Channel
• Tool

That means most "I want ZeroClaw to do something new" work lands in one of three buckets:

You want to add...	You usually work in...
a new model backend or wire protocol	zeroclaw-providers
a new messaging or ingress surface	zeroclaw-channels
a new agent capability	zeroclaw-tools

The broader workspace also includes dedicated memory and hardware crates, but providers, channels, and tools are the extension surfaces most developers hit first.

3. Request lifecycle

At runtime, the overall loop is straightforward even though the implementation is not small:

1. a channel receives a message, event, or request,
2. it delivers that input to the runtime,
3. the runtime calls a provider with the current messages and tool schema,
4. the provider streams back text and possibly tool calls,
5. the runtime runs those tool calls through security policy,
6. approved calls execute through tools,
7. results go back into the model turn,
8. the final response returns through the channel.

That shape explains why ZeroClaw can look like very different products from the outside:

• a terminal agent,
• a Discord or Telegram bot,
• a gateway-backed dashboard,
• an IDE-connected agent via ACP,
• an always-on automation runtime.

Under the hood, those are different edges around the same core loop.

4. Providers: more than simple API wrappers

Providers are not just thin HTTP clients. The project docs make a point of these runtime responsibilities:

• pluggable model families
• same-provider retries
• fallback chains
• routing
• support for OpenAI-compatible endpoints

That is why provider configuration is one of the most important parts of the system. The provider layer is where ZeroClaw turns "talk to a model" into an operational surface that can survive real-world failures and vendor differences.

5. Channels: one runtime, many surfaces

Channels are the way ZeroClaw reaches the outside world. The official docs divide them into broad groups:

• chat platforms such as Discord, Telegram, Matrix, Slack, and others,
• social/broadcast surfaces,
• email,
• voice/telephony,
• webhooks and programmatic surfaces such as CLI, gateway, and ACP.

The important architectural point is that one ZeroClaw instance can bind multiple channels simultaneously. That gives you one runtime with a shared policy and shared model/provider setup rather than one bot process per platform.

The channel docs also emphasize compile-time feature gating. A minimal build does not need to ship every platform integration.

6. Tools, memory, and gateway

Tools

Tools are the action surface. The README and architecture docs highlight things like:

• shell,
• browser,
• HTTP,
• PDF-related work,
• hardware-facing capabilities,
• custom MCP-backed integrations.

Memory

Memory is a dedicated subsystem rather than an afterthought. The architecture docs describe a zeroclaw-memory crate with SQLite, embeddings, and vector retrieval concerns in scope.

Gateway

The gateway is its own first-class subsystem:

• HTTP and WebSocket access,
• dashboard UI,
• webhook ingress,
• config-related workflows,
• quickstart and runtime management surfaces.

This is one reason ZeroClaw feels like a runtime platform rather than just a TUI.

7. Security is in the loop, not outside it

A subtle but important point: security is not bolted on after the tool call. It is part of the runtime turn itself.

The request lifecycle documented upstream explicitly inserts security validation between model tool intent and actual tool execution. That lines up with the broader project posture:

• supervised-by-default autonomy,
• approval gates,
• sandbox backends,
• receipts and auditability.

If you are reading the code, it helps to think of ZeroClaw as:

an agent loop plus a policy engine

not just as a chat wrapper over model APIs.

8. Other runtime surfaces worth knowing

The README and docs point to several capabilities that matter for advanced use cases:

Surface	Why it matters
SOP engine	Event-triggered standard operating procedures with approvals and resumable runs
ACP	Agent Client Protocol for IDE/editor integration over JSON-RPC
Hardware	GPIO, I2C, SPI, USB, and board integrations
Service mode	Lets the runtime operate as a long-lived background system

These are the pieces that move ZeroClaw beyond "chat with tools" into "programmable agent runtime."