Struct Config 

pub struct Config {

    pub data_dir: PathBuf,
    pub config_path: PathBuf,
    pub env_overridden_paths: HashSet<String>,
    pub pre_override_snapshots: HashMap<String, String>,
    pub onepassword_reference_snapshots: HashMap<String, String>,
    pub dirty_paths: HashSet<String>,
    pub degraded_security: Vec<String>,
    pub degraded_sections: Vec<String>,
    pub schema_version: u32,
    pub providers: Providers,
    pub model_routes: Vec<ModelRouteConfig>,
    pub embedding_routes: Vec<EmbeddingRouteConfig>,
    pub observability: ObservabilityConfig,
    pub trust: TrustConfig,
    pub security: SecurityConfig,
    pub backup: BackupConfig,
    pub data_retention: DataRetentionConfig,
    pub cloud_ops: CloudOpsConfig,
    pub conversational_ai: ConversationalAiConfig,
    pub security_ops: SecurityOpsConfig,
    pub runtime: RuntimeConfig,
    pub reliability: ReliabilityConfig,
    pub scheduler: SchedulerConfig,
    pub eval: EvalHarnessConfig,
    pub pacing: PacingConfig,
    pub skills: SkillsConfig,
    pub pipeline: PipelineConfig,
    pub query_classification: QueryClassificationConfig,
    pub heartbeat: HeartbeatConfig,
    pub todotracker: TodoTrackerConfig,
    pub cron: HashMap<String, CronJobDecl>,
    pub acp: AcpConfig,
    pub channels: ChannelsConfig,
    pub memory: MemoryConfig,
    pub storage: StorageConfig,
    pub tunnel: TunnelConfig,
    pub gateway: GatewayConfig,
    pub a2a: A2aServerSection,
    pub wss: WssConfig,
    pub composio: ComposioConfig,
    pub microsoft365: Microsoft365Config,
    pub secrets: SecretsConfig,
    pub browser: BrowserConfig,
    pub browser_delegate: BrowserDelegateConfig,
    pub http_request: HttpRequestConfig,
    pub multimodal: MultimodalConfig,
    pub media_pipeline: MediaPipelineConfig,
    pub web_fetch: WebFetchConfig,
    pub link_enricher: LinkEnricherConfig,
    pub text_browser: TextBrowserConfig,
    pub web_search: WebSearchConfig,
    pub project_intel: ProjectIntelConfig,
    pub google_workspace: GoogleWorkspaceConfig,
    pub proxy: ProxyConfig,
    pub cost: CostConfig,
    pub peripherals: PeripheralsConfig,
    pub delegate: DelegateToolConfig,
    pub agents: HashMap<String, AliasedAgentConfig>,
    pub risk_profiles: HashMap<String, RiskProfileConfig>,
    pub runtime_profiles: HashMap<String, RuntimeProfileConfig>,
    pub skill_bundles: HashMap<String, SkillBundleConfig>,
    pub knowledge_bundles: HashMap<String, KnowledgeBundleConfig>,
    pub mcp_bundles: HashMap<String, McpBundleConfig>,
    pub peer_groups: HashMap<String, PeerGroupConfig>,
    pub hooks: HooksConfig,
    pub hardware: HardwareConfig,
    pub transcription: TranscriptionConfig,
    pub tts: TtsConfig,
    pub mcp: McpConfig,
    pub nodes: NodesConfig,
    pub onboard_state: OnboardStateConfig,
    pub notion: NotionConfig,
    pub jira: JiraConfig,
    pub node_transport: NodeTransportConfig,
    pub knowledge: KnowledgeConfig,
    pub linkedin: LinkedInConfig,
    pub image_gen: ImageGenConfig,
    pub file_upload: FileUploadConfig,
    pub file_upload_bundle: FileUploadBundleConfig,
    pub file_download: FileDownloadConfig,
    pub plugins: PluginsConfig,
    pub locale: Option<String>,
    pub verifiable_intent: VerifiableIntentConfig,
    pub claude_code: ClaudeCodeConfig,
    pub claude_code_runner: ClaudeCodeRunnerConfig,
    pub codex_cli: CodexCliConfig,
    pub gemini_cli: GeminiCliConfig,
    pub opencode_cli: OpenCodeCliConfig,
    pub sop: SopConfig,
    pub shell_tool: ShellToolConfig,
    pub escalation: EscalationConfig,
}

