Config Reference

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

Section	Description
`a2a`	A2A section wrapper that leaves room for future sibling configuration.
`acp`	ACP (Agent Client Protocol) server configuration (`[acp]` section).
`agents`	Aliased agents in this install. Each entry under `[agents.<alias>]`
`backup`	Backup tool configuration (`[backup]` section).
`browser`	Browser automation configuration (`[browser]` section).
`browser_delegate`
`channels`	Top-level channel configurations (`[channels]` section).
`claude_code`	Claude Code CLI tool configuration (`[claude_code]` section).
`claude_code_runner`	Claude Code task runner configuration (`[claude_code_runner]` section).
`cloud_ops`	Controls the read-only cloud transformation analysis tools:
`codex_cli`	Codex CLI tool configuration (`[codex_cli]` section).
`composio`	Composio managed OAuth tools integration (`[composio]` section).
`conversational_ai`	Conversational AI agent builder configuration (`[conversational_ai]` section).
`cost`	Cost tracking and budget enforcement configuration (`[cost]` section).
`cron`	Declarative cron jobs (`[cron.<alias>]`), alias-keyed.
`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
`escalation`	Escalation routing configuration (`[escalation]` section).
`eval`	Configuration for the agent evaluation harness (`[eval]`), surfaced via the
`file_download`	Standalone file download tool configuration (`[file_download]`).
`file_upload`	Standalone file upload tool configuration (`[file_upload]`).
`file_upload_bundle`	Standalone multi-file bundle upload tool configuration
`gateway`	Gateway server configuration (`[gateway]` section).
`gemini_cli`	Gemini CLI tool configuration (`[gemini_cli]` section).
`google_workspace`	Google Workspace CLI (`gws`) tool configuration (`[google_workspace]` section).
`hardware`	Wizard-driven hardware configuration for physical world interaction.
`heartbeat`	Heartbeat configuration for periodic health pings (`[heartbeat]` section).
`hooks`
`http_request`	HTTP request tool configuration (`[http_request]` section).
`image_gen`	Standalone image generation tool configuration (`[image_gen]`).
`jira`	Jira integration configuration (`[jira]`).
`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]`).
`linkedin`	LinkedIn integration configuration (`[linkedin]` section).
`locale`	Locale for tool descriptions (e.g. `"en"`, `"zh-CN"`).
`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]`).
`memory`	Memory backend configuration (`[memory]` section).
`microsoft365`	Microsoft 365 integration via Microsoft Graph API (`[microsoft365]` section).
`model_routes`	Model-routing rules — route `hint:<name>` to specific
`multimodal`	Multimodal (image) handling configuration (`[multimodal]` section).
`node_transport`	Secure transport configuration for inter-node communication (`[node_transport]`).
`nodes`	Configuration for the dynamic node discovery system (`[nodes]`).
`notion`	Notion integration configuration (`[notion]`).
`observability`	Observability backend configuration (`[observability]` section).
`onboard_state`	Multi-client workspace isolation configuration.
`opencode_cli`	OpenCode CLI tool configuration (`[opencode_cli]` section).
`pacing`	Pacing controls for slow/local LLM workloads (`[pacing]` section).
`peer_groups`	Named peer groups (`[peer_groups.<name>]`). Each entry binds a
`peripherals`	Peripheral board integration configuration (`[peripherals]` section).
`pipeline`	Pipeline tool configuration (`[pipeline]` section).
`plugins`	Plugin system configuration.
`project_intel`	Project delivery intelligence configuration (`[project_intel]` section).
`providers`	Top-level wrapper for every configured provider category.
`proxy`	Proxy configuration for outbound HTTP/HTTPS/SOCKS5 traffic (`[proxy]` section).
`query_classification`	Automatic query classification — classifies user messages by keyword/pattern
`reliability`	Reliability and supervision configuration (`[reliability]` section).
`risk_profiles`	Named risk/autonomy profiles (`[risk_profiles.<alias>]`).
`runtime`	Runtime adapter configuration (`[runtime]` section).
`runtime_profiles`	Named runtime/LLM execution profiles (`[runtime_profiles.<alias>]`).
`scheduler`	Scheduler configuration for periodic task execution (`[scheduler]` section).
`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.
`security_ops`	Managed Cybersecurity Service (MCSS) dashboard agent configuration (`[security_ops]`).
`shell_tool`	Shell tool configuration (`[shell_tool]` section).
`skill_bundles`	Named skill bundles (`[skill_bundles.<alias>]`).
`skills`	Skills loading configuration (`[skills]` section).
`sop`	Standard Operating Procedures engine configuration (`[sop]`).
`storage`	Persistent storage configuration (`[storage]` section).
`text_browser`	Text browser tool configuration (`[text_browser]` section).
`todotracker`	ZeroCode live task tracker configuration (`[todotracker]` section).
`transcription`	Voice transcription configuration with multi-provider support.
`trust`
`tts`	Text-to-Speech subsystem configuration (`[tts]`).
`tunnel`	Tunnel configuration for exposing the gateway publicly (`[tunnel]` section).
`verifiable_intent`	Verifiable Intent (VI) credential verification and issuance (`[verifiable_intent]` section).
`web_fetch`	Web fetch tool configuration (`[web_fetch]` section).
`web_search`	Web search tool configuration (`[web_search]` section).
`wss`	WebSocket Secure (WSS) transport for remote TUI-to-daemon connections (`[wss]`).

`a2a`

A2A section wrapper that leaves room for future sibling configuration.

Key	Type	Default	Description
`server`	object	`—`	Inbound A2A discovery server configuration.

`a2a.server`

Inbound A2A discovery server configuration.

Key	Type	Default	Description
`bind`	string?	`—`	Optional advertise-only host override for card endpoint URLs. The
`enabled`	bool	`false`	Master switch for the inbound A2A surface. Default `false`: no
`port`	integer?	`—`	Optional advertise-only port override, paired with `bind`. `None`
`public_base_url`	string	`""`	Operator-supplied base URL advertised in agent card endpoints.

`acp`

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

Key	Type	Default	Description
`default_agent`	string?	`—`	Agent alias to use when `session/new` omits `agentAlias` and more than
`max_sessions`	integer	`10`	Maximum number of concurrent ACP sessions. Default: `10`.
`session_timeout_secs`	integer	`3600`	Idle session timeout in seconds. Sessions with no activity for this

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.

`agents.<alias>`

Configuration for an aliased agent. Each [agents.<alias>] TOML block deserializes into one of these. The DelegateTool looks up entries here to dispatch a subtask to a named sibling agent.

Key	Type	Default	Description
`a2a`	object	`—`	Per-agent A2A publication and exposed-skill configuration.
`acp_enable_mcp`	bool	`false`	Initialize this agent’s `mcp_bundles` tools when it serves an ACP
`channels`	string[]	`[]`	Channel aliases this agent handles (e.g. `["telegram.<alias>", "discord.<alias>"]`).
`classifier_provider`	string	`—`	Reference to a configured `[providers.models.<type>.<alias>]` entry.
`cron_jobs`	string[]	`[]`	Cron job aliases. Each entry references `cron[key]`, a declarative
`delegate_same_risk_profile`	bool	`true`	Auto-allow delegation to every agent sharing this agent’s risk
`delegates`	object[]	`[]`	Explicit delegate roster: additional agent aliases this agent may
`enabled`	bool	`true`	Whether this agent is active. Set false to disable without removing the definition.
`identity`	object	`—`	Identity format configuration (`[identity]` section).
`knowledge_bundles`	string[]	`[]`	Knowledge bundle aliases. Additive: the agent loads every listed
`mcp_bundles`	string[]	`[]`	MCP bundle aliases. Each entry references `mcp_bundles[key]`, a named
`memory`	object	`—`	Per-agent memory backend selection and its persistence contract.
`model_provider`	string	`—`	Reference to a configured `[providers.models.<type>.<alias>]` entry.
`precheck`	object	`—`	Per-channel reply-intent precheck configuration.
`risk_profile`	string	`—`	Reference to a configured `[risk_profiles.<type>.<alias>]` entry.
`runtime_profile`	string	`—`	Reference to a configured `[runtime_profiles.<type>.<alias>]` entry.
`skill_bundles`	string[]	`[]`	Skill bundle aliases. Each entry resolves to
`summary_provider`	string	`—`	Reference to a configured `[providers.models.<type>.<alias>]` entry.
`transcription_provider`	string	`—`	Reference to a configured `[providers.transcription.<type>.<alias>]` entry.
`tts_provider`	string	`—`	Reference to a configured `[providers.tts.<type>.<alias>]` entry.
`workspace`	object	`—`	Per-agent workspace and cross-agent access configuration.

`agents.<alias>.a2a`

Per-agent A2A publication and exposed-skill configuration.

Key	Type	Default	Description
`exposed_skills`	string[]	`[]`	Filter selecting which resolved skill ids appear on this alias’s
`published`	bool	`false`	Publish this alias as a discoverable A2A agent. Default `false`:

`agents.<alias>.identity`

Identity format configuration ([identity] section).

Supports "openclaw" (default) or "aieos" identity documents.

Key	Type	Default	Description
`aieos_inline`	string?	`null`	Inline AIEOS JSON (alternative to file path)
`aieos_path`	string?	`null`	Path to AIEOS JSON file (relative to workspace)
`format`	string	`"openclaw"`	Identity format: “openclaw” (default) or “aieos”

`agents.<alias>.memory`

Per-agent memory backend selection and its persistence contract.

Key	Type	Default	Description
`backend`	table	`—`	Selects the memory backend used by an agent.

`agents.<alias>.precheck`

Per-channel reply-intent precheck configuration.

Key	Type	Default	Description
`enabled`	bool	`true`	When false, the precheck is skipped entirely for this agent and every
`timeout_secs`	integer	`5`	Hard ceiling (seconds) on the precheck LLM call. On timeout the

`agents.<alias>.workspace`

Per-agent workspace and cross-agent access configuration.

Key	Type	Default	Description
`access`	map	`{}`	Cross-agent workspace allowlist. An empty map grants no sibling access.
`path`	string?	`—`	Optional explicit workspace path. `None` = derive from
`read_memory_from`	string[]	`[]`	Cross-agent memory allowlist. An empty list grants access only to local memory.
`unrestricted_filesystem`	bool	`false`	Escape hatch: when `true`, the agent can read or write anywhere

`backup`

Backup tool configuration ([backup] section).

Key	Type	Default	Description
`compress`	bool	`true`	Compress backup archives.
`destination_dir`	string	`"state/backups"`	Output directory for backup archives (relative to workspace root).
`enabled`	bool	`true`	Enable the `backup` tool.
`encrypt`	bool	`false`	Encrypt backup archives (requires a configured secret store key).
`include_dirs`	string[]	`["config","memory","audit","knowledge"]`	Workspace subdirectories to include in backups.
`max_keep`	integer	`10`	Maximum number of backups to keep (oldest are pruned).
`schedule_cron`	string?	`null`	Optional cron expression for scheduled automatic backups.
`schedule_timezone`	string?	`null`	IANA timezone for `schedule_cron`.

`browser`

Browser automation configuration ([browser] section).

Controls the browser_open tool and browser automation backends.

Key	Type	Default	Description
`allowed_domains`	string[]	`["*"]`	Allowed domains for `browser_open` (exact or subdomain match)
`allowed_private_hosts`	string[]	`[]`	Private/internal hosts allowed to bypass SSRF protection.
`backend`	string	`"agent_browser"`	Browser automation backend: “agent_browser” \| “rust_native” \| “computer_use” \| “auto”
`computer_use`	object	`—`	Computer-use sidecar configuration (`[browser.computer_use]` section).
`enabled`	bool	`true`	Enable `browser_open` tool (opens URLs in the system browser without scraping)
`headed`	bool?	`null`	Show browser window for agent_browser backend. When unset, inherits AGENT_BROWSER_HEADED.
`native_chrome_path`	string?	`null`	Optional Chrome/Chromium executable path for rust-native backend
`native_headless`	bool	`true`	Headless mode for rust-native backend
`native_webdriver_url`	string	`"http://127.0.0.1:9515"`	WebDriver endpoint URL for rust-native backend (e.g. `http://127.0.0.1:9515`)
`session_name`	string?	`null`	Browser session name (for agent-browser automation)

