clawseed-config — 配置加载与管理

概述

clawseed-config 负责 TOML 配置文件的发现、加载和环境变量覆盖。

配置发现

配置文件搜索顺序（优先级从高到低）：

1. $CLAWSEED_CONFIG_DIR/clawseed.toml（环境变量指定目录）
2. ~/.clawseed/clawseed.toml（默认配置目录）
3. ./clawseed.toml（当前工作目录）

首次运行时自动创建 ~/.clawseed/ 目录。

默认路径

路径	函数	默认值
配置目录	default_config_dir()	~/.clawseed/
工作目录	default_workspace_dir()	~/.clawseed/workspace/

配置 Schema

顶层 Config

pub struct Config {
    pub providers: ProvidersConfig,
    pub agent: AgentConfig,
    pub gateway: GatewayConfig,
    pub storage: StorageConfig,
    pub reliability: ReliabilityConfig,
    pub secrets: SecretsConfig,
    pub runtime: RuntimeConfig,
    pub memory: MemoryConfig,
    pub user_model: UserModelConfig,
    pub autonomy: AutonomyConfig,
    pub cron: CronConfig,
    pub scheduler: SchedulerConfig,
    pub backup: BackupConfig,
    pub composio: ComposioConfig,
    pub mcp: McpConfig,
    pub hooks: HooksConfig,
    pub tunnel: TunnelConfig,
    pub nodes: NodesConfig,
    pub cost: CostConfig,
    pub channels: ChannelsConfig,
    pub browser: BrowserConfig,
    pub http_request: HttpRequestConfig,
    pub web_fetch: WebFetchConfig,
    pub transcription: TranscriptionConfig,
    pub web_search: WebSearchConfig,
    pub agents: HashMap<String, AgentEntryConfig>,
    pub identity: IdentityConfig,
    pub locale: Option<String>,
    // ...
}

ProvidersConfig — 提供商配置

pub struct ProvidersConfig {
    pub default: Option<String>,
    pub default_model: Option<String>,
    pub default_api_key: Option<String>,
    pub default_base_url: Option<String>,
    pub default_timeout_secs: Option<u64>,
    pub extra_headers: HashMap<String, String>,
    pub models: HashMap<String, ModelProviderConfig>,
    pub model_routes: Vec<ModelRouteConfig>,
    pub embedding_routes: Vec<EmbeddingRouteConfig>,
    pub fallback: Option<String>,
    pub reasoning_effort: Option<String>,
    pub reasoning_enabled: Option<bool>,
}

pub struct ModelProviderConfig {
    pub api_key: Option<String>,
    pub name: Option<String>,
    pub base_url: Option<String>,
    pub api_path: Option<String>,
    pub model: Option<String>,
    pub temperature: Option<f64>,
    pub timeout_secs: Option<u64>,
    pub extra_headers: HashMap<String, String>,
    pub wire_api: Option<String>,
    pub max_tokens: Option<u32>,
    pub provider_extra: Option<serde_json::Value>,
    pub merge_system_into_user: bool,
}

AgentConfig — Agent 配置

pub struct AgentConfig {
    pub max_tool_iterations: usize,           // 最大工具循环次数（默认 25）
    pub temperature: Option<f64>,
    pub max_tokens: Option<u32>,
    pub auto_continue_on_truncation: bool,
    pub max_auto_continue: usize,
    pub web_search_enabled: bool,
    pub web_search_provider: Option<String>,
    pub system_prompt: Option<String>,
    pub memory_namespace: Option<String>,
    pub daily_budget_usd: Option<f64>,
    pub turn_budget_usd: Option<f64>,
    pub allowed_tools: Vec<String>,           // glob 模式工具白名单（空 = 允许全部）
    pub denied_tools: Vec<String>,            // glob 模式工具黑名单（优先于白名单）
    pub mcp_tool_filters: HashMap<String, Vec<String>>,  // MCP 服务器级工具过滤
}

GatewayConfig — 网关配置

pub struct GatewayConfig {
    pub host: String,
    pub port: u16,
    pub timeout_secs: u64,
    pub path_prefix: Option<String>,
    pub session_persistence: bool,
    pub session_ttl_hours: u32,
    pub tls: Option<GatewayTlsConfig>,
    pub enable_cors: bool,
    pub require_pairing: bool,
    pub paired_tokens: Vec<String>,
    pub allow_public_bind: bool,
    pub pair_rate_limit_per_minute: u32,
    pub webhook_rate_limit_per_minute: u32,
    pub rate_limit_max_keys: usize,
    pub idempotency_ttl_secs: u64,
    pub idempotency_max_keys: usize,
    pub trust_forwarded_headers: bool,
    pub web_dist_dir: Option<String>,
    pub pairing_dashboard: PairingDashboardConfig,
}

MemoryConfig — 记忆配置

