TypeSafe AI¶

官方外部 typesafe 插件将 OpenClaw 的可选决策模型角色连接到 TypeSafe AI 的托管 Jev 模型，或显式配置的本地 System One 服务器（例如 Kev）。其模型会显示在独立的 Decision 选择器中，而不会出现在对话模型选择器中。

该适配器与决策模型角色是在已发布的 OpenClaw 2026.9.5 之后添加的。打包安装要求宿主和插件 API 至少为 2026.9.6；安装程序会在加载插件之前拒绝较旧的宿主。

有关模型角色、可用后端、评分标准示例以及提供商中立的插件 API，请参阅 Decision models。

该插件默认禁用。安装或启用它不会选择决策模型，也不会安排后台工作。

安装¶

TypeSafe AI 与核心部分分开打包，以便发布到 npm 和 ClawHub。其首次发布正在等待一个支持性版本。发布后，可在兼容的宿主上从 npm 安装：

openclaw plugins install @openclaw/typesafe

若要显式选择 ClawHub：

openclaw plugins install clawhub:@openclaw/typesafe

在支持性版本可用之前，请使用包含 decision-provider API 和 extensions/typesafe 的源代码检出。使用 pnpm install --frozen-lockfile 和 pnpm build 构建它，然后应用以下配置。源代码检出插件使用宿主的同版本开发 API；这并不意味着打包插件与 OpenClaw 2026.9.5 兼容。

启用并配置¶

对于托管 Jev，请在“设置 → Secrets”中创建一个受保护的凭据，然后在插件配置中引用它。将此示例合并到现有配置中；保留 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。未设置的 agent 覆盖会继承 agents.defaults.decisionModel；空覆盖会禁用该 agent 的决策。未设置或为空的全局角色默认保持决策关闭。

托管模式会为每个请求读取宿主准备好的 SecretRef 值。它不会独立读取环境凭据，也不会缓存之前的凭据。缺失或不可用的凭据会使决策不可用。更改凭据后，请使用正常的 secret refresh flow。

选择决策模型会授权受支持的、原本已启用的消费者将其选定的证据发送到已配置的端点。托管 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 字段经过验证并移除；所有答案类型、标签、概率和评分量表边界保留与托管结果相同的验证。

决策契约¶

消费者调用提供商中立的决策运行时。宿主提供为拥有该智能体所选的模型。适配器转换支持的类型：

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 ms，并将提供商请求限制为该设置和宿主剩余截止时间中较短者。类型化答案提供证据，而不是发布、发送消息或更改持久状态的许可。

HTTP 413（Content Too Large）和 TypeSafe 的文档中的 422 请求验证响应 返回 unsupported-input，而不是提供商中断。422 不会专门确立上下文溢出。适配器取消错误正文而不读取它们，因为它们可能反映凭据或提交的证据。身份验证（401/403）、速率限制（429）和其他 HTTP/传输故障保留其现有分类；不会添加自动重试。

现有外部安装¶

官方包保留原型和早期开发检出使用的 typesafe 插件 ID。切换时保留 plugins.entries.typesafe、其受保护的凭据和智能体 decisionModel 选择。使用受支持的插件管理流程替换旧安装，如果显式原型路径会覆盖已安装包，则从 plugins.load.paths 中移除它。不要将两个副本配置为独立提供商。安装包不会删除原型文件或凭据。