Top-level ZeroClaw configuration, loaded from config.toml.

Resolution order: ZEROCLAW_CONFIG_DIR env → ZEROCLAW_WORKSPACE env → ~/.zeroclaw/config.toml.

Fields

data_dir: PathBuf

Shared instance data directory (databases, hygiene state, cost records, daemon state files). Computed from ZEROCLAW_CONFIG_DIR / ZEROCLAW_DATA_DIR / ZEROCLAW_WORKSPACE (deprecated) at load time, not serialized. Per-agent identity + markdown lives at agent_workspace_dir(&alias), not here.

config_path: PathBuf

Path to config.toml - computed from home, not serialized

env_overridden_paths: HashSet<String>

Dotted prop-paths overridden by ZEROCLAW_* env vars at load time. Populated by apply_env_overrides; consulted by save() to mask the env-injected values back to disk-or-default before encryption, and by prop_is_env_overridden for O(1) display-layer lookup (config list, dashboard, quickstart).

pre_override_snapshots: HashMap<String, String>

Per-path snapshot of pre-override raw values, captured at apply time from the post-decrypt_secrets in-memory state (so secret entries hold plaintext, not the display mask). save() restores from this map so env-injected values never reach disk and the operator’s original on-disk credentials survive any save cycle.

onepassword_reference_snapshots: HashMap<String, String>

Per-path snapshot of op:// external secret references captured before decrypt_secrets() resolves them for runtime use. save() restores these references unless the same path was intentionally edited.

dirty_paths: HashSet<String>

Dotted prop-paths mutated since the last persist; drives the per-path PATCH applied by save_dirty().

degraded_security: Vec<String>

Security-critical sections the resilient loader reset to Default because the on-disk block was malformed. Non-empty = posture may be weaker than intended; exposure gating should refuse to trust the instance until repaired. Never serialized — a load-time signal.

degraded_sections: Vec<String>

Non-security sections the resilient loader reset to Default because the on-disk block was malformed (e.g. [plugins.entries] written where [[plugins.entries]] was meant). Never serialized; a load-time signal the CLI surfaces on stderr so a silently-dropped section is impossible to miss.

schema_version: u32

Config file schema version.

providers: Providers

All configured provider profiles, grouped by category under a single [providers] root. Categories today: models, tts, transcription. Shape: [providers.<category>.<type>.<alias>], e.g. [providers.models.anthropic.default], [providers.tts.openai.default], [providers.transcription.groq.default].

model_routes: Vec<ModelRouteConfig>

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

embedding_routes: Vec<EmbeddingRouteConfig>

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

observability: ObservabilityConfig

Observability backend configuration ([observability]).

trust: TrustConfig

Trust scoring and regression detection configuration ([trust]).

security: SecurityConfig

Security subsystem configuration ([security]).

backup: BackupConfig

Backup tool configuration ([backup]).

data_retention: DataRetentionConfig

Data retention and purge configuration ([data_retention]).

cloud_ops: CloudOpsConfig

Cloud transformation accelerator configuration ([cloud_ops]).

conversational_ai: ConversationalAiConfig

Conversational AI agent builder configuration ([conversational_ai]).

Experimental / future feature — not yet wired into the agent runtime. Omitted from generated config files when disabled (the default). Existing configs that already contain this section will continue to deserialize correctly thanks to #[serde(default)].

security_ops: SecurityOpsConfig

Managed cybersecurity service configuration ([security_ops]).

runtime: RuntimeConfig

Runtime adapter configuration ([runtime]). Controls native vs Docker execution.

reliability: ReliabilityConfig

Reliability settings: retries, backoff, key rotation ([reliability]).

scheduler: SchedulerConfig

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

eval: EvalHarnessConfig

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

pacing: PacingConfig

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

skills: SkillsConfig

Skills loading and community repository behavior ([skills]).

pipeline: PipelineConfig

Pipeline tool configuration ([pipeline]).

query_classification: QueryClassificationConfig

Automatic query classification — maps user messages to model hints.

heartbeat: HeartbeatConfig

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

todotracker: TodoTrackerConfig

ZeroCode live task tracker ([todotracker]), the read-only TodoWrite visual tracker in the Code pane.

cron: HashMap<String, CronJobDecl>

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

acp: AcpConfig

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

channels: ChannelsConfig

Channel configurations: Telegram, Discord, Slack, etc. ([channels]).

memory: MemoryConfig

