配置系统

OpenClaw 的配置系统支持多层配置、文件监听和热加载策略，让 Gateway 在大部分情况下无需重启即可应用新配置。

配置加载

Source: src/config/config.ts

配置从 ~/.openclaw/openclaw.json 加载，经过校验和规范化后供各模块使用：

// src/config/config.ts (simplified)
function loadConfig(): OpenClawConfig {
  // 1. Read ~/.openclaw/openclaw.json
  // 2. Validate schema via Zod
  // 3. Apply defaults
  // 4. Normalize values
}

配置文件结构

{
  "gateway": {
    "port": 18789,
    "auth": { "mode": "token", "token": "..." }
  },
  "models": {
    "default": "claude-sonnet-4-5-20250929",
    "profiles": { /* ... */ }
  },
  "channels": {
    "telegram": { "token": "...", "allowFrom": [...] },
    "discord": { "token": "...", "guildId": "..." },
    "whatsapp": { /* ... */ }
  },
  "plugins": { /* ... */ },
  "hooks": { /* ... */ },
  "cron": { /* ... */ }
}

热加载机制

Source: src/gateway/config-reload.ts

Gateway 使用 chokidar 监听配置文件变化，并根据预定义规则决定如何处理变更：

重载计划

// src/gateway/config-reload.ts (simplified)
interface GatewayReloadPlan {
  restartGateway: boolean;    // Need full restart?
  hotReasons: string[];       // Hot-reloadable changes
  noopPaths: string[];        // Ignored changes
}

function getGatewayReloadPlan(
  changedPaths: string[]
): GatewayReloadPlan {
  // Analyze each changed file against reload rules
}

重载规则

每个配置路径对应一个重载规则：

配置类别	重载类型	说明
插件配置	restart	需要重新加载插件 registry
Gateway 核心配置	restart	端口、认证等核心参数变更
Hooks 配置	hot	运行时重新注册 hooks
Cron 配置	hot	运行时重新调度定时任务
浏览器配置	hot	重新初始化浏览器 profile
通道配置	hot	按通道重新加载
身份配置	none	下次会话生效
向导配置	none	仅初始化时使用
日志配置	none	需手动重启
模型配置	none	会话级别生效

通道级重载规则

不同通道的重载规则不同：

// src/gateway/config-reload.ts (simplified)
// Channel-specific reload rules
const channelReloadRules = {
  telegram: "hot",     // Can hot-reload (reconnect bot)
  whatsapp: "restart", // Needs full restart (Baileys session)
  discord: "hot",      // Can hot-reload (reconnect client)
  slack: "hot",        // Can hot-reload
  signal: "restart",   // Needs restart (signal-cli process)
};

去抖机制

// src/gateway/config-reload.ts (simplified)
// Debounce 300ms to batch rapid changes
const RELOAD_DEBOUNCE_MS = 300;

当用户快速编辑配置文件时（如保存多次），去抖机制会将 300ms 内的所有变更合并成一次重载操作。

运行时配置

Source: src/gateway/server-runtime-config.ts

除了文件配置，Gateway 还维护运行时配置状态：

// src/gateway/server-runtime-config.ts (simplified)
interface RuntimeConfig {
  // Dynamic configuration that can be patched at runtime
  // Without writing to disk
}

运行时配置通过 config.patch WebSocket 方法修改，变更立即生效但不持久化到文件。

配置校验

配置使用 Zod schema 进行校验，确保类型安全：

// Configuration validation
// Each section has its own Zod schema
// Invalid configs are rejected with descriptive error messages

重载 Handler

Source: src/gateway/server-reload-handlers.ts

热加载由专门的 reload handler 处理：

// src/gateway/server-reload-handlers.ts (simplified)
// Each hot-reloadable section has a handler:
// - reloadHooks(): Re-register all hooks
// - reloadCron(): Re-schedule all cron jobs
// - reloadChannels(): Reconnect affected channels
// - reloadBrowser(): Reinitialize browser profiles

小结

• 配置从 ~/.openclaw/openclaw.json 加载，使用 Zod 校验
• chokidar 监听文件变化，300ms 去抖 合并快速变更
• 三种重载策略：restart（完全重启）、hot（热加载）、none（忽略）
• Hooks、Cron、浏览器、部分通道支持热加载
• 插件和 Gateway 核心配置需要完全重启
• 运行时配置通过 config.patch 方法修改，立即生效但不持久化

下一章：Channels 概述