决策模型¶

决策模型 对照评分标准评估提供的证据，并返回带类型的回答：一个选择、一个分数，或一个布尔概率。将其用于有界判断，例如路由请求、评估其紧急程度，或检查其是否满足某个条件。

decisionModel 是一个具有共享 API 的模型角色。其提供商可以使用不同的模型架构和推理后端。共享接口并不意味着它们的推理能力或概率可以互换。

该角色和 TypeSafe AI 适配器是在已发布的 OpenClaw 2026.9.5 之后添加的。这些说明适用于包含这些功能的开发检出，以及包含这些功能的后续版本。有关其主机要求，请参阅各提供商的设置页面。

决策模型在 Control UI 中有一个独立的 Decision 选择器。选择会为显式评估和受支持的消费者选择提供商。核心 decision_evaluate 工具遵循该选择以及普通工具策略。选择不会启动后台工作，也不会替换聊天模型。自动实验性消费者还需要显式决策辅助选择加入。该 Labs 条目目前仅提供门控基础，没有连接自动消费者；显式 decision_evaluate 仍独立于 Labs。

选择提供商和模型¶

在选择其模型之前，先配置提供商插件：

• ONNX 在持久子进程中运行本地 CPU 分类器。按照其开发检出或兼容软件包设置进行操作，然后显式下载模型或准备本地导出。推理不需要托管 API 凭据。
• TypeSafe AI 连接到托管 Jev 或本地 System One 服务器（例如 Kev）。安装并启用外部插件，然后配置受保护的托管凭据或显式回环 baseUrl。托管评估会将所选证据发送到 TypeSafe，并产生其正常使用费用。

当前插件声明了以下模型引用：

这两个插件目前均为未发布的候选项。它们的设置页面说明了源码检出用法和打包主机最低要求。该表描述的是插件声明的模型，而不是您机器上哪些工件或凭据已就绪。

完成提供商设置后，将角色选择合并到您的配置中：

{
  agents: {
    ownership: "explicit",
    defaults: { decisionModel: "onnx/gliclass-edge-v3.0" },
    entries: {
      support: { decisionModel: "typesafe/jev-latest" },
      quiet: { decisionModel: "" },
    },
  },
}

未设置的代理覆盖会继承全局默认值。空的代理覆盖会禁用该代理的决策。未设置或为空的全局默认值会使该角色保持关闭。没有自动回退到对话模型。

用于本地设置验证，openclaw onnx models 会列出预设，openclaw onnx probe gliclass-edge-v3.0 会在模型下载后运行 Choice、Score 和 Boolean 冒烟评估。

定义决策¶

每个请求都包含共享的 state 和一个 questions 映射。State 接受文本、JSON 对象或数组，或 null。问题键用于标识答案；instructions 和 criteria 定义判断。评分标准随每个请求一起传递，因此没有单独的评分标准注册步骤。

使用描述性替代项和可观察的分数锚点。当目标为 ONNX 时，为布尔问题提供两种描述。让证据聚焦于问题本身；ONNX 的 token 预算包括 state、instructions 和 rubric。

代理评估工具¶

decision_evaluate 是核心工具。当某个代理具有有效的 decisionModel 时，该代理会收到此工具，但需遵循常规工具策略、显式拒绝以及当前 harness 的能力。未配置的代理，或具有空 per-agent 覆盖的代理，不会收到该工具。无论其他实验性消费者是否使用 Decision 模型，该工具都保持可用。Provider 插件仍需要它们自己的常规配置。

使用显式的共享 state 和一个 questions 映射来调用它：

{
  "state": { "message": "Checkout is failing for all customers." },
  "questions": {
    "escalate": {
      "type": "boolean",
      "instructions": "Does this need incident response?",
      "criteria": {
        "true": { "includes": ["Widespread service outages"] },
        "false": "A routine request can follow normal handling"
      }
    },
    "route": {
      "type": "choice",
      "criteria": { "support": "Service failures", "billing": "Payment questions" }
    },
    "urgency": {
      "type": "score",
      "criteria": ["No disruption", "One workflow blocked", "Widespread outage"]
    }
  }
}