Memory backend configuration: sqlite, markdown, embeddings ([memory]).

storage: StorageConfig

Persistent storage model_provider configuration ([storage]).

tunnel: TunnelConfig

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

gateway: GatewayConfig

Gateway server configuration: host, port, pairing, rate limits ([gateway]).

a2a: A2aServerSection

Inbound A2A discovery server ([a2a.server]). Default-closed: serves the well-known catalog card and per-alias agent cards only when enabled = true. See crate::multi_agent::A2aServerConfig.

wss: WssConfig

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

composio: ComposioConfig

Composio managed OAuth tools integration ([composio]).

microsoft365: Microsoft365Config

Microsoft 365 Graph API integration ([microsoft365]).

secrets: SecretsConfig

Secrets encryption configuration ([secrets]).

browser: BrowserConfig

Browser automation configuration ([browser]).

browser_delegate: BrowserDelegateConfig

Browser delegation configuration ([browser_delegate]).

Delegates browser-based tasks to a browser-capable CLI subprocess (e.g. Claude Code with claude-in-chrome MCP tools). Useful for interacting with corporate web apps (Teams, Outlook, Jira, Confluence) that lack direct API access. A persistent Chrome profile can be configured so SSO sessions survive across invocations.

Fields:

• enabled (bool, default false) — enable the browser delegation tool.
• cli_binary (String, default "claude") — CLI binary to spawn for browser tasks.
• chrome_profile_dir (String, default "") — Chrome user-data directory for persistent SSO sessions. When empty, a fresh profile is used each invocation.
• allowed_domains (Vec<String>, default []) — allowlist of domains the browser may navigate to. Empty means all non-blocked domains are permitted.
• blocked_domains (Vec<String>, default []) — denylist of domains. Blocked domains take precedence over allowed domains.
• task_timeout_secs (u64, default 120) — per-task timeout in seconds.

Compatibility: additive and disabled by default; existing configs remain valid when omitted. Rollback/migration: remove [browser_delegate] or keep enabled = false to disable.

http_request: HttpRequestConfig

HTTP request tool configuration ([http_request]).

multimodal: MultimodalConfig

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

media_pipeline: MediaPipelineConfig

Automatic media understanding pipeline ([media_pipeline]).

web_fetch: WebFetchConfig

Web fetch tool configuration ([web_fetch]).

link_enricher: LinkEnricherConfig

Link enricher configuration ([link_enricher]).

text_browser: TextBrowserConfig

Text browser tool configuration ([text_browser]).

web_search: WebSearchConfig

Web search tool configuration ([web_search]).

project_intel: ProjectIntelConfig

Project delivery intelligence configuration ([project_intel]).

google_workspace: GoogleWorkspaceConfig

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

proxy: ProxyConfig

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

cost: CostConfig

Cost tracking and budget enforcement configuration ([cost]). Also hosts the operator-managed rate sheet at [cost.rates.<type>.<model>].

peripherals: PeripheralsConfig

Peripheral board configuration for hardware integration ([peripherals]).

delegate: DelegateToolConfig

Delegate tool global default configuration ([delegate]).

agents: HashMap<String, AliasedAgentConfig>

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.

risk_profiles: HashMap<String, RiskProfileConfig>

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

runtime_profiles: HashMap<String, RuntimeProfileConfig>

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

skill_bundles: HashMap<String, SkillBundleConfig>

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

knowledge_bundles: HashMap<String, KnowledgeBundleConfig>

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

mcp_bundles: HashMap<String, McpBundleConfig>

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

peer_groups: HashMap<String, PeerGroupConfig>

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.

hooks: HooksConfig

Hooks configuration (lifecycle hooks and built-in hook toggles).

hardware: HardwareConfig

Hardware configuration (wizard-driven physical world setup).

transcription: TranscriptionConfig

Voice transcription configuration (Whisper API via Groq).

tts: TtsConfig

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

mcp: McpConfig

External MCP server connections ([mcp]).

nodes: NodesConfig

Dynamic node discovery configuration ([nodes]).

onboard_state: OnboardStateConfig

Meta-state for the Quickstart flow (which sections the user has already walked through). Not user-facing config ([onboard_state]).

notion: NotionConfig

Notion integration configuration ([notion]).

jira: JiraConfig

Jira integration configuration ([jira]).

node_transport: NodeTransportConfig

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

knowledge: KnowledgeConfig

Knowledge graph configuration ([knowledge]).

