OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

快速开始

Agent harness plugins

Agent harness 是已准备好的单次 OpenClaw 智能体轮次的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。有关面向用户的心智模型，请参阅 Agent Runtimes。

仅将此接口用于内置或可信的原生插件。此契约仍处于实验阶段，因为其参数类型有意与当前的嵌入式运行器保持一致。

何时使用 harness

当某个模型系列拥有自己的原生会话运行时，并且常规 OpenClaw 提供商传输并非合适的抽象时，请注册 Agent harness：

  • 自行管理线程和压缩的原生编码智能体服务器
  • 必须以流式方式传输原生计划、推理和工具事件的本地 CLI 或守护进程
  • 除 OpenClaw 会话记录外，还需要自身恢复 ID 的模型运行时

不要仅为了添加新的 LLM API 而注册 harness。对于常规 HTTP 或 WebSocket 模型 API，请构建提供商插件。

核心仍负责的内容

在选择 harness 之前，OpenClaw 已经解析了：

  • 提供商和模型
  • 运行时身份验证状态，除非 harness 声明由其负责身份验证引导
  • 思考级别和上下文预算
  • OpenClaw 记录/会话文件
  • 工作区、沙箱和工具策略
  • 渠道回复回调和流式传输回调
  • 模型回退和实时模型切换策略

harness 运行一次已准备好的尝试；它不会选择提供商、取代渠道交付，也不会静默切换模型。

harness 负责的身份验证引导

默认情况下，核心会在调用 harness 前解析提供商凭据。能够通过自身原生运行时进行身份验证的可信 harness，可以在其静态 AgentHarness 注册中设置 authBootstrap: "harness"。随后，对于该 harness 声明处理的每次尝试，核心都会跳过通用的提供商凭据引导和缺少凭据错误。

如果存在兼容且经过明确选择或排序的 OpenClaw 身份验证配置文件及其限定作用域的存储，核心仍会将其转发。harness 必须在发出模型请求前解析该配置文件或其原生凭据，将密钥的作用域限制在本次尝试内，并提供可采取行动的身份验证错误。不要为仅在某些情况下负责身份验证的 harness 设置此能力。

已验证的设置运行时工件

能够为首次运行设置提供推理能力的本地 harness，必须证明完成探测的实现。当 params.captureRuntimeArtifact 为 true 时，返回包含稳定 ID 和内容指纹的不透明 result.runtimeArtifact。注册相匹配的 runtimeArtifact.validate(...) 能力，用于重新检查该绑定，而不加载其他 harness 或扫描无关插件。

已验证的 Crestodian 延续也会传入 params.expectedRuntimeArtifact。harness 必须将其与实际获取的原生进程进行比较；如果二者不同，必须在启动或恢复原生线程前失败。普通智能体轮次会省略这两个字段，因此内容哈希不会进入常规请求的热路径。远程/WebSocket harness 必须具备服务器证明契约后才能参与；仅有版本字符串不足以作为工件身份。

已准备好的尝试还包含 params.runtimePlan，这是 OpenClaw 负责管理的策略包，用于必须在 OpenClaw 与原生 harness 之间保持一致的运行时决策：

  • runtimePlan.tools.normalize(...) 和 runtimePlan.tools.logDiagnostics(...)：用于感知提供商的工具架构策略
  • runtimePlan.transcript.resolvePolicy(...)：用于记录清理和工具调用修复策略
  • runtimePlan.delivery.isSilentPayload(...)：用于共享的 NO_REPLY 和媒体交付抑制
  • runtimePlan.outcome.classifyRunResult(...)：用于模型回退分类
  • runtimePlan.observability：用于已解析的提供商、模型和 harness 元数据

harness 可以使用该计划来执行需要与 OpenClaw 行为保持一致的决策，但应将其视为由宿主负责的尝试状态：不要修改它，也不要利用它在轮次内切换提供商或模型。

请求传输契约

supports(ctx) 通过 ctx.modelProvider 接收已解析的模型传输。以下两个不含密钥、由提供商负责的事实描述了所选路由：

  • runtimePolicy.compatibleIds 列出提供商声明与该具体路由兼容的运行时 ID。缺少此策略意味着提供商未声明路由级兼容性；这并不表示可以假定支持。
  • requestTransportOverrides: "none" 表示无需复现任何由提供商/模型定义的请求覆盖。"present" 表示存在自定义请求头、身份验证传输、代理、TLS、本地服务、专用网络行为或请求参数。此事实不会公开这些值。

