Heuristic:Openclaw Openclaw Config Cascade Resolution
| Knowledge Sources | |
|---|---|
| Domains | Configuration, Architecture |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Configuration resolution pattern using a three-level cascade: function override, per-channel/per-agent setting, global config default, with a hardcoded fallback.
Description
OpenClaw resolves configuration values using a multi-level cascade pattern. For any configurable parameter, the resolution order is: (1) explicit function-call override, (2) per-channel or per-agent configuration, (3) global configuration value, (4) hardcoded default. This pattern is applied consistently across the codebase for ports, debounce times, retry counts, model selection, and feature flags. The cascade uses nullish coalescing (`??`) to fall through levels, ensuring that a `0` or `false` value at any level is respected rather than skipped.
Usage
Apply this heuristic when adding any new configurable parameter. Follow the cascade order: override > channel/agent-specific > global > default. Use nullish coalescing (`??`) instead of logical OR (`||`) to preserve intentional falsy values (0, false, empty string).
The Insight (Rule of Thumb)
- Action: Resolve config values as `override ?? channelSpecific ?? globalConfig ?? DEFAULT_VALUE`.
- Value: The `??` operator preserves 0, false, and empty string as valid values. The `||` operator would skip them.
- Trade-off: More configuration layers mean more complexity. Keep the cascade to 3-4 levels maximum.
- Validation: Use `resolveMs()` or `clampNumber()` helpers to validate and coerce values at each level before cascading.
Reasoning
The cascade pattern allows flexible configuration without requiring every deployment to specify every parameter. Per-channel overrides enable channel-specific behavior (e.g., longer debounce for Telegram, shorter for Discord) without affecting other channels. The nullish coalescing operator is critical: a debounce of 0ms (disable debouncing) must be distinguishable from "not configured" (use default).
Code Evidence from `src/auto-reply/inbound-debounce.ts:21-34`:
export function resolveInboundDebounceMs(params: {
cfg: OpenClawConfig;
channel: string;
overrideMs?: number;
}): number {
const inbound = params.cfg.messages?.inbound;
const override = resolveMs(params.overrideMs);
const byChannel = resolveChannelOverride({
byChannel: inbound?.byChannel,
channel: params.channel,
});
const base = resolveMs(inbound?.debounceMs);
return override ?? byChannel ?? base ?? 0;
}
Port resolution cascade from `src/config/paths.ts:236-254`:
export function resolveGatewayPort(cfg?, env?): number {
const envRaw = env.OPENCLAW_GATEWAY_PORT?.trim() || env.CLAWDBOT_GATEWAY_PORT?.trim();
if (envRaw) { /* env override */ return parsed; }
const configPort = cfg?.gateway?.port;
if (typeof configPort === "number") { /* config */ return configPort; }
return DEFAULT_GATEWAY_PORT; // hardcoded default
}