何时使用 harness
当某个模型家族拥有自己的原生会话运行时,而普通 OpenClaw 提供商传输抽象并不适合时,请注册一个智能体 harness。 示例:- 拥有线程和压缩逻辑的原生 coding-agent 服务器
- 必须流式传输原生计划/推理/工具事件的本地 CLI 或守护进程
- 除 OpenClaw 会话转录之外,还需要自己的恢复 ID 的模型运行时
core 仍然负责的内容
在选择 harness 之前,OpenClaw 已经解析好以下内容:- 提供商和模型
- 运行时认证状态
- 思考级别和上下文预算
- OpenClaw 转录/会话文件
- 工作区、沙箱和工具策略
- 渠道回复回调和流式传输回调
- 模型回退和实时模型切换策略
params.runtimePlan,这是一个由 OpenClaw 持有的运行时策略包,用于那些必须在 PI 和原生 harness 之间共享的运行时决策:
runtimePlan.tools.normalize(...)和runtimePlan.tools.logDiagnostics(...),用于 provider 感知的工具 schema 策略runtimePlan.transcript.resolvePolicy(...),用于转录净化和工具调用修复策略runtimePlan.delivery.isSilentPayload(...),用于共享的NO_REPLY和媒体投递抑制runtimePlan.outcome.classifyRunResult(...),用于模型回退分类runtimePlan.observability,用于已解析的 provider/模型/harness 元数据
注册 harness
导入:openclaw/plugin-sdk/agent-harness
选择策略
OpenClaw 会在提供商/模型解析完成后选择 harness:- 现有会话中记录的 harness ID 优先,因此配置/环境变量变更不会将该转录热切换到另一个运行时。
OPENCLAW_AGENT_RUNTIME=<id>会为尚未固定的会话强制使用具有该 ID 的已注册 harness。OPENCLAW_AGENT_RUNTIME=pi会强制使用内置的 PI harness。OPENCLAW_AGENT_RUNTIME=auto会让已注册的 harness 询问自己是否支持已解析的提供商/模型。- 如果没有匹配的已注册 harness,OpenClaw 会使用 PI,除非 PI 回退已禁用。
auto 模式下,仅当没有任何已注册插件 harness 支持已解析的提供商/模型时,才会使用 PI 回退。一旦某个插件 harness 已经接管一次运行,OpenClaw 不会再通过 PI 重放同一轮次,因为那可能改变认证/运行时语义,或造成副作用重复执行。
选中的 harness ID 会在一次内嵌运行后与会话 ID 一起持久化。对于在 harness 固定机制引入前创建的旧会话,只要它们已有转录历史,就会被视为已固定到 PI。要在 PI 与原生插件 harness 之间切换,请使用新的/已重置的会话。/status 会在 Fast 旁边显示非默认 harness ID,例如 codex;PI 因为是默认兼容路径,所以会隐藏。如果选中的 harness 出乎你的意料,请启用 agents/harness 调试日志,并检查 Gateway 网关中的结构化 agent harness selected 记录。它包含所选 harness ID、选择原因、运行时/回退策略,以及在 auto 模式下每个插件候选项的支持结果。
内置 Codex 插件将 codex 注册为其 harness ID。core 将其视为普通的插件 harness ID;Codex 特定别名应放在插件或运维配置中,而不应放在共享运行时选择器中。
提供商与 harness 配对
大多数 harness 也应注册一个 provider。provider 会让模型引用、认证状态、模型元数据和/model 选择对 OpenClaw 其余部分可见。然后 harness 再在 supports(...) 中声明自己接管该 provider。
内置 Codex 插件遵循这一模式:
- 首选用户模型引用:
openai/gpt-5.5加上agentRuntime.id: "codex" - 兼容性引用:旧版
codex/gpt-*引用仍然可用,但新配置不应将其用作普通 provider/模型引用 - harness ID:
codex - 认证:合成 provider 可用性,因为 Codex harness 拥有原生 Codex 登录/会话
- app-server 请求:OpenClaw 向 Codex 发送裸模型 ID,并由 harness 与原生 app-server 协议通信
openai/gpt-* 引用仍继续使用普通 OpenClaw provider 路径,除非你通过 agentRuntime.id: "codex" 强制使用 Codex harness。旧版 codex/gpt-* 引用仍会为兼容性目的选择 Codex provider 和 harness。
有关运维设置、模型前缀示例和仅 Codex 配置,请参见 Codex harness。
OpenClaw 要求 Codex app-server 为 0.125.0 或更高版本。Codex 插件会检查 app-server 初始化握手,并阻止较旧或未带版本号的服务器,以确保 OpenClaw 仅在其已测试过的协议表面上运行。0.125.0 这一最低版本包含了在 Codex 0.124.0 中引入的原生 MCP hook 载荷支持,同时也将 OpenClaw 固定在更新且已验证的稳定版本线上。
工具结果中间件
当内置插件在其清单中的contracts.agentToolResultMiddleware 声明了目标运行时 ID 时,它们可以通过 api.registerAgentToolResultMiddleware(...) 附加运行时中立的工具结果中间件。这个受信任接缝适用于那些必须在 PI 或 Codex 将工具输出回传给模型之前运行的异步工具结果转换。
旧版内置插件仍可使用 api.registerCodexAppServerExtensionFactory(...) 处理仅适用于 Codex app-server 的中间件,但新的结果转换应使用运行时中立 API。仅适用于 Pi 的 api.registerEmbeddedExtensionFactory(...) hook 已被移除;Pi 工具结果转换必须使用运行时中立中间件。
终态结果分类
拥有自身协议投影的原生 harness,可在一次已完成轮次未产生可见 assistant 文本时,使用openclaw/plugin-sdk/agent-harness-runtime 中的 classifyAgentHarnessTerminalOutcome(...)。该辅助函数会返回 empty、reasoning-only 或 planning-only,以便 OpenClaw 的回退策略判断是否应在不同模型上重试。它有意不对提示错误、进行中的轮次,以及诸如 NO_REPLY 之类的有意静默回复进行分类。
原生 Codex harness 模式
内置的codex harness 是内嵌 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置 codex 插件;如果你的配置使用了限制性允许列表,还需要将 codex 加入 plugins.allow。原生 app-server 配置应使用 openai/gpt-* 搭配 agentRuntime.id: "codex"。如果要通过 PI 使用 Codex OAuth,请改用 openai-codex/*。旧版 codex/* 模型引用仍作为原生 harness 的兼容别名保留。
在此模式下运行时,Codex 负责原生线程 ID、恢复行为、压缩和 app-server 执行。OpenClaw 仍负责聊天渠道、可见转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径才能接管该次运行时,请使用不带 fallback 覆盖的 agentRuntime.id: "codex"。显式插件运行时默认已经是失败即关闭。只有在你明确希望由 PI 处理缺失的 harness 选择时,才设置 fallback: "pi"。Codex app-server 失败本来就会直接失败,而不会通过 PI 重试。
禁用 PI 回退
默认情况下,OpenClaw 会以agents.defaults.agentRuntime 设置为 { id: "auto", fallback: "pi" } 来运行内嵌智能体。在 auto 模式下,已注册的插件 harness 可以接管某个 provider/模型组合。如果没有匹配项,OpenClaw 会回退到 PI。
在 auto 模式下,如果你需要在没有插件 harness 选中时直接失败,而不是使用 PI,请设置 fallback: "none"。显式插件运行时(如 runtime: "codex")默认已经是失败即关闭,除非在同一配置或环境变量覆盖作用域中设置了 fallback: "pi"。已选中的插件 harness 失败总是会硬失败。这不会阻止显式 runtime: "pi" 或 OPENCLAW_AGENT_RUNTIME=pi。
对于仅使用 Codex 的内嵌运行:
runtime: "auto" 并禁用回退:
OPENCLAW_AGENT_RUNTIME 仍会覆盖已配置运行时。使用 OPENCLAW_AGENT_HARNESS_FALLBACK=none 可通过环境变量禁用 PI 回退。
原生会话与转录镜像
harness 可以保留一个原生会话 ID、线程 ID 或守护进程端恢复 token。请将这种绑定明确关联到 OpenClaw 会话,并持续将用户可见的 assistant/工具输出镜像到 OpenClaw 转录中。 OpenClaw 转录仍然是以下场景的兼容层:- 渠道可见的会话历史
- 转录搜索和索引
- 在后续轮次切回内置 PI harness
- 通用
/new、/reset和会话删除行为
reset(...),以便 OpenClaw 在所属 OpenClaw 会话被重置时清除它。
工具和媒体结果
core 会构建 OpenClaw 工具列表,并将其传入已准备好的尝试。当 harness 执行动态工具调用时,请通过 harness 结果结构返回工具结果,而不是自行发送渠道媒体。 这样可以让文本、图像、视频、音乐、TTS、审批和消息工具输出,与基于 PI 的运行保持在同一投递路径上。当前限制
- 公共导入路径是通用的,但出于兼容性考虑,某些 attempt/result 类型别名仍然带有
Pi名称。 - 第三方 harness 安装仍属实验性。在你确实需要原生会话运行时之前,请优先使用提供商插件。
- 支持跨轮次切换 harness。不要在单个轮次中途切换 harness,尤其是在原生工具、审批、assistant 文本或消息发送已经开始之后。