一、整体定位配置分层体系属于 UpClaw「配置分离」改造板块底层基础设施为前文全部能力可插拔运行时、ConditionalOnProperty、三层Tool治理、Cron安全、并发安全、提示词六层MD、沙箱策略等提供统一配置加载、优先级覆盖、环境变量注入底座。核心目标一套程序镜像支持开发/测试/生产/离线私有化多环境部署不修改代码、不修改基础配置支持租户、Agent、全局三级差异化策略覆盖原生支持环境变量${VAR:default}插值适配容器、K8s、云原生标准实践配置变更支持热重载部分层级无需重启网关清晰优先级规则避免多层配置互相冲突难以排查。OpenClaw 配置三层分层定义优先级从低 → 高高层覆盖低层同名KeyLayer1内置基准配置Base DefaultLayer2全局静态配置文件global.yamlLayer3运行时动态配置环境变量 租户/Agent独立配置 命令行参数优先级排序越靠后优先级越高内置基准配置 global.yaml Agent独立yaml 租户配置 命令行参数 OS环境变量二、三层配置分层详细拆解Layer 1内置基准配置Base Default最低优先级承载形式代码内硬编码默认值、内置默认yaml资源文件打包进程序二进制/镜像内部。生效时机网关初始化最先加载所有配置缺失时的兜底基线。包含内容全部能力出厂默认参数沙箱默认超时、Context Compaction 默认阈值SessionLock 默认模式排队模式、锁超时时间Langfuse 默认采样率子代理最大嵌套深度maxSubAgentDepth1四层追踪默认开关、Cron默认调度参数所有ConditionalOnProperty默认值关键特征不可直接修改只能被上层配置覆盖用于保证程序开箱可用即使外部不提供任何配置文件也能正常启动基准配置全部写入文档便于运维知晓出厂基线热重载无法修改本层只能修改上层。示例基准默认claw.compaction.enable:trueclaw.session.lock.mode:queueclaw.subagent.maxDepth:1claw.tool.sandbox.timeout:30sLayer 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:10Layer 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.xxxvalue优先级高于所有yaml文件。适合容器临时覆盖、应急调试。./openclaw--claw.compaction.enablefalse3.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.yamlagent.yamltenant.yaml⚠️ MD提示文件rules.md / SOUL.md等默认不启用变量插值如需在MD内启用变量需要显式开启claw.md.interpolate.enabletrue。和云原生适配价值私有化离线部署、K8s场景配置文件可以固化镜像内密钥、地址全部通过环境变量注入同一套镜像开发、测试、生产仅需要注入不同环境变量无需修改yaml密钥不在静态配置文件明文存储符合安全规范。四、完整合并执行时序网关启动流程Step1 加载 Layer1内置基准默认配置 Step2 加载 Layer2global.yaml同名key覆盖基准 Step3 扫描所有Agent目录加载 agent.yaml覆盖上层 Step4 扫描租户配置 tenant.yaml覆盖上层 Step5 解析命令行启动参数覆盖所有yaml配置 Step6 读取OS环境变量覆盖所有配置最高优先级 Step7 全局执行 ${VAR:default} 变量插值渲染 Step8 配置校验检查必填项、参数范围、插件依赖约束 Step9 完成配置合并供给所有模块使用热重载流程claw config reload重新加载 global.yaml / agent.yaml / tenant.yaml再次执行变量插值触发ConditionalOnProperty条件组件重新装配插件启用/禁用、参数刷新注意环境变量不会在热重载阶段重新读取环境变量仅网关启动时读取一次。五、与核心体系联动关系1. 联动 12 ConditionalOnPropertyConditionalOnProperty读取合并后的最终配置视图三层分层决定条件判断最终取值。典型场景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写入当前生效关键配置快照便于问题排查。六、冲突排查原则运维标准流程当参数预期和实际行为不一致时遵循排查步骤查询最终合并后的生效配置视图内置命令claw config dump在dump结果中找到目标key查看元标签source[base/global/agent/tenant/cmd/env]显示该值来自哪一层根据三层优先级定位是上层配置覆盖导致预期不符。七、优缺点总结优势环境治理标准化一套镜像多环境交付符合容器云原生规范分层权责清晰全局统一基线 业务Agent个性化覆盖 租户差异化管控${VAR:default}原生支持密钥外部注入静态配置不存放敏感凭证支持配置热重载变更策略无需重启网关统一配置源所有组件沙箱、调度、观测、安全规则共用同一套加载引擎。短板环境变量仅启动时加载运行时修改OS环境变量不会自动生效MD文件默认不支持变量插值如需动态参数传入提示词需要显式开启并注意安全注入风险多层叠加复杂后运维人员需要清晰记忆优先级顺序否则容易出现配置覆盖预期之外。八、对比原生AgentScope / Codex / Claude Code原生 AgentScope大多硬编码默认值 单层配置文件没有Agent/租户分层无标准化环境变量插值体系缺少热重载能力。OpenAI Codex配置完全云端厂商管控用户无分层配置能力不支持本地配置文件、环境变量注入。Claude Code本地单用户单层配置不存在多租户、多Agent分层模型无企业级分层覆盖机制。OpenClaw三层配置架构面向多租户AI中台设计内置完整优先级覆盖模型原生支持云原生变量插值作为整套企业能力统一配置底座。九、生产落地最佳实践安全规范API Key、数据库密钥、凭证一律使用${VAR:}无默认语法通过环境变量注入禁止写入yaml基线治理全局global.yaml定义生产安全底线默认关闭高危工具、收紧子代理权限差异化策略下沉业务专属参数放到对应agent.yaml不要污染global.yaml离线私有化部署利用环境变量切换模型插件、关闭外网相关组件尽量避免多层反复覆盖多层覆盖过多会增加故障排查成本重要安全类参数沙箱、子代理递归开关建议在global.yaml锁定禁止低层租户随意覆盖支持配置锁readonly:true防止下层覆盖。
OpenClaw 配置分层：三层架构 + ${VAR:default} 变量解析完整详解
一、整体定位配置分层体系属于 UpClaw「配置分离」改造板块底层基础设施为前文全部能力可插拔运行时、ConditionalOnProperty、三层Tool治理、Cron安全、并发安全、提示词六层MD、沙箱策略等提供统一配置加载、优先级覆盖、环境变量注入底座。核心目标一套程序镜像支持开发/测试/生产/离线私有化多环境部署不修改代码、不修改基础配置支持租户、Agent、全局三级差异化策略覆盖原生支持环境变量${VAR:default}插值适配容器、K8s、云原生标准实践配置变更支持热重载部分层级无需重启网关清晰优先级规则避免多层配置互相冲突难以排查。OpenClaw 配置三层分层定义优先级从低 → 高高层覆盖低层同名KeyLayer1内置基准配置Base DefaultLayer2全局静态配置文件global.yamlLayer3运行时动态配置环境变量 租户/Agent独立配置 命令行参数优先级排序越靠后优先级越高内置基准配置 global.yaml Agent独立yaml 租户配置 命令行参数 OS环境变量二、三层配置分层详细拆解Layer 1内置基准配置Base Default最低优先级承载形式代码内硬编码默认值、内置默认yaml资源文件打包进程序二进制/镜像内部。生效时机网关初始化最先加载所有配置缺失时的兜底基线。包含内容全部能力出厂默认参数沙箱默认超时、Context Compaction 默认阈值SessionLock 默认模式排队模式、锁超时时间Langfuse 默认采样率子代理最大嵌套深度maxSubAgentDepth1四层追踪默认开关、Cron默认调度参数所有ConditionalOnProperty默认值关键特征不可直接修改只能被上层配置覆盖用于保证程序开箱可用即使外部不提供任何配置文件也能正常启动基准配置全部写入文档便于运维知晓出厂基线热重载无法修改本层只能修改上层。示例基准默认claw.compaction.enable:trueclaw.session.lock.mode:queueclaw.subagent.maxDepth:1claw.tool.sandbox.timeout:30sLayer 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:10Layer 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.xxxvalue优先级高于所有yaml文件。适合容器临时覆盖、应急调试。./openclaw--claw.compaction.enablefalse3.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.yamlagent.yamltenant.yaml⚠️ MD提示文件rules.md / SOUL.md等默认不启用变量插值如需在MD内启用变量需要显式开启claw.md.interpolate.enabletrue。和云原生适配价值私有化离线部署、K8s场景配置文件可以固化镜像内密钥、地址全部通过环境变量注入同一套镜像开发、测试、生产仅需要注入不同环境变量无需修改yaml密钥不在静态配置文件明文存储符合安全规范。四、完整合并执行时序网关启动流程Step1 加载 Layer1内置基准默认配置 Step2 加载 Layer2global.yaml同名key覆盖基准 Step3 扫描所有Agent目录加载 agent.yaml覆盖上层 Step4 扫描租户配置 tenant.yaml覆盖上层 Step5 解析命令行启动参数覆盖所有yaml配置 Step6 读取OS环境变量覆盖所有配置最高优先级 Step7 全局执行 ${VAR:default} 变量插值渲染 Step8 配置校验检查必填项、参数范围、插件依赖约束 Step9 完成配置合并供给所有模块使用热重载流程claw config reload重新加载 global.yaml / agent.yaml / tenant.yaml再次执行变量插值触发ConditionalOnProperty条件组件重新装配插件启用/禁用、参数刷新注意环境变量不会在热重载阶段重新读取环境变量仅网关启动时读取一次。五、与核心体系联动关系1. 联动 12 ConditionalOnPropertyConditionalOnProperty读取合并后的最终配置视图三层分层决定条件判断最终取值。典型场景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写入当前生效关键配置快照便于问题排查。六、冲突排查原则运维标准流程当参数预期和实际行为不一致时遵循排查步骤查询最终合并后的生效配置视图内置命令claw config dump在dump结果中找到目标key查看元标签source[base/global/agent/tenant/cmd/env]显示该值来自哪一层根据三层优先级定位是上层配置覆盖导致预期不符。七、优缺点总结优势环境治理标准化一套镜像多环境交付符合容器云原生规范分层权责清晰全局统一基线 业务Agent个性化覆盖 租户差异化管控${VAR:default}原生支持密钥外部注入静态配置不存放敏感凭证支持配置热重载变更策略无需重启网关统一配置源所有组件沙箱、调度、观测、安全规则共用同一套加载引擎。短板环境变量仅启动时加载运行时修改OS环境变量不会自动生效MD文件默认不支持变量插值如需动态参数传入提示词需要显式开启并注意安全注入风险多层叠加复杂后运维人员需要清晰记忆优先级顺序否则容易出现配置覆盖预期之外。八、对比原生AgentScope / Codex / Claude Code原生 AgentScope大多硬编码默认值 单层配置文件没有Agent/租户分层无标准化环境变量插值体系缺少热重载能力。OpenAI Codex配置完全云端厂商管控用户无分层配置能力不支持本地配置文件、环境变量注入。Claude Code本地单用户单层配置不存在多租户、多Agent分层模型无企业级分层覆盖机制。OpenClaw三层配置架构面向多租户AI中台设计内置完整优先级覆盖模型原生支持云原生变量插值作为整套企业能力统一配置底座。九、生产落地最佳实践安全规范API Key、数据库密钥、凭证一律使用${VAR:}无默认语法通过环境变量注入禁止写入yaml基线治理全局global.yaml定义生产安全底线默认关闭高危工具、收紧子代理权限差异化策略下沉业务专属参数放到对应agent.yaml不要污染global.yaml离线私有化部署利用环境变量切换模型插件、关闭外网相关组件尽量避免多层反复覆盖多层覆盖过多会增加故障排查成本重要安全类参数沙箱、子代理递归开关建议在global.yaml锁定禁止低层租户随意覆盖支持配置锁readonly:true防止下层覆盖。
