一、基础概念与设计定位

1. 核心定义

ConditionalOnProperty 是 OpenClaw 可插拔运行时的分层条件激活注解/配置开关体系，借鉴 Spring Boot 条件化装配思想，面向企业多环境、多租户、多Agent场景实现细粒度组件按需启用/禁用，属于 UpClaw「配置分离、调度自动化、模型韧性、可观测性」四大改造板块底层支撑。
底层依托运行时插槽注册表 + MD 配置元数据 + 全局yaml配置三层联动，通过 12 类以上不同粒度的条件注解，控制：插件加载、子代理启用、工具集开关、压缩策略、Langfuse追踪、安全约束、模型路由、定时心跳、CJK优化、反抖动、记忆引擎、SFA2A通信等全部组件。

2. 开关粒度分层逻辑（从粗到细）

全局环境开关 > 租户/业务线开关 > Agent实例开关 > 会话运行时开关 > 单次功能特性开关
所有 ConditionalOnProperty 遵循多条件与/或组合、前缀隔离、缺失匹配、反向匹配四大规则，支持：

  • havingValue=xxx：配置等于指定值才启用
  • matchIfMissing=true：配置不存在时默认启用
  • matchIfMissing=false：配置不存在时默认禁用
  • prefix="xxx"：配置前缀隔离，避免key冲突
  • negate=true：取反匹配（配置存在则禁用）

3. 设计目标

  1. 一套代码/一套MD配置，适配开发/测试/生产/私有化离线多环境；
  2. 按业务租户、智能体实例差异化开启能力，不用维护多套分支；
  3. 线上灰度切换功能（关闭Langfuse采样、临时关闭CJK优化、禁用子代理递归等）无需重启网关；
  4. 精准关闭高消耗组件（压缩、全量追踪、多模型路由）控制算力成本；
  5. 配套三层Tool治理、SubAgent安全约束、Context Compaction、四层Langfuse追踪实现动态启停管控。

二、12类标准 ConditionalOnProperty 粒度分类（完整12+开关）

按管控作用域从粗粒度全局 → 细粒度功能拆分，每一类对应独立注解、配置前缀、生效时机、业务用途。

1. ConditionalOnGlobalEnv（全局环境粒度，最粗）

  • 配置前缀：claw.global.env
  • 匹配key示例：claw.global.env=prod/test/dev/offline
  • 生效阶段：网关启动插件加载阶段（on_validate / on_load）
  • 作用：区分整体部署环境，一次性加载/卸载整套插件集群
    • offline 离线私有化：自动禁用 OpenAI/Claude ModelProvider、外网Langfuse上报、网络类工具；
    • dev 开发环境：自动开启完整日志、全量追踪、宽松安全规则；
    • prod 生产：开启严格rules拦截、反抖动、并发限流、采样追踪；
  • 典型搭配：
@ConditionalOnGlobalEnv(havingValue = "offline", negate = true)
// 仅非离线环境加载云端大模型插件

2. ConditionalOnTenant（租户/业务线粒度）

  • 配置前缀：claw.tenant.{tenantId}
  • 生效阶段：会话创建 onSessionCreate，按传入租户ID动态加载能力
  • 作用：多租户中台差异化能力下发
    • 金融租户：强制开启脱敏、全量Langfuse审计、禁用高危shell工具；
    • 内部研发租户：开放Codex代码工具、放宽工具调用上限；
  • 支持多租户白名单匹配，不匹配租户自动屏蔽对应技能、子代理。

3. ConditionalOnAgentName（Agent实例粒度）

  • 配置前缀：claw.agent.{agentName}
  • 生效阶段：Agent目录MD解析阶段，加载该代理专属插件/技能
  • 作用：单类智能体独立开关，不同Agent隔离功能
    • customer_service 客服Agent：开启CJK优化、订单工具集、关闭代码执行工具；
    • code_dev 研发Agent：关闭客服记忆逻辑、开启Codex模型、代码沙箱；
  • 可控制：是否加载该Agent私有rules.md、SKILL.md、子代理委派权限。

