跳转至

实验性功能

实验性功能是由配置标志控制的预览功能面。在它们的形态和行为成为长期契约之前,还需要更多真实环境中的使用经验。

  • 除非功能文档另有说明,否则默认关闭。
  • 其形态和行为可能比稳定配置变化更快。
  • 如果已存在稳定路径,请优先使用稳定路径。
  • 先在较小环境中测试,再广泛推出。

所有插件 API 也都是实验性的。 该稳定性标签不要求普通插件使用 Labs 开关;下面的 Custom plugin UI 标志仅控制用户安装的原生浏览器代码。

当前已记录的标志

功能面 键 适用场景 更多
Codex harness plugins.entries.codex.config.appServer.experimental.sandboxExecServer 希望原生 Codex app-server 0.143.0 或更高版本指向由 OpenClaw 沙箱支持的 exec-server,而不是禁用 Code Mode Codex harness 参考
Code Mode tools.codeMode.enabled 希望对隐藏的 OpenClaw 工具目录进行紧凑的代码编排访问 Code Mode
Cloud workers cloudWorkers.desktop 希望从 Control UI 监视或控制具备桌面能力的云 worker 环境 Cloud Worker Desktop
Custom plugin UI gateway.controlUi.experimental.customPlugins 希望受信任的用户安装插件添加原生 Control UI 视图或替换内置视图 功能插件
Host Desktop desktop.host.enabled 希望通过其 VNC 或 Screen Sharing 服务器监视或控制 Gateway 主机 桌面
Tool Search tools.toolSearch.enabled 希望控制全局 Tool Search 默认值,该默认值已启用 Tool Search

Control UI Labs

打开 设置 → Labs 以管理具有 Control UI 开关的实验。启用或禁用某个 lab 会立即修补规范的 Gateway 配置,而无需重启 Gateway。

Labs 包括 Decision 辅助、Code Mode、适用于所有模型的 Tool Search、Custom plugin UI、Host Desktop 和 Cloud Worker Desktop。在默认重载模式下,自定义插件视图和桌面可用性会在已连接的 Control UI 页面中更新。Code Mode 和 Tool Search 的更改将对未来的代理运行生效。禁用 Custom plugin UI 后,请重新加载浏览器标签页,以清除已经运行的插件 JavaScript。Cloud Worker Desktop lab 控制对现有具备桌面能力的 worker 的访问;更改某个 profile 的 settings.desktop 仅影响新配置的 worker。

Custom plugin UI 默认关闭。已启用的捆绑插件(包括 Workboard)在该设置关闭时仍保留其原生 UI。后端 API 和普通插件仍可用,安装或批准插件工件不会启用该 lab。

Code Mode 保持禁用,直到你打开其 Labs 开关,或显式将 tools.codeMode 设置为 true 或 "auto"。Labs 开关会写入 "auto",因此它仅对标记为 Code Mode 优选表现者的模型生效;它不会为每个模型强制启用 Code Mode。

当 tools.toolSearch 未设置时,Tool Search 默认启用。关闭其 Labs 开关会禁用全局默认值;打开它会恢复该默认值。

Decision 辅助

此选择加入项会在内置 OpenClaw 运行时中启用实验性的对话式工具过滤。在符合条件的用户轮次之前,已配置的 Decision provider 会判断请求是否需要工具。对话结果可以省略该轮次中的可选工具。其他 harness 保留其正常工具,并且不执行自动预过滤推理。该开关不会选择 provider、配置凭据、下载模型或启用无关的消费者模式。

该开关和手动编写的配置使用同一个全局布尔值:

{
  agents: {
    defaults: {
      experimental: { decisionAssistance: true },
    },
  },
}

默认值为 关闭。只有显式的 true 才会选择加入;省略、false 或无关的实验选项不会。诸如 decisionAssistance: { enabled: true } 的对象无效。关闭 Labs 开关会移除其覆盖并恢复为关闭,同时保留模型选择和同级设置。没有浏览器本地偏好设置。

已保存的选择加入项并不等同于按代理的资格。自动消费者还需要为其所属代理具备有效的 Decision 模型。未设置的代理模型会继承 agents.defaults.decisionModel;显式空值 agents.entries.<id>.decisionModel 会禁用该代理的资格。仅选择模型本身永远不会选择加入。全局开关并不意味着每个代理都具备资格,也不意味着已配置的 provider 已就绪。没有模型时,开启偏好设置仍会保存,但无法运行自动 Decision 推理。

显式 decision_evaluate 工具在其常规模型选择和工具策略契约下独立于 Labs。Labs 不会限制共享 Decision 运行时或提供方注册,也从不授予操作权限。

核心消费者契约

核心实现可以从 src/agents/decision-assistance.ts 导入 isDecisionAssistanceEligible(config: OpenClawConfig, agentId: string): boolean。请提供已准备好的配置和受信任的拥有代理 ID,而不是模型提供的 ID。该辅助函数恰好返回 decisionAssistance === true && resolveDecisionModelSetting(config, agentId) !== undefined。它不执行提供方检查、密钥解析、文件读取、网络请求、模型加载或推理,也不返回提供方就绪诊断。这是一个内部基础边界,而不是新的插件 SDK 接口面。

例如,在自动消费者边界处:

import { isDecisionAssistanceEligible } from "./decision-assistance.js";

if (!isDecisionAssistanceEligible(preparedConfig, owningAgentId)) {
  return existingBaseline;
}
// Separately check this consumer’s explicit mode, harness support, and authority
// before loading its optional implementation or preparing evaluation evidence.

使用现有的配置发布/刷新生命周期,而不是文件轮询。消费者在 Decision 提供方分发时,在等待准备完成后再次检查选择加入。禁用辅助会阻止后续评估开始;已分发的评估可能完成,包括提供方准备和网络 I/O,并且其结果仍可能被使用。模型选择、实时权限、取消、截止时间以及提供方/凭证有效性仍会独立检查。该辅助函数不是权限 Token 或取消所有者。

会话工具过滤

升级行为: 现有已保存的 decisionAssistance: true 是面向未来自动 Decision 实验的选择加入意图。当此消费者安装后,它可以在具有有效 Decision 模型的代理的符合条件的回合上运行;该偏好不会选择新的提供方或授予工具权限。不希望自动评估的运营人员可以关闭该偏好或清除该代理的 Decision 模型。下方描述了传递的证据和成本。

预过滤器会将完整的当前请求以及近期会话的确定性、有界投影发送到拥有代理所配置的 Decision 提供方。它保留最近的完整用户/助手交换,并在空间允许时按时间顺序额外保留一个交换。普通 before_prompt_build 钩子的已解析输出如果存在,也会以带标签字段原样发送:prependContext、appendContext、systemPrompt、prependSystemContext 和 appendSystemContext。适用两个内部文本界限:

  • 最新请求加上保留的用户/助手交换文本限制为 6,000 个 UTF-16 码元。只能省略整个较早的交换。
  • 该会话文本加上全部五个原样钩子字段值总共必须适合 8,000 个 UTF-16 码元。超大的钩子字段不会被截断。

这些是对证据文本的 JavaScript 字符串长度界限,而不是对序列化 JSON、UTF-8 传输字节或 Token 的界限。字段名、JSON 转义、省略事实、工具结果计数以及固定评分标准会增加序列化开销。当前请求和必要上下文绝不会被裁剪以强制分类;超大、格式错误、缺失或以其他方式不合适的必要上下文会保留正常工具。真正的新会话仅使用当前请求进行评估。现有不完整历史不被视为新会话;缺失的指代对象和不确定性必须保留工具。