pub struct MemoryConfig {
    pub backend: String,           // "sqlite" / "none"
    pub auto_save: bool,
    pub min_relevance_score: f64,
    pub response_cache_enabled: bool,
    pub response_cache_ttl_minutes: u64,
    pub response_cache_max_entries: usize,
    pub response_cache_hot_entries: usize,
    pub namespace: Option<String>,
    pub qdrant: QdrantConfig,
    pub hygiene_enabled: bool,
    pub conversation_retention_days: u32,
    pub snapshot_enabled: bool,
    pub auto_hydrate: bool,
    pub conflict_threshold: f64,
    pub conflict_mode: Option<ConflictMode>,
    pub auto_recall: bool,
    pub auto_recall_limit: usize,
    pub embedding_provider: Option<String>,
    pub embedding_model: Option<String>,
    pub embedding_dims: Option<usize>,
    pub search_mode: Option<SearchMode>,
    pub vector_weight: Option<f32>,
    pub keyword_weight: Option<f32>,
    pub merge_strategy: Option<MergeStrategy>,
    pub embedding_cache_max: Option<usize>,
    pub backfill_on_startup: bool,
    pub defer_embedding: Option<bool>,
    pub stable_memory_in_system_prompt: Option<bool>,
    pub min_retention_floor: Option<usize>,
    pub daily_retention_floor: Option<usize>,
    pub conversation_retention_floor: Option<usize>,
}

AutonomyConfig — 自主等级配置

pub struct AutonomyConfig {
    pub level: AutonomyLevel,      // ReadOnly / Supervised / Full
    pub auto_approve: Vec<String>,
    pub always_ask: Vec<String>,
    pub allowed_commands: Vec<String>,
    pub non_cli_excluded_tools: Vec<String>,
    pub max_actions_per_hour: u32,
}

ReliabilityConfig — 可靠性配置

pub struct ReliabilityConfig {
    pub max_retries: u32,
    pub retry_delay_secs: u64,
    pub scheduler_poll_secs: u64,
    pub enable_fallback: bool,
    pub scheduler_retries: u32,
    pub provider_backoff_ms: u64,
    pub api_keys: Vec<String>,
}

环境变量覆盖

环境变量优先级高于配置文件：

环境变量	对应配置项
CLAWSEED_PROVIDER	默认提供商
CLAWSEED_MODEL	默认模型
CLAWSEED_API_KEY	API 密钥
CLAWSEED_PROVIDER_URL	提供商 URL
CLAWSEED_PROVIDER_TIMEOUT_SECS	提供商超时
CLAWSEED_GATEWAY_HOST	网关监听地址
CLAWSEED_GATEWAY_PORT	网关监听端口
CLAWSEED_WORKSPACE	工作目录
CLAWSEED_EXTRA_HEADERS	额外 HTTP 头（逗号分隔 key=value）
CLAWSEED_TEMPERATURE	采样温度
CLAWSEED_STORAGE_DB_URL	存储 DB URL
CLAWSEED_WEB_SEARCH_ENABLED	启用网页搜索
CLAWSEED_WEB_SEARCH_PROVIDER	网页搜索提供商
CLAWSEED_WEB_SEARCH_TAVILY_API_KEY	Tavily API 密钥
CLAWSEED_EMBEDDING_PROVIDER	记忆嵌入提供商
CLAWSEED_EMBEDDING_MODEL	记忆嵌入模型
CLAWSEED_EMBEDDING_API_KEY	第一条 embedding route 的 API 密钥
CLAWSEED_EMBEDDING_DIMENSIONS	记忆嵌入维度

配置示例

workspace_dir = "/home/user/workspace"

[providers]
fallback = "anthropic"

[providers.models.anthropic]
model = "claude-sonnet-4-20250514"
api_key = "${ANTHROPIC_API_KEY}"

[providers.models.groq]
model = "llama-3.1-8b"
api_key = "${GROQ_API_KEY}"

[agent]
max_tokens = 4096
max_tool_iterations = 25
allowed_tools = ["file_*", "memory_*", "shell"]
denied_tools = ["dangerous_tool"]

[agent.mcp_tool_filters]
my_mcp_server = ["search_*", "read_*"]

[gateway]
host = "0.0.0.0"
port = 3000

[memory]
backend = "sqlite"
auto_save = true

[user_model]
enabled = true
max_prompt_items = 20
auto_infer = false
inference_min_confidence = 0.8
max_inferred_items_per_turn = 3

[autonomy]
level = "supervised"
allowed_commands = ["ls", "cat", "grep", "find", "git"]
max_actions_per_hour = 100

[reliability]
max_retries = 2
provider_backoff_ms = 500

[identity]
format = "openclaw"
# format = "aieos"
# aieos_path = "identity.json"

[secrets]
encrypt = true

[hooks]
enabled = true

[[hooks.chain]]
type = "security_policy"

[[hooks.chain]]
type = "audit_log"
config = { level = "info" }

user_model.enabled 控制结构化本地用户画像。画像数据存储在 <workspace>/user_model/profiles.db；max_prompt_items 限制注入 Agent 系统提示中 处于 active 且未过期的条目数量。auto_infer 是默认关闭的选择加入开关；开启后， Agent 会在成功回合结束后以后台低温模型调用提取画像，不延迟主回复。系统只接受达到 inference_min_confidence 的非敏感条目，每轮最多写入 max_inferred_items_per_turn 条，且不会覆盖 explicit、imported 或 rejected 条目。

IdentityConfig — 身份配置

pub struct IdentityConfig {
    pub format: String,               // "openclaw"（默认）或 "aieos"
    pub aieos_path: Option<String>,   // AIEOS JSON 文件路径（相对于工作区）
    pub aieos_inline: Option<String>, // 内联 AIEOS JSON 字符串
}

OpenClaw 模式（默认）使用工作区目录中的 Markdown 文件（SOUL.md、IDENTITY.md 等）。AIEOS 模式使用结构化 JSON 身份。详见人格与身份教程。

密钥管理

• secrets.rs — 密钥加密/解密
• 配置文件中的 API 密钥支持 ${ENV_VAR} 语法引用环境变量，避免明文存储