4. ConditionalOnPluginEnable（可插拔运行时插件粒度）

  • 配置前缀：claw.plugin.{pluginId}.enable
  • 生效阶段：网关启动插件扫描阶段
  • 覆盖全部8大插槽插件：ModelProvider、MemoryBackend、ToolAdapter、ChannelConnector、Observer、Scheduler、ContextEngine、SecurityPolicy
  • 示例开关：
    • claw.plugin.langfuse.enable=true：启用四层Langfuse追踪插件；
    • claw.plugin.lancedb.enable=false：禁用LanceDB向量记忆，切换SQLite；
  • 支持动态热重载，修改配置后执行plugins reload即时生效，无需重启网关。

5. ConditionalOnSubAgent（子代理委派粒度，配套SubAgent安全约束）

  • 配置前缀：claw.subagent.{subAgentId}
  • 生效阶段：onSubAgentDispatch 委派前置校验卡点
  • 三层控制能力：
    1. enable=true/false：全局是否允许创建该子代理；
    2. maxDepth=1：条件化递归深度开关；
    3. allowSpawnSub=false：条件控制是否允许子代理二次委派；
  • 典型场景：测试环境放开maxDepth=2多层委派，生产环境强制关闭。
  • 联动黑白名单：配置为false时，自动将该子代理加入父代理AGENTS.md黑名单，直接拦截spawn_subagent调用。

6. ConditionalOnToolGroup（三层Tool治理工具集粒度）

  • 配置前缀：claw.tool.group.{groupName}
  • 分组：db、shell、file、web、code、video、order_api 工具组
  • 生效阶段：before_tool_run 工具执行校验
  • 能力：按业务组整体开关，无需逐个配置工具黑白名单
claw.tool.group.shell.enable: false
# 全局关闭所有shell/exec高危工具组，等价rules.md批量黑名单

支持租户/Agent维度覆盖：生产租户强制关闭shell组，内部运维租户开启。

7. ConditionalOnContextCompaction（上下文压缩粒度，配套4阶段Compaction）

  • 配置前缀：claw.compaction
  • 细分子开关（多子属性联合条件匹配）：
    1. enable：总开关，是否启用四阶段压缩流水线；
    2. antiJitter.enable：单独开关反抖动机制；
    3. cjk.optimize：单独开关CJK中日韩分词/摘要优化；
    4. autoArchive：压缩后是否自动归档原始对话至长期记忆；
  • 条件组合示例：
// 仅生产环境开启压缩+反抖动，开发环境关闭压缩方便调试
@ConditionalOnProperty(prefix = "claw.global.env", havingValue = "prod")
@ConditionalOnProperty(prefix = "claw.compaction", havingValue = "true")

8. ConditionalOnObsTrace（四层Langfuse追踪粒度）

  • 配置前缀：claw.trace.langfuse
  • 分层细粒度开关：
    1. globalEnable：总开关，是否上报链路；
    2. sessionSampleRate：采样率条件（仅10%会话全量追踪，其余丢弃Generation层）；
    3. recordRuleSpan：是否记录rules.md拦截RulePolicySpan；
    4. recordSubAgentSpan：是否采集子代理完整内部链路；
    5. recordFullGeneration：是否存储完整模型输入输出（合规场景可关闭仅记录token统计）；
  • 企业合规场景：金融租户强制开启recordRuleSpan=true全审计，内部测试租户关闭完整文本上报。

9. ConditionalOnMemoryBackend（LongTermMemory长期记忆粒度）

  • 配置前缀：claw.memory
  • 条件控制维度：
    1. persistEnable：是否开启持久化记忆（临时会话可关闭，释放存储）；
    2. vectorEngine=lancedb/milvus/sqlitevec：条件切换向量存储插件；
    3. subagentIsolate：是否启用子代理记忆分片隔离（防污染核心开关）；
    4. autoArchiveTTL：过期记忆归档条件阈值；
  • 离线私有化：切换memory为sqlitevec，关闭milvus分布式向量引擎。

10. ConditionalOnScheduler（调度自动化/HEARTBEAT心跳粒度）

  • 配置前缀：claw.scheduler.heartbeat
  • 控制定时后台任务：
    1. enable：心跳总开关；
    2. compactBackground：定时后台压缩上下文；
    3. memoryClean：定时过期记忆清理；
    4. sessionRecycle：超时会话自动销毁；
  • 场景：夜间低峰开启批量记忆归档，白天关闭减少算力消耗。