`browser.computer_use`

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

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

Key	Type	Default	Description
`allow_remote_endpoint`	bool	`false`	Allow remote/public endpoint for computer-use sidecar (default: false)
`api_key` 🔑	string?	`null`	Optional bearer token for computer-use sidecar
`endpoint`	string	`"http://127.0.0.1:8787/v1/actions"`	Sidecar endpoint for computer-use actions (OS-level mouse/keyboard/screenshot)
`max_coordinate_x`	integer?	`null`	Optional X-axis boundary for coordinate-based actions
`max_coordinate_y`	integer?	`null`	Optional Y-axis boundary for coordinate-based actions
`timeout_ms`	integer	`15000`	Per-action request timeout in milliseconds
`window_allowlist`	string[]	`[]`	Optional window title/process allowlist forwarded to sidecar policy

`browser_delegate`

Key	Type	Default
`allowed_domains`	string[]	`[]`
`blocked_domains`	string[]	`[]`
`chrome_profile_dir`	string	`""`
`cli_binary`	string	`"claude"`
`enabled`	bool	`false`
`task_timeout_secs`	integer	`120`

`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").

Key	Type	Default	Description
`ack_reactions`	bool	`true`	Whether to add acknowledgement reactions (👀 on receipt, ✅/⚠️ on
`amqp`	map	`—`	AMQP channel instances (`[channels.amqp.<alias>]`).
`bluesky`	map	`—`	Bluesky channel instances (`[channels.bluesky.<alias>]`).
`clawdtalk`	map	`—`	ClawdTalk voice channel instances (`[channels.clawdtalk.<alias>]`).
`cli`	bool	`true`	Enable the CLI interactive channel. Default: `true`.
`debounce_ms`	integer	`0`	Inbound message debounce window in milliseconds. When a sender fires
`dingtalk`	map	`—`	DingTalk channel instances (`[channels.dingtalk.<alias>]`).
`discord`	map	`—`	Discord bot channel instances (`[channels.discord.<alias>]`).
`email`	map	`—`	Email channel instances (`[channels.email.<alias>]`).
`filesystem`	map	`—`	Filesystem SOP listener instances (`[channels.filesystem.<alias>]`).
`git`	map	`—`	Git-forge channel instances (`[channels.git.<alias>]`). GitHub is
`gmail_push`	map	`—`	Gmail Pub/Sub push notification channel instances (`[channels.gmail_push.<alias>]`).
`imessage`	map	`—`	iMessage channel instances (`[channels.imessage.<alias>]`, macOS only).
`irc`	map	`—`	IRC channel instances (`[channels.irc.<alias>]`).
`lark`	map	`—`	Lark channel instances (`[channels.lark.<alias>]`).
`line`	map	`—`	LINE Messaging API channel instances (`[channels.line.<alias>]`).
`linq`	map	`—`	Linq Partner API channel instances (`[channels.linq.<alias>]`).
`matrix`	map	`—`	Matrix channel instances (`[channels.matrix.<alias>]`).
`mattermost`	map	`—`	Mattermost bot channel instances (`[channels.mattermost.<alias>]`).
`max_concurrent_per_channel`	integer	`4`	Per-channel multiplier for the global channel message in-flight budget.
`message_timeout_secs`	integer	`300`	Base timeout in seconds for processing a single channel message (LLM + tools).
`mochat`	map	`—`	Mochat customer service channel instances (`[channels.mochat.<alias>]`).
`mqtt`	map	`—`	MQTT channel instances (`[channels.mqtt.<alias>]`).
`nextcloud_talk`	map	`—`	Nextcloud Talk bot channel instances (`[channels.nextcloud_talk.<alias>]`).
`nostr`	map	`—`
`qq`	map	`—`	QQ Official Bot channel instances (`[channels.qq.<alias>]`).
`reddit`	map	`—`	Reddit channel instances (`[channels.reddit.<alias>]`).
`session_backend`	string	`"sqlite"`	Session persistence backend: `"jsonl"` (legacy) or `"sqlite"` (new default).
`session_persistence`	bool	`true`	Persist channel conversation history to JSONL files so sessions survive
`session_ttl_hours`	integer	`0`	Auto-archive stale sessions older than this many hours. `0` disables. Default: `0`.
`show_tool_calls`	bool	`false`	Whether to send tool-call notification messages (e.g. `🔧 web_search_tool: …`)
`signal`	map	`—`	Signal channel instances (`[channels.signal.<alias>]`).
`slack`	map	`—`	Slack bot channel instances (`[channels.slack.<alias>]`).
`telegram`	map	`—`	Telegram bot channel instances (`[channels.telegram.<alias>]`).
`twitch`	map	`—`	Twitch chat channel instances (`[channels.twitch.<alias>]`).
`twitter`	map	`—`	X/Twitter channel instances (`[channels.twitter.<alias>]`).
`voice_call`	map	`—`	Voice call channel instances (`[channels.voice_call.<alias>]`).
`voice_duplex`	map	`—`	Voice duplex instances (`[channels.voice_duplex.<alias>]`).
`voice_wake`	map	`—`	Voice wake word detection channel instances (`[channels.voice_wake.<alias>]`).
`wati`	map	`—`	WATI WhatsApp Business API channel instances (`[channels.wati.<alias>]`).
`webhook`	map	`—`	Webhook channel instances (`[channels.webhook.<alias>]`).
`wechat`	map	`—`	WeChat personal iLink Bot channel instances (`[channels.wechat.<alias>]`).
`wecom`	map	`—`	WeCom (WeChat Enterprise) Bot Webhook channel instances (`[channels.wecom.<alias>]`).
`wecom_ws`	map	`—`	WeCom AI Bot WebSocket channel instances (`[channels.wecom_ws.<alias>]`).
`whatsapp`	map	`—`	WhatsApp channel instances (`[channels.whatsapp.<alias>]`).

`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.

Key	Type	Default	Description
`allowed_tools`	string[]	`["Read","Edit","Bash","Write"]`	Claude Code tools the subprocess is allowed to use
`enabled`	bool	`false`	Enable the `claude_code` tool
`env_passthrough`	string[]	`[]`	Extra env vars passed to the claude subprocess (e.g. ANTHROPIC_API_KEY for API-key billing)
`max_output_bytes`	integer	`2097152`	Maximum output size in bytes (2MB default)
`system_prompt`	string?	`null`	Optional system prompt appended to Claude Code invocations
`timeout_secs`	integer	`600`	Maximum execution time in seconds (coding tasks can be long)

`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.

Key	Type	Default	Description
`enabled`	bool	`false`	Enable the `claude_code_runner` tool
`session_ttl`	integer	`3600`	Session time-to-live in seconds before auto-cleanup (default: 3600)
`ssh_host`	string?	`null`	SSH host for session handoff links (e.g. “myhost.example.com”)
`tmux_prefix`	string	`"zc-claude-"`	Prefix for tmux session names (default: “zc-claude-”)

`cloud_ops`

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

Key	Type	Default	Description
`cost_threshold_monthly_usd`	number	`100.0`	Monthly USD threshold to flag cost items. Default: 100.0.
`default_cloud`	string	`"aws"`	Default cloud model_provider for analysis context. Default: “aws”.
`enabled`	bool	`false`	Enable cloud operations tools. Default: false.
`iac_tools`	string[]	`["terraform"]`	Supported IaC tools for review. Default: [`terraform`].
`supported_clouds`	string[]	`["aws","azure","gcp"]`	Supported cloud model_providers. Default: [`aws`, `azure`, `gcp`].
`well_architected_frameworks`	string[]	`["aws-waf"]`	Well-Architected Frameworks to check against. Default: [`aws-waf`].

`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.

Key	Type	Default	Description
`enabled`	bool	`false`	Enable the `codex_cli` tool
`env_passthrough`	string[]	`[]`	Extra env vars passed to the codex subprocess (e.g. OPENAI_API_KEY)
`extra_args`	string[]	`[]`	Extra CLI arguments appended to `codex exec` before the prompt.
`max_output_bytes`	integer	`2097152`	Maximum output size in bytes (2MB default)
`timeout_secs`	integer	`600`	Maximum execution time in seconds (coding tasks can be long)

`composio`

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

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

Key	Type	Default	Description
`api_key` 🔑	string?	`null`	Composio API key (stored encrypted when secrets.encrypt = true)
`enabled`	bool	`false`	Enable Composio integration for 1000+ OAuth tools
`entity_id`	string	`"default"`	Default entity ID for multi-user setups

`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.

Key	Type	Default	Description
`analytics_enabled`	bool	`false`	Enable conversation analytics tracking. Default: false (privacy-by-default).
`auto_detect_language`	bool	`true`	Automatically detect user language from message content. Default: true.
`conversation_timeout_secs`	integer	`1800`	Conversation timeout in seconds (inactivity). Default: 1800.
`default_language`	string	`"en"`	Default language for conversations (BCP-47 tag). Default: “en”.
`enabled`	bool	`false`	Enable conversational AI features. Default: false.
`escalation_confidence_threshold`	number	`0.3`	Intent confidence below this threshold triggers escalation. Default: 0.3.
`knowledge_base_tool`	string?	`null`	Optional tool name for RAG-based knowledge base lookup during conversations.
`max_conversation_turns`	integer	`50`	Maximum conversation turns before auto-ending. Default: 50.
`supported_languages`	string[]	`["en","de","fr","it"]`	Supported languages for conversations. Default: [`en`, `de`, `fr`, `it`].

`cost`

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

Key	Type	Default	Description
`allow_override`	bool	`false`	Allow requests to exceed budget with –override flag (default: false)
`daily_limit_usd`	number	`10.0`	Daily spending limit in USD (default: 10.00)
`enabled`	bool	`true`	Enable cost tracking (default: true)
`enforcement`	object	`—`	Configuration for cost enforcement behavior when budget limits are reached.
`monthly_limit_usd`	number	`100.0`	Monthly spending limit in USD (default: 100.00)
`rates`	object	`—`	`[cost.rates]` — top-level rate-sheet namespace. Mirrors the
`track_per_agent`	bool	`true`	Stamp each recorded cost entry with the originating agent alias so
`warn_at_percent`	integer	`80`	Warn when spending reaches this percentage of limit (default: 80)

`cost.enforcement`

Configuration for cost enforcement behavior when budget limits are reached.

Key	Type	Default	Description
`mode`	string	`"warn"`	Enforcement mode: “warn”, “block”, or “route_down”.
`reserve_percent`	integer	`10`	Reserve this percentage of budget for critical operations.
`route_down_model`	string?	`null`	Model hint to route to when budget is exceeded (used with “route_down” mode).

`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.

Key	Type	Default	Description
`providers`	object	`—`	`[cost.rates.providers.*]` — provider-shaped rate sheets. Each field
`tools`	map	`{}`	`[cost.rates.tools.<name>]` — per-call rates for tools that

`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]).

Key	Type	Default	Description
`models`	object	`—`	`[cost.rates.providers.models.<type>.<model>]` — token-cost rates
`transcription`	object	`—`	`cost.rates.providers.transcription.<type>.<model>`
`tts`	object	`—`	`cost.rates.providers.tts.<type>.<voice>`

`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].

`cron.<alias>`

A declarative cron job definition ([cron.<alias>]).

Stored alias-keyed on Config.cron. The map key serves as the stable job id. Synced into the database at scheduler startup with source = "declarative", distinguishing them from jobs created imperatively via CLI or API. Declarative config takes precedence on each sync: if the config changes, the DB is updated to match. Imperative jobs are never deleted by sync.

Key	Type	Default	Description
`allowed_tools`	string[]?	`null`	Optional allowlist of tool names for agent jobs. When omitted, scheduler
`command`	string?	`null`	Shell command to run (required when `job_type = "shell"`).
`delivery`	object	`—`	Delivery configuration for declarative cron jobs.
`enabled`	bool	`true`	Whether the job is enabled. Default: `true`.
`job_type`	string	`"shell"`	Job type: `"shell"` (default) or `"agent"`.
`model`	string?	`null`	Model override for agent jobs.
`name`	string?	`null`	Human-readable name.
`prompt`	string?	`null`	Agent prompt (required when `job_type = "agent"`).
`schedule`	table	`—`	Schedule variant for declarative cron jobs.
`session_target`	string?	`null`	Session target: `"isolated"` (default) or `"main"`.
`uses_memory`	bool	`true`	Whether to recall and inject memory context before this agent job runs.

