Config Reference

ZeroClaw is configured via a TOML file. All fields are optional unless noted.

acp

ACP (Agent Client Protocol) server configuration ([acp] section).

agents

Aliased agents in this install. Each entry under [agents.<alias>] is one user-facing agent with its own identity, channels, model provider, risk profile, workspace, and memory scope. DelegateTool consults this map when one agent delegates a subtask to another.

backup

Backup tool configuration ([backup] section).

browser

Browser automation configuration ([browser] section).

Controls the browser_open tool and browser automation backends.

browser.computer_use

Computer-use sidecar configuration ([browser.computer_use] section).

Delegates OS-level mouse, keyboard, and screenshot actions to a local sidecar.

browser_delegate

channels

Top-level channel configurations ([channels] section).

each channel type is a keyed table of named instances (aliases). [channels.telegram.default] is the conventional single-instance key. Access via config.channels.telegram.get("default").

claude_code

Claude Code CLI tool configuration ([claude_code] section).

Delegates coding tasks to the claude -p CLI. Authentication uses the binary’s own OAuth session (Max subscription) by default — no API key needed unless env_passthrough includes ANTHROPIC_API_KEY.

claude_code_runner

Claude Code task runner configuration ([claude_code_runner] section).

Spawns Claude Code in a tmux session with HTTP hooks that POST tool execution events back to ZeroClaw’s gateway, updating a Slack message in-place with progress plus an SSH handoff link.

cloud_ops

Controls the read-only cloud transformation analysis tools: IaC review, migration assessment, cost analysis, and architecture review.

codex_cli

Codex CLI tool configuration ([codex_cli] section).

Delegates coding tasks to the codex exec CLI. Authentication uses the binary’s own session by default — no API key needed unless env_passthrough includes OPENAI_API_KEY.

composio

Composio managed OAuth tools integration ([composio] section).

Provides access to 1000+ OAuth-connected tools via the Composio platform.

conversational_ai

Conversational AI agent builder configuration ([conversational_ai] section).

Status: Reserved for future use. This configuration is parsed but not yet consumed by the runtime. Setting enabled = true will produce a startup warning.

cost

Cost tracking and budget enforcement configuration ([cost] section).

cost.enforcement

Configuration for cost enforcement behavior when budget limits are reached.

cost.rates

[cost.rates] — top-level rate-sheet namespace. Mirrors the [providers.*] shape so each subsection here points at the same kind of resource its [providers.*] counterpart configures.

cost.rates.providers

[cost.rates.providers.*] — provider-shaped rate sheets. Each field here mirrors a corresponding field on [providers.*] with the trailing alias segment replaced by the resource the rate prices. The inner typed wrappers carry the per-provider-type slot layout and own dispatch (their slot list is the single source of truth, shared with their providers counterpart via the for_each_*_provider_slot! macros in [crate::providers]).

cron

Declarative cron jobs ([cron.<alias>]), alias-keyed.

Each entry is a named scheduled job synced into the database at scheduler startup. Subsystem runtime knobs (enable/disable, catch-up, run-history retention) live on [scheduler].

data_retention

Data retention and purge configuration ([data_retention] section).

delegate

Global delegate tool configuration for default timeout values.

embedding_routes

Embedding-routing rules — route hint:<name> to specific model_provider + model combos for embedding requests.

escalation

Escalation routing configuration ([escalation] section).

Controls which channels receive alert notifications when escalate_to_human is called with high or critical urgency. Channels are identified by name (e.g. "telegram", "slack"). Alerts are sent best-effort and do not block the escalation.

file_download

Standalone file download tool configuration ([file_download]).

When url is set to a non-empty value, registers a file_download tool that GETs a file from the configured endpoint and writes it to the agent’s workspace filesystem. The LLM supplies only a document identifier and a workspace-relative destination path; the endpoint URL comes solely from this config and is never model-controlled. Response bytes are streamed to disk and never loaded into model context.

When url is None or empty, the tool is not registered.

file_upload

Standalone file upload tool configuration ([file_upload]).

When url is set to a non-empty value, registers a file_upload tool that POSTs files from the agent’s local filesystem to the configured endpoint using multipart/form-data. The LLM provides only a file path; the host reads the bytes and uploads them without ever including file content in the model context.

When url is None or empty, the tool is not registered.

file_upload_bundle

Standalone multi-file bundle upload tool configuration ([file_upload_bundle]).

