Struct Config 

pub struct Config {

    pub llm_provider: String,
    pub api_key: String,
    pub api_keys: Vec<String>,
    pub model: String,
    pub provider_presets: HashMap<String, LlmProviderProfile>,
    pub llm_providers: HashMap<String, LlmProviderProfile>,
    pub llm_base_url: Option<String>,
    pub llm_user_agent: String,
    pub max_tokens: u32,
    pub max_tool_iterations: usize,
    pub compaction_timeout_secs: u64,
    pub aux_models: AuxModels,
    pub fallback_model: Option<String>,
    pub max_history_messages: usize,
    pub max_document_size_mb: u64,
    pub memory_token_budget: usize,
    pub memory_l0_identity_pct: usize,
    pub memory_l1_essential_pct: usize,
    pub memory_max_entries_per_chat: usize,
    pub memory_max_global_entries: usize,
    pub kg_max_triples_per_chat: usize,
    pub tool_result_truncation_threshold_chars: usize,
    pub tool_result_truncation_head_chars: usize,
    pub tool_result_truncation_tail_chars: usize,
    pub tool_result_artifact_ttl_hours: u64,
    pub memory_recency_half_life_days: f64,
    pub memory_graph_recall_enabled: bool,
    pub memory_graph_max_hops: usize,
    pub memory_graph_max_triples: usize,
    pub tool_repeat_window: usize,
    pub tool_repeat_limit: usize,
    pub anthropic_prompt_cache_enabled: bool,
    pub anthropic_prompt_cache_ttl: String,
    pub checkpoints_enabled: bool,
    pub skill_archive_after_days: u64,
    pub skills_catalog_top_k: usize,
    pub system_prompt_time_detail: SystemPromptTimeDetail,
    pub max_session_messages: usize,
    pub diff_max_lines: usize,
    pub file_diffs_in_chat: bool,
    pub allow_governance_file_writes: bool,
    pub model_context_window: usize,
    pub context_pressure_compact_pct: usize,
    pub self_recheck: SelfRecheckConfig,
    pub compact_keep_recent: usize,
    pub default_tool_timeout_secs: u64,
    pub tool_timeout_overrides: HashMap<String, u64>,
    pub default_mcp_request_timeout_secs: u64,
    pub show_thinking: bool,
    pub subagents: SubagentConfig,
    pub idle_checkin: IdleCheckinConfig,
    pub heartbeat: HeartbeatConfig,
    pub token_budget: TokenBudgetConfig,
    pub alerts: AlertsConfig,
    pub trust_report: TrustReportConfig,
    pub user_message_language: UserMessageLanguage,
    pub sleep_time: SleepTimeConfig,
    pub interjection: InterjectionConfig,
    pub a2a: A2AConfig,
    pub chat_turn_queue_max_pending: usize,
    pub enable_mid_turn_injection: bool,
    pub mid_turn_injection_echo: bool,
    pub parallel_tool_max_concurrency: usize,
    pub tool_concurrency_overrides: HashMap<String, String>,
    pub openai_compat_body_overrides: HashMap<String, Value>,
    pub openai_compat_body_overrides_by_provider: HashMap<String, HashMap<String, Value>>,
    pub openai_compat_body_overrides_by_model: HashMap<String, HashMap<String, Value>>,
    pub data_dir: String,
    pub skills_dir: Option<String>,
    pub working_dir: String,
    pub working_dir_isolation: WorkingDirIsolation,
    pub high_risk_tool_user_confirmation_required: bool,
    pub bash_dangerous_patterns: Vec<String>,
    pub rtk: RtkConfig,
    pub sandbox: SandboxConfig,
    pub override_timezone: Option<String>,
    pub timezone: String,
    pub control_chat_ids: Vec<i64>,
    pub discord_bot_token: Option<String>,
    pub discord_allowed_channels: Vec<u64>,
    pub discord_no_mention: bool,
    pub allow_group_slash_without_mention: bool,
    pub web_enabled: bool,
    pub web_host: String,
    pub web_port: u16,
    pub web_max_inflight_per_session: usize,
    pub web_max_requests_per_window: usize,
    pub web_rate_window_seconds: u64,
    pub web_run_history_limit: usize,
    pub web_session_idle_ttl_seconds: u64,
    pub web_fetch_validation: WebContentValidationConfig,
    pub web_fetch_url_validation: WebFetchUrlValidationConfig,
    pub web_search: SearchProviderConfig,
    pub output_guardrail: OutputGuardrailConfig,
    pub tool_policy: ToolPolicyConfig,
    pub egress_policy: EgressPolicyConfig,
    pub embedding_provider: Option<String>,
    pub embedding_api_key: Option<String>,
    pub embedding_base_url: Option<String>,
    pub embedding_model: Option<String>,
    pub embedding_dim: Option<usize>,
    pub openai_api_key: Option<String>,
    pub model_prices: Vec<ModelPrice>,
    pub reflector_enabled: bool,
    pub reflector_interval_mins: u64,
    pub dlq_replay_enabled: bool,
    pub dlq_replay_interval_secs: u64,
    pub dlq_max_replay_attempts: u32,
    pub skill_review_min_tool_calls: usize,
    pub soul_path: Option<String>,
    pub souls_dir: Option<String>,
    pub context_dir: Option<String>,
    pub context_max_chars: usize,
    pub voice_round_trip: bool,
    pub user_model_max_chars: usize,
    pub clawhub: ClawHubConfig,
    pub plugins: PluginsConfig,
    pub media: MediaConfig,
    pub openai_base_url: Option<String>,
    pub voice_provider: String,
    pub voice_transcription_command: Option<String>,
    pub observability: Option<Value>,
    pub channels: HashMap<String, Value>,
    pub telegram_bot_token: String,
    pub bot_username: String,
    pub allowed_groups: Vec<i64>,
}