`cron.<alias>.delivery`

Delivery configuration for declarative cron jobs.

Key	Type	Default	Description
`best_effort`	bool	`true`	Best-effort delivery. Default: `true`.
`channel`	string?	`null`	Channel name (e.g. `"telegram"`, `"discord"`).
`mode`	string	`"none"`	Delivery mode: `"none"` or `"announce"`.
`thread_id`	string?	`—`	Optional thread/conversation identifier carried into the outbound send.
`to`	string?	`null`	Target/recipient identifier.

`data_retention`

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

Key	Type	Default	Description
`categories`	string[]	`[]`	Limit retention enforcement to specific data categories (empty = all).
`dry_run`	bool	`false`	Preview what would be deleted without actually removing anything.
`enabled`	bool	`false`	Enable the `data_management` tool.
`retention_days`	integer	`90`	Days of data to retain before purge eligibility.

`delegate`

Global delegate tool configuration for default timeout values.

Key	Type	Default	Description
`agentic_timeout_secs`	integer	`300`	Default timeout in seconds for agentic sub-agent runs.
`timeout_secs`	integer	`120`	Default timeout in seconds for non-agentic sub-agent model_provider calls.

`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.

Key	Type	Default	Description
`alert_channels`	string[]	`[]`	Channel names to alert on high/critical escalations (default: empty).

`eval`

Configuration for the agent evaluation harness ([eval]), surfaced via the zeroclaw eval command. Distinct from [agent.eval], which is the in-loop response-quality scorer.

Key	Type	Default	Description
`mode`	string	`"replay"`	Default execution mode (`replay` or `live`) used when `--mode` is omitted.
`suite_dir`	string	`"evals"`	Default directory of `*.json` trace fixtures used when `--suite` is omitted.

`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.

Key	Type	Default	Description
`headers` 🔑	map	`{}`	Static HTTP headers attached to every download request — typically an
`max_file_size_bytes`	integer	`26214400`	Maximum download size in bytes. Enforced while streaming: the transfer
`timeout_secs`	integer	`120`	Request timeout in seconds. Default: 120.
`url`	string?	`null`	Download endpoint URL. Tool is disabled when this is `None` or empty.

`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.

Key	Type	Default	Description
`field_name`	string	`"file"`	Multipart form-field name for the file part. Default: `file`.
`headers` 🔑	map	`{}`	Static HTTP headers attached to every upload request. Same shape as
`max_file_size_bytes`	integer	`26214400`	Maximum file size in bytes. Larger files are rejected before any
`method`	string	`"POST"`	HTTP method. Only `POST` (default) and `PUT` are accepted.
`timeout_secs`	integer	`60`	Request timeout in seconds. Default: 60.
`url`	string?	`null`	Upload endpoint URL. Tool is disabled when this is `None` or empty.

`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.

Key	Type	Default	Description
`field_name`	string	`"file"`	Multipart form-field name reused across every file part. Default: `file`.
`headers` 🔑	map	`{}`	Static HTTP headers attached to every upload request.
`max_file_size_bytes`	integer	`10485760`	Maximum per-file size in bytes. Default: 10 MiB.
`max_files`	integer	`16`	Maximum number of files per call. Default: 16.
`max_response_body_bytes`	integer	`4096`	Maximum response body bytes to read from the upload endpoint.
`max_total_size_bytes`	integer	`33554432`	Maximum cumulative size across every file in one call. Default: 32 MiB.
`method`	string	`"POST"`	HTTP method. Only `POST` (default) and `PUT` are accepted.
`timeout_secs`	integer	`120`	Request timeout in seconds. Default: 120.
`url`	string?	`null`	Upload endpoint URL. Tool is disabled when this is `None` or empty.

`gateway`

Gateway server configuration ([gateway] section).

Controls the HTTP gateway for webhook and pairing endpoints.

Key	Type	Default	Description
`allow_public_bind`	bool	`false`	Allow binding to non-localhost without a tunnel (default: false)
`allow_remote_admin`	bool	`false`	Allow authenticated remote callers to use admin endpoints that are
`allow_self_upgrade`	bool	`false`	Allow triggering a self-upgrade (binary swap via `zeroclaw update`) from
`check_updates`	bool	`true`	Poll GitHub for newer releases and show an “update available” indicator
`host`	string	`"127.0.0.1"`	Gateway host (default: 127.0.0.1)
`idempotency_max_keys`	integer	`10000`	Maximum distinct idempotency keys retained in memory.
`idempotency_ttl_secs`	integer	`300`	TTL for webhook idempotency keys.
`long_running_request_timeout_secs`	integer	`600`	HTTP request timeout (seconds) for `POST /api/cron/{id}/run`, which
`pair_rate_limit_per_minute`	integer	`10`	Max `/pair` requests per minute per client key.
`paired_tokens` 🔑	string[]	`[]`	Paired bearer tokens (managed automatically, not user-edited)
`pairing_dashboard`	object	`—`	Pairing dashboard configuration (`[gateway.pairing_dashboard]`).
`path_prefix`	string?	`null`	Optional URL path prefix for reverse-proxy deployments.
`port`	integer	`42617`	Gateway port (default: 42617)
`rate_limit_max_keys`	integer	`10000`	Maximum distinct client keys tracked by gateway rate limiter maps.
`request_timeout_secs`	integer	`30`	HTTP request timeout (seconds) for gateway routes other than the
`require_pairing`	bool	`true`	Require pairing before accepting requests (default: true)
`session_persistence`	bool	`true`	Persist gateway WebSocket chat sessions to SQLite. Default: true.
`session_ttl_hours`	integer	`0`	Auto-archive stale gateway sessions older than N hours. 0 = disabled. Default: 0.
`tls`	object	`—`	TLS configuration for the gateway server (`[gateway.tls]`).
`trust_forwarded_headers`	bool	`false`	Trust proxy-forwarded client IP headers (`X-Forwarded-For`, `X-Real-IP`).
`web_dist_dir`	string?	`null`	Path to the web dashboard `dist` directory. When set, the gateway
`webhook_rate_limit_per_minute`	integer	`60`	Max `/webhook` requests per minute per client key.

`gateway.pairing_dashboard`

Pairing dashboard configuration ([gateway.pairing_dashboard]).

Key	Type	Default	Description
`code_length`	integer	`8`	Length of pairing codes (default: 8)
`code_ttl_secs`	integer	`3600`	Time-to-live for pending pairing codes in seconds (default: 3600)
`lockout_secs`	integer	`300`	Lockout duration in seconds after max attempts (default: 300)
`max_failed_attempts`	integer	`5`	Maximum failed pairing attempts before lockout (default: 5)
`max_pending_codes`	integer	`3`	Maximum concurrent pending pairing codes (default: 3)

`gateway.tls`

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

Key	Type	Default	Description
`cert_path`*	string	`—`	Path to the PEM-encoded server certificate file.
`client_auth`	object	`—`	Client certificate authentication (mTLS) configuration (`[gateway.tls.client_auth]`).
`enabled`	bool	`false`	Enable TLS for the gateway (default: false).
`key_path`*	string	`—`	Path to the PEM-encoded server private key file.

`gateway.tls.client_auth`

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

Key	Type	Default	Description
`ca_cert_path`	string	`""`	Path to the PEM-encoded CA certificate used to verify client certs.
`enabled`	bool	`false`	Enable client certificate verification (default: false).
`pinned_certs`	string[]	`[]`	Optional SHA-256 fingerprints for certificate pinning.
`require_client_cert`	bool	`true`	Reject connections that do not present a valid client certificate (default: true).

`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.

Key	Type	Default	Description
`enabled`	bool	`false`	Enable the `gemini_cli` tool
`env_passthrough`	string[]	`[]`	Extra env vars passed to the gemini subprocess (e.g. GOOGLE_API_KEY)
`max_output_bytes`	integer	`2097152`	Maximum output size in bytes (2MB default)
`timeout_secs`	integer	`600`	Maximum execution time in seconds (coding tasks can be long)

`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.