只有用户可见文本、返回/失败的工具调用计数以及所列已解析普通钩子字段才是次要证据。其他系统/开发者指令、隐藏推理、原始工具参数或结果、内部事件信封以及媒体不会被发送。工具返回计数并不断言操作已成功。托管提供方会接收此有界证据并可能产生费用;本地提供方保持推理在本地。分类会在主要模型请求之前增加工作,并不保证延迟改进。

当前内部预算为 500 ms,不是配置选项。一个现有 Decision 批次会询问两个独立的布尔问题:最新请求是否具有未解决的上下文引用,以及满足它是否需要在下一个响应中使用工具。要省略可选工具,两个概率都必须低于 0.35。缺失、肯定或不确定的答案会保留工具。这些是“是”的概率,而不是工具使用程度或单独的置信值。

结构化状态会命名最新请求、按时间顺序的近期交换,以及关于被省略的较早会话和原始工具负载的事实。每个问题都会显式引用这些字段。较早对工具的提及本身不会请求新操作,仅被省略的较早历史也不会否决过滤。这遵循 TypeSafe 原子 Noul 指南,同时使用提供方中立的 Decision 契约;它不发出提供方特定请求,也不提供校准正确性保证。没有模型感知的输入估计器、自动裁剪重试或第二提供方。普通不可用结果,包括截止时间或实际提供方输入拒绝,会保留正常工具表面。调用方预算截止时间不计为提供方故障,也不会打开共享健康熔断器,因此重复的可选预过滤器超时不会禁用显式 decision_evaluate 请求。真实的提供方传输、身份验证和速率限制故障仍保留其共享健康处理;进行中的工作在其结算前仍拥有其并发槽位。取消、权限关闭和契约错误仍保持为错误,而不是启动回退工作。冷模型加载可能超出预算。分类器估计并不保证每个操作请求都会保留其可选工具。

过滤跳过原始检查、续接、内部事件、排队中的转向、孤儿修复、待处理工具工作、钩子集 toolsAllow 限制,以及依赖权限且需要已确定工具的 prompt 构建钩子。普通 prompt 构建钩子正常运行,其已解析字段可以为 Decision 评估提供参考,而不改变公共钩子契约。它不再仅仅因为存在先前的助手或工具消息就拒绝某一轮。完整的上下文审批仍然是操作请求,而对话性确认可以在后续轮次中省略可选工具。它使用现有宿主工具策略,保留已必需的工具,而不授予被拒绝的工具,并保持已提交的模式、发现和可调用性一致。 每个后续轮次都从自身的正常工具基线开始。选择退出不会从已分发的 Decision 评估中撤回限制。模型选择变更仍会阻止应用等待中的限制,并会在等待准备完成后,在前台主模型分发时重新检查。该变更仅撤回可选限制,并恢复当前允许的工具面,同时保留独立的钩子上限和必需工具。不会重写历史转录,也不会重新创建原生线程。

当为嵌入式运行器启用 DEBUG 日志时,在首次前台主分发处的安全记录会报告 Decision 状态/原因、Decision 延迟、上下文计数和省略标志、可见工具计数、保留的必需工具,以及规范化工具定义 JSON 的 UTF-16 字符差异(name、description 和 parameters)的前后对比。Tool Search 和 Code Mode 仅统计实际暴露的控件/直接工具,包括其描述——而不是每个隐藏目录模式。此仅模式指标不是提供商传输字节、完整 prompt 节省、Token、成本,也不是提供商接受请求的证明。与工具相关的 prompt 指导报告为未测量。未知测量保持未知,而不是零。DEBUG-off 避免额外的定义序列化。此记录不会记录对话、工具负载、完整模式或凭据;现有日志记录和跟踪关联控制适用。

本地模型精简模式

精简模式是一种高级故障排查覆盖,在 Labs 之外配置。其现有 experimental.localModelLean 键仍受支持。有关功能限制、配置示例和恢复指导,请参阅本地模型精简模式。

实验性并不意味着隐藏

实验性功能应在文档和配置路径本身中明确说明,而不是隐藏在看似稳定的默认开关后面。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw