Luna/Documentation/References/ZeroClaw/Configuration.md

Configuration

ZeroClaw utilizes a TOML-based configuration system designed for modularity, security, and extensibility. The configuration is primarily managed through config.toml, which is loaded from the workspace directory or a fallback legacy location.

---

Config Struct

The core of the configuration system is defined in config/schema.rs via the Config struct. It contains over 30 sections, each governing a specific subsystem.

Global Settings

• workspace_dir: The root directory for ZeroClaw data (computed at runtime).
• config_path: The path to the active config.toml.
• api_key: Global API key for the default provider.
• api_url: Base URL override for provider APIs.
• default_provider: The primary provider ID (e.g., "anthropic", "ollama").
• default_model: The default model used for queries.
• default_temperature: Model temperature (0.0 to 2.0, default 0.7).

Subsystem Sections

• observability: Tracing and metrics configuration.
• autonomy: Security policies and autonomy levels.
• security: Secret management and sandbox settings.
• runtime: Native vs Docker execution modes.
• reliability: Retry logic and fallback providers.
• scheduler: Periodic task execution settings.
• agent: Orchestration parameters (history size, tool iterations).
• skills: Skill loading and prompt injection modes.
• model_routes: Routing specific hints to provider/model pairs.
• embedding_routes: Routing for vector embedding models.
• channels_config: Configuration for Telegram, Discord, Slack, etc.
• memory: Backend settings for SQLite or vector storage.
• storage: Persistent file storage provider configuration.
• secrets: Encryption settings for credentials.
• browser: Browser automation and "computer-use" sidecar.
• identity: AIEOS or OpenClaw format identity documents.
• cost: Budget enforcement and price tracking.
• hardware: Physical world interaction (serial/probe) settings.
• hooks: Lifecycle and built-in hook toggles.

---

ModelProviderConfig

ZeroClaw supports multiple provider profiles via the model_providers HashMap.

pub struct ModelProviderConfig {
    pub name: Option<String>,
    pub base_url: Option<String>,
    pub wire_api: Option<String>,
    pub requires_openai_auth: bool,
    pub azure_openai_resource: Option<String>,
    pub azure_openai_deployment: Option<String>,
    pub azure_openai_api_version: Option<String>,
}

This allows for configuring multiple instances of the same provider (e.g., local Ollama vs. remote Ollama) or complex Azure OpenAI deployments with distinct resource names and versions.

---

DelegateAgentConfig

Sub-agents used by the delegate tool are configured separately to allow for specialized behavior.

pub struct DelegateAgentConfig {
    pub provider: String,
    pub model: String,
    pub system_prompt: Option<String>,
    pub api_key: Option<String>,
    pub temperature: Option<f64>,
    pub max_depth: u32,
    pub agentic: bool,
    pub allowed_tools: Vec<String>,
    pub max_iterations: usize,
}

Sub-agents can be limited to specific toolsets and have a max_depth to prevent infinite delegation loops.

---

TOML Structure

Example config.toml demonstrating provider setup and security routing:

default_provider = "anthropic"
default_model = "claude-3-5-sonnet"

[model_providers.ollama_local]
name = "ollama"
base_url = "http://localhost:11434"

[[model_routes]]
hint = "fast"
provider = "ollama_local"
model = "llama3"

[security]
encrypt = true

[autonomy]
level = "high"

---

Hot-Reload

ZeroClaw supports hot-reloading for specific runtime fields without requiring a full service restart.

Supported Fields

• api_key / api_url
• default_provider
• default_model
• default_temperature
• reliability settings

Mechanism

The system utilizes a file watcher (via config_file_stamp) that monitors the config.toml modification time. When a change is detected, the maybe_apply_runtime_config_update function reloads the file, decrypts any secrets using the SecretStore, and updates the runtime provider cache.

---

Relevance to Luna

ZeroClaw's configuration architecture serves as the target state for Configuration in Luna.

• Subsystem Isolation: Luna plans to migrate from appsettings.json to a per-subsystem TOML structure to improve modularity, similar to ZeroClaw's section pattern.
• Security First: The pattern of separating autonomy and security configs is a requirement for Luna's Core.
• Hot-Reload: ZeroClaw's implementation of lightweight file watching for key LLM parameters is a "nice-to-have" feature Luna aims to adopt during the migration.

---

Configuration | Core