linkedin: LinkedInConfig

LinkedIn integration configuration ([linkedin]).

image_gen: ImageGenConfig

Standalone image generation tool configuration ([image_gen]).

file_upload: FileUploadConfig

Standalone file upload tool configuration ([file_upload]).

file_upload_bundle: FileUploadBundleConfig

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

file_download: FileDownloadConfig

Standalone file download tool configuration ([file_download]).

plugins: PluginsConfig

Plugin system configuration ([plugins]).

locale: Option<String>

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

verifiable_intent: VerifiableIntentConfig

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

claude_code: ClaudeCodeConfig

Claude Code tool configuration ([claude_code]).

claude_code_runner: ClaudeCodeRunnerConfig

Claude Code task runner with Slack progress and SSH session handoff ([claude_code_runner]).

codex_cli: CodexCliConfig

Codex CLI tool configuration ([codex_cli]).

gemini_cli: GeminiCliConfig

Gemini CLI tool configuration ([gemini_cli]).

opencode_cli: OpenCodeCliConfig

OpenCode CLI tool configuration ([opencode_cli]).

sop: SopConfig

Standard Operating Procedures engine configuration ([sop]).

shell_tool: ShellToolConfig

Shell tool configuration ([shell_tool]).

escalation: EscalationConfig

Escalation routing configuration ([escalation]).

Implementations

impl Config

pub fn configurable_prefix() -> &'static str

Returns the #[prefix] value for this Configurable struct.

pub fn secret_fields(&self) -> Vec<SecretFieldInfo>

Returns metadata about all #[secret] fields on this struct and nested children.

pub fn secret_field_terminals() -> Vec<&'static str>

pub fn encrypt_secrets(&mut self, store: &SecretStore) -> Result<(), Error>

Encrypt all secret fields in place using the provided store.

pub fn decrypt_secrets(&mut self, store: &SecretStore) -> Result<(), Error>

Decrypt all secret fields in place using the provided store.

pub fn set_secret(&mut self, name: &str, value: String) -> Result<(), Error>

Set a secret field by its full dotted name, dispatching to nested children.

pub fn prop_fields(&self) -> Vec<PropFieldInfo>

Returns metadata about all property fields on this struct and nested children.

pub fn get_prop(&self, name: &str) -> Result<String, Error>

Get a property value by its full dotted name, returning it as a display string.

pub fn set_prop(&mut self, name: &str, value_str: &str) -> Result<(), Error>

Set a property value by its full dotted name, parsing from string.

pub fn prop_is_secret(name: &str) -> bool

Check if a property name refers to a secret field (static, no instance needed).

pub fn init_defaults(&mut self, prefix: Option<&str>) -> Vec<&'static str>

Instantiate None nested sections whose prefix matches. Returns the prefixes that were initialized.

pub fn map_key_sections() -> Vec<MapKeySection>

Enumerate every map-keyed (HashMap<String, T>) and list-shaped (Vec<T>) section discoverable from this Configurable’s tree. The dashboard / CLI consume this to surface “+ Add” affordances without hardcoding the section list.

pub fn nested_section_help(name: &str) -> Option<&'static str>

Help blurb for a #[nested] field on this struct, sourced from the field-level /// docstring. Returns None for unknown names so callers can fall through to a different lookup.

pub fn nested_section_group(name: &str) -> Option<&'static str>

pub fn get_map_keys(&self, section_path: &str) -> Option<Vec<String>>

Return the current alias keys at section_path, or None if the path doesn’t resolve to a map-keyed section in this tree.

pub fn nested_option_entries(&self) -> Vec<NestedOptionEntry>

pub fn create_map_key( &mut self, section_path: &str, map_key: &str, ) -> Result<bool, String>

pub fn delete_map_key( &mut self, section_path: &str, map_key: &str, ) -> Result<bool, String>

pub fn rename_map_key( &mut self, section_path: &str, map_key: &str, new_key: &str, ) -> Result<bool, String>

impl Config

pub fn resolve_alias_source(&self, source: AliasSource) -> Vec<String>

Resolve the configured alias values valid for an crate::traits::AliasSource. Two-tier sources return dotted <type>.<alias> keys; flat sources return bare alias keys. The single resolver every surface uses for PropKind::AliasRef pickers and validation.

pub fn resolve_default_model(&self) -> Option<String>

Return the first concrete model string available for use as a default. Scans every typed slot’s entries (iteration order is the macro slot order) for one with model set. Returns None only when no model-provider entry has any model configured at all.

pub fn risk_profile_for_agent( &self, agent_alias: &str, ) -> Option<&RiskProfileConfig>

Resolve the risk profile for an explicit agent alias.

Each agent’s risk_profile field names a [risk_profiles.<alias>] entry that gates its actions. There is no “global” risk profile in every callsite must come through an agent. When the agent has no profile set or names a missing entry, returns None and the caller decides how to handle it (validation rejects this shape at load time; the runtime treating None as a config error).

pub fn reachable_delegate_target_configs( &self, caller_alias: &str, ) -> Vec<DelegateTargetConfig>

Resolve the delegate targets caller_alias may reach: same-profile peers when delegate_same_risk_profile is set, unioned with the explicit delegates roster, minus the caller. Single source of truth for delegate reach and mode; gating (delegation_policy) is enforced separately by the caller. Deduped, sorted; unknown caller yields empty. Disabled targets are never reachable. Explicit entries override the bounded mode used for implicit same-profile peers.

pub fn reachable_delegate_targets(&self, caller_alias: &str) -> Vec<String>

Resolve only the agent aliases reachable by caller_alias. Use Self::reachable_delegate_target_configs when the target mode matters.

pub fn delegate_target_mode( &self, caller_alias: &str, target_alias: &str, ) -> Option<DelegateExecutionMode>

Resolve the execution mode for one reachable delegate target.

Target aliases are normalized the same way the reachable roster normalizes explicit delegates entries. This keeps callers that need one target mode aligned with the canonical roster resolver instead of creating a subtly different admission rule.

pub fn runtime_profile_for_agent( &self, agent_alias: &str, ) -> Option<&RuntimeProfileConfig>

Resolve the [runtime_profiles.<alias>] entry owned by an agent (via agents.<alias>.runtime_profile). Returns None when the agent has no runtime profile set or names a missing entry. Unlike risk_profile_for_agent, the missing case is not a hard error because runtime budgets and tunables fall back to global defaults.

pub fn effective_summary_provider( &self, agent_alias: &str, ) -> Option<ModelProviderRef>

Effective context-compression summarizer provider for an agent: agent-level summary_provider override → the runtime profile’s context_compression.summary_provider → None (the caller then reuses the agent’s own provider+model, optionally via the deprecated summary_model swap). Unlike the inert agent-inline tunables below, the agent-level override IS consulted — it’s an explicit per-agent choice, mirroring classifier_provider’s “empty = inherit” semantics.

pub fn effective_max_tool_iterations(&self, agent_alias: &str) -> usize

pub fn effective_max_history_messages(&self, agent_alias: &str) -> usize

pub fn effective_structured_max_history_messages( &self, agent_alias: &str, ) -> usize

Resolve the whole-turn history cap used by structured Agent sessions.

An explicit runtime-profile cap remains authoritative. When omitted, the cap scales with the profile’s tool-iteration limit while preserving the legacy floor of 50 messages.

pub fn effective_max_context_tokens(&self, agent_alias: &str) -> usize

pub fn effective_model_context_window(&self, agent_alias: &str) -> usize

Returns the model’s context window size (max input tokens). Source: provider config context_window → fallback 32,000. Does NOT check runtime profile (that’s for output budget).

pub fn effective_memory_recall_limit(&self, agent_alias: &str) -> usize

pub fn effective_compact_context(&self, agent_alias: &str) -> bool

pub fn effective_parallel_tools(&self, agent_alias: &str) -> bool

pub fn effective_tool_dispatcher(&self, agent_alias: &str) -> String

pub fn effective_tool_call_dedup_exempt(&self, agent_alias: &str) -> Vec<String>

pub fn effective_max_system_prompt_chars(&self, agent_alias: &str) -> usize

pub fn effective_max_tool_result_chars(&self, agent_alias: &str) -> usize

pub fn effective_keep_tool_context_turns(&self, agent_alias: &str) -> usize

pub fn resolved_agent_config( &self, agent_alias: &str, ) -> Option<AliasedAgentConfig>

Return a clone of the named agent’s AliasedAgentConfig with all runtime-profile overrides baked in. Use this when an Agent (or any other struct) needs to own a self-contained, already-resolved view of the agent’s runtime knobs without holding a reference to the full Config.

Returns None when agent_alias is not present in agents.

Semantics: every field touched here mirrors the matching effective_* helper above. If you add a new runtime_profile knob, add it both to an effective_* helper and to this function so downstream consumers see consistent values regardless of which surface they read from.

pub fn effective_skills_prompt_mode( &self, agent_alias: &str, ) -> SkillsPromptInjectionMode

Resolve the effective skills prompt-injection mode for an agent: the agent’s resolved runtime profile’s prompt_injection_mode override when set, otherwise the global [skills] prompt_injection_mode. Agents with no runtime profile (or an unknown alias) fall back to the global value.

Keyed on the resolved runtime profile — the sanctioned surface for per-agent runtime tunables — so agent-inline knobs stay inert. Centralizing the fallback here keeps the system-prompt builder and the read_skill tool-registration gate in lockstep on one effective mode, so a compact prompt is never paired with a missing read_skill tool (or a full prompt with a spurious one).

pub fn model_provider_for_agent( &self, agent_alias: &str, ) -> Option<&ModelProviderConfig>

Resolve an agent’s model_provider reference ("<type>.<alias>") to its concrete ModelProviderConfig entry. Returns None when the agent doesn’t exist, the reference is unparseable, or the <type>.<alias> pair doesn’t resolve in providers.models.

This is the lookup the orchestrator uses to build per-agent model_provider runtime options via explicit <type>.<alias> resolution — there is no concept of a “first” or “default” provider. The matching split logic lives in crates/zeroclaw-runtime/src/tools/delegate.rs::resolve_brain for the delegation path; this helper exposes the same contract for the channel-server startup path.