When url is set to a non-empty value, registers a file_upload_bundle tool that POSTs N files from the agent’s local filesystem to the configured endpoint as a single multipart/form-data request. The LLM provides only file paths; the host reads the bytes.

When url is None or empty, the tool is not registered.

gateway

Gateway server configuration ([gateway] section).

Controls the HTTP gateway for webhook and pairing endpoints.

gateway.pairing_dashboard

Pairing dashboard configuration ([gateway.pairing_dashboard]).

gateway.tls

TLS configuration for the gateway server ([gateway.tls]).

gateway.tls.client_auth

Client certificate authentication (mTLS) configuration ([gateway.tls.client_auth]).

gemini_cli

Gemini CLI tool configuration ([gemini_cli] section).

Delegates coding tasks to the gemini -p CLI. Authentication uses the binary’s own session by default — no API key needed unless env_passthrough includes GOOGLE_API_KEY.

google_workspace

Google Workspace CLI (gws) tool configuration ([google_workspace] section).

Defaults

• enabled: false (tool is not registered unless explicitly opted-in).
• allowed_services: empty vector, which grants access to the full default service set: drive, sheets, gmail, calendar, docs, slides, tasks, people, chat, classroom, forms, keep, meet, events.
• allowed_operations: empty vector, which preserves the legacy behavior of allowing any resource/method under the allowed service set.
• credentials_path: None (uses default gws credential discovery).
• default_account: None (uses the gws active account).
• rate_limit_per_minute: 60.
• timeout_secs: 30.
• audit_log: false.

Compatibility

Configs that omit the [google_workspace] section entirely are treated as GoogleWorkspaceConfig::default() (disabled, all defaults allowed). Adding the section is purely opt-in and does not affect other config sections.

Rollback / Migration

To revert, remove the [google_workspace] section from the config file (or set enabled = false). No data migration is required; the tool simply stops being registered.

hardware

Wizard-driven hardware configuration for physical world interaction.

heartbeat

Heartbeat configuration for periodic health pings ([heartbeat] section).

hooks

hooks.builtin

hooks.builtin.webhook_audit

Configuration for the webhook-audit builtin hook.

Sends an HTTP POST with a JSON body to an external endpoint each time a tool call matches one of the configured patterns. Useful for centralised audit logging, SIEM ingestion, or compliance pipelines.

http_request

HTTP request tool configuration ([http_request] section).

Domain filtering: allowed_domains controls which hosts are reachable (use ["*"] for all public hosts, which is the default). If allowed_domains is empty, all requests are rejected.

image_gen

Standalone image generation tool configuration ([image_gen]).

When enabled, registers an image_gen tool that generates images via fal.ai’s synchronous API (Flux / Nano Banana models) and saves them to the workspace images/ directory.

jira

Jira integration configuration ([jira]).

When enabled = true, registers the jira tool which can get tickets, search with JQL, and add comments. Requires base_url and api_token (or the JIRA_API_TOKEN env var).

Defaults

• enabled: false
• allowed_actions: ["get_ticket"] — read-only by default. Add "search_tickets" or "comment_ticket" to unlock them.
• timeout_secs: 30

Auth

Jira Cloud uses HTTP Basic auth: email + api_token. Jira Server/Data Center uses Bearer token auth: omit email and set api_token to a personal access token. api_token is stored encrypted at rest; set it here or via JIRA_API_TOKEN.

knowledge

Knowledge graph configuration for capturing and reusing expertise.

knowledge_bundles

Named knowledge bundles ([knowledge_bundles.<alias>]).

link_enricher

Automatic link understanding for inbound channel messages ([link_enricher]).

When enabled, URLs in incoming messages are automatically fetched and summarised. The summary is prepended to the message before the agent processes it, giving the LLM context about linked pages without an explicit tool call.

linkedin

LinkedIn integration configuration ([linkedin] section).

When enabled, the linkedin tool is registered in the agent tool surface. Requires LINKEDIN_* credentials in the workspace .env file.

linkedin.content

Content strategy configuration for LinkedIn auto-posting ([linkedin.content]).

The agent reads this via the linkedin get_content_strategy action to know what feeds to check, which repos to highlight, and how to write posts.

linkedin.image

Image generation configuration for LinkedIn posts ([linkedin.image]).

linkedin.image.dalle

OpenAI DALL-E settings ([linkedin.image.dalle]).

linkedin.image.flux

Flux (fal.ai) image generation settings ([linkedin.image.flux]).