状态、指令和标准描述接受文本、JSON 对象或数组，或 null。每个问题看到相同的 state，并且无法看到批次中的其他答案。当一个问题依赖于较早的答案时，请使用后续调用。该工具不会收集环境对话。其受信任的调用代理绑定会选择 provider 和 model；输入无法覆盖该身份或选择。

结果保留布尔概率、基于零的小数分数、原始分布和舍入、可选的置信度和用量，以及 provider/model 来源信息。它们不会生成解释，也不会授予执行操作的权限。证据会发送到所选 provider 的已配置端点或本地运行时；仅发送已授权发送到该目的地的数据。Provider 插件负责凭据、模型加载、传输和特定于 wire 的验证。

Provider 能力随其模型元数据声明，并通过 models.list.decisionModels 暴露。不支持的问题和边界会生成可操作且范围有限的指导。请求会被拒绝，而不是被静默截断或拆分。当已配置的 provider 不可用时，不要改用 shell 或 HTTP 调用，不要在聊天中请求凭据，也不要将失败视为否定答案。

缺少凭据、速率限制、过载和临时 provider 错误会使已配置的工具保持可用，并返回不可用结果。配置更改遵循现有的工具/上下文刷新生命周期；执行时会重新检查有效选择和权限。取消会传播到共享的 Decision 运行时，并且不得启动回退工作。

从插件调用¶

从实时工具、hook 或其他自有操作中进行调用。此处 api 是插件 API，agentId 标识拥有该工作的代理，signal 是该操作的取消信号。消费者无需 provider SDK 或 API key。

const outcome = await api.runtime.decisions.evaluate(
  {
    state: { message: "Checkout is failing for all customers." },
    questions: {
      route: {
        type: "choice",
        instructions: "Which team should handle this?",
        criteria: {
          support: "Technical problems and service outages",
          billing: "Invoices, refunds, and incorrect charges",
          sales: "Pricing and purchasing questions",
        },
      },
      urgency: {
        type: "score",
        instructions: "Assess the operational impact.",
        criteria: [
          "No service disruption",
          "Minor inconvenience with a workaround",
          "An important workflow is blocked",
          "A widespread production outage",
        ],
      },
      escalate: {
        type: "boolean",
        instructions: "Does this require human incident response?",
        criteria: {
          true: "A serious service incident needs human attention",
          false: "A routine request can follow normal handling",
        },
      },
    },
  },
  {
    agentId,
    purpose: "support.triage",
    rubricVersion: "1",
    timeoutMs: 30000,
    signal,
  },
);

宿主从拥有该工作的代理配置中选择 provider 和 model。purpose 标识消费者操作；rubricVersion 在结果来源信息中标识其 rubric。它们不会替代问题指令。当 rubric 的含义发生变化时，更改 rubric 版本。仅在有意使用全局默认选择时省略 agentId。

ok 结果包含 outcome.result.answers，以提交的问题 ID 为键，外加 provider 报告的 model、可选用量以及 provider/rubric/runtime 来源信息。报告的别名（例如 kev-latest）不会标识某个特定已加载的 checkpoint。缺失的用量或置信度将保持缺失。例如，这些是示例答案，而非承诺的模型响应：

{
  "route": {
    "type": "choice",
    "choice": "support",
    "probabilities": { "support": 0.97, "billing": 0.02, "sales": 0.01 }
  },
  "urgency": {
    "type": "score",
    "score": 2.85,
    "probabilities": [0, 0, 0.15, 0.85]
  },
  "escalate": { "type": "boolean", "probabilityTrue": 0.96 }
}

宿主在返回任何答案之前会验证完整批次。在 TypeScript 中访问类型特定字段之前，先根据其 type 对答案进行类型收窄。

解释分数和概率¶

分数是基于零的 rubric 位置。上述四个 urgency 描述定义了从 0 到 3 的刻度，包括小数。分数 2.85 位于最高影响锚点附近。显示可以重新缩放该位置：

if (outcome.status === "ok") {
  const urgency = outcome.result.answers.urgency;
  if (urgency?.type === "score") {
    const scoreOutOf100 = (100 * urgency.score) / 3;
  }
}

除数是最后一个评分标准索引：criteria.length - 1。显示值是量表上的一个位置，而不是置信百分比或正确的概率。评分标准的措辞决定了该量表所表示的含义。