Fields

llm_provider: String

api_key: String

api_keys: Vec<String>

Additional API keys forming a rotation pool with api_key: on auth (401/403) or rate-limit (429) errors the provider advances to the next key before retrying.

model: String

provider_presets: HashMap<String, LlmProviderProfile>

llm_providers: HashMap<String, LlmProviderProfile>

llm_base_url: Option<String>

llm_user_agent: String

max_tokens: u32

max_tool_iterations: usize

compaction_timeout_secs: u64

aux_models: AuxModels

Optional per-task auxiliary model overrides (e.g. a cheaper model for compaction). Empty by default, in which case the main model is used.

fallback_model: Option<String>

Optional fallback model used when the primary model’s provider keeps failing (after retries) or its circuit breaker is open. None disables fallback (and the breaker wrapper) entirely — behaviour is then identical to the primary provider alone.

max_history_messages: usize

max_document_size_mb: u64

memory_token_budget: usize

memory_l0_identity_pct: usize

Percentage of memory_token_budget reserved for L0 Identity (PROFILE) memories. Default: 20.

memory_l1_essential_pct: usize

Percentage of memory_token_budget reserved for L1 Essential (high-confidence) memories. Default: 30.

memory_max_entries_per_chat: usize

memory_max_global_entries: usize

kg_max_triples_per_chat: usize

Maximum active triples per chat in the knowledge graph. 0 = unlimited. Default: 1000.

tool_result_truncation_threshold_chars: usize

Tool-result content over this many Unicode characters is truncated in the message history and the full body is stored as an artifact the agent can read via fetch_artifact. Set to 0 to disable. Default: 4000.

tool_result_truncation_head_chars: usize

When truncating, keep this many leading characters of the original content in the message history. Default: 1500.

tool_result_truncation_tail_chars: usize

When truncating, keep this many trailing characters (so the agent still sees errors/summaries that often live at the end). Default: 500.

tool_result_artifact_ttl_hours: u64

Lifetime for stashed tool-result artifacts before they’re pruned. Long enough to span a typical multi-turn task. Default: 24 hours.

memory_recency_half_life_days: f64

Half-life (in days) of the recency-decay multiplier applied to non-PROFILE memories during L1/L2 ranking. After half_life_days, a memory’s effective score is half of its raw confidence; PROFILE memories never decay. Set to 0 to disable decay. Default: 30.

memory_graph_recall_enabled: bool

