一、整体定位

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

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

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

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

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

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

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

承载形式

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

生效时机

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

包含内容

全部能力出厂默认参数：

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

关键特征

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

示例基准默认：

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：环境变量不存在 / 为空时使用的默认值
• 支持嵌套、字符串、数字、布尔、空值
• 插值解析时机：配置加载阶段实时渲染

解析规则

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

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

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

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

热重载流程（claw config reload）

1. 重新加载 global.yaml / agent.yaml / tenant.yaml
2. 再次执行变量插值
3. 触发ConditionalOnProperty条件组件重新装配（插件启用/禁用、参数刷新）
4. 注意：环境变量不会在热重载阶段重新读取！环境变量仅网关启动时读取一次。

五、与核心体系联动关系

1. 联动 12+ ConditionalOnProperty

ConditionalOnProperty读取合并后的最终配置视图；三层分层决定条件判断最终取值。
典型场景：

• global.yaml 默认关闭shell工具；
• 运维租户 tenant.yaml 覆盖开启shell；
  最终ConditionalOnTenant判断生效。

2. 联动 可插拔运行时插件

插件启用开关claw.plugin.xxx.enable遵循三层优先级；
热重载配置后，插件自动加载/卸载（遵循插件热插拔规范）。

3. 联动 SubAgent 安全约束、Cron安全约束

子代理最大深度、防递归开关、Cron最大并发等参数全部走三层配置；
生产环境global.yaml收紧基线；内部运维租户配置适度放开。

4. 联动 Context Compaction、深度推理自适应

压缩阈值、反抖动参数、自适应档位区间支持Agent独立配置覆盖全局基线。

5. 联动四层Langfuse观测

所有配置最终生效值可以通过观测接口输出；可在LangfuseSessionSpan写入当前生效关键配置快照，便于问题排查。

六、冲突排查原则（运维标准流程）

当参数预期和实际行为不一致时，遵循排查步骤：

1. 查询最终合并后的生效配置视图（内置命令：claw config dump）；
2. 在dump结果中找到目标key；
3. 查看元标签source=[base/global/agent/tenant/cmd/env]，显示该值来自哪一层；
4. 根据三层优先级定位是上层配置覆盖导致预期不符。

七、优缺点总结

优势

1. 环境治理标准化，一套镜像多环境交付，符合容器云原生规范；
2. 分层权责清晰：全局统一基线 + 业务Agent个性化覆盖 + 租户差异化管控；
3. ${VAR:default}原生支持密钥外部注入，静态配置不存放敏感凭证；
4. 支持配置热重载，变更策略无需重启网关；
5. 统一配置源，所有组件（沙箱、调度、观测、安全规则）共用同一套加载引擎。

短板

1. 环境变量仅启动时加载，运行时修改OS环境变量不会自动生效；
2. MD文件默认不支持变量插值，如需动态参数传入提示词需要显式开启并注意安全注入风险；
3. 多层叠加复杂后，运维人员需要清晰记忆优先级顺序，否则容易出现配置覆盖预期之外。

八、对比原生AgentScope / Codex / Claude Code

1. 原生 AgentScope
   大多硬编码默认值 + 单层配置文件；没有Agent/租户分层；无标准化环境变量插值体系；缺少热重载能力。
2. OpenAI Codex
   配置完全云端厂商管控，用户无分层配置能力，不支持本地配置文件、环境变量注入。
3. Claude Code
   本地单用户单层配置，不存在多租户、多Agent分层模型，无企业级分层覆盖机制。
4. OpenClaw三层配置架构
   面向多租户AI中台设计，内置完整优先级覆盖模型，原生支持云原生变量插值，作为整套企业能力统一配置底座。

九、生产落地最佳实践

1. 安全规范：API Key、数据库密钥、凭证一律使用${VAR:}无默认语法，通过环境变量注入，禁止写入yaml；
2. 基线治理：全局global.yaml定义生产安全底线（默认关闭高危工具、收紧子代理权限）；
3. 差异化策略下沉：业务专属参数放到对应agent.yaml，不要污染global.yaml；
4. 离线私有化部署：利用环境变量切换模型插件、关闭外网相关组件；
5. 尽量避免多层反复覆盖；多层覆盖过多会增加故障排查成本；
6. 重要安全类参数（沙箱、子代理递归开关）建议在global.yaml锁定，禁止低层租户随意覆盖（支持配置锁：readonly:true防止下层覆盖）。