当 harness 无法复现已准备好的传输时，返回 { supported: false, reason }。选择完成后，不要通过读取原始配置来推断支持情况。当身份验证准备过程产生多个重试路由时，必须有同一个 harness 支持所有路由，才能进行分派。如果没有插件能够负责完整路由集合，隐式选择将使用 OpenClaw；明确或持久化的插件选择则会采用失败关闭策略。

注册 harness

导入： openclaw/plugin-sdk/agent-harness

typescript
  const myHarness: AgentHarness = {  id: "my-harness",  label: "我的原生智能体 harness",   supports(ctx) {    const routeSupportsHarness =      ctx.modelProvider?.runtimePolicy?.compatibleIds.includes("my-harness") === true;    const canReproduceRequest = ctx.modelProvider?.requestTransportOverrides !== "present";    return ctx.provider === "my-provider" && routeSupportsHarness && canReproduceRequest      ? { supported: true, priority: 100 }      : { supported: false, reason: "有效路由与 harness 不兼容" };  },   async runAttempt(params) {    // 启动或恢复你的原生线程。    // 使用 params.prompt、params.tools、params.images、params.onPartialReply、    // params.onAgentEvent 以及其他已准备的尝试字段。    return await runMyNativeTurn(params);  },}; export default definePluginEntry({  id: "my-native-agent",  name: "我的原生智能体",  description: "通过原生智能体守护进程运行选定的模型。",  register(api) {    api.registerAgentHarness(myHarness);  },});

此通用示例有意省略了 authBootstrap。仅当 harness 满足上述契约时，才添加 authBootstrap: "harness"。

委托执行

harness 所有者可以将 delegatedExecutionPluginIds 设置为需要执行现有模型锁定会话的受信任插件的 ID，例如由语音传输继续 Codex 支持的对话。这是所有者的静态授权，而不是核心允许列表。应严格限制其范围。

被委托方仅获得工作准入和嵌入式执行权限。OpenClaw 要求提供完全匹配的已存储会话键、存储路径和会话 ID；modelSelectionLocked: true；以及匹配的 agentHarnessId 和 agentHarnessRuntimeOverride 值。随后，此运行将限定在 harness 所有者的权限范围内。会话创建、修补、重置、删除、归档以及 Gateway 网关变更仍仅限所有者执行。

选择策略

OpenClaw 在完成提供商/模型解析后选择 harness：

  1. 模型范围的运行时策略优先。
  2. 其次是提供商范围的运行时策略。
  3. auto 会询问已注册的 harness 是否支持解析后的有效路由。仅凭提供商/模型前缀绝不会选择 harness。
  4. 如果没有匹配的已注册 harness，OpenClaw 将使用其嵌入式运行时。

插件 harness 故障会作为运行故障呈现。在 auto 模式下，仅当没有已注册的插件 harness 支持解析后的提供商/模型时，才会使用嵌入式回退。一旦插件 harness 接管某次运行，OpenClaw 就不会通过其他运行时重放同一轮次，因为这可能改变身份验证/运行时语义或造成重复副作用。

配置的运行时策略对所需运行时始终具有权威性。在路由/身份验证准备仍未完成时，持久化会话的 agentHarnessId 会继续拥有其原生转录记录。两者都无法使不兼容的路由变得兼容：准备好的事实一旦存在，选定或固定的 harness 就必须支持它们，否则运行将以关闭方式失败。/status 会显示根据策略、持久化所有权和路由支持情况选择的有效运行时。 准备状态是明确的：缺少 runtimePolicy 时会保持未声明状态，而不会根据恰好存在的传输字段进行推断。 当 harness 所有的身份验证尚未解析出唯一的物理路由时，准备好的支持事实是这些路由的兼容运行时 ID 的交集；如果任何候选路由具有请求覆盖，也会报告该信息。因此，只要其中一个候选路由未声明，原生兼容性就为空；preparedAuth.source: "harness" 表示身份验证所有者，并不代表可以据此推断路由支持。

如果选中的 harness 出乎预期，请启用 agents/harness 调试日志，并检查 Gateway 网关的结构化 agent harness selected 记录：其中包含选中的 harness ID、选择原因、运行时/回退策略，以及在 auto 模式下每个插件候选项的支持结果。

内置 Codex 插件将 codex 注册为其 harness id。核心将其视为普通的插件 harness id；Codex 专用别名应位于插件或操作员配置中，而不是共享运行时选择器中。

提供商与 harness 配对

大多数 harness 还应注册提供商。提供商让 OpenClaw 的其余部分能够看到模型引用、身份验证状态、模型元数据和 /model 选择。随后，harness 会在 supports(...) 中声明支持该提供商。

内置 Codex 插件遵循此模式：

  • 首选用户模型引用：openai/gpt-5.6-sol
  • 兼容性引用：仍接受旧版 codex/gpt-* 引用，但新配置不应将其用作常规提供商/模型引用
  • harness id：codex
  • 身份验证：合成的提供商可用性，因为 Codex harness 负责原生 Codex 登录/会话
  • app-server 请求：OpenClaw 将不含前缀的模型 id 发送给 Codex，并由 harness 与原生 app-server 协议通信

Codex 插件以增量方式生效。未设置运行时策略或将其设为 auto 时，仅当提供商所拥有的路由契约声明与 codex 兼容时，OpenAI 才能选择 Codex：即精确匹配官方 HTTPS Platform Responses 或 ChatGPT Responses 路由，且没有自行设定的请求覆盖项。仅有 openai/* 前缀绝不会选择 Codex。自定义端点、Completions 适配器以及自行设定的请求行为仍由 OpenClaw 处理。明文的官方 HTTP 端点会被拒绝。较旧的 codex/gpt-* 引用仍可作为兼容性输入。请参阅 OpenAI 隐式 Agent runtime。

有关操作员设置、模型前缀示例和仅限 Codex 的配置，请参阅 Codex Harness。

Codex 插件会强制执行 Codex Harness 中记录的最低 app-server 版本。它会检查 initialize 握手并阻止较旧或未标明版本的服务器，从而确保 OpenClaw 仅针对经过测试的协议接口运行。

工具结果中间件

当内置插件和明确启用且清单契约匹配的已安装插件在其清单的 contracts.agentToolResultMiddleware 中声明目标运行时 id 时，可以通过 api.registerAgentToolResultMiddleware(...) 附加不依赖特定运行时的工具结果中间件。这个可信接口用于异步转换工具结果，并且这些转换必须在 OpenClaw 或 Codex 将工具输出反馈给模型之前运行。

旧版内置插件仍可使用 api.registerCodexAppServerExtensionFactory(...) 注册仅适用于 Codex app-server 的中间件，但新的结果转换应使用不依赖特定运行时的 API。仅适用于嵌入式运行器的 api.registerEmbeddedExtensionFactory(...) 钩子已被移除；嵌入式工具结果转换必须使用不依赖特定运行时的中间件。

终端结果分类

拥有自身协议投影的原生 harness，在已完成的轮次未产生可见的助手文本时，可以使用 openclaw/plugin-sdk/agent-harness-runtime 中的 classifyAgentHarnessTerminalOutcome(...)。该辅助函数返回 empty、reasoning-only 或 planning-only，以便 OpenClaw 的回退策略决定是否使用其他模型重试。 planning-only 要求 harness 提供显式的 planText 字段；OpenClaw 不会根据助手文本推断该字段。该辅助函数有意不对提示词错误、进行中的轮次以及 NO_REPLY 等有意保持静默的回复进行分类。

Agent 结束时的副作用

原生 harness 必须在完成一次尝试后，调用 openclaw/plugin-sdk/agent-harness-runtime 中的 runAgentEndSideEffects(...)。它会分派可移植的 agent_end 钩子和 OpenClaw 的研究捕获，同时不会延迟交互式回复。对于本地非交互式运行，如果必须等到这些副作用完成后才能结束尝试，请使用 awaitAgentEndSideEffects(...)。这两个辅助函数都接受与 runAgentHarnessAgentEndHook(...) 相同的 { event, ctx } 载荷；它们的失败不会改变已完成尝试的结果。

用户输入和工具表面

公开运行时级用户输入请求的原生 harness 应使用 openclaw/plugin-sdk/agent-harness-runtime 中的用户输入辅助函数来格式化提示词、通过 OpenClaw 的阻塞式回复路径进行传递，并将选择题/自由格式答案规范化回运行时的原生响应结构。该辅助函数可保持渠道/TUI 呈现一致，同时各 harness 仍负责自身的协议解析和待处理请求生命周期。

需要类似 PI 的紧凑工具路由的原生 harness 应使用 openclaw/plugin-sdk/agent-harness-tool-runtime 中的 createAgentHarnessToolSurfaceRuntime(...)。它负责工具搜索/代码模式控制选择、本地模型精简默认值、与运行时兼容的 schema 过滤、隐藏目录执行、目录加载和目录清理。Harness 仍负责其 SDK 特定的工具转换和原生执行回调。

Native Codex harness 模式

内置的 codex harness 是嵌入式 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置的 codex 插件；如果你的配置使用限制性允许列表，还需将 codex 加入 plugins.allow。原生 app-server 配置应使用 openai/gpt-*；仅当有效路由声明兼容 Codex 时，OpenAI 智能体轮次才会选择 Codex harness。旧版 Codex 模型引用应使用 openclaw doctor --fix 修复，而旧版 codex/* 模型引用仍作为原生 harness 的兼容性别名保留。

此模式运行时，Codex 负责原生线程 ID、恢复行为、压缩和 app-server 执行。OpenClaw 仍负责聊天渠道、可见的对话记录镜像、工具策略、审批、媒体传递和会话选择。当你需要证明只有 Codex app-server 路径能够接管运行时，请使用提供商/模型的 agentRuntime.id: "codex"。显式插件运行时采用故障关闭策略；Codex app-server 选择失败和运行时失败不会通过其他运行时重试。

运行时严格性

默认情况下，OpenClaw 使用 auto 提供商/模型运行时策略：已注册的插件 harness 可以接管兼容的有效路由；如果没有匹配项，则由嵌入式运行时处理该轮次。仅凭提供商/模型前缀绝不会选择 harness。如果缺少 harness 时应失败，而不是路由到嵌入式运行时，请使用显式的提供商/模型插件运行时，例如 agentRuntime.id: "codex"。显式选择不会使不兼容的路由变得兼容。所选插件 harness 的失败始终会导致硬失败。这不会阻止显式的提供商/模型 agentRuntime.id: "openclaw"。

对于仅使用 Codex 的嵌入式运行：

json
{  "models": {    "providers": {      "openai": {        "agentRuntime": {          "id": "codex"        }      }    }  },  "agents": {    "defaults": {      "model": "openai/gpt-5.6-sol"    }  }}

如果你想为一个规范模型使用 CLI 后端，请将运行时配置放在该模型条目中：

json
{  "agents": {    "defaults": {      "model": "anthropic/claude-opus-4-8",      "models": {        "anthropic/claude-opus-4-8": {          "agentRuntime": {            "id": "claude-cli"          }        }      }    }  }}

每个智能体的覆盖配置使用相同的模型级结构：

json
{  "agents": {    "list": [      {        "id": "codex-only",        "model": "openai/gpt-5.6-sol",        "models": {          "openai/gpt-5.6-sol": {            "agentRuntime": { "id": "codex" }          }        }      }    ]  }}

类似下面的旧版整智能体运行时示例会被忽略：

json
{  "agents": {    "defaults": {      "agentRuntime": {        "id": "codex"      }    }  }}

使用显式插件运行时后，如果请求的 harness 未注册、不支持解析后的提供商/模型，或在产生轮次副作用之前失败，会话将提前失败。对于仅使用 Codex 的部署，以及必须证明 Codex app-server 路径确实正在使用的实时测试，这是有意设计的行为。

此设置仅控制嵌入式智能体 harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商特定的模型路由。

原生会话和对话记录镜像

Harness 可以保留原生会话 ID、线程 ID 或守护进程端的恢复令牌。请确保该绑定与 OpenClaw 会话显式关联，并持续将用户可见的助手/工具输出镜像到 OpenClaw 对话记录中。

OpenClaw 对话记录仍是以下功能的兼容层：

  • 渠道可见的会话历史记录
  • 对话记录搜索和索引
  • 在后续轮次中切换回内置 OpenClaw harness
  • 通用的 /new、/reset 和会话删除行为

如果你的 harness 存储了 sidecar 绑定，请实现 reset(...)，以便 OpenClaw 在重置所属的 OpenClaw 会话时将其清除。

工具和媒体结果

核心会构建 OpenClaw 工具列表，并将其传入准备好的尝试。当 harness 执行动态工具调用时，应通过 harness 结果结构返回工具结果，而不是自行发送渠道媒体。

这样可让文本、图像、视频、音乐、TTS、审批和消息工具输出使用与 OpenClaw 支持的运行相同的传递路径。

当前限制

  • 公共导入路径是通用的，但某些尝试/结果类型别名仍为兼容性保留旧版名称。
  • 第三方 harness 安装仍处于实验阶段。在需要原生会话运行时之前，优先使用提供商插件。
  • 支持在不同轮次之间切换 harness。在原生工具、审批、助手文本或消息发送已经开始后，请勿在轮次中途切换 harness。

相关内容

Was this useful?
On this page

On this page