zeroclaw-api-client-python

Your ZeroClaw, from Python. Typed calls, live streams, resilient by default.

Docs · Quick start · Guides · Resilience · Endpoint map · Architecture · ZeroClaw

zeroclaw-api-client is a typed, resilient, async Python client for the ZeroClaw gateway: its HTTP API, its Server-Sent Events stream and its WebSocket chat. It is the Python port of zeroclaw-api-client-rust and zeroclaw-api-client-go, with the same surface, behavior and tests.

An independent, community-maintained client. It is not affiliated with or endorsed by ZeroClaw Labs; ZeroClaw is a trademark of ZeroClaw Labs.

pip install zeroclaw-api-client     # or: uv add zeroclaw-api-client

import asyncio

from zeroclaw_client import Client


async def main() -> None:
    async with Client("http://127.0.0.1:42617", token="zc_…") as client:
        status = await client.system.status()
        channels = await client.channels.list()
        await client.config.set("agents.helper.model", "gpt-5.4-mini")

        async with await client.chat("helper") as chat:
            reply = await chat.ask("How many orders are pending?")
        print(status.version, len(channels), reply.full_response)


asyncio.run(main())

Why an SDK

ZeroClaw is a self-hosted AI agent runtime. Everything an operator can do with it (configure agents, models and channels, pair devices, run SOPs, schedule jobs, read sessions and costs, talk to an agent) is exposed by its gateway over HTTP and WebSockets. Calling that surface by hand from every application that embeds ZeroClaw means repeating, in each of them:

• the contract: about 150 routes, a dozen response shapes for errors, a JSON Patch dialect for the configuration, an event stream whose frames have no names, a chat protocol with typed frames;
• the edge cases: secrets that are never returned, paths that must be encoded segment by segment, a gateway that drops connections while it reloads, routes that only exist with some build features;
• the resilience: timeouts that must not cut a stream, retries that must never repeat a write, back-pressure.

This package does it once, typed and tested, so applications talk to ZeroClaw in terms of channels, agents and sessions instead of URLs and JSON. When the gateway changes, one place changes.

Features

• The whole client surface of the gateway, one attribute per area:

  Attribute	Covers
  config	per-field reads and writes, atomic JSON Patch, map aliases (agents, providers, channels), drift, catalogs, setup sections
  pairing	pairing codes, bearer tokens, paired devices
  channels	channel state, sending, group chats and their members, identity binding, relinking
  chat()	agent chat over WebSocket: streamed replies, tool calls, tool approvals
  sessions, events	transcripts, session state, the live Server-Sent Events stream
  agent(), files, skills	agent workspaces, personality files, shared files, image uploads, skill bundles
  cron, memory, cost	scheduled jobs, long-term memory, usage and cost
  sops, canvas, quickstart	SOP authoring, runs and approvals; canvases; the first-agent setup
  system	health, status, metrics, diagnostics, tools, logs, upgrades, reload
  webhook, webauthn	one-shot webhook and A2A messages; hardware-key ceremonies

• Async from end to end (asyncio): one client is shared by every task; the streams are async iterators.

• Resilient by default, built as a stack of layers over an httpx transport: answer timeouts that never cut a stream, retries with jittered exponential backoff for idempotent calls only that honor Retry-After (tenacity), and, opt-in, a circuit breaker (purgatory), a client-side rate limit (aiolimiter) and a shared concurrency limit; plus your own middleware (metrics, tracing, signing) around every request.

• Typed end to end: every answer is a pydantic model validated on arrival, the package ships py.typed and passes mypy --strict.

• Typed errors: every failure is a ZeroClawError; a gateway refusal is an APIError that keeps its status, its explanation and its JSON body; is_not_found, is_unauthorized, is_rate_limited and is_transient classify any error.

• Pull, not callbacks: the event feed is an EventStream, the canvas and SOP-run feeds a Feed, and a chat a session you iterate with async for. The client starts no background work of its own.

• Safe by construction: every path segment is percent-encoded, the token never appears in repr, nothing is printed or logged.

Technologies

Architecture

 your code
    │  await client.channels.rooms("whatsapp.main")
    ▼
 Client ── resource attributes (config, channels, chat, …) ── pydantic requests/responses
    │
    ├─ HTTP ──► your middleware ─► circuit breaker ─► concurrency limit ─► retry ─► rate limit ─► deadline ─► httpx transport ─► gateway
    ├─ SSE ───► the same stack; the body is read as a stream of events
    └─ WebSocket ─► websockets (chat, canvas and SOP-run feeds)

Each method's docstring names the route it calls; the endpoint map is generated from them.

Resilience

from zeroclaw_client import CircuitBreaker, Client, RateLimit, RetryPolicy

client = Client(
    "http://127.0.0.1:42617",
    token="zc_…",
    timeout=10,  # wait for an answer at most 10 s
    retry=RetryPolicy(max_retries=5, base_delay=0.25, max_delay=8),
    concurrency_limit=4,  # shared by every copy
    rate_limit=RateLimit(rate=10, burst=20),  # 10 requests/s, bursts of 20
    circuit_breaker=CircuitBreaker(),  # open after 5 failures in a row, for 30 s
    middleware=[my_middleware],  # async (request, next) -> response
)

Retries apply to GET, HEAD, OPTIONS, PUT and DELETE after a connection failure, a connection dropped before the answer, a timeout, or a 408, 429, 502, 503 or 504, with jittered backoff and the gateway's Retry-After honored. A POST or PATCH is never repeated. An open breaker fails calls at once with CircuitOpenError; the rate limit fails a wait longer than the timeout with RateLimitedError. The timeout bounds the wait for the answer's headers, so the event stream stays open.

Examples

Runnable scripts under examples/:

ZEROCLAW_URL=http://127.0.0.1:42617 ZEROCLAW_TOKEN=zc_… python examples/status.py

Testing

• Parametrized unit tests for every piece of logic: error mapping, URL encoding, SSE parsing, chat frames, retry decisions, backoff, patch operations, schedules.
• HTTP-boundary tests for every endpoint against a mock gateway: method, path, query, body and decoding; plus retry, timeout, circuit breaker, rate limit, concurrency and middleware behavior.
• Response vectors: answers captured from a real gateway (scripts/capture-vectors.py, anonymized) must decode into the SDK's models and re-encode without losing a field.
• Live tests against a running gateway (pytest -m live): every read decodes real answers, and a write suite covers the rest of the surface, cleaning up after itself.

uv sync && uv run pytest

Compatibility

Targets the ZeroClaw 0.8.5 gateway; see Compatibility for the builds it is verified against and the routes that need a newer one.

Contributing

Work happens on branches with pull requests to main; see CONTRIBUTING.md and AGENTS.md.

License

Licensed under either of Apache License, Version 2.0 or MIT license, at your option.

The Python logo is a trademark of the Python Software Foundation, used here to say the client is written in Python, in line with the PSF Trademark Usage Policy.