linkedin.image.imagen

Google Imagen (Vertex AI) settings ([linkedin.image.imagen]).

linkedin.image.stability

Stability AI image generation settings ([linkedin.image.stability]).

locale

Locale for tool descriptions (e.g. "en", "zh-CN").

When set, tool descriptions shown in system prompts are loaded from Fluent .ftl locale files. Falls back to embedded English, then to hardcoded descriptions.

If omitted or empty, the locale is auto-detected from ZEROCLAW_LOCALE, LANG, or LC_ALL environment variables (defaulting to "en").

mcp

External MCP client configuration ([mcp] section).

mcp_bundles

Named MCP server bundles ([mcp_bundles.<alias>]).

media_pipeline

Automatic media understanding pipeline configuration ([media_pipeline]).

When enabled, inbound channel messages with media attachments are pre-processed before reaching the agent: audio is transcribed, images are annotated, and videos are summarised.

memory

Memory backend configuration ([memory] section).

Controls conversation memory storage, embeddings, hybrid search, response caching, and memory snapshot/hydration. Backend-specific connection settings live under [storage.<backend>.<alias>]; this section selects which storage instance to use via the backend dotted reference.

memory.policy

Memory policy configuration ([memory.policy] section).

microsoft365

Microsoft 365 integration via Microsoft Graph API ([microsoft365] section).

Provides access to Outlook mail, Teams messages, Calendar events, OneDrive files, and SharePoint search.

model_routes

Model-routing rules — route hint:<name> to specific model_provider + model combos.

multimodal

Multimodal (image) handling configuration ([multimodal] section).

Privacy and cost note

Tool results that print real local image paths (e.g. shell tools doing ls /pictures or find . -name '*.png') are canonicalized into [IMAGE:...] markers and base64-inlined into the next provider request. This means image bytes that previously stayed local will be uploaded to the configured provider when surfaced by a tool.

max_images (and the trim_old_images LRU policy) bounds the per-request image budget, but operators running shell-style tools over directories of personal or sensitive images should be aware of the upload semantics. See docs/book/src/contributing/privacy.md for the project’s privacy stance.

node_transport

Secure transport configuration for inter-node communication ([node_transport]).

nodes

Configuration for the dynamic node discovery system ([nodes]).

When enabled, external processes/devices can connect via WebSocket at /ws/nodes and advertise their capabilities at runtime.

notion

Notion integration configuration ([notion]).

When enabled = true, the agent polls a Notion database for pending tasks and exposes a notion tool for querying, reading, creating, and updating pages. Requires api_key (or the NOTION_API_KEY env var) and database_id.

observability

Observability backend configuration ([observability] section).

onboard_state

Multi-client workspace isolation configuration.

When enabled, each client engagement gets an isolated workspace with separate memory, audit, secrets, and tool restrictions. Opaque state the Quickstart flow writes so it can tell, on a re-run, which sections the user has already walked through at least once — which lets it offer “Reconfigure? [y/N]” skip gates instead of forcing users through every field again.

This is meta-state about the Quickstart flow, not user-facing config.

opencode_cli

OpenCode CLI tool configuration ([opencode_cli] section).

Delegates coding tasks to the opencode run CLI. Authentication uses the binary’s own session by default — no API key needed unless env_passthrough includes provider-specific keys.

pacing

Pacing controls for slow/local LLM workloads ([pacing] section).

All fields are optional and default to values that preserve existing behavior. When set, they extend — not replace — the existing timeout and loop-detection subsystems.

peer_groups

Named peer groups ([peer_groups.<name>]). Each entry binds a channel, a list of member agents, and optional non-agent (external) members and a per-group blocklist. Mutual opt-in: two agents become peers only when both appear in the same group’s agents. Empty by default for single-agent installs. See crate::multi_agent::PeerGroupConfig.

peripherals

Peripheral board integration configuration ([peripherals] section).

Boards become agent tools when enabled.

pipeline

Pipeline tool configuration ([pipeline] section).

plugins

Plugin system configuration.

plugins.security

Plugin signature verification configuration ([plugins.security]).

Controls Ed25519 signature verification for plugin manifests. In strict mode, only plugins signed by a trusted publisher key are loaded. In permissive mode, unsigned or untrusted plugins produce warnings but are still loaded. In disabled mode (the default), no signature checking occurs.

project_intel

Project delivery intelligence configuration ([project_intel] section).

providers

Top-level wrapper for every provider category. TOML root sees a single [providers] table with one sub-key per category:

[providers.models.anthropic.default]
api_key = "..."

[providers.tts.openai.default]
api_key = "..."

[providers.transcription.groq.default]
api_key = "..."

Each category keeps its own typed-slot internals (so per-family endpoints and extras stay validated at the type level); this wrapper just gives them a shared top-level home.

providers.models

Typed model provider container — one slot per canonical model_provider type.

Replaces the HashMap<String, HashMap<String, ModelProviderConfig>> with a typed struct so each family’s per-alias map carries its own typed config (with the family’s *Endpoint enum and family-specific extras visible at the type level).

TOML shape is preserved byte-identical: each named field deserializes from the same [model_providers.<type>.<alias>] block as before.

Adding a new model_provider family means: define the typed config in schema.rs, then add one row to for_each_model_provider_slot!, and every helper picks up the new slot automatically.

One slot per family (ai21, aihubmix, anthropic, anyscale, arcee, astrai, atomic_chat, avian, azure, baichuan, baseten, bedrock, cerebras, cloudflare, cohere, copilot, custom, deepinfra, deepmyst, deepseek, doubao, featherless, fireworks, friendli, gemini, gemini_cli, github_models, glm, groq, huggingface, hunyuan, hyperbolic, inception, kilo, kilocli, lambda_ai, lepton, litellm, llamacpp, lmstudio, minimax, mistral, moonshot, morph, nebius, novita, nscale, nvidia, ollama, openai, opencode, openrouter, osaurus, ovh, perplexity, qianfan, qwen, reka, sambanova, sglang, siliconflow, stepfun, synthetic, telnyx, together, upstage, venice, vercel, vllm, xai, yi, zai). Each slot is a [providers.models.<slot>.<alias>] map; see the dedicated section page for the per-field reference.

providers.transcription

Typed transcription-provider container — one slot per STT family. Mirrors ModelProviders / TtsProviders. Closed set of 6 families: groq, openai, deepgram, assemblyai, google, local_whisper.

One slot per family (assemblyai, deepgram, google, groq, local_whisper, openai). Each slot is a [providers.transcription.<slot>.<alias>] map; see the dedicated section page for the per-field reference.

providers.tts

Typed TTS-provider container — one slot per TTS family. Mirrors ModelProviders but smaller (TTS has a closed set of 5 families: openai, elevenlabs, google, edge, piper). No catch-all needed.

One slot per family (edge, elevenlabs, google, openai, piper). Each slot is a [providers.tts.<slot>.<alias>] map; see the dedicated section page for the per-field reference.

proxy

Proxy configuration for outbound HTTP/HTTPS/SOCKS5 traffic ([proxy] section).

query_classification

Automatic query classification — classifies user messages by keyword/pattern and routes to the appropriate model hint. Disabled by default.

reliability

Reliability and supervision configuration ([reliability] section).

Controls model_provider retries, API key rotation, and channel restart backoff.

risk_profiles

Named risk/autonomy profiles ([risk_profiles.<alias>]).

runtime

Runtime adapter configuration ([runtime] section).

runtime.docker

Docker runtime configuration ([runtime.docker] section).

runtime_profiles

Named runtime/LLM execution profiles ([runtime_profiles.<alias>]).

scheduler

Scheduler configuration for periodic task execution ([scheduler] section).

Owns the cron-runtime knobs: per-job declarations live on Config.cron: HashMap<String, CronJobDecl> (alias-keyed), while the scheduler loop’s runtime behavior (enabled, polling cap, catch-up) lives here.

schema_version

Config file schema version.

secrets

Secrets encryption configuration ([secrets] section).

security

Security configuration for audit logging, OTP, e-stop, IAM/SSO, and WebAuthn.

Sandbox backend and resource limits live on per-agent risk profiles (see RiskProfileConfig::sandbox_* and RiskProfileConfig::max_*); the runtime resolves them via Config::active_risk_profile(agent_alias).

security.audit

Audit logging configuration

security.estop

Emergency stop configuration.

security.nevis

Nevis IAM integration configuration.

When enabled is true, ZeroClaw validates incoming requests against a Nevis Security Suite instance and maps Nevis roles to tool/workspace permissions.

security.otp

Security OTP configuration.

security.webauthn

WebAuthn / FIDO2 hardware key authentication configuration ([security.webauthn]).

Enables registration and authentication via hardware security keys (YubiKey, SoloKey, etc.) and platform authenticators (Touch ID, Windows Hello).