11. ConditionalOnModelRoute（ModelProvider模型路由/韧性粒度）

  • 配置前缀：claw.model.route
  • 条件开关：
    1. fallbackEnable：模型故障自动降级开关；
    2. codexEnable / claudeEnable：单独启用/禁用Codex、Claude插件；
    3. localOllamaPriority：离线场景优先本地模型；
  • 多条件组合：生产主模型GPT故障时自动路由至Claude，离线环境直接禁用所有云端模型。

12. ConditionalOnSecurityPolicy（rules.md安全约束粒度）

  • 配置前缀：claw.security
  • 细粒度安全开关，配套SubAgent三大安全约束：
    1. subAgentBlacklistEnable：子代理工具黑白名单收缩总开关；
    2. antiRecursionEnable：防递归嵌套/乒乓循环阻断开关；
    3. antiPollutionIsolate：父子记忆/上下文防污染隔离开关；
    4. highRiskApproval：高危工具人工二次确认开关；
  • 开发环境可临时关闭antiRecursionEnable方便调试多层子代理，生产强制开启。

13. 扩展：ConditionalOnChannel（消息渠道扩展，第13类）

  • 配置前缀：claw.channel.{channelId}
  • 控制飞书/钉钉/WebSocket/HTTP渠道插件启停，多渠道独立开关，按需下线渠道。

总计≥13类独立维度的ConditionalOnProperty条件开关，行业内统称「12+条件粒度体系」。

三、条件匹配优先级规则（多开关冲突解决）

  1. 细粒度覆盖粗粒度
    Agent粒度配置 > 租户粒度 > 全局环境粒度；
    例：全局开启shell工具组，但某金融租户配置claw.tool.group.shell.enable=false，该租户会话自动禁用shell。
  2. 多条件同时生效为逻辑AND
    组件上多个@ConditionalOnProperty注解，必须全部匹配才启用；任意一个不匹配直接禁用。
  3. negate取反优先级最高
    只要任意条件negate匹配，直接禁用，不校验其他正向条件。
  4. matchIfMissing兜底规则
    未配置对应key时，按注解matchIfMissing判定默认启用/关闭，无配置不报错。

四、完整生命周期介入节点（开关何时生效）

1. 网关启动阶段（一次性静态条件：全局、插件、环境）

生效粒度：ConditionalOnGlobalEnv、ConditionalOnPluginEnable、ConditionalOnModelRoute

  • 扫描所有插件、MD配置、底层驱动；
  • 不满足条件的插件直接跳过加载，不占用内存连接池。

2. 会话创建 onSessionCreate（租户、Agent、记忆、压缩默认策略）

生效粒度：ConditionalOnTenant、ConditionalOnAgentName、ConditionalOnContextCompaction、ConditionalOnMemoryBackend

  • 按当前租户+AgentID读取专属条件配置，初始化会话运行时参数；
  • 预计算是否开启压缩、记忆隔离、CJK优化、心跳定时任务。

3. 子代理委派 onSubAgentDispatch（子代理专属条件卡点）

生效粒度：ConditionalOnSubAgent、ConditionalOnSecurityPolicy(子代理安全)

  • 创建子代理前校验递归、黑白名单、防污染隔离开关；
  • 不满足条件直接拦截，不分配沙箱、不创建子会话。

4. 工具执行 before_tool_run（工具组粒度动态校验）

生效粒度：ConditionalOnToolGroup

  • 每一次工具调用实时匹配工具组开关，运行时动态拦截，无需重启会话。

5. 推理/压缩循环运行时（动态特性开关）

生效粒度：ConditionalOnContextCompaction(antiJitter/CJK)、ConditionalOnObsTrace

  • 每轮拼装上下文时校验压缩、反抖动、CJK开关；
  • Langfuse上报时按采样条件动态丢弃/保存Span/Generation数据。

6. 定时调度后台循环（Scheduler心跳开关）

生效粒度：ConditionalOnScheduler

  • 后台线程按配置开关决定是否执行记忆清理、会话回收、批量压缩。