Graph-augmented memory recall: after the flat L0-L2 layers are built, seed the temporal knowledge graph from entities the query mentions and pull in connected facts a few hops out (a “# Connected” block). Surfaces multi-hop context the flat layers miss, using the graph the reflector already builds — local-only, no embeddings or extra LLM calls. Default: true.

memory_graph_max_hops: usize

Maximum hops to expand outward from query-seeded entities during graph-augmented recall. Clamped to 1-3. Default: 2.

memory_graph_max_triples: usize

Maximum number of connected triples injected by graph-augmented recall (also bounded by the overall memory token budget). Set to 0 to disable. Default: 10.

tool_repeat_window: usize

Sliding-window size (in past tool calls) used by the duplicate-call circuit breaker. When the same (tool_name, args) shows up tool_repeat_limit times within this many recent calls, the next invocation is short-circuited with an error so the agent picks a different approach. Set to 0 to disable. Default: 10.

tool_repeat_limit: usize

Repeat threshold for the duplicate-call circuit breaker. Default: 3.

anthropic_prompt_cache_enabled: bool

Enable Anthropic prompt-cache breakpoints (system + last 3 messages). Cuts repeat-turn input cost ~75% for multi-turn chats. Anthropic-only; no effect on OpenAI-compatible providers. Default: true.

anthropic_prompt_cache_ttl: String

Cache TTL for Anthropic prompt cache. “5m” (default) or “1h”. “1h” requires extended-cache opt-in on the API key.

checkpoints_enabled: bool

Enable transparent filesystem checkpoints via a shadow git repo. When on, microclaw snapshots each chat’s working directory at the start of every agent turn so users can /rewind to a prior state. Off by default — opt in per chat or via global config. Requires git on PATH.

skill_archive_after_days: u64

Auto-archive agent-created skills that haven’t been activated in this many days and are themselves at least this old. The skill dir is moved under <skills_dir>/.archived/ (recoverable). Set to 0 to disable. Default: 30 days.

skills_catalog_top_k: usize

When building the skills section of the system prompt, inline the full body of the top-K skills whose descriptions match the user query and list the rest as name: description only. Cuts prompt cost as the skill library grows. Set to 0 to fall back to the flat catalog. Default: 3.

system_prompt_time_detail: SystemPromptTimeDetail

How much live time detail the system prompt carries. The default date keeps the cached prefix stable within a local day; the live clock and query-scoped context are injected per turn instead. Set to full to restore the previous always-current timestamps in the system prompt.

max_session_messages: usize

diff_max_lines: usize

Cap on rendered unified-diff lines attached by file-modifying tools (edit_file / write_file). Default: 120.

file_diffs_in_chat: bool

Deliver file-edit diffs as chat messages on channels that opted into progress updates. The web UI always receives diff events. Default: true.

allow_governance_file_writes: bool

Let write_file / edit_file modify MicroClaw’s own governance files (the config file, AGENTS.md / SOUL.md / USER.md under data_dir, soul and context directories, the path allowlist). Off by default: those files are injected into every chat’s prompt or define access policy, so only scoped tools such as write_memory may change them.

model_context_window: usize

Approximate context window (tokens) of the configured model, used by the mid-turn context-pressure check. Default: 200000.

context_pressure_compact_pct: usize

Compact the session mid-turn once a request consumes this percentage of model_context_window. 0 disables the pressure check (the overflow-error retry still applies). Default: 85.

self_recheck: SelfRecheckConfig

Opt-in post-edit quality pass: after a turn that ran edit_file / write_file, one extra review iteration runs before the reply is finalized.

compact_keep_recent: usize

default_tool_timeout_secs: u64

tool_timeout_overrides: HashMap<String, u64>

default_mcp_request_timeout_secs: u64

show_thinking: bool

subagents: SubagentConfig

idle_checkin: IdleCheckinConfig

heartbeat: HeartbeatConfig

token_budget: TokenBudgetConfig

alerts: AlertsConfig

trust_report: TrustReportConfig

user_message_language: UserMessageLanguage

Language for user-facing refusals/approval prompts/notices.

sleep_time: SleepTimeConfig

interjection: InterjectionConfig

a2a: A2AConfig

chat_turn_queue_max_pending: usize

Maximum number of pending messages per chat before oldest are dropped.

enable_mid_turn_injection: bool

Inject pending messages into the active agent loop between iterations, rather than queuing them for a separate re-run. Default: true.

mid_turn_injection_echo: bool

On non-web channels (Telegram/Discord/Slack), send a small ack message when a follow-up arrives mid-turn and is folded into the active loop. Default: true. Has no effect when enable_mid_turn_injection is false.

parallel_tool_max_concurrency: usize

Maximum number of tools to execute concurrently in a single wave.

tool_concurrency_overrides: HashMap<String, String>

Override concurrency class for specific tools (e.g., promote safe MCP tools). Keys are tool names, values are “read_only”, “side_effect”, or “exclusive”.

openai_compat_body_overrides: HashMap<String, Value>

OpenAI-compatible request-body overrides applied for all models/providers. Set a key to null to remove that field from the outgoing JSON body.

openai_compat_body_overrides_by_provider: HashMap<String, HashMap<String, Value>>

OpenAI-compatible request-body overrides keyed by provider name. Provider keys are normalized to lowercase.

openai_compat_body_overrides_by_model: HashMap<String, HashMap<String, Value>>

OpenAI-compatible request-body overrides keyed by model name.

data_dir: String

skills_dir: Option<String>

working_dir: String

working_dir_isolation: WorkingDirIsolation

high_risk_tool_user_confirmation_required: bool

bash_dangerous_patterns: Vec<String>

Regex patterns that always require operator approval before bash will run, even in non-control chats. Extends the per-chat risk policy with command-content inspection so destructive shell snippets cannot slip through just because the caller happens to be in a permissive chat. Patterns are matched case-insensitively against the full command string. Set to an empty list to disable command-content gating.

rtk: RtkConfig

RTK (Rust Token Killer) bash-output compression. Off by default.

sandbox: SandboxConfig

override_timezone: Option<String>

timezone: String

control_chat_ids: Vec<i64>

discord_bot_token: Option<String>

discord_allowed_channels: Vec<u64>

discord_no_mention: bool

allow_group_slash_without_mention: bool

web_enabled: bool

web_host: String

web_port: u16

web_max_inflight_per_session: usize

web_max_requests_per_window: usize

web_rate_window_seconds: u64

web_run_history_limit: usize

web_session_idle_ttl_seconds: u64

web_fetch_validation: WebContentValidationConfig

web_fetch_url_validation: WebFetchUrlValidationConfig

web_search: SearchProviderConfig

Pluggable web-search backend (duckduckgo | searxng | brave | tavily). Defaults to DuckDuckGo, preserving historical behavior.

output_guardrail: OutputGuardrailConfig

Outbound message guardrail (off | redact | block). Off by default; scans delivered bot messages for credential-like strings.

tool_policy: ToolPolicyConfig

Pre-tool-call policy (mode off | warn | block, deny_tools, max_risk, allow_tools). Off by default; violations are sealed into the audit log.

egress_policy: EgressPolicyConfig

Process policy for configured HTTP(S) endpoints and every URL exposed through the shared tool registry. Off by default for compatibility.

embedding_provider: Option<String>

embedding_api_key: Option<String>

embedding_base_url: Option<String>

embedding_model: Option<String>

embedding_dim: Option<usize>

openai_api_key: Option<String>

model_prices: Vec<ModelPrice>

reflector_enabled: bool

reflector_interval_mins: u64

dlq_replay_enabled: bool

Automatically retry scheduled tasks that landed in the dead-letter queue (e.g. a one-shot task that hit a transient failure), up to dlq_max_replay_attempts times. Default: true.

dlq_replay_interval_secs: u64

How often the DLQ auto-replay sweep runs, in seconds. Default: 300.

dlq_max_replay_attempts: u32

Maximum automatic replay attempts per task before it is left in the DLQ for manual inspection. Default: 3.

skill_review_min_tool_calls: usize

Minimum tool_use blocks in a turn before the end-of-turn skill review fires. Autonomous skill creation is on by default; set to 0 to disable entirely. Default: 5.

soul_path: Option<String>

Path to a SOUL.md file that defines the bot’s personality, voice, and values. If not set, looks for SOUL.md in data_dir root, then current directory.

souls_dir: Option<String>

Directory for per-bot SOUL files. Defaults to <data_dir>/souls when unset.

context_dir: Option<String>

Directory of project-level context Markdown files injected into the system prompt for every chat. Use this for workspace-wide facts that belong above per-chat memory but are not personality (which lives in SOUL.md). Defaults to <data_dir>/context/ when unset; missing directories are silently skipped.

context_max_chars: usize

Hard cap (in characters) on the combined size of all loaded context files, to keep prefix-cache friendly system prompts from blowing up. Set to 0 to disable the project-context layer entirely.

voice_round_trip: bool

When a turn was triggered by an inbound voice message and this is true, the bot’s text reply is also rendered to audio via the TTS layer and sent back through the same channel. Off by default — opt in explicitly because each round trip burns one extra TTS call. Has no effect unless media.tts.enabled is also true.

user_model_max_chars: usize

Hard cap on USER.md size. Hermes ships a 1375-char limit on its equivalent file to force the curator to summarize rather than append. Set to 0 to disable the user-model layer entirely; the chat falls back to PROFILE memories alone. Curation is folded into the reflector LLM call (see scheduler.rs), so there is no per-tick amortization knob: the LLM itself returns null when no rewrite is warranted.

clawhub: ClawHubConfig

plugins: PluginsConfig

media: MediaConfig

Multimedia tool configuration (image generation / vision / TTS / STT). When unset, each tool defaults to enabled: false. API key and base URL fall back to openai_api_key / openai_base_url, so users who already have their OpenAI credential wired up get zero-config.

openai_base_url: Option<String>

Override for the OpenAI-compatible base URL used by media tools. When unset, media tools use https://api.openai.com/v1.

voice_provider: String

Voice transcription provider: “openai” uses OpenAI Whisper API, “local” uses voice_transcription_command

voice_transcription_command: Option<String>

Command template for local voice transcription. Use {file} as placeholder for audio file path. Example: “whisper-mlx –file {file}” or “/usr/local/bin/whisper {file}”

observability: Option<Value>

channels: HashMap<String, Value>

Per-channel configuration. Keys are channel names (e.g. “telegram”, “discord”, “slack”, “irc”, “web”). Each value is channel-specific config deserialized by the adapter. If empty, synthesized from legacy flat fields below in post_deserialize().

telegram_bot_token: String

bot_username: String

allowed_groups: Vec<i64>

Implementations

impl Config

pub fn is_control_chat(&self, chat_id: i64) -> bool

Whether chat_id is a control chat. An empty control_chat_ids list means NO chat has control privileges (default deny) — every privileged surface (skill management, /learn, /log, …) must route through this so that rule stays in one place.

pub fn set_provider_override_for_channel( &mut self, channel: &str, provider: Option<&str>, )

pub fn set_model_override_for_channel( &mut self, channel: &str, model: Option<&str>, )

pub fn provider_override_for_channel(&self, channel: &str) -> Option<String>

pub fn model_override_for_channel(&self, channel: &str) -> Option<String>

pub fn soul_path_for_channel(&self, channel: &str) -> Option<String>

pub fn bot_username_for_channel(&self, channel: &str) -> String

pub fn bot_username_overrides(&self) -> HashMap<String, String>

pub fn llm_provider_overrides(&self) -> HashMap<String, String>

pub fn data_root_dir(&self) -> PathBuf

Data root directory from config.

pub fn runtime_data_dir(&self) -> String

Runtime data directory (db, memory, exports, etc.).

pub fn skills_data_dir(&self) -> String

Skills directory. Priority: MICROCLAW_SKILLS_DIR env var > skills_dir config > <data_dir>/skills

pub fn souls_data_dir(&self) -> String

Souls directory. Priority: souls_dir config > <data_dir>/souls

pub fn clawhub_lockfile_path(&self) -> PathBuf

pub fn clawhub_load_verification(&self) -> Option<(PathBuf, bool)>

Lockfile path plus block flag for load-time skill verification, or None when clawhub_verify_on_load: off.

pub fn config_path_for_setup() -> PathBuf

pub fn resolve_config_path() -> Result<Option<PathBuf>, MicroClawError>

pub fn channel_enabled(&self, channel: &str) -> bool

pub fn channel_status(&self) -> (Vec<&'static str>, Vec<&'static str>)

Classify every known channel into (enabled, configured_but_disabled). A channel is “configured” when it has credentials/config present (a channels.<name> block or a legacy top-level token); it is “enabled” per [channel_enabled]. Used both for the no-channel config error and for microclaw doctor, so the two stay consistent.

pub fn load() -> Result<Self, MicroClawError>

Load config from YAML file.

pub fn load_from_path(path: &Path) -> Result<Self, MicroClawError>

Load and validate a specific YAML configuration file.

pub fn load_from_path_for_headless(path: &Path) -> Result<Self, MicroClawError>

Load a specific configuration for a channel-free foreground runtime.

All provider, tool, path, and security validation is retained. Only the Server requirement that at least one delivery channel be enabled is waived, because Work and other headless callers deliver results through their own application boundary.

pub fn for_embedded( provider: impl Into<String>, model: impl Into<String>, api_key: impl Into<String>, base_url: Option<String>, ) -> Result<Self, MicroClawError>

Build and validate a channel-free configuration for an embedded caller.

pub fn post_deserialize(&mut self) -> Result<(), MicroClawError>

Apply post-deserialization normalization and validation.

pub fn resolve_llm_provider_profile( &self, alias: &str, ) -> Option<ResolvedLlmProviderProfile>

pub fn list_llm_provider_profiles(&self) -> Vec<ResolvedLlmProviderProfile>

pub fn channel_config<T: DeserializeOwned>(&self, name: &str) -> Option<T>

Deserialize a typed channel config from the channels map.

pub fn model_price(&self, model: &str) -> Option<&ModelPrice>

pub fn estimate_cost_usd( &self, model: &str, input_tokens: i64, output_tokens: i64, ) -> Option<f64>

pub fn tool_timeout_secs(&self, tool_name: &str, fallback: u64) -> u64

pub fn mcp_request_timeout_secs(&self) -> u64

pub fn save_yaml(&self, path: &str) -> Result<(), MicroClawError>

Save config as YAML to the given path.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Self

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