TypeSafe AI¶
官方外部 typesafe 插件将 OpenClaw 的可选决策模型角色连接到 TypeSafe AI 托管的 Jev 模型,或显式配置的本地 System One 服务器(如 Kev)。其模型显示在独立的决策选择器中,绝不会出现在对话模型选择器中。
该适配器和决策模型角色是在 OpenClaw 2026.9.5 发布之后添加的。打包安装需要主机和插件 API 至少为 2026.9.6;安装程序会在加载插件之前拒绝旧版本主机。
有关模型角色、可用后端、评分规则示例和提供商中立的插件 API,请参阅决策模型。
该插件默认禁用。安装或启用它不会选择决策模型,也不会安排后台任务。
安装¶
TypeSafe AI 与核心分开打包,以便发布到 npm 和 ClawHub。其首次发布正在等待配套版本。一旦发布,即可从 npm 在兼容主机上安装:
要显式选择 ClawHub:
在配套版本可用之前,请使用包含决策提供商 API 和 extensions/typesafe 的源码检出。使用 pnpm install --frozen-lockfile 和 pnpm build 构建,然后应用下面的配置。源码检出插件使用主机的同版本开发 API;这并不会使打包插件与 OpenClaw 2026.9.5 兼容。
启用和配置¶
对于托管 Jev,请在“设置 → 机密”中创建受保护的凭据,然后在插件配置中引用它。将此示例合并到现有配置中;保留 plugins.allow 中的任何其他条目。
{
plugins: {
allow: ["typesafe"],
entries: {
typesafe: {
enabled: true,
config: {
apiKey: { source: "store", provider: "default", id: "TYPESAFE_API_KEY" },
},
},
},
},
agents: {
ownership: "explicit",
defaults: { decisionModel: "typesafe/jev-latest" },
entries: {
research: { decisionModel: "typesafe/jev-1.13.0" },
},
},
}
typesafe/jev-latest 显示为 Jev;固定版本的 typesafe/jev-1.13.0 显示为 Jev 1.13.0。未设置的代理覆盖继承 agents.defaults.decisionModel;空覆盖会禁用该代理的决策。未设置或空的全局角色默认关闭决策。
托管模式在每次请求时读取主机准备好的 SecretRef 值。它不会独立读取环境凭据或缓存先前的凭据。缺失或不可用的凭据会使决策不可用。更改凭据后,请使用常规的机密刷新流程。
选择决策模型将授权受支持且已启用的消费者将其选定的证据发送到配置的端点。托管 Jev 请求会产生 TypeSafe 的正常使用费用。消费者的调度和发布权限保持不变。清除角色或显式禁用插件会阻止这些消费者使用它。
本地 System One 服务器¶
运行 Kev¶
Kev 是一个 Apache-2.0 许可证的决策模型系列,通过持久的 Python 进程提供 System One API。它支持 Apple Silicon 和 CUDA。基于 Qwen3 的 Kev-0.6B、Kev-4B 和 Kev-8B 检查点已通过此适配器测试。
对于 Mac,请从基于 Qwen3 的 Kev-4B 检查点开始。此示例需要 Python 3.12+ 和 uv,并将经过测试的适配器修订版固定到本地目录。首次启动服务器时还会下载其基础模型权重:
git clone https://github.com/jaredpalmer/kev.git
cd kev
git checkout 5f78968927069eaacc3b2bdb688586989b3933ac
uv sync --frozen --extra serve
uv run python - <<'PY'
from huggingface_hub import snapshot_download
snapshot_download(
"jaredpalmer/kev-4b",
revision="c4bfa11b0dc07691884f2d97f1c4c4c05c92e416",
local_dir="models/kev-4b-qwen3",
)
PY
KEV_DTYPE=bf16 uv run --extra serve python -m kev.serve \
--run models/kev-4b-qwen3 --port 8009
较新的默认 Kev-4B 检查点使用 Qwen3.5;其在 Mac 上的性能与上述 Qwen3 检查点不同。选择其他检查点时,请遵循上游模型卡片。Kev-0.6B 使用更少内存;Kev-8B 以更多内存和延迟换取决策质量。对于你下面配置的服务器,它们都使用相同的 OpenClaw 模型标签。
在第二个终端中,从同一个 Kev 检出目录验证已加载的检查点并运行 Kev 的 API 测试:
curl --fail http://127.0.0.1:8009/v1/models
KEV_BASE_URL=http://127.0.0.1:8009 \
uv run --extra serve python -m pytest tests/test_api.py -q
连接 OpenClaw¶
单独启动你的 System One 服务器,然后将 baseUrl 设置为其回环源,并选择 typesafe/kev-latest:
{
plugins: {
allow: ["typesafe"],
entries: {
typesafe: {
enabled: true,
config: { baseUrl: "http://127.0.0.1:8009" },
},
},
},
agents: {
defaults: { decisionModel: "typesafe/kev-latest" },
},
}
将示例与现有设置合并,保留其他已允许的插件。本地推理时省略 apiKey。插件在此路径上不会读取或发送托管凭据;如果主机也应停止准备该凭据,请移除保留的 SecretRef。
该端点适用于来自此插件的每个请求,包括模型标签命名为 Jev 的请求。模型选择不会在托管端点和本地端点之间进行选择。kev-latest 标签需要 baseUrl,并且永远不会发送到托管的 TypeSafe 端点。
baseUrl 接受 localhost、127.0.0.1 或 [::1] 上的 HTTP 或 HTTPS,可带端口和尾部斜杠。请提供源,不要包含 /v1、凭据、查询参数或片段;插件会追加 /v1/systemone。不接受局域网和远程主机。这些请求不使用常规的环境 HTTP 代理变量;显式启用的托管代理策略仍然适用。
Kev 每个服务器进程运行一个检查点。其请求模型标签不会加载或切换权重。启动服务器时选择检查点,并通过检查 GET /v1/models 进行验证。参见 Kev 的服务说明了解安装、模型选择和硬件要求。OpenClaw 不会下载权重或启动该进程。不可用的服务器会产生不可用决策,而不会自动切换到托管 Jev。
为降低延迟,可在一次调用中对相同状态下的独立问题进行批处理。尽可能保持重复证据不变,以便 Kev 复用其前缀缓存。经过测试的 Kev 服务器会串行化推理;更多并发 HTTP 调用会增加排队时间。原生决策每个提供商最多允许四个并发请求,超过该限制时返回 overloaded。核心评估工具使用相同的准入限制。
取消会关闭 OpenClaw 的 HTTP 请求,但 Kev 服务器可能完成已在进行的推理。避免立即重新提交已取消的工作;请选择一个允许在你的硬件上进行推理和排队的截止时间。
为了本地兼容性,省略的问题指令会以 null 发送。结构化 Score 评分标准级别以文本编码;返回的图例必须与所传输的评分标准匹配,之后才能在决策结果中恢复原始级别描述。Kev 的可选非负 latency_ms 字段会被验证并移除;所有答案类型、标签、概率和评分标准边界均保留与托管结果相同的验证。
决策契约¶
消费者调用提供商中立的决策运行时。宿主提供为拥有代理所选定的模型。适配器转换受支持的问题类型:
| OpenClaw | TypeSafe | 结果 |
|---|---|---|
| Choice | Choice | 报告的标签和概率估计 |
| Score | Score | 报告的基于零的小数评分标准位置和估计 |
| Boolean | Noul | 为真的概率,保留在 0 到 1 之间 |
Choice 支持 2–255 个备选;Score 支持 2–10 个评分标准级别。不受支持的输入会在传输前被拒绝;适配器不会截断或拆分消费者的评分标准。响应必须匹配完整的问题批次、其标签、类型和评分标准边界。
报告的概率可能经过四舍五入,因此可能不会恰好加总为一。报告的标签或 Score 也可能与基于这些估计值的计算结果不同。OpenClaw 保留返回的值。对估计值进行归一化或选择其最大值是明确的消费者策略。概率和置信度不是已证明的准确性保证或行动许可。
宿主负责并发、熔断器健康、截止时间、取消和提供商生命周期。原生决策最长为 30 秒;更短的消费者或插件超时仍然适用。请求使用固定的 TypeSafe HTTPS 端点,除非 baseUrl 选择本地服务器。两条路径都拒绝重定向,并且不会自动重试。消费者决定如何处理不可用决策;调用方取消不得启动回退工作。
代理评估工具¶
当代理具有有效的 decisionModel 选择时,Core 会自动提供 decision_evaluate。常规工具策略(包括显式拒绝)以及活动 harness 的能力仍然适用。无需 TypeSafe 工具注册或额外的启用设置。参见提供商中立的工具契约了解其请求结构和结果。
该工具接受显式共享的 state 以及独立的 boolean、choice 和 score 问题。调用代理的可信身份会选择其继承的或按代理的 decisionModel;没有按调用的提供商或模型覆盖。对于 TypeSafe 选择,适配器会将 Boolean 问题转换为 Noul,并仅将提供的证据发送到托管 Jev 或配置的本地端点。
临时凭据或提供商故障会返回可操作的不可用结果,并保持已配置工具可用。清除代理的有效选择会通过常规工具/上下文刷新生命周期移除资格。执行会重新检查选择和当前权限。timeoutMs 默认为 30,000 毫秒,并将提供商请求限制为该设置与宿主剩余截止时间中较短者。类型化答案提供证据,而不是发布、发送消息或更改持久状态的许可。
HTTP 400(错误请求)、HTTP 413(内容过大)以及 TypeSafe 的已记录的 422 请求验证响应返回 unsupported-input,而不是提供商故障。请求被拒绝并不专门确立上下文溢出。适配器会取消错误主体而不读取它们,因为它们可能反映凭据或已提交的证据。身份验证(401/403)、速率限制(429)以及其他 HTTP/传输故障保留其现有分类;不会添加自动重试。
现有外部安装¶
官方包保留原型和早期开发检出所使用的 typesafe 插件 ID。切换时,请保留 plugins.entries.typesafe、其受保护的凭据以及代理 decisionModel 选择。使用受支持的插件管理流程替换旧安装,如果显式原型路径会覆盖已安装包,请从 plugins.load.paths 中移除该路径。不要将两个副本配置为独立提供商。安装包不会删除原型文件或凭据。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw