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 dirty_paths: HashSet<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 pacing: PacingConfig,
    pub skills: SkillsConfig,
    pub pipeline: PipelineConfig,
    pub query_classification: QueryClassificationConfig,
    pub heartbeat: HeartbeatConfig,
    pub cron: HashMap<String, CronJobDecl>,
    pub acp: AcpConfig,
    pub channels: ChannelsConfig,
    pub memory: MemoryConfig,
    pub storage: StorageConfig,
    pub tunnel: TunnelConfig,
    pub gateway: GatewayConfig,
    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, onboarding).

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.

dirty_paths: HashSet<String>

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

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

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

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

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 zeroclaw onboard (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 ZEROCLAW_LOCALE, LANG, or LC_ALL environment variables (defaulting to "en").

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>

Static enumeration of every #[secret] field’s terminal name (snake_case, matching the on-disk TOML key) reachable from this type via #[nested] traversal. Unlike secret_fields(), this requires no instance — the per-struct codegen literals are joined at call time with recursive calls into the inner types’ own secret_field_terminals().

Used by the migration crate’s raw-TOML encrypt walker as the secret-key allowlist. prop_fields()-derived allowlists skip compound (non-Vec) #[secret] fields, so this method is the authoritative source.

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

Encrypt all secret fields in place using the provided store.

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

Decrypt all secret fields in place using the provided store.

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

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>

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

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

Snapshot of every #[nested] Option<T> field on this struct as (field_name, is_some) tuples, in declaration order.

field_name is the raw Rust ident (snake_case) — consumers can map to display names via their own table. The schema is the single source of truth: adding a new pub foo: Option<FooConfig> field with #[nested] surfaces here without touching any caller.

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

Insert a default-valued entry under a map-keyed section, or append to a list-shaped one, with map_key as the new entry’s natural identifier (HashMap key for Map sections; identifier field for List sections).

Returns Ok(true) if a new entry was created, Ok(false) if the entry already existed (idempotent), or Err(reason) if the section path doesn’t resolve to a Map/List in this tree.

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

Remove the entry identified by map_key from the map-keyed section at section_path.

Returns Ok(true) if the entry existed and was removed, Ok(false) if it didn’t exist, or Err(reason) if the section path doesn’t resolve.

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

Rename map_key to new_key within the map-keyed section at section_path, preserving the entry’s value.

Returns Ok(true) if renamed, Ok(false) if map_key didn’t exist, or Err(reason) if new_key already exists or the section path doesn’t resolve.

impl Config

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 first_model_provider(&self) -> Option<&ModelProviderConfig>

Return the first ModelProviderConfig (the shared base) from model_providers, if any exists.

pub fn first_model_provider_mut(&mut self) -> Option<&mut ModelProviderConfig>

Mutable form of Self::first_model_provider.

pub fn first_model_provider_type(&self) -> Option<&'static str>

Return the model-provider type key of the first entry in model_providers, if any. Use this when callers need the bare type name (e.g. provider routing factories that take "openrouter" not "openrouter.default").

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

Return the dotted <type>.<alias> identifier of the first configured model-provider entry, if any. Use this when callers need the alias reference (matches agents.<x>.model_provider values).

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 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 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 instead of falling back to first_model_provider(), which silently collapses multiple aliases under the same model_provider family to whichever entry happens to be first. 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 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 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 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, onboarding).

pub async fn load_or_init() -> Result<Self>

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 validate(&self) -> Result<()>

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 clear_dirty(&mut self)

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

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

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

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

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

Formats the value using the given formatter.

impl Default for Config

fn default() -> Self

Returns the “default value” for a type.

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

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::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: &Self)

impl Serialize for Config

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

where __S: Serializer,

Serialize this value into the given Serde serializer.