security_ops

Managed Cybersecurity Service (MCSS) dashboard agent configuration ([security_ops]).

shell_tool

Shell tool configuration ([shell_tool] section).

Controls the behaviour of the shell execution tool. The main tunable is timeout_secs — the maximum wall-clock time a single shell command may run before it is killed.

skill_bundles

Named skill bundles ([skill_bundles.<alias>]).

skills

Skills loading configuration ([skills] section).

skills.install_suggestions

Prompt-triggered skill install suggestions ([skills.install_suggestions] section).

skills.skill_creation

Autonomous skill creation configuration ([skills.skill_creation] section).

skills.skill_improvement

Skill self-improvement configuration ([skills.auto_improve] section).

sop

Standard Operating Procedures engine configuration ([sop]).

The default_execution_mode field uses the SopExecutionMode type from sop::types (re-exported via sop::SopExecutionMode). To avoid circular module references, config stores it using the same enum definition.

storage

Persistent storage configuration ([storage] section).

Storage is a two-tier alias-keyed map: [storage.<backend>.<alias>], parallel to [model_providers.<type>.<alias>]. Each backend has its own typed config struct. MemoryConfig.backend carries a dotted reference ("sqlite.default", "postgres.work") that resolves to one of these entries via [Config::resolve_active_storage].

One slot per family (lucid, markdown, postgres, qdrant, sqlite). Each slot is a [storage.<slot>.<alias>] map; see the dedicated section page for the per-field reference.

text_browser

Text browser tool configuration ([text_browser] section).

Uses text-based browsers (lynx, links, w3m) to render web pages as plain text. Designed for headless/SSH environments without graphical browsers.

transcription

Voice transcription configuration with multi-provider support.

The top-level api_url, model, and api_key fields remain for backward compatibility with existing Groq-based configurations.

transcription.assemblyai

AssemblyAI STT model_provider configuration ([transcription.assemblyai]).

transcription.deepgram

Deepgram STT model_provider configuration ([transcription.deepgram]).

transcription.google

Google Cloud Speech-to-Text model_provider configuration ([transcription.google]).

transcription.local_whisper

Local/self-hosted Whisper-compatible STT endpoint ([transcription.local_whisper]).

Configures a self-hosted STT endpoint. Can be on localhost, a private network host, or any reachable URL.

transcription.openai

OpenAI Whisper STT model_provider configuration ([transcription.openai]).

trust

tts

Text-to-Speech subsystem configuration ([tts]).

Per-instance TTS configs live under [tts_providers.<type>.<alias>] (parallel to providers.models). What remains here are the global runtime knobs that apply to every model_provider invocation.

tunnel

Tunnel configuration for exposing the gateway publicly ([tunnel] section).

Supported model_providers: "none" (default), "cloudflare", "tailscale", "ngrok", "openvpn", "pinggy", "custom".

tunnel.cloudflare

tunnel.custom

tunnel.ngrok

tunnel.openvpn

OpenVPN tunnel configuration ([tunnel.openvpn]).

Required when tunnel.tunnel_provider = "openvpn". Omitting this section entirely preserves previous behavior. Setting tunnel.tunnel_provider = "none" (or removing the [tunnel.openvpn] block) cleanly reverts to no-tunnel mode.

Defaults: connect_timeout_secs = 30.

tunnel.pinggy

tunnel.tailscale

verifiable_intent

Verifiable Intent (VI) credential verification and issuance ([verifiable_intent] section).

web_fetch

Web fetch tool configuration ([web_fetch] section).

Fetches web pages and converts HTML to plain text for LLM consumption. Domain filtering: allowed_domains controls which hosts are reachable (use ["*"] for all public hosts). blocked_domains takes priority over allowed_domains. If allowed_domains is empty, all requests are rejected (deny-by-default).

web_fetch.firecrawl

Firecrawl fallback configuration for JS-heavy and bot-blocked sites.

When enabled, if the standard web fetch fails (HTTP error, empty body, or body shorter than 100 characters suggesting a JS-only page), the tool falls back to the Firecrawl API for stealth content extraction.

web_search

Web search tool configuration ([web_search] section).

wss

WebSocket Secure (WSS) transport for remote TUI-to-daemon connections ([wss]).

When enabled, the daemon listens for TLS-encrypted WebSocket connections on the configured bind address and port. TUI clients connect via --connect wss://host:port.