本地 ONNX 决策模型¶

可安装的 ONNX 插件通过决策模型 API在本地运行分类器。它使用一个独立的、常驻的 Node 进程，并采用 ONNX Runtime 的 CPU 后端。推理不会将状态或问题发送到远程服务。只有在你显式运行下载命令时，模型才会下载。

关于模型角色、rubric 示例以及提供者无关的插件 API，请参阅决策模型。

设置¶

decision-provider API 是在已发布的 OpenClaw 2026.9.5 之后新增的。打包的 ONNX 安装要求宿主和插件 API 至少为 2026.9.6；安装程序会在加载插件之前拒绝 2026.9.5。原生运行时属于插件包，不会捆绑进核心。

当前开发检出¶

在支持性版本可用之前，请使用同时包含 decision-provider API 和 extensions/onnx 的 OpenClaw 源码检出。使用 pnpm install --frozen-lockfile 和 pnpm build 构建该检出，然后按下面的配置启用插件并选择其模型。在检出目录中运行以下命令：

pnpm openclaw onnx models
pnpm openclaw onnx download gliclass-edge-v3.0
pnpm openclaw onnx probe gliclass-edge-v3.0

检出中的同版本源码插件使用宿主的开发 API。这并不会使打包插件与已发布的 2026.9.5 宿主兼容。

打包安装¶

在兼容的宿主上，安装本地构建的包并准备模型：

openclaw plugins install npm-pack:/path/to/openclaw-onnx.tgz
openclaw onnx models
openclaw onnx download gliclass-edge-v3.0
openclaw onnx probe gliclass-edge-v3.0

配置¶

为全局或单个 agent 选择该角色：

{
  agents: {
    defaults: { decisionModel: "onnx/gliclass-edge-v3.0" },
  },
  plugins: {
    entries: {
      onnx: {
        enabled: true,
        config: { threads: 2, maxLoadedModels: 2 },
      },
    },
  },
}

默认产物目录为 <stateDir>/models/onnx。如果要用其他目录，请设置插件的 modelDir；download、verify 和 probe 命令也接受 --model-dir <path>。产物按模型 ID 分组。下载使用固定的仓库修订版本、大小和 SHA256 哈希。已存在但不匹配的文件会被拒绝，而不会被覆盖。openclaw onnx verify <model> 用于检查安装。验证和缓存下载检查会流式读取文件，因此检查大型图不需要与图大小相当的内存缓冲区。推理仍会将已验证的图字节加载到其 worker 中。

模型¶

托管的预设使用 FP32 图。模型许可证和转换来源链接自原始 GLiClass、GLiNER2 和 DeBERTa 模型页面。下载的权重与 OpenClaw 的包保持分离。

对于 Instruct 模型，请使用已安装插件的 dist/scripts/export-gliclass-instruct.py 辅助脚本，并使用 --help 列出的固定 Python 包。请提供 openclaw onnx models 打印出的精确官方 checkpoint 修订版本的本地副本：

python export-gliclass-instruct.py --model edge \
  --source /path/to/checkpoint \
  --output /path/to/models/gliclass-instruct-edge-v1.0
openclaw onnx verify gliclass-instruct-edge-v1.0 --model-dir /path/to/models

该辅助脚本会验证源文件，运行时不依赖远程模型代码或下载，并创建一个新目录，其中包含图、tokenizer 和 model.json 导出清单。本地导出是操作者提供的产物：运行时检查其声明的源修订版本和文件哈希。它们的图哈希不是已发布的第三方证明。此导出不支持 few-shot 示例部分。

问题语义¶

这些模型根据 rubric 对文本进行分类。JSON 状态和 rubric 条目会被序列化为文本；指令和标准描述会影响分类结果。尽可能使用描述性标准，而不是不透明的 ID。

• Choice（选择）： 对模型完整标签 logits 做 softmax；概率最高的标签获胜。
• Score（分数）： 对有序的标准等级进行分类，然后返回其期望的从零开始的索引。
• Boolean（布尔）： 为 criteria.true 和 criteria.false 都提供有意义的谓词描述。不支持裸布尔问题，因为 true 和 false 这样的标签无法可靠地表达零样本谓词。

概率是模型估计值，而不是经过校准的保证。这些分类器并不能在每项推理任务上都与 Jev 互换。在依赖其决策质量之前，请在代表性示例上验证评估标准。

该插件每个问题最多支持 32 个问题和 64 个标签，整个批次的编译输入限制为 1 MiB。每个编码后的输入（包括其 rubric）必须适配 512 个 token。它会拒绝不支持的输入，而不是截断。GLiClass 预留了其标签、分隔符和示例标记。GLiNER2.5 还会拒绝 schema 的保留标记以及 rubric 中的括号；普通状态文本可以包含标点符号。

生命周期与运行时¶

在插件服务启动期间，最多 maxLoadedModels 个选定模型会进行预热。后续 请求会复用原生会话；当常驻缓存已满时，会逐出最近最少使用的模型。缺失的文件和失败的制品完整性检查不会使预热会话不可用。逐出发生在制品验证和 分词器准备之后、加载替换原生会话之前。threads 将 CPU 操作内并行度设置为 1 到 8。

在较慢的机器上，冷加载大型模型可能会耗尽请求的截止时间。 主机允许最多 30 秒；消费者可以请求更短的时间。 当代理使用多个模型时，如果内存允许，请设置 maxLoadedModels 以 保留活动模型，或选择更小的模型。默认 缓存保留两个模型；最大值为五个。

主机仍会强制执行其 30 秒决策截止时间和四次调用的提供商 限制。工作进程会串行化原生操作。排队中的取消会保持 预热进程完好；取消活动原生工作会在释放请求之前终止并等待该 进程结束。下一个实时请求会启动一个新的工作进程。 插件退役会停止工作进程及其拥有的工作。

运行时要求受支持的 Node.js 和可选的 onnxruntime-node 原生 包。CPU 推理是初始后端；GPU 和 WASM 执行未 由本插件启用。原生库和模型分词器在工作 进程内加载，使其不进入 Gateway 发现和常规插件注册。