OpenClaw 配置分层：三层架构 + ${VAR:default} 变量解析完整详解-拓冰建站

一、整体定位

配置分层体系属于 UpClaw「配置分离」改造板块底层基础设施，为前文全部能力（可插拔运行时、ConditionalOnProperty、三层Tool治理、Cron安全、并发安全、提示词六层MD、沙箱策略等）提供统一配置加载、优先级覆盖、环境变量注入底座。
核心目标：

一套程序镜像，支持开发/测试/生产/离线私有化多环境部署，不修改代码、不修改基础配置；
支持租户、Agent、全局三级差异化策略覆盖；
原生支持环境变量${VAR:default}插值，适配容器、K8s、云原生标准实践；
配置变更支持热重载，部分层级无需重启网关；
清晰优先级规则，避免多层配置互相冲突难以排查。

OpenClaw 配置三层分层定义（优先级从低 → 高；高层覆盖低层同名Key）

Layer1：内置基准配置（Base Default）
Layer2：全局静态配置文件（global.yaml）
Layer3：运行时动态配置（环境变量 + 租户/Agent独立配置 + 命令行参数）

优先级排序（越靠后优先级越高）：
内置基准配置 < global.yaml < Agent独立yaml < 租户配置 < 命令行参数 < OS环境变量

二、三层配置分层详细拆解

Layer 1｜内置基准配置（Base Default，最低优先级）

承载形式

代码内硬编码默认值、内置默认yaml资源文件（打包进程序二进制/镜像内部）。

生效时机

网关初始化最先加载；所有配置缺失时的兜底基线。

包含内容

全部能力出厂默认参数：

沙箱默认超时、Context Compaction 默认阈值
SessionLock 默认模式（排队模式）、锁超时时间
Langfuse 默认采样率
子代理最大嵌套深度maxSubAgentDepth=1
四层追踪默认开关、Cron默认调度参数
所有ConditionalOnProperty默认值

关键特征

不可直接修改；只能被上层配置覆盖；
用于保证程序开箱可用，即使外部不提供任何配置文件也能正常启动；
基准配置全部写入文档，便于运维知晓出厂基线；
热重载无法修改本层，只能修改上层。

示例基准默认：

claw.compaction.enable:trueclaw.session.lock.mode:queueclaw.subagent.maxDepth:1claw.tool.sandbox.timeout:30s

Layer 2｜全局静态配置 global.yaml（中间优先级）

承载形式

文件路径可通过启动参数指定，默认路径./config/global.yaml

生效时机

网关启动加载；支持claw config reload global热重载。

定位

集群网关共享的统一基线，适用于整个部署实例所有会话通用策略。
适合配置：

插件开关（Langfuse、LanceDB、各Channel插件）
全局安全基线：全局工具黑名单、沙箱基础策略
全局模型路由、并发池大小、最大并发子代理数量
全局Cron调度基础参数
全局rules.md引用路径

覆盖规则

同名Key直接覆盖 Layer1 内置基准；
不填写的Key，沿用下层基准默认值。

# global.yaml 示例claw.plugin.langfuse.enable:trueclaw.plugin.langfuse.baseUrl:"${LANGFUSE_URL:http://langfuse:3000}"claw.tool.group.shell.enable:falseclaw.scheduler.maxConcurrentCronJobs:10

Layer 3｜运行时动态配置层（最高优先级，多层子集）

Layer3 内部又细分多个子层级，子层级之间继续遵循覆盖规则：

Agent独立配置 < 租户配置 < 启动命令行参数 < OS环境变量

3.1 Agent独立配置`agent.yaml`

路径规范：./agents/{agentName}/agent.yaml
作用：针对单个智能体差异化配置，对应ConditionalOnAgentName。
典型配置：

当前Agent是否启用matplotlib技能
Agent专属上下文压缩阈值
Agent自适应推理档位区间
Agent专属工具白名单、子代理允许列表
是否启用CJK优化

3.2 租户配置 tenant.yaml

多租户中台场景启用：./tenants/{tenantId}/tenant.yaml
对应ConditionalOnTenant；可以覆盖全局、Agent配置。
典型场景：金融租户强制开启全量审计、禁止高危工具组。

3.3 命令行启动参数

启动时--claw.xxx=value，优先级高于所有yaml文件。
适合容器临时覆盖、应急调试。

./openclaw--claw.compaction.enable=false

3.4 OS环境变量（最高优先级）

云原生、K8s首选；环境变量命名规则：
配置key中.替换为_，全部大写
例：
claw.plugin.langfuse.enable→CLAW_PLUGIN_LANGFUSE_ENABLE
环境变量可以直接在任意yaml中配合${VAR:default}插值使用。

三、变量插值语法：${VAR:default} 规范

完整语法定义

${ENV_VAR_NAME:fallback_value}

ENV_VAR_NAME：操作系统环境变量名
:后面fallback_value：环境变量不存在 / 为空时使用的默认值
支持嵌套、字符串、数字、布尔、空值
插值解析时机：配置加载阶段实时渲染

解析规则

插值在三层配置加载合并之后统一执行；
先读取真实环境变量；变量存在且非空 → 使用变量值；
变量不存在/为空字符串 → 使用冒号后的默认值；
如果写成${VAR}不带默认：变量缺失则启动报错（强制必填）；
支持转义\${VAR}，原样输出不解析；
布尔、数字自动类型转换；默认值支持字符串"true"、数字、空字符串""。

使用示例

# 有兜底默认claw.model.openai.apiKey:"${OPENAI_API_KEY:}"claw.plugin.langfuse.baseUrl:"${LANGFUSE_URL:http://127.0.0.1:3000}"claw.compaction.softTrimRatio:"${COMPACTION_SOFT_RATIO:0.7}"# 无默认值，缺失直接启动失败（必填参数）claw.tenant.master.key:"${MASTER_TENANT_KEY}"

插值生效范围

所有层级yaml全部支持插值：

global.yaml
agent.yaml
tenant.yaml

⚠️ MD提示文件（rules.md / SOUL.md等）默认不启用变量插值；如需在MD内启用变量，需要显式开启claw.md.interpolate.enable=true。

和云原生适配价值

私有化离线部署、K8s场景：

配置文件可以固化镜像内，密钥、地址全部通过环境变量注入；
同一套镜像，开发、测试、生产仅需要注入不同环境变量，无需修改yaml；
密钥不在静态配置文件明文存储，符合安全规范。

四、完整合并执行时序（网关启动流程）

Step1 加载 Layer1：内置基准默认配置 Step2 加载 Layer2：global.yaml，同名key覆盖基准 Step3 扫描所有Agent目录，加载 agent.yaml，覆盖上层 Step4 扫描租户配置 tenant.yaml，覆盖上层 Step5 解析命令行启动参数，覆盖所有yaml配置 Step6 读取OS环境变量，覆盖所有配置（最高优先级） Step7 全局执行 ${VAR:default} 变量插值渲染 Step8 配置校验：检查必填项、参数范围、插件依赖约束 Step9 完成配置合并，供给所有模块使用