Key	Type	Default	Description
`allowed_operations`	object[]	`[]`	Restrict which resource/method combinations the agent can access.
`allowed_services`	string[]	`[]`	Restrict which Google Workspace services the agent can access.
`audit_log`	bool	`false`	Enable audit logging of every `gws` invocation (service, resource,
`credentials_path`	string?	`null`	Path to service account JSON or OAuth client credentials file.
`default_account`	string?	`null`	Default Google account email to pass to `gws --account`.
`enabled`	bool	`false`	Enable the `google_workspace` tool. Default: `false`.
`rate_limit_per_minute`	integer	`60`	Maximum number of `gws` API calls allowed per minute. Default: `60`.
`timeout_secs`	integer	`30`	Command execution timeout in seconds. Default: `30`.

`hardware`

Wizard-driven hardware configuration for physical world interaction.

Key	Type	Default	Description
`baud_rate`	integer	`115200`	Baud rate negotiated on the serial link. 115200 matches the common Arduino / ESP32 bootloader default; bump to 230400+ when your firmware explicitly supports faster rates and you need the throughput.
`enabled`	bool	`false`	Opt in to direct physical-hardware control — GPIO pins, USB-tethered microcontrollers (Arduino, ESP32, Nucleo), or SWD/JTAG debug probes. Leave off for software-only use; turning it on without the right transport configured does nothing.
`probe_target`	string?	`null`	Target chip identifier for `transport = probe` (e.g. `STM32F401RE`, `nRF52840_xxAA`). Passed straight to probe-rs for flash/debug operations; must match a chip probe-rs recognizes.
`serial_port`	string?	`null`	TTY path for the `serial` transport — e.g. `/dev/ttyACM0` on Linux, `/dev/tty.usbmodem1` on macOS, `COM3` on Windows. Ignored for other transports.
`transport`	`None` \| `Native` \| `Serial` \| `Probe`	`—`	Hardware transport mode.
`workspace_datasheets`	bool	`false`	Index pre-converted `.md` and `.txt` datasheets from the workspace into

`heartbeat`

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

Key	Type	Default	Description
`adaptive`	bool	`false`	Enable adaptive intervals that back off on failures and speed up for
`agent`	string	`""`	Configured agent alias the heartbeat worker runs as. Required
`deadman_channel`	string?	`null`	Channel for dead-man’s switch alerts (e.g. `telegram`). Falls back to
`deadman_timeout_minutes`	integer	`0`	Dead-man’s switch timeout in minutes. If the heartbeat has not ticked
`deadman_to`	string?	`null`	Recipient for dead-man’s switch alerts. Falls back to `to`.
`enabled`	bool	`false`	Enable periodic heartbeat pings. Default: `false`. When enabled,
`interval_minutes`	integer	`30`	Interval in minutes between heartbeat pings. Minimum: `1`. Default: `30`.
`load_session_context`	bool	`false`	Load the channel session history before each heartbeat task execution so
`max_interval_minutes`	integer	`120`	Maximum interval in minutes when adaptive mode backs off. Default: `120`.
`max_run_history`	integer	`100`	Maximum number of heartbeat run history records to retain. Default: `100`.
`message`	string?	`null`	Optional fallback task text when `HEARTBEAT.md` has no task entries.
`min_interval_minutes`	integer	`5`	Minimum interval in minutes when adaptive mode is enabled. Default: `5`.
`target`	string?	`null`	Optional delivery channel for heartbeat output (for example: `telegram`).
`task_timeout_secs`	integer	`600`	Maximum wall-clock seconds allowed for a single agent invocation
`to`	string?	`null`	Optional delivery recipient/chat identifier (required when `target` is
`two_phase`	bool	`true`	Enable two-phase heartbeat: Phase 1 asks LLM whether to run, Phase 2

`hooks`

Key	Type	Default	Description
`builtin`	object	`—`
`enabled`	bool	`true`	Enable lifecycle hook execution.

`hooks.builtin`

Key	Type	Default	Description
`command_logger`	bool	`false`	Enable the command-logger hook (logs tool calls for auditing).
`webhook_audit`	object	`—`	Configuration for the webhook-audit builtin hook.

`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.

Key	Type	Default	Description
`enabled`	bool	`false`	Enable the webhook-audit hook. Default: `false`.
`include_args`	bool	`false`	Include tool call arguments in the audit payload. Default: `false`.
`max_args_bytes`	integer	`4096`	Maximum size (in bytes) of serialised arguments included in a single
`tool_patterns`	string[]	`[]`	Glob patterns for tool names to audit (e.g. `["Bash", "Write"]`).
`url`	string	`""`	Target URL that will receive the audit POST requests.

`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.

Key	Type	Default	Description
`allow_private_hosts`	bool	`false`	Allow requests to private/LAN hosts (RFC 1918, loopback, link-local, .local).
`allowed_domains`	string[]	`["*"]`	Allowed domains for HTTP requests (exact or subdomain match)
`allowed_private_hosts`	string[]	`[]`	Private/internal hosts explicitly allowed to bypass SSRF protection.
`enabled`	bool	`true`	Enable `http_request` tool for API interactions
`max_response_size`	integer	`1000000`	Maximum response size in bytes (default: 1MB, 0 = unlimited)
`secrets` 🔑	map	`{}`	Named authorization secrets for `auth_secret` requests.
`timeout_secs`	integer	`30`	Request timeout in seconds (default: 30)

`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.

Key	Type	Default	Description
`api_key_env`	string	`"FAL_API_KEY"`	Environment variable name holding the fal.ai API key.
`default_model`	string	`"fal-ai/flux/schnell"`	Default fal.ai model identifier.
`enabled`	bool	`false`	Enable the standalone image generation tool. Default: false.

`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.

Key	Type	Default	Description
`allowed_actions`	string[]	`["get_ticket"]`	Actions the agent is permitted to call.
`api_token` 🔑	string	`""`	Jira API token. Encrypted at rest. Falls back to `JIRA_API_TOKEN` env var.
`base_url`	string	`""`	Atlassian instance base URL, e.g. `https://yourco.atlassian.net`.
`email`	string?	`—`	Jira account email used for Basic auth (Cloud).
`enabled`	bool	`false`	Enable the `jira` tool. Default: `false`.
`timeout_secs`	integer	`30`	Request timeout in seconds. Default: `30`.

`knowledge`

Knowledge graph configuration for capturing and reusing expertise.

Key	Type	Default	Description
`auto_capture`	bool	`false`	Automatically capture knowledge from conversations. Default: false.
`db_path`	string	`"/home/runner/.zeroclaw/knowledge.db"`	Path to the knowledge graph SQLite database.
`enabled`	bool	`false`	Enable the knowledge graph tool. Default: false.
`max_nodes`	integer	`100000`	Maximum number of knowledge nodes. Default: 100000.
`suggest_on_query`	bool	`true`	Proactively suggest relevant knowledge on queries. Default: true.

`knowledge_bundles`

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

`knowledge_bundles.<alias>`

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

A reusable set of knowledge sources (documents, URLs, or RAG corpus paths) that can be attached to an agent by alias.

Key	Type	Default	Description
`sources`	string[]	`[]`	Paths or URLs to include in this knowledge bundle.
`tags`	string[]	`[]`	Tags for filtering or categorising sources within the bundle.

`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.

Key	Type	Default	Description
`enabled`	bool	`false`	Enable the link enricher pipeline stage (default: false)
`max_links`	integer	`3`	Maximum number of links to fetch per message (default: 3)
`timeout_secs`	integer	`10`	Per-link fetch timeout in seconds (default: 10)

`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.

Key	Type	Default	Description
`api_version`	string	`"202602"`	LinkedIn REST API version header (YYYYMM format).
`content`	object	`—`	Content strategy configuration for LinkedIn auto-posting (`[linkedin.content]`).
`enabled`	bool	`false`	Enable the LinkedIn tool.
`image`	object	`—`	Image generation configuration for LinkedIn posts (`[linkedin.image]`).

`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.

Key	Type	Default	Description
`github_repos`	string[]	`[]`	GitHub repositories to highlight (format: `owner/repo`).
`github_users`	string[]	`[]`	GitHub usernames whose public activity to reference.
`instructions`	string	`""`	Freeform posting instructions for the AI agent.
`persona`	string	`""`	Professional persona description (name, role, expertise).
`rss_feeds`	string[]	`[]`	RSS feed URLs to monitor for topic inspiration (titles only).
`topics`	string[]	`[]`	Topics of expertise and interest for post themes.

`linkedin.image`

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

Key	Type	Default	Description
`card_accent_color`	string	`"#0A66C2"`	Accent color for the fallback card (CSS hex).
`dalle`	object	`—`	OpenAI DALL-E settings (`[linkedin.image.dalle]`).
`enabled`	bool	`false`	Enable image generation for posts.
`fallback_card`	bool	`true`	Generate a branded SVG text card when all AI model_providers fail.
`flux`	object	`—`	Flux (fal.ai) image generation settings (`[linkedin.image.flux]`).
`imagen`	object	`—`	Google Imagen (Vertex AI) settings (`[linkedin.image.imagen]`).
`providers`	string[]	`["stability","imagen","dalle","flux"]`	ModelProvider priority order. Tried in sequence; first success wins.
`stability`	object	`—`	Stability AI image generation settings (`[linkedin.image.stability]`).
`temp_dir`	string	`"linkedin/images"`	Temp directory for generated images, relative to workspace.

`linkedin.image.dalle`

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

Key	Type	Default	Description
`api_key_env`	string	`"OPENAI_API_KEY"`	Environment variable name holding the OpenAI API key.
`model`	string	`"dall-e-3"`	DALL-E model identifier.
`size`	string	`"1024x1024"`	Image dimensions.

`linkedin.image.flux`

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

Key	Type	Default	Description
`api_key_env`	string	`"FAL_API_KEY"`	Environment variable name holding the fal.ai API key.
`model`	string	`"fal-ai/flux/schnell"`	Flux model identifier.

`linkedin.image.imagen`

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

Key	Type	Default	Description
`api_key_env`	string	`"GOOGLE_VERTEX_API_KEY"`	Environment variable name holding the API key.
`project_id_env`	string	`"GOOGLE_CLOUD_PROJECT"`	Environment variable for the Google Cloud project ID.
`region`	string	`"us-central1"`	Vertex AI region.

`linkedin.image.stability`

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

Key	Type	Default	Description
`api_key_env`	string	`"STABILITY_API_KEY"`	Environment variable name holding the API key.
`model`	string	`"stable-diffusion-xl-1024-v1-0"`	Stability model identifier.

`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 the host system’s locale (defaulting to "en" if that can’t be determined).

`mcp`

External MCP client configuration ([mcp] section).

Key	Type	Default	Description
`deferred_loading`	bool	`false`	Load MCP tool schemas on-demand via `tool_search` instead of eagerly
`enabled`	bool	`true`	Enable MCP tool loading.
`servers`	object[]	`[]`	Configured MCP servers. The `#[nested]` annotation makes the macro

`mcp_bundles`

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

`mcp_bundles.<alias>`

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

A reusable group of MCP servers granted to an agent that references the bundle by alias in agents.<alias>.mcp_bundles. Server IDs are matched against [mcp.servers] by name. Resolution is secure by default (see Config::mcp_servers_for_bundles): an ID with no matching server grants nothing, and exclude wins over servers across every bundle an agent references.

Key	Type	Default	Description
`exclude`	string[]	`[]`	MCP server IDs removed from the grant. Deny wins: a name listed here is
`servers`	string[]	`[]`	MCP server IDs (`[mcp.servers].name`) granted by this bundle.

`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.

Key	Type	Default	Description
`describe_images`	bool	`true`	Add image descriptions when a vision-capable model is active.
`enabled`	bool	`false`	Master toggle for the media pipeline (default: false).
`summarize_video`	bool	`true`	Summarize video attachments (placeholder — requires external API).
`transcribe_audio`	bool	`true`	Transcribe audio attachments using the configured transcription model_provider.

`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.

Key	Type	Default	Description
`archive_after_days`	integer	`7`	Move daily/session files to the archive directory after this many days. Keeps the hot working set small without deleting history.
`audit_enabled`	bool	`false`	Enable audit logging of memory operations.
`audit_retention_days`	integer	`30`	Retention period for audit entries in days (default: 30).
`auto_hydrate`	bool	`true`	Auto-hydrate from MEMORY_SNAPSHOT.md when brain.db is missing
`auto_reindex_on_identity_change`	bool	`false`	Automatically re-embed all memories in the background when a change of embedding provider/model/dimensions is detected at startup (after the stale vectors have been cleared). Costs one embedding API call per memory, so it’s off by default — leave it off for large stores and run `zeroclaw memory reindex` explicitly instead.
`auto_save`	bool	`true`	Auto-save what you tell ZeroClaw into memory as conversation history — the agent’s own replies are not saved. Turn off if you want memory to only hold things you explicitly record via the memory tool.
`backend`	string	`"sqlite"`	Dotted reference to the active storage instance: `<backend>.<alias>`
`candidate_multiplier`	integer	`4`	Candidate pool multiplier over the final recall limit before blend/rerank trimming.
`chunk_max_tokens`	integer	`512`	Max tokens per chunk for document splitting
`conflict_supersede_enabled`	bool	`true`	Enable reversible supersede soft-hide machinery when wired.
`conflict_threshold`	number	`0.85`	Cosine similarity threshold for conflict detection (0.0–1.0).
`consolidation_extract_facts`	bool	`false`	Also extract atomic durable facts from each consolidated turn and store
`conversation_retention_days`	integer	`30`	Delete conversation rows older than this many days from the DB (sqlite backend only). Age is measured by `updated_at` (last write time). 0 = keep forever.
`core_max_bytes`	integer	`0`	Maximum Core bytes before budget compaction. 0 = unbounded.
`core_max_rows`	integer	`0`	Maximum Core rows before budget compaction. 0 = unbounded.
`core_retention_days`	integer	`0`	Delete core memory rows older than this many days from the DB. Age is measured by `created_at` (first-write time). Neither recall nor ordinary rewrites refresh `created_at` under the current SQLite upsert, so core retention is an absolute age limit from first write. Set this to a generously large window for durable core memories, or keep 0 = keep forever.
`daily_max_rows`	integer	`0`	Maximum Daily rows before budget compaction. 0 = unbounded.
`daily_retention_days`	integer	`0`	Delete daily memory rows older than this many days from the DB. Age is measured by `updated_at` (last write time). 0 = keep forever.
`dedup_action`	table	`—`	Write-time duplicate handling policy for memory entries.
`dedup_jaccard_threshold`	number	`0.8`	Jaccard threshold for text-only duplicate detection.
`dedup_on_write`	bool	`false`	Enable write-time near-duplicate detection.
`default_namespace`	string	`"default"`	Default namespace for memory entries.
`embedding_api_key` 🔑	string?	`—`	Optional API key for the embedding endpoint. When set, embedding calls use this key instead of inheriting one from the seed model provider — decoupling embeddings from the chat model. Use it when the chat model runs on a provider that carries no usable embedding credential (e.g. an OAuth-only provider) while embeddings keep hitting an `openai`/`custom:` endpoint with their own key. Leave unset to inherit the seed provider’s key (backward-compatible default).
`embedding_cache_size`	integer	`10000`	Max embedding cache entries before LRU eviction
`embedding_dimensions`	integer	`1536`	Vector width produced by the embedding model — must match the model’s native dimension or vectors won’t store correctly. Look up the number on the model_provider’s model page.
`embedding_model`	string	`"text-embedding-3-small"`	Embedding model identifier — must match a model your chosen embedding model_provider serves (e.g. `text-embedding-3-small` for OpenAI). Changing this invalidates existing embeddings: the change is detected at startup and stale vectors are cleared automatically; run `zeroclaw memory reindex` to re-embed (or set `auto_reindex_on_identity_change`).
`embedding_provider`	string	`"none"`	Source of embedding vectors for semantic search. `none` = keyword-only retrieval (no API calls, no vector cost); `openai` = OpenAI’s embedding API; `custom:URL` = any OpenAI-compatible embedding endpoint (LiteLLM, local gateway, etc.).
`evict_order`	table	`—`	Memory budget eviction order.
`fts_early_return_score`	number	`0.85`	Reserved (0.0-1.0): the FTS score above which recall would skip the
`hygiene_enabled`	bool	`true`	Run the periodic hygiene pass that archives stale daily/session files and enforces retention windows. Leave on unless you want to manage cleanup yourself.
`importance_weight`	number	`0.2`	Importance weight used by the recall blend.
`keyword_weight`	number	`0.3`	How heavily BM25 (keyword) overlap counts when `search_mode = hybrid`. Raise toward 1.0 for exact-term matching; lower it when paraphrases should still score well.
`min_relevance_score`	number	`0.4`	Minimum hybrid score (0.0–1.0) for a memory to be included in context.
`mmr_lambda`	number	`0.7`	MMR relevance-vs-diversity weight, where 1.0 means relevance-only.
`pin_min_importance`	number	`1.01`	Pin entries at or above this importance. >1.0 means disabled.
`pin_namespaces`	string[]	`[]`	Namespaces protected from budget eviction.
`policy`	object	`—`	Memory policy configuration (`[memory.policy]` section).
`purge_after_days`	integer	`30`	Delete archived files permanently after this many days. Set high if you need long-term history; set low for privacy / disk-space reasons.
`recency_weight`	number	`0.1`	Recency weight used by the recall blend.
`rerank_enabled`	bool	`false`	Enable the recall rerank stage: blend retrieval score with importance
`rerank_strategy`	string	`"none"`	Advanced rerank strategy. Valid: “none”, “mmr”.
`rerank_threshold`	integer	`5`	Minimum candidate count to trigger the advanced rerank strategy.
`response_cache_enabled`	bool	`false`	Enable LLM response caching to avoid paying for duplicate prompts
`response_cache_hot_entries`	integer	`256`	Max in-memory hot cache entries for the two-tier response cache (default: 256)
`response_cache_max_entries`	integer	`5000`	Max number of cached responses before LRU eviction (default: 5000)
`response_cache_ttl_minutes`	integer	`60`	TTL in minutes for cached responses (default: 60)
`retrieval_stages`	string[]	`["fts","vector"]`	Retrieval stages for per-agent recall. Only `"cache"` is active: it
`search_mode`	table	`—`	Search strategy for memory recall.
`snapshot_enabled`	bool	`false`	Enable periodic export of core memories to MEMORY_SNAPSHOT.md
`snapshot_on_hygiene`	bool	`false`	Run snapshot during hygiene passes (heartbeat-driven)
`types`	object	`—`	Typed memory configuration (`[memory.types]` section).
`vector_weight`	number	`0.7`	How heavily vector (semantic) similarity counts when `search_mode = hybrid`. Raise toward 1.0 to favor meaning-based matches; lower it to lean on keyword overlap instead.

`memory.policy`

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

Key	Type	Default	Description
`max_entries_per_category`	integer	`0`	Maximum entries per category (0 = unlimited).
`max_entries_per_namespace`	integer	`0`	Maximum entries per namespace (0 = unlimited).
`read_only_namespaces`	string[]	`[]`	Namespaces that are read-only (writes are rejected).
`redact_categories`	string[]	`["secret","api_key","private_key","email","phone"]`	Redaction categories applied when `redact_on_write` is true.
`redact_on_write`	bool	`false`	Redact configured secret/PII categories before persistence.
`retention_days_by_category`	map	`{}`	Retention days by category (overrides global). Keys: “core”, “daily”, “conversation”.
`threat_scan`	string	`"on"`	Content scan mode for durable memory writes: “off”, “on”, or “strict”.
`threat_scan_load_time`	bool	`true`	Re-scan stored entries at recall/read time and withhold flagged entries.
`threat_scan_on_hit`	string	`"reject"`	Behavior when a write-time content scan matches: “reject” or

`memory.types`

Typed memory configuration ([memory.types] section).

Behaviour-neutral by default: enabled gates MemoryKind assignment on new consolidation writes and defaults off; the flip is sequenced in a later phase. SQLite-only: enabling requires the sqlite memory backend globally and on every agent (validated at config load).

Key	Type	Default	Description
`enabled`	bool	`false`	Assign a first-class MemoryKind to new consolidation writes.

`microsoft365`

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

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

Key	Type	Default	Description
`auth_flow`	string	`"client_credentials"`	Authentication flow: “client_credentials” or “device_code”
`client_id`	string?	`null`	Azure AD application (client) ID
`client_secret` 🔑	string?	`null`	Azure AD client secret (stored encrypted when secrets.encrypt = true)
`enabled`	bool	`false`	Enable Microsoft 365 integration
`scopes`	string[]	`["https://graph.microsoft.com/.default"]`	OAuth scopes to request
`tenant_id`	string?	`null`	Azure AD tenant ID
`token_cache_encrypted`	bool	`true`	Encrypt the token cache file on disk
`user_id`	string?	`null`	User principal name or “me” (for delegated flows)

`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.

Key	Type	Default	Description
`allow_remote_fetch`	bool	`false`	Allow fetching remote image URLs (http/https). Disabled by default.
`max_image_size_mb`	integer	`5`	Maximum image payload size in MiB before base64 encoding.
`max_image_turns`	integer	`0`	Maximum age of images in conversation turns.
`max_images`	integer	`4`	Maximum number of image attachments accepted per request.
`vision_model`	string?	`null`	Model to use when routing to the vision model_provider (e.g. `"llava:7b"`).
`vision_model_provider`	string?	`null`	ModelProvider name to use for vision/image messages (e.g. `"ollama"`).

`node_transport`

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

Key	Type	Default	Description
`allowed_peers`	string[]	`[]`	Allow specific node IPs/CIDRs.
`connection_pool_size`	integer	`4`	Maximum number of connections per peer.
`enabled`	bool	`true`	Enable the secure transport layer.
`max_request_age_secs`	integer	`300`	Maximum age of signed requests in seconds (replay protection).
`mutual_tls`	bool	`false`	Require client certificates (mutual TLS).
`require_https`	bool	`true`	Require HTTPS for all node communication.
`shared_secret` 🔑	string	`""`	Shared secret for HMAC authentication between nodes.
`tls_cert_path`	string?	`null`	Path to TLS certificate file.
`tls_key_path`	string?	`null`	Path to TLS private key file.

`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.

Key	Type	Default	Description
`auth_token` 🔑	string?	`null`	Optional bearer token for node authentication.
`enabled`	bool	`false`	Enable dynamic node discovery endpoint.
`max_nodes`	integer	`16`	Maximum number of concurrent node connections.
`mdns`	object	`—`	Configuration for LAN-local mDNS peer discovery (`[nodes.mdns]`).

`nodes.mdns`

Configuration for LAN-local mDNS peer discovery ([nodes.mdns]).

This config controls only discovery behavior. The advertised gateway endpoint is derived from the running gateway’s actual host, port, and path prefix at startup so [nodes.mdns] does not duplicate gateway listen state.

Key	Type	Default	Description
`announce_interval_secs`	integer	`30`	How often this node re-broadcasts its presence, in seconds.
`enabled`	bool	`false`	Enable mDNS local peer discovery.
`max_peers`	integer	`16`	Maximum number of unauthenticated LAN peer hints retained in memory.
`node_name`	string?	`null`	Human-readable node name advertised to LAN peers. Defaults to a stable
`peer_ttl_secs`	integer	`90`	Seconds after the last announcement before a peer is evicted.

`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.

Key	Type	Default
`api_key` 🔑	string	`""`
`database_id`	string	`""`
`enabled`	bool	`false`
`input_property`	string	`"Input"`
`max_concurrent`	integer	`4`
`poll_interval_secs`	integer	`5`
`recover_stale`	bool	`true`
`result_property`	string	`"Result"`
`status_property`	string	`"Status"`

`observability`

Observability backend configuration ([observability] section).

Key	Type	Default	Description
`backend`	`none` \| `log` \| `verbose` \| `prometheus` \| `otel`	`—`	Observability sink backend.
`log_llm_request_payload`	`off` \| `redacted` \| `full`	`—`	LLM request payload capture policy. Mirrors [`LogToolIo`] but gates the
`log_persistence`	table	`—`	JSONL log persistence mode.
`log_persistence_max_bytes`	integer	`0`	Size threshold in bytes that triggers an archive rotation when
`log_persistence_max_entries`	integer	`200`	Maximum entries retained when `log_persistence = "rolling"`.
`log_persistence_path`	string	`"state/runtime-trace.jsonl"`	Log persistence file path. Relative paths resolve under workspace_dir.
`log_persistence_retention_max_age_days`	integer	`0`	Retention cap on the age (in days) of rotated archive files when
`log_persistence_retention_max_files`	integer	`7`	Retention cap on the number of rotated archive files kept alongside the
`log_persistence_rotate_daily`	bool	`true`	Rotate the active file to an archive on a UTC day boundary when
`log_tool_io`	`off` \| `redacted` \| `full`	`—`	Tool I/O capture policy.
`log_tool_io_denylist`	string[]	`[]`	Tool names whose I/O is never logged beyond name + outcome + duration
`log_tool_io_truncate_bytes`	integer	`40960`	Truncate the captured tool input and output at this many bytes when
`otel_endpoint`	string?	`null`	OTLP endpoint (e.g. `"http://localhost:4318"`). Only used when backend = `"otel"`.
`otel_genai_content`	`off` \| `redacted` \| `full`	`—`	OTel content capture policy. Mirrors [`LogToolIo`] but gates OTel span
`otel_genai_content_max_chars`	integer	`1000`	Per-field character truncation limit for OTel GenAI content when
`otel_headers` 🔑	map?	`null`	Optional HTTP headers sent with every OTLP export request (e.g. authorization).
`otel_service_name`	string?	`null`	Service name reported to the OTel collector. Defaults to “zeroclaw”.
`otel_tool_io`	`off` \| `redacted` \| `full`	`—`	OTel content capture policy. Mirrors [`LogToolIo`] but gates OTel span
`otel_tool_io_max_chars`	integer	`1000`	Per-field character truncation limit for OTel tool I/O when

`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.

Key	Type	Default	Description
`completed_sections`	string[]	`[]`	Section keys the user has completed at least once.
`quickstart_completed`	bool	`false`	`true` once the Quickstart has applied a `BuilderSubmission`

`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.

Key	Type	Default	Description
`enabled`	bool	`false`	Enable the `opencode_cli` tool
`env_passthrough`	string[]	`[]`	Extra env vars passed to the opencode subprocess
`max_output_bytes`	integer	`2097152`	Maximum output size in bytes (2MB default)
`timeout_secs`	integer	`600`	Maximum execution time in seconds (coding tasks can be long)

`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.

Key	Type	Default	Description
`loop_detection_enabled`	bool	`true`	Enable pattern-based loop detection (exact repeat, ping-pong,
`loop_detection_max_repeats`	integer	`3`	Number of consecutive identical tool+args calls before the first
`loop_detection_min_elapsed_secs`	integer?	`null`	Minimum elapsed seconds before loop detection activates.
`loop_detection_window_size`	integer	`20`	Sliding window size for the pattern-based loop detector.
`loop_ignore_tools`	string[]	`[]`	Tool names excluded from identical-output / alternating-pattern loop
`message_timeout_scale_max`	integer?	`null`	Override for the hardcoded timeout scaling cap (default: 4).
`step_timeout_secs`	integer?	`null`	Per-step timeout in seconds: the maximum time allowed for a single

`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.

`peer_groups.<alias>`

[peer_groups.<name>] — mutual-opt-in peer group on a channel type.

Key	Type	Default	Description
`admin_for_agent_scope`	bool	`false`	When `true`, members of this peer group are authorized to issue
`agents`	string[]	`[]`	Member agents by alias.
`channel`	string	`—`	Reference to a configured `[channels.<type>.<alias>]` entry.
`external_peers`	string[]	`[]`	Non-agent members by channel-native username.
`ignore`	string[]	`[]`	Per-group blocklist; subtracts from the resolved peer set.
`output_modality`	table	`—`	Preferred output modality for a peer group.

`peripherals`

Peripheral board integration configuration ([peripherals] section).

Boards become agent tools when enabled.

Key	Type	Default	Description
`boards`	object[]	`[]`	Board configurations (nucleo-f401re, rpi-gpio, etc.)
`datasheet_dir`	string?	`null`	Path to datasheet docs (relative to workspace) for RAG retrieval.
`enabled`	bool	`false`	Enable peripheral support (boards become agent tools)

`pipeline`

Pipeline tool configuration ([pipeline] section).

Key	Type	Default	Description
`allowed_tools`	string[]	`[]`	Tools allowed in pipeline steps. Steps referencing tools not on this
`enabled`	bool	`false`	Enable the `execute_pipeline` meta-tool.
`max_steps`	integer	`20`	Maximum number of steps allowed in a single pipeline invocation.

`plugins`

Plugin system configuration.

Key	Type	Default	Description
`auto_discover`	bool	`false`	Auto-discover and load plugins on startup
`enabled`	bool	`false`	Enable the plugin system (default: false)
`entries`	object[]	`[]`
`limits`	object	`—`	Per-call WASM execution limits (`[plugins.limits]`).
`max_plugins`	integer	`50`	Maximum number of plugins that can be loaded
`plugins_dir`	string	`"/home/runner/.zeroclaw/plugins"`	Directory where plugins are stored
`security`	object	`—`	Plugin signature verification configuration (`[plugins.security]`).

`plugins.limits`

Per-call WASM execution limits ([plugins.limits]).

Bounds a single plugin call so a runaway or malicious component traps instead of hanging the host or exhausting memory. call_fuel caps instructions per call; the memory, table, and instance ceilings bound a store’s growth. Every value is operator-tunable and validated as non-zero.

Key	Type	Default	Description
`call_fuel`	integer	`1000000000`	Fuel budget per plugin call (wasmtime instruction units).
`max_instances`	integer	`64`	Maximum component instances a plugin store may create.
`max_memory_mb`	integer	`256`	Maximum linear memory a plugin store may grow to, in megabytes.
`max_table_elements`	integer	`100000`	Maximum table elements a plugin store may allocate.

`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.

Key	Type	Default	Description
`signature_mode`	string	`"disabled"`	Signature enforcement mode: “disabled”, “permissive”, or “strict”.
`trusted_publisher_keys`	string[]	`[]`	Hex-encoded Ed25519 public keys of trusted plugin publishers.

`project_intel`

Project delivery intelligence configuration ([project_intel] section).

Key	Type	Default	Description
`default_language`	string	`"en"`	Default report language (en, de, fr, it). Default: “en”.
`enabled`	bool	`false`	Enable the project_intel tool. Default: false.
`include_git_data`	bool	`true`	Include git log data in reports. Default: true.
`include_jira_data`	bool	`false`	Include Jira data in reports. Default: false.
`jira_base_url`	string?	`null`	Jira instance base URL (required if include_jira_data is true).
`report_output_dir`	string	`"/home/runner/.zeroclaw/project-reports"`	Output directory for generated reports.
`risk_sensitivity`	string	`"medium"`	Risk detection sensitivity: low, medium, high. Default: “medium”.
`templates_dir`	string?	`null`	Optional custom templates directory.

`providers`

Top-level wrapper for every configured provider category.

Key	Type	Default	Description
`models`	object	`—`	Typed model provider container with one alias map per provider family.
`transcription`	object	`—`	Typed transcription-provider container — one slot per STT family.
`tts`	object	`—`	Typed TTS-provider container — one slot per TTS family. Mirrors

`providers.models`

Typed model provider container with one alias map per provider family.

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, manifest, minimax, mistral, moonshot, morph, nearai, 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).

Key	Type	Default	Description
`all_proxy`	string?	`null`	Fallback proxy URL for all schemes.
`enabled`	bool	`false`	Enable proxy support for selected scope.
`http_proxy`	string?	`null`	Proxy URL for HTTP requests (supports http, https, socks5, socks5h).
`https_proxy`	string?	`null`	Proxy URL for HTTPS requests (supports http, https, socks5, socks5h).
`no_proxy`	string[]	`[]`	No-proxy bypass list. Same format as NO_PROXY.
`scope`	table	`—`	Proxy application scope — determines which outbound traffic uses the proxy.
`services`	string[]	`[]`	Service selectors used when scope = “services”.

`query_classification`

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

Key	Type	Default	Description
`enabled`	bool	`false`	Enable automatic query classification. Default: `false`.
`rules`	object[]	`[]`	Classification rules evaluated in priority order.

`reliability`

Reliability and supervision configuration ([reliability] section).

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

Key	Type	Default	Description
`api_keys` 🔑	string[]	`[]`	Additional API keys for round-robin rotation on rate-limit (429) errors.
`channel_initial_backoff_secs`	integer	`2`	Initial backoff for channel/daemon restarts.
`channel_max_backoff_secs`	integer	`60`	Max backoff for channel/daemon restarts.
`provider_backoff_ms`	integer	`500`	Base backoff (ms) for model_provider retry delay.
`provider_retries`	integer	`2`	Retries per model_provider before bailing.
`scheduler_poll_secs`	integer	`15`	Scheduler polling cadence in seconds.
`scheduler_retries`	integer	`2`	Max retries for cron job execution attempts.

`risk_profiles`

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

`risk_profiles.<alias>`

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

Unified policy surface. Agents reference a profile by alias and the runtime resolves through it for shell command allowlists, approval gates, sandbox/resource limits, and delegation guardrails. The conventional risk_profiles["default"] is the resolution target for non-agent contexts (orchestrator init, cron worker startup); the Default impl below mirrors the legacy safety-first defaults so a fresh install behaves the same as a config from before the per-profile split.

Key	Type	Default	Description
`allowed_commands`	string[]	`["git","npm","cargo","ls","cat","grep","find","echo","pwd","wc","head","tail","date","df","du","uname","uptime","hostname","python","python3","pip","node","free"]`	Allowlist of executable names for shell execution.
`allowed_roots`	string[]	`[]`	Extra directory roots the agent may access.
`allowed_tools`	string[]	`[]`	Tools the agent may call in agentic mode. Empty = inherit / no
`always_ask`	string[]	`[]`	Tools that always require approval in this profile.
`approval_route`	object	`—`	Routes tool approvals to a distinct approver channel with fail-closed defaults.
`auto_approve`	string[]	`["file_read","memory_recall","web_search_tool","web_fetch","calculator","glob_search","content_search","image_info","weather","tool_search","browser","browser_open"]`	Tools that never require approval in this profile.
`block_high_risk_commands`	bool	`true`	Block high-risk commands even when allowlisted.
`delegation_policy`	object	`—`	Risk-profile delegation policy for work sent to agents that share it.
`excluded_tools`	string[]	`[]`	Tools excluded from non-CLI channels under this profile.
`firejail_args`	string[]	`[]`	Extra arguments forwarded to firejail when sandbox_backend = “firejail”.
`forbidden_paths`	string[]	`["/etc","/root","/home","/usr","/bin","/sbin","/lib","/opt","/boot","/dev","/proc","/sys","/var","/tmp","~/.ssh","~/.gnupg","~/.aws","~/.config"]`	Explicit path denylist.
`level`	table	`—`	The agent’s autonomy level, ordered from least to most autonomous.
`require_approval_for_medium_risk`	bool	`true`	Require approval for medium-risk operations.
`sandbox_backend`	string?	`null`	Sandbox backend identifier (e.g. `"firejail"`, `"landlock"`). `None` inherits.
`sandbox_enabled`	bool?	`null`	Whether the sandbox is enabled for this profile. `None` inherits global.
`shell_env_passthrough`	string[]	`[]`	Environment variable names passed through to shell subprocesses.
`workspace_only`	bool	`true`	Restrict filesystem access to workspace-relative paths. Default: `false`.

`risk_profiles.<alias>.approval_route`

Routes tool approvals to a distinct approver channel with fail-closed defaults.

Key	Type	Default	Description
`approver_channel`*	string	`—`	A registered channel name (NOT the originator) — the distinct-approver hop.
`on_no_approver`	table	`—`	What to do when a configured approver cannot be reached. Default FAIL-CLOSED.
`timeout_secs`	integer	`120`	Bound the approver’s response window; a timeout denies (DoS guard). Default 120s.

`risk_profiles.<alias>.delegation_policy`

Risk-profile delegation policy for work sent to agents that share it.

Key	Type	Default	Description
`mode`	table	`—`	Delegation mode for a risk profile.

`runtime`

Runtime adapter configuration ([runtime] section).

Key	Type	Default	Description
`docker`	object	`—`	Docker runtime configuration (`[runtime.docker]` section).
`kind`	`native` \| `docker` \| `cloudflare`	`—`	Runtime adapter kind.
`reasoning_effort`	string?	`null`	Optional reasoning effort for model_providers that expose a level control.
`reasoning_enabled`	bool?	`null`	Global reasoning override for model_providers that expose explicit controls.
`shell`	string?	`null`	Shell binary the native runtime uses for command execution.

`runtime.docker`

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

Key	Type	Default	Description
`allowed_workspace_roots`	string[]	`[]`	Optional workspace root allowlist for Docker mount validation.
`cpu_limit`	number?	`1.0`	Optional CPU limit (`None` = no explicit limit).
`image`	string	`"alpine:3.20"`	Runtime image used to execute shell commands.
`memory_limit_mb`	integer?	`512`	Optional memory limit in MB (`None` = no explicit limit).
`mount_workspace`	bool	`true`	Mount configured workspace into `/workspace`.
`network`	string	`"none"`	Docker network mode (`none`, `bridge`, etc.).
`read_only_rootfs`	bool	`true`	Mount root filesystem as read-only.

`runtime_profiles`

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

`runtime_profiles.<alias>`

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

Reusable operational tuning: agentic mode, iteration caps, context budget, parallel dispatch, resource ceilings, recursion depth, and the budget knobs that SecurityPolicy enforces with subagent parent-subset discipline. Anything authorization-shaped (allowed commands/tools/paths, approval gates, sandbox) lives on [risk_profiles.<alias>]. Anything model-provider shaped (model, temperature, max_tokens, timeout_secs) lives on [providers.models.<type>.<alias>].

Key	Type	Default	Description
`agentic`	bool	`false`	Enable agentic (multi-turn tool-call loop) mode.
`agentic_timeout_secs`	integer?	`null`	Agentic delegate run timeout in seconds. `None` inherits global.
`auto_classify`	object	`—`
`compact_context`	bool?	`null`	Use compact bootstrap (6000 chars / 2 RAG chunks). `None` inherits.
`context_compression`	object	`—`
`delegation_timeout_secs`	integer?	`null`	Delegate call timeout in seconds. `None` inherits global delegate timeout.
`eval`	object	`—`
`history_pruning`	object	`—`
`keep_tool_context_turns`	integer?	`null`	Number of recent turns whose full tool context is preserved. `None` inherits.
`max_actions_per_hour`	integer	`20`	Maximum actions allowed per hour. `0` is a hard zero budget — the
`max_context_tokens`	integer?	`null`	Maximum estimated tokens for context before compaction. `None` inherits.
`max_cost_per_day_cents`	integer	`500`	Maximum cost per day in cents. `0` inherits the global limit.
`max_delegation_depth`	integer	`0`	Maximum delegation recursion depth. `0` inherits the default.
`max_history_messages`	integer?	`null`	Maximum conversation history messages retained per session. `None` inherits.
`max_system_prompt_chars`	integer?	`null`	Maximum characters for the assembled system prompt. `None` inherits.
`max_tool_iterations`	integer	`0`	Maximum tool-call iterations in agentic mode. `0` inherits the global default.
`max_tool_result_chars`	integer?	`null`	Maximum characters for a single tool result. `None` inherits.
`memory_recall_limit`	integer?	`null`	Maximum memory entries injected per turn. `None` inherits global default (5).
`parallel_tools`	bool?	`null`	Enable parallel tool execution per iteration. `None` inherits.
`prompt_injection_mode`	table	`—`	Skills loading configuration (`[skills]` section).
`shell_timeout_secs`	integer	`60`	Shell subprocess timeout in seconds. `0` inherits the global timeout.
`strict_tool_parsing`	bool	`false`
`thinking`	object	`—`	Configuration for thinking/reasoning level control.
`tool_call_dedup_exempt`	string[]	`[]`	Tools exempt from within-turn dedup check.
`tool_dispatcher`	string?	`null`	Tool dispatch strategy (e.g. `"auto"`). `None` inherits.
`tool_filter_groups`	object[]	`[]`
`tool_receipts`	object	`—`	HMAC tool execution receipt configuration, per agent

`runtime_profiles.<alias>.auto_classify`

Key	Type	Default
`complex_hint`	string?	`null`
`cost_optimized_hint`	string	`"cost-optimized"`
`simple_hint`	string?	`null`
`standard_hint`	string?	`null`

`runtime_profiles.<alias>.context_compression`

Key	Type	Default	Description
`enabled`	bool	`true`
`identifier_policy`	string	`"strict"`
`max_passes`	integer	`3`
`protect_first_n`	integer	`3`
`protect_last_n`	integer	`4`
`source_max_chars`	integer	`50000`
`summary_max_chars`	integer	`4000`
`summary_model`	string?	`null`	DEPRECATED bare model id retained as a compatibility fallback.
`summary_provider`	string	`—`	Reference to a configured `[providers.models.<type>.<alias>]` entry.
`threshold_ratio`	number	`0.5`
`timeout_secs`	integer	`60`
`tool_result_retrim_chars`	integer	`2000`
`tool_result_trim_exempt`	string[]	`[]`

`runtime_profiles.<alias>.eval`

Key	Type	Default
`enabled`	bool	`false`
`max_retries`	integer	`1`
`min_quality_score`	number	`0.5`

`runtime_profiles.<alias>.history_pruning`

Key	Type	Default
`collapse_tool_results`	bool	`true`
`enabled`	bool	`false`
`keep_recent`	integer	`4`
`max_tokens`	integer	`8192`

`runtime_profiles.<alias>.thinking`

Configuration for thinking/reasoning level control.

Key	Type	Default	Description
`budget_tokens`	map	`{}`
`default_level`	`off` \| `minimal` \| `low` \| `medium` \| `high` \| `max`	`—`	How deeply the model should reason for a given message.
`native_thinking`	bool	`false`	Enables provider-native thinking parameters when the selected level has a budget.

`runtime_profiles.<alias>.tool_receipts`

HMAC tool execution receipt configuration, per agent ([agents.<alias>.tool_receipts]).

Receipts are short HMAC-SHA256 tags appended to tool results so the model cannot claim it ran a tool that never actually executed. See docs/book/src/security/tool-receipts.md.

Key	Type	Default	Description
`enabled`	bool	`false`	Generate HMAC receipts on every tool execution. Default: `false`.
`inject_system_prompt`	bool	`true`	Inject the receipt-echo instruction into the system prompt so the
`show_in_response`	bool	`false`	Append a trailing `Tool receipts:` block to user-visible replies so

`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.

Key	Type	Default	Description
`catch_up_on_startup`	bool	`true`	Run all overdue jobs at scheduler startup. Default: `true`.
`enabled`	bool	`true`	Enable the built-in scheduler loop. When false, no cron jobs run.
`max_concurrent`	integer	`4`	Maximum tasks executed in parallel within a single polling cycle.
`max_run_history`	integer	`50`	Maximum number of historical cron run records to retain. Default: `50`.
`max_tasks`	integer	`64`	Maximum number of persisted scheduled tasks per polling cycle.

`schema_version`

Config file schema version.

`secrets`

Secrets encryption configuration ([secrets] section).

Key	Type	Default	Description
`encrypt`	bool	`true`	Enable encryption for API keys and tokens at rest

`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).

Key	Type	Default	Description
`audit`	object	`—`	Audit logging configuration
`estop`	map	`—`	Emergency stop configuration.
`leak_detection`	object	`—`	Outbound credential leak detection configuration.
`nevis`	map	`—`	Nevis IAM integration configuration.
`otp`	map	`—`	Security OTP configuration.
`webauthn`	object	`—`	WebAuthn / FIDO2 hardware key authentication configuration (`[security.webauthn]`).

`security.audit`

Audit logging configuration

Key	Type	Default	Description
`enabled`	bool	`true`	Enable audit logging
`log_path`	string	`"audit.log"`	Path to audit log file (relative to zeroclaw dir)
`max_size_mb`	integer	`100`	Maximum log size in MB before rotation
`sign_events`	bool	`false`	Sign events with HMAC for tamper evidence

`security.estop`

Emergency stop configuration.

Key	Type	Default	Description
`enabled`	bool	`false`	Enable emergency stop controls.
`require_otp_to_resume`	bool	`true`	Require a valid OTP before resume operations.
`state_file`	string	`"/home/runner/.zeroclaw/estop-state.json"`	File path used to persist estop state.

`security.leak_detection`

Outbound credential leak detection configuration.

These settings control the final guardrail pass over outbound channel responses before they are delivered. Deterministic credential patterns include API keys, private keys, database URLs, bot tokens, and related token syntax. The high-entropy pass is a separate heuristic for standalone opaque tokens.

Key	Type	Default	Description
`enabled`	bool	`true`	Enable outbound credential leak detection and redaction.
`high_entropy_tokens`	bool	`true`	Enable high-entropy token redaction; deterministic patterns still run when false.
`sensitivity`	number	`0.7`	Detection sensitivity from 0.0 to 1.0; higher is more aggressive.

`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.

Key	Type	Default	Description
`client_id`	string	`""`	OAuth2 client ID registered in Nevis.
`client_secret` 🔑	string?	`null`	OAuth2 client secret. Encrypted via SecretStore when stored on disk.
`enabled`	bool	`false`	Enable Nevis IAM integration. Defaults to false for backward compatibility.
`instance_url`	string	`""`	Base URL of the Nevis instance (e.g. `https://nevis.example.com`).
`jwks_url`	string?	`null`	JWKS endpoint URL for local token validation.
`realm`	string	`"master"`	Nevis realm to authenticate against.
`require_mfa`	bool	`false`	Require MFA verification for all Nevis-authenticated requests.
`role_mapping`	map[]	`[]`	Nevis role to ZeroClaw permission mappings.
`session_timeout_secs`	integer	`3600`	Session timeout in seconds.
`token_validation`	string	`"local"`	Token validation strategy: `"local"` (JWKS) or `"remote"` (introspection).

`security.otp`

Security OTP configuration.

Key	Type	Default	Description
`cache_valid_secs`	integer	`300`	Reuse window for recently validated OTP codes.
`challenge_max_attempts`	integer	`3`	Maximum number of OTP challenge attempts before lockout.
`enabled`	bool	`false`	Enable OTP gating. Defaults to disabled for backward compatibility.
`gated_actions`	string[]	`["shell","file_write","browser_open","browser","memory_forget"]`	Tool/action names gated by OTP. Empty or malformed entries are rejected
`gated_domain_categories`	string[]	`[]`	Domain-category presets expanded into `gated_domains`.
`gated_domains`	string[]	`[]`	Explicit domain patterns gated by OTP.
`method`	table	`—`	OTP validation strategy.
`token_ttl_secs`	integer	`30`	TOTP time-step in seconds.

`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).

Key	Type	Default	Description
`enabled`	bool	`false`	Enable WebAuthn authentication. Default: false.
`rp_id`	string	`"localhost"`	Relying Party ID (domain name, e.g. “example.com”). Default: “localhost”.
`rp_name`	string	`"ZeroClaw"`	Relying Party display name. Default: “ZeroClaw”.
`rp_origin`	string	`"http://localhost:42617"`	Relying Party origin URL (e.g. `"https://example.com"`). Default: `"http://localhost:42617"`.

`security_ops`

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

Key	Type	Default	Description
`auto_triage`	bool	`false`	Automatically triage incoming alerts without user prompt.
`enabled`	bool	`false`	Enable security operations tools.
`max_auto_severity`	string	`"low"`	Maximum severity level that can be auto-remediated without approval.
`playbooks_dir`	string	`"/home/runner/.zeroclaw/playbooks"`	Directory containing incident response playbook definitions (JSON).
`report_output_dir`	string	`"/home/runner/.zeroclaw/security-reports"`	Directory for generated security reports.
`require_approval_for_actions`	bool	`true`	Require human approval before executing playbook actions.
`siem_integration`	string?	`null`	Optional SIEM webhook URL for alert ingestion.

`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.

Key	Type	Default	Description
`timeout_secs`	integer	`60`	Maximum shell command execution time in seconds (default: 60).

`skill_bundles`

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

`skill_bundles.<alias>`

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

A reusable group of skills that can be attached to an agent or channel by alias, controlling which skills are loaded and from where.

Key	Type	Default	Description
`directory`	string?	`null`	Directory path (relative to workspace root) to load skills from.
`exclude`	string[]	`[]`	Skill names to exclude from this bundle.
`include`	string[]	`[]`	Skill names to include. Empty means include all skills in `directory`.

`skills`

Skills loading configuration ([skills] section).

Key	Type	Default	Description
`allow_scripts`	bool	`false`	Allow script-like files in skills (`.sh`, `.bash`, `.ps1`, shebang shell files).
`extra_registries`	object[]	`—`	Additional user-configured skill registries, installed via
`install_suggestions`	object	`—`	Prompt-triggered skill install suggestions (`[skills.install_suggestions]` section).
`open_skills_dir`	string?	`null`	Optional path to a local open-skills repository.
`open_skills_enabled`	bool	`false`	Enable loading and syncing the community open-skills repository.
`prompt_injection_mode`	table	`—`	Skills loading configuration (`[skills]` section).
`registry_url`	string?	`null`	URL of the skills registry repository for bare-name installs.
`skill_creation`	object	`—`	Autonomous skill creation configuration (`[skills.skill_creation]` section).
`skill_improvement`	object	`—`	Skill self-improvement configuration (`[skills.skill-improvement]` section).

`skills.install_suggestions`

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

Key	Type	Default	Description
`enabled`	bool	`false`	Enable suggestions for installable skills before normal agent turns.

`skills.skill_creation`

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

Key	Type	Default	Description
`enabled`	bool	`false`	Enable automatic skill creation after successful multi-step tasks.
`max_final_answer_chars`	integer	`2000`	Maximum characters of the final assistant answer fed into the
`max_skills`	integer	`500`	Maximum number of auto-generated skills to keep.
`max_task_chars`	integer	`1000`	Maximum characters of the task description fed into the reflection
`max_tool_trace_chars`	integer	`4000`	Maximum characters of the rendered tool-call trace fed into the
`reflection_enabled`	bool	`false`	Synthesize a canonical `SKILL.md` from the execution trace via a
`similarity_threshold`	number	`0.85`	Embedding similarity threshold for deduplication.

`skills.skill_improvement`

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

Controls the post-turn background review fork that may patch, expand, or archive skills based on what the conversation revealed. The fork runs in a restricted toolset (only skills_list, skill_view, skill_manage) and never touches the user-visible conversation.

Key	Type	Default	Description
`cooldown_secs`	integer	`3600`	Minimum interval (in seconds) between reviews for the same skill.
`enabled`	bool	`false`	Enable the background skill-review fork. Default: `false`.
`max_review_iterations`	integer	`8`	Maximum tool-call iterations the review fork itself is allowed to make.
`nudge_interval_iterations`	integer	`10`	Spawn a review fork once at least this many tool-call iterations have

`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.

Key	Type	Default	Description
`approval`	object	`—`	`[sop.approval]` - approval broker policy config. A permanent identity source
`approval_mode`	table	`—`	WHO may clear a SOP approval gate. Layered with execution_mode / priority /
`approval_timeout_action`	table	`—`	What happens to a SOP approval gate when it times out. Default is fail-closed:
`approval_timeout_secs`	integer	`300`	Approval timeout in seconds. When a run waits for approval longer than
`default_execution_mode`	string	`"supervised"`	Default execution mode for SOPs that omit `execution_mode`.
`maintenance_interval_secs`	integer	`60`	How often (seconds) the daemon runs the SOP maintenance tick: fire
`max_concurrent_total`	integer	`4`	Maximum total concurrent SOP runs across all SOPs.
`max_finished_runs`	integer	`100`	Maximum number of finished runs kept in memory for status queries.
`max_step_retries`	integer	`2`	Maximum retries allowed by a step failure policy.
`max_step_visits`	integer	`256`	Maximum times a routed SOP run can visit one step.
`persist_runs`	bool	`true`	Persist run state durably across restarts. Default `true`: `build_sop_engine`
`procedural_memory_enabled`	bool	`false`	Enable SOP procedural-memory proposal tooling. Default false keeps
`run_state_dir`	string?	`null`	Directory for the durable run store (created mode-0700). When omitted,
`run_store_backend`	table	`—`	Durable SOP run-state backend selector. A closed, compile-time-known set, so it
`sops_dir`	string?	`null`	Directory containing SOP definitions (subdirs with SOP.toml + SOP.md).
`step_mandatory_tools`	string[]	`["sop_advance","sop_approve","sop_status"]`	Tool names that remain available while step scope is enforced.
`step_schema_enforce`	bool	`true`	Enforce per-step input/output schemas when a step declares them.
`step_scope_enforce`	bool	`false`	Enforce per-step tool scope. Default false keeps `tools:` advisory.
`untrusted_frame_warning`	bool	`true`	Include the explanatory warning text inside untrusted-content frames.
`untrusted_guard_sensitivity`	number	`0.7`	Prompt-guard and outbound-redaction sensitivity for untrusted SOP content.
`untrusted_input_guard`	string	`"warn"`	Prompt-guard action for untrusted SOP trigger input: warn, block, or sanitize.
`untrusted_outbound_redact`	bool	`true`	Redact outbound SOP content before persistence/audit consumers write it.
`untrusted_payload_max_bytes`	integer	`8192`	Maximum bytes accepted from untrusted SOP trigger payload/topic content

`sop.approval`

[sop.approval] - approval broker policy config. A permanent identity source for channel-provided approvers (not a stopgap): the approval broker consumes it for group-membership and quorum checks. Empty = no broker policy applies.

One slot per family (groups, policies). Each slot is a [sop.approval.<slot>.<alias>] map; see the dedicated section page for the per-field reference.

`storage`

Persistent storage configuration ([storage] section).

Storage is a two-tier alias-keyed map: [storage.<backend>.<alias>], parallel to [providers.models.<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.

Key	Type	Default	Description
`allowed_private_hosts`	string[]	`[]`	Private/internal hosts allowed to bypass SSRF protection.
`enabled`	bool	`false`	Enable `text_browser` tool
`preferred_browser`	string?	`null`	Preferred text browser (“lynx”, “links”, or “w3m”). If unset, auto-detects.
`timeout_secs`	integer	`30`	Request timeout in seconds (default: 30)

`todotracker`

ZeroCode live task tracker configuration ([todotracker] section).

Read-only visual tracker driven by the model’s TodoWrite tool.

Key	Type	Default	Description
`enabled`	bool	`true`	Master switch. When `false` the tracker never renders and never
`enabled_at_start`	bool	`false`	Whether the panel is visible at launch (when `enabled`). When
`location`	table	`—`	Location of the ZeroCode TodoWrite tracker panel.
`max_height`	integer	`5`	Bottom-strip maximum height in rows (grows up to this). Ignored for
`width`	integer	`32`	Side-panel target column width (left/right). Runtime-clamped to at

`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.

Key	Type	Default	Description
`api_key` 🔑	string?	`null`	API key used for transcription requests (Groq transcription provider).
`api_url`	string	`"https://api.groq.com/openai/v1/audio/transcriptions"`	Whisper API endpoint URL (Groq transcription provider).
`assemblyai`	object	`—`	AssemblyAI STT model_provider configuration (`[transcription.assemblyai]`).
`deepgram`	object	`—`	Deepgram STT model_provider configuration (`[transcription.deepgram]`).
`enabled`	bool	`false`	Enable voice transcription for channels that support it.
`google`	object	`—`	Google Cloud Speech-to-Text model_provider configuration (`[transcription.google]`).
`initial_prompt`	string?	`null`	Optional initial prompt to bias transcription toward expected vocabulary
`language`	string?	`null`	Optional language hint (ISO-639-1, e.g. “en”, “ru”) for Groq transcription provider.
`local_whisper`	object	`—`	Local/self-hosted Whisper-compatible STT endpoint (`[transcription.local_whisper]`).
`max_audio_bytes`	integer?	`null`	Optional global audio size upper bound in bytes, enforced before
`max_duration_secs`	integer	`120`	Maximum voice duration in seconds (messages longer than this are skipped).
`model`	string	`"whisper-large-v3-turbo"`	Whisper model name (Groq transcription provider).
`openai`	object	`—`	OpenAI Whisper STT model_provider configuration (`[transcription.openai]`).
`transcribe_non_ptt_audio`	bool	`false`	Also transcribe non-PTT (forwarded/regular) audio messages on WhatsApp,

`transcription.assemblyai`

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

Key	Type	Default	Description
`api_key` 🔑	string?	`null`	AssemblyAI API key.

`transcription.deepgram`

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

Key	Type	Default	Description
`api_key` 🔑	string?	`null`	Deepgram API key.
`model`	string	`"nova-2"`	Deepgram model name (default: “nova-2”).

`transcription.google`

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

Key	Type	Default	Description
`api_key` 🔑	string?	`null`	Google Cloud API key.
`language_code`	string	`"en-US"`	BCP-47 language code (default: “en-US”).

`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.

Key	Type	Default	Description
`bearer_token` 🔑	string?	`null`	Bearer token for endpoint authentication.
`max_audio_bytes`	integer	`26214400`	Maximum audio file size in bytes accepted by this endpoint.
`timeout_secs`	integer	`300`	Request timeout in seconds. Defaults to 300 (large files on local GPU).
`url`*	string	`—`	HTTP or HTTPS endpoint URL, e.g. `"http://10.10.0.1:8001/v1/transcribe"`.

`transcription.openai`

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

Key	Type	Default	Description
`api_key` 🔑	string?	`null`	OpenAI API key for Whisper transcription.
`model`	string	`"whisper-1"`	Whisper model name (default: “whisper-1”).

`trust`

Key	Type	Default
`correction_penalty`	number	`0.05`
`decay_half_life_days`	number	`30.0`
`initial_score`	number	`0.8`
`regression_threshold`	number	`0.5`
`success_boost`	number	`0.01`

`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.

Key	Type	Default	Description
`default_format`	string	`"mp3"`	Default audio output format (`"mp3"`, `"opus"`, `"wav"`).
`default_voice`	string	`"alloy"`	Default voice ID passed to the selected tts provider.
`enabled`	bool	`false`	Enable TTS synthesis.
`max_text_length`	integer	`4096`	Maximum input text length in characters (default 4096).

`tunnel`

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

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

Key	Type	Default	Description
`cloudflare`	object	`—`
`custom`	object	`—`
`ngrok`	object	`—`
`openvpn`	object	`—`	OpenVPN tunnel configuration (`[tunnel.openvpn]`).
`pinggy`	object	`—`
`tailscale`	object	`—`
`tunnel_provider`	string	`"none"`	How the gateway gets exposed to the public internet so webhooks (Telegram, Slack, etc.) can reach it. `none` = keep it local, no tunnel; `cloudflare` = Cloudflare Tunnel via cloudflared (needs a Zero Trust account and token); `tailscale` = Tailscale Funnel/Serve (tailnet-only or public, no account beyond tailscale); `ngrok` = ngrok agent with auth token; `openvpn` = bring-your-own OpenVPN egress; `pinggy` = Pinggy SSH tunnels (quick one-shot URLs); `custom` = run an arbitrary command you define under `[tunnel.custom]`.

`tunnel.cloudflare`

Key	Type	Default	Description
`token` 🔑	string	`""`	Cloudflare Tunnel token (from Zero Trust dashboard)

`tunnel.custom`

Key	Type	Default	Description
`health_url`	string?	`null`	Optional URL to check tunnel health
`start_command`	string	`""`	Command template to start the tunnel. Use {port} and {host} placeholders.
`url_pattern`	string?	`null`	Optional regex to extract public URL from command stdout

`tunnel.ngrok`

Key	Type	Default	Description
`auth_token` 🔑	string	`""`	ngrok auth token
`domain`	string?	`null`	Optional custom domain

`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.

Key	Type	Default	Description
`advertise_address`	string?	`null`	Advertised address once VPN is connected (e.g., `"10.8.0.2:42617"`).
`auth_file`	string?	`null`	Optional path to auth credentials file (`--auth-user-pass`).
`config_file`*	string	`—`	Path to `.ovpn` configuration file (must not be empty).
`connect_timeout_secs`	integer	`30`	Connection timeout in seconds (default: 30, must be > 0).
`extra_args`	string[]	`[]`	Extra openvpn CLI arguments forwarded verbatim.

`tunnel.pinggy`

Key	Type	Default	Description
`region`	string?	`null`	Server region: `"us"` (USA), `"eu"` (Europe), `"ap"` (Asia), `"br"` (South America), `"au"` (Australia), or omit for auto.
`token` 🔑	string?	`null`	Pinggy access token (optional — free tier works without one).

`tunnel.tailscale`

Key	Type	Default	Description
`funnel`	bool	`false`	Use Tailscale Funnel (public internet) vs Serve (tailnet only)
`hostname`	string?	`null`	Optional hostname override

`verifiable_intent`

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

Key	Type	Default	Description
`enabled`	bool	`false`	Enable VI credential verification on commerce tool calls (default: false).
`strictness`	string	`"strict"`	Strictness mode for constraint evaluation: “strict” (fail-closed on unknown

`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).