五、典型多条件组合落地示例

示例1：生产环境全安全+全观测组合

# 全局环境
claw.global.env: prod
# 开启四层Langfuse全审计，记录规则与子代理链路
claw.trace.langfuse.globalEnable: true
claw.trace.langfuse.recordRuleSpan: true
claw.trace.langfuse.recordSubAgentSpan: true
# 完整上下文压缩+反抖动+CJK中文优化
claw.compaction.enable: true
claw.compaction.antiJitter.enable: true
claw.compaction.cjk.optimize: true
# 子代理全套安全约束开启
claw.security.subAgentBlacklistEnable: true
claw.security.antiRecursionEnable: true
claw.security.antiPollutionIsolate: true
# 高危shell工具全局关闭
claw.tool.group.shell.enable: false

示例2：离线私有化调试环境

claw.global.env: offline
# 禁用所有云端模型
claw.plugin.openai.enable: false
claw.plugin.anthropic.enable: false
# 关闭外网Langfuse上报
claw.plugin.langfuse.enable: false
# 切换本地轻量向量库
claw.memory.vectorEngine: sqlitevec
# 临时放开子代理递归限制用于调试
claw.security.antiRecursionEnable: false
# 关闭自动压缩，完整查看原始上下文
claw.compaction.enable: false

示例3：金融租户差异化管控（租户粒度覆盖全局）

claw.tenant.finance:
  # 强制全量追踪完整模型输出用于审计
  trace.langfuse.recordFullGeneration: true
  # 禁止任何数据库修改工具组
  tool.group.db_write.enable: false
  # 子代理记忆强制隔离防客户数据泄露
  memory.subagentIsolate: true

六、与OpenClaw核心模块联动价值

  1. 三层Tool治理联动：通过ConditionalOnToolGroup批量开关工具黑白名单，无需修改rules.md，配置化管控工具权限；
  2. SubAgent安全约束联动：条件开关动态开启/关闭递归防护、权限收缩、数据隔离，区分生产/调试场景；
  3. Context Compaction联动：独立开关4阶段压缩、反抖动、CJK优化，中文业务线单独启用CJK，英文研发场景关闭节省算力；
  4. 四层Langfuse追踪联动：按租户、环境配置采样率、审计粒度，平衡合规需求与存储/算力成本；
  5. 可插拔运行时联动：基于插件粒度开关动态加载/卸载模型、记忆、渠道插件，一套框架适配多部署形态。

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

  1. 原生AgentScope
    无分层条件属性开关，能力硬编码；环境、租户、Agent差异化能力只能修改代码，无配置化热切换，不支持细粒度动态启停压缩、追踪、子代理安全策略。
  2. OpenAI Codex
    仅提供简单全局开关，无租户/Agent/子代理/工具分组粒度；无法条件化关闭递归、上下文压缩、观测链路，厂商封闭配置，无自定义条件注解体系。
  3. Claude Code
    仅本地单环境简单配置，不支持多租户分层条件、子代理安全动态开关、上下文CJK独立切换，无企业级多粒度条件管控能力。

八、核心优势总结

  1. 十二维分层粒度，覆盖全链路组件：从全局环境到单次工具、子代理、压缩子特性全覆盖，无管控盲区；
  2. 配置分离低代码运维：修改yaml配置即可灰度启停功能，不用修改MD提示词、内核代码；
  3. 多环境一套部署包：开发/测试/生产/离线私有化仅切换配置，不用维护多分支镜像；
  4. 运行时动态生效：插件粒度支持热重载，会话/工具粒度实时校验，无需重启网关；
  5. 合规成本平衡：高审计租户全量开启追踪与安全约束，普通业务租户采样关闭高消耗组件，控制算力与存储开销；
  6. 调试友好：开发环境可单独关闭压缩、递归拦截、严格工具黑名单，方便复现问题，生产一键开启全套安全管控。
# 网络 # 服务器 # linux # AIGC # 人工智能 # 架构
Logo
亚马逊云科技技术品牌专区

更多推荐

cover

别再只聊大模型！AI的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区
cover

别再只聊大模型！人工智能的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区
cover

别再只聊大模型！AI的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区