pub fn resolved_model_provider_for_agent( &self, agent_alias: &str, ) -> Option<(&'static str, &str, &ModelProviderConfig)>

Resolve (provider_type, provider_alias, &ModelProviderConfig) for an agent. Same lookup as model_provider_for_agent but also returns the 'static type key that downstream provider factories (create_routed_model_provider_with_options, etc.) need. Returns None when the agent has no model_provider set, when the reference is unparseable, or when the resolved entry has been deleted from providers.models.

pub fn agent_for_channel(&self, channel_alias: &str) -> Option<&str>

Reverse-lookup the agent alias that owns a configured channel (<type>.<alias>). Returns the first agent listing the channel in its channels field. None when no agent owns the channel — orphaned channels are a config error the orchestrator surfaces at startup.

pub fn channel_workspace_dir(&self, channel_ref: &str) -> PathBuf

Workspace dir a channel’s inbound-media handler writes into. Resolves the channel’s owning agent and returns <install>/agents/<alias>/workspace/; falls back to data_dir for orphan channels (no owning agent enabled).

pub fn channels_by_alias(&self) -> Vec<ChannelAliasInfo>

Schema-walk: every populated [channels.<type>.<alias>] block. Type names come from the prop_fields() enumeration (kebab as the macro emits them) so adding a new channel type via the macro surfaces here without touching this code. Alias keys are HashMap keys; not kebab-converted.

pub fn agent_for_cron_job(&self, cron_alias: &str) -> Option<&str>

Reverse-lookup the agent alias that owns a declaratively-configured cron job ([cron.<alias>]). Returns the first agent listing the alias in its cron_jobs field. None when no agent claims the job — orphaned cron jobs are skipped at scheduler time with a warning. Imperative jobs (created at runtime via cron_add) have UUID-shaped ids that won’t match any agent’s cron_jobs; the scheduler treats those separately (carrying their owning agent alongside the DB row is a follow-up).

pub fn agent_workspace_dir(&self, agent_alias: &str) -> PathBuf

Resolve the per-agent workspace directory for alias.

Returns the agent’s [agents.<alias>.workspace.path] override when set (operator-explicit, e.g. for putting a workspace on a different disk), otherwise derives <install>/agents/<alias>/workspace/ from the install root (the directory containing config.toml).

Per-agent workspaces live under <install>/agents/<alias>/workspace/ and hold the agent’s markdown memory (MEMORY.md), identity files (IDENTITY.md, SOUL.md), and any other per-agent plaintext state. Shared databases (SQLite memory, sessions, cost records) live under config.data_dir instead and partition by agent at the row level. Per-agent overrides via [agents.<alias>.workspace.path] pin an arbitrary filesystem path (e.g. a different mount).

pub fn mcp_servers_for_agent(&self, agent_alias: &str) -> Vec<McpServerConfig>

Effective MCP servers granted to an agent by its mcp_bundles.

Secure by default: omission is not a grant. An agent is reached via resolved_agent_config; an unknown alias or one with no mcp_bundles receives NO MCP servers. See Self::mcp_servers_for_bundles for how a non-empty bundle list resolves to servers.

pub fn mcp_servers_for_bundles( &self, bundle_aliases: &[String], ) -> Vec<McpServerConfig>

Resolve a set of [mcp_bundles.<alias>] references to the concrete [mcp.servers] entries they grant.

Secure by default: omission is not a grant.

• An empty bundle_aliases grants NO servers (Vec::new()).
• The grant is the union of each referenced bundle’s servers, in first-seen order with duplicates dropped.
• Deny wins: a server name listed in ANY referenced bundle’s exclude is removed from the grant, regardless of which bundle included it.
• An unknown bundle alias grants nothing (it is skipped, not an error) and a server name with no matching [mcp.servers] entry grants nothing. Both fail closed: a misconfiguration narrows access, never widens it.

pub fn shared_workspace_dir(&self) -> PathBuf

<install>/shared/ — directory shared across every agent on this host. Holds skills, skill bundles, knowledge bundles, and any other content not scoped to a single agent’s workspace. Distinct from agent_workspace_dir(alias) (per-agent state) and data_dir (databases + runtime state).

pub fn install_root_dir(&self) -> PathBuf

Install root: <install>/ derived from config_path’s parent. Used to compute <install>/shared/, <install>/agents/, and the skill-bundle directory defaults. Public so consumers (gateway, CLI, SkillsService) share the same anchor.

pub fn agent(&self, agent_alias: &str) -> Option<&AliasedAgentConfig>

Resolve an aliased-agent config by alias. None when the alias isn’t configured; callers should treat this as a config error rather than synthesizing a default.

pub fn resolved_runtime_agent_alias(&self) -> Option<&str>

Resolve the runtime-active agent alias the orchestrator binds channels to. Mirrors the same selection logic as start_channels() in zeroclaw-channels: prefer the migration- synthesized "default" agent, otherwise fall back to the lexicographically-smallest enabled alias. Returns None only when no enabled agent is configured.

Used by per-agent infrastructure (TtsManager, TranscriptionManager) to pick which agent’s tts_provider / transcription_provider drives the manager’s resolved alias. Until the per-channel dispatch refactor lands, the orchestrator runs in single-agent mode, so all manager instances share the same resolved agent.

pub fn resolve_active_storage(&self) -> ActiveStorage<'_>

Resolve the active storage backend for the memory subsystem.

MemoryConfig.backend is a dotted reference (<backend>.<alias>) into Config.storage.<backend>.<alias>. Bare backend names are interpreted as <backend>.default for back-compat.

Returns ActiveStorage::None when no backend is configured, when the backend is "none", or when the dotted alias does not resolve to a configured entry.

impl Config

pub fn channel_external_peers( &self, channel_type: &str, alias: &str, ) -> Vec<String>

External-peer usernames authorized on <channel_type>.<alias>.

A [peer_groups.<name>] contributes when its channel field either matches channel_type (type-wide group, applies to every alias of that type) or matches the full dotted "<channel_type>.<alias>" (instance-scoped group, applies to that one alias only).

pub fn channel_voice_peers( &self, channel_type: &str, alias: &str, ) -> Vec<String>

Voice-peer usernames for <channel_type>.<alias> that should always receive TTS voice replies.

A [peer_groups.<name>] contributes when its channel field matches (type-wide or dotted) and output_modality = "voice".

This is the live-resolve counterpart of channel_external_peers, filtered to voice-only peer groups. No cache — single source of truth is self.peer_groups.

pub fn channel_agent_scope_admins( &self, channel_type: &str, alias: &str, agent_alias: &str, ) -> Vec<String>

Sender usernames authorized to issue /model --agent <model> on <channel_type>.<alias> for agent agent_alias. A [peer_groups.<name>] contributes when its channel matches (type-wide or dotted), its admin_for_agent_scope = true, and its agents list (if non-empty) contains agent_alias. Returns deduped and sorted. Live-resolve against the Config this method is called on — no internal cache. Edits to peer_groups take effect at the next Config::channel_agent_scope_admins call; the orchestrator gate reads through a snapshot of this Config, so operator edits become visible after the runtime context is rebuilt (daemon restart).

pub fn integration_descriptors(&self) -> Vec<IntegrationDescriptor>

Collect the IntegrationDescriptor from every nested config that declares one via #[integration(...)]. Adding a new toggleable integration is one struct-level attribute on the new config + one row in this method. The integrations registry consumes the result without per-vendor branches.

pub fn unknown_keys(raw_toml: &str) -> Vec<String>

Return top-level TOML keys in raw_toml that Config does not recognise.

Keys present in Config::default() serialization pass immediately. Remaining keys are probed: the key is deserialized in isolation and the result compared to the default — a changed output means serde consumed it (covers Option<T> fields and #[serde(alias)] names). V1 legacy keys (consumed by migration) are also accepted.

pub fn unknown_provider_families(raw_toml: &str) -> Vec<String>

Return <kind>.<family> entries under [providers] in raw_toml whose family is not a known typed slot (kinds: models, tts, transcription). Serde silently drops these sections at deserialize time, so a typo’d family ([providers.models.antropic.x]) or one from a newer binary vanishes on reload: the alias “works” in the session that created it, then disappears after restart.

pub fn prop_is_env_overridden(&self, path: &str) -> bool

Returns true if path was populated by a ZEROCLAW_* env-var override at load time. O(1) HashSet lookup; safe to call per row in list-rendering paths (config list, dashboard, quickstart).

pub async fn load_or_init() -> Result<Config, Error>

pub fn collect_warnings(&self) -> Vec<ValidationWarning>

Collect non-fatal validation warnings — config that loads and validates successfully (validate() returns Ok(())) but will fail at runtime because of a logical inconsistency the schema cannot enforce structurally.

Called by validate() (which emits each warning via tracing::warn! for log visibility) and by the gateway HTTP API (which returns the structured list in PropResponse / PatchResponse so dashboard callers see the same signal the CLI sees on stderr).

Adding a new warning: append a check here, pick a stable code, and document the code in validation_warnings.rs.

pub fn reply_pacing_entries(&self) -> Vec<(String, &dyn HasReplyPacing)>

Walk every channel HashMap that carries reply pacing fields and yield (dotted-path-prefix, &dyn HasReplyPacing) pairs. Used by validation and by anywhere that wants a single source of truth for which channel types participate in pacing.

pub fn validate(&self) -> Result<(), Error>

Validate configuration values that would cause runtime failures.

Called after TOML deserialization and env-override application to catch obviously invalid values early instead of failing at arbitrary runtime points.

pub fn mark_dirty(&mut self, path: &str)

pub fn ensure_map_key_for_path(&mut self, path: &str) -> bool

Auto-create the parent map key for a dotted set-prop path when it does not yet exist, so a set_prop on a brand-new alias’s field materializes the entry first.

Returns true iff it REFUSED to create the reserved default agent: a set-prop surface should then surface a reserved-name error rather than the generic “not configured” that the still-missing entry would otherwise produce. Returns false in every other case (created, already existed, or the path is not a map-keyed entry). The bool is advisory; statement-callers that do not distinguish the reserved case may ignore it.

#[resource_key] sections are excluded. Their keys are values drawn from another domain (model id, voice, tool name) and may themselves contain dots, so the first-dot split below would read cost.rates.providers.models.openai.gpt-4.1.input_per_mtok as the bogus alias gpt-4 plus a nonsense tail, and create_map_key skips validate_alias_key for those sections so nothing else rejects it. Rate rows are created explicitly through POST /api/config/map-key instead.

pub fn clear_dirty(&mut self)

pub fn set_prop_persistent( &mut self, name: &str, value_str: &str, ) -> Result<(), Error>

pub fn set_secret_persistent( &mut self, name: &str, value: String, ) -> Result<(), Error>

pub async fn save(&self) -> Result<(), Error>

pub async fn save_dirty(&mut self) -> Result<(), Error>

Incremental save: only the paths in self.dirty_paths are written against the existing on-disk file. Non-dirty entries (including secret ciphertext) are left untouched; dirty paths whose value equals the schema default are removed from the doc instead of written. Falls back to a full save() when the file doesn’t exist yet. Clears the dirty set on success.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Config

fn default() -> Config

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Config

fn deserialize<__D>( __deserializer: __D, ) -> Result<Config, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for Config

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl MaskSecrets for Config

fn mask_secrets(&mut self)

fn restore_secrets_from(&mut self, current: &Config)

impl Serialize for Config

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.