Key	Type	Default	Description
`allowed_domains`	string[]	`["*"]`	Allowed domains for web fetch (exact or subdomain match; `["*"]` = all public hosts)
`allowed_private_hosts`	string[]	`[]`	Private/internal hosts allowed to bypass SSRF protection (e.g. `["192.168.1.10", "internal.local"]`).
`blocked_domains`	string[]	`[]`	Blocked domains (exact or subdomain match; always takes priority over allowed_domains)
`enabled`	bool	`true`	Enable `web_fetch` tool for fetching web page content
`firecrawl`	object	`—`	Firecrawl fallback configuration for JS-heavy and bot-blocked sites.
`max_response_size`	integer	`500000`	Maximum response size in bytes (default: 500KB, plain text is much smaller than raw HTML)
`timeout_secs`	integer	`30`	Request timeout in seconds (default: 30)

`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.

Key	Type	Default	Description
`api_key_env`	string	`"FIRECRAWL_API_KEY"`	Environment variable name for the Firecrawl API key
`api_url`	string	`"https://api.firecrawl.dev/v1"`	Firecrawl API base URL
`enabled`	bool	`false`	Enable Firecrawl fallback
`mode`	table	`—`	Firecrawl fallback mode: scrape a single page or crawl linked pages.

`web_search`

Web search tool configuration ([web_search] section).

Key	Type	Default	Description
`bocha_api_key` 🔑	string?	`null`	Bocha AI Web Search API key (required if search_provider is `"bocha"`). Obtain at https://open.bochaai.com.
`brave_api_key` 🔑	string?	`null`	Brave Search API key (required if search_provider is “brave”)
`enabled`	bool	`true`	Enable `web_search_tool` for web searches
`jina_api_key` 🔑	string?	`null`	Jina AI API key (required if search_provider is “jina”)
`max_results`	integer	`5`	Maximum results per search (1-10)
`search_provider`	string	`"duckduckgo"`	Search provider: “duckduckgo” (free), “brave” (requires API key), “tavily” (requires API key), “searxng” (self-hosted), “jina” (requires API key), or “bocha” (Bocha AI, requires API key — Chinese-friendly, https://open.bochaai.com)
`searxng_instance_url`	string?	`null`	SearXNG instance URL (required if search_provider is `"searxng"`), e.g. `"https://searx.example.com"`.
`tavily_api_key` 🔑	string?	`null`	Tavily Search API key (required if search_provider is “tavily”)
`timeout_secs`	integer	`15`	Request timeout in seconds

`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.

Key	Type	Default	Description
`bind`	string	`"0.0.0.0"`	Bind address for the WSS listener (default: “0.0.0.0”).
`cert_path`	string	`""`	Path to the PEM-encoded server certificate file.
`enabled`	bool	`false`	Enable the WSS listener (default: false).
`key_path`	string	`""`	Path to the PEM-encoded server private key file.
`port`	integer	`9781`	Port for the WSS listener (default: 9781).

Keyboard shortcuts

ZeroClaw Docs