ONNX 使用 softmax 对实际标签 logits 进行归一化。Choice 使用最大值；Score 是概率加权的评分标准索引。TypeSafe 保留 Jev 报告的标签、得分和概率估计。经过四舍五入的供应商概率不必精确相加为 1，其报告的得分也不必等于根据这些四舍五入值计算出的期望值。

较低的布尔概率偏向 false；接近 0.5 的值对两种结果赋予相近的权重。证据缺失并不保证值接近 0.5。如果该结果很重要，请包含一个明确的“证据不足”Choice 替代项。Choice 替代项会相互竞争；对于独立标签，请使用单独的布尔问题。

你的消费方会选择一种行动策略，例如当 probabilityTrue 至少为 0.9 时进行升级。请在具有代表性的示例上验证该阈值。概率和可选的供应商特定 confidence 值都是估计值，并非已证实的准确性保证。答案并不授予发送消息或执行其他效果的权限。

限制与不可用结果¶

对于可移植的评分标准，最多使用 32 个问题、2–64 个 Choice 替代项、2–10 个有意义的 Score 锚点、明确的 true/false 描述和简洁的证据。提供方限制有所不同：

宿主将请求限制为 1 MiB、20,000 个 JSON 节点、深度 32 和 256 个问题。每个提供方最多允许四个请求，并将每个截止时间限制在 30 秒内。提供方特定限制可能更严格。不支持的输入会被拒绝，而不是被静默截断。

unavailable 结果包含一个原因，例如 disabled、not-configured、unsupported-input、overloaded 或 deadline。消费方决定是跳过、推迟还是使用其现有的回退。调用方取消、已关闭的消费方权限和契约错误都会导致拒绝；不要将取消变成回退工作。完整的生命周期和错误行为请参见 SDK 契约。

消费方应构建有界且有用的证据，只评估一次，并在提供方返回 unsupported-input（包括上下文溢出）时保持其正常行为。运行时不会估算模型 token、截断证据、重试，或选择另一个提供方/模型。输入被拒绝不会触发提供方的熔断器；取消和已关闭的权限保持终态。

decisions 记录器会记录 DEBUG 结果、调度状态、经过时间、问题数量、提供的 JSON 字节数，以及可用的实际提供方使用情况。JSON 字节不是模型 token。用途/提供方/模型标识符会经过哈希处理；现有的环境追踪关联保持不变。它不记录提交的文本、评分标准、凭据或提供方错误响应体，并且在 DEBUG 禁用时不进行额外的输入序列化。通用的输入拒绝警告会被限流。日志将提供方结果与调用方效果区分开来，后者在此处仍不可观测。

对于 ONNX，在较慢的机器上冷加载大型模型可能会超过截止时间。在内存允许时保持活动模型为热状态，或选择更小的模型。有关缓存设置和主动取消的影响，请参阅 ONNX 生命周期与运行时。若缺少 TypeSafe 凭据，请遵循其 设置说明。

从插件提供模型¶

提供方插件实现来自 openclaw/plugin-sdk/decisions 的 DecisionProviderV1，并通过 api.registerDecisionProvider(provider) 注册它。其 id 和 contractVersion: 1 标识该契约；evaluate(batch, context) 返回验证后的类型化答案或受支持的不可用原因。上下文包含所选模型、可选的代理 ID、组合出的取消信号以及单调的截止时间。

在插件清单中声明提供方所有权和静态模型元数据：

{
  "contracts": { "decisionProviders": ["example-decisions"] },
  "decisionModels": [{ "provider": "example-decisions", "id": "fast", "name": "Fast decisions" }]
}

此清单片段在单独的决策目录中暴露选择器 example-decisions/fast。消费方对每个提供方使用相同的评估 API。它本身不注册提供方。

提供方负责模型特定的输入转换、传输或本地推理、在需要时准备好的凭据，以及取消时的物理清理。注册和可选的 isReady() 必须是同步且无网络的；isReady() 检查已准备凭据的可用性，而不是模型预热。返回真实的模型估计，而不是仅根据标签响应制造确定性。

提供方契约 涵盖完整的 SDK 规则；清单参考 涵盖发现字段。对于现有集成，请使用 ONNX 或 TypeSafe AI 的设置页面。