古法编程

Appearance

Agent Harness 是替换 OpenClaw 默认 PI 执行器的底层接口，适用于需要原生会话运行时的模型家族（如 Codex 本地编码代理）。注册时需在 supports 中声明支持的 provider/model，选择策略支持 auto 模式（优先匹配插件，否则回退 PI）或显式指定运行时 ID。当前为实验性特性，第三方插件安装需谨慎，推荐对常规 HTTP/WebSocket 模型使用 provider 插件。

OpenClaw Agent Harness 插件配置与运行时选择 ​

一个 Agent Harness（智能体执行器）是为一次准备好的 OpenClaw 智能体轮次执行的低层执行器。它不是模型提供者、渠道或工具注册表。关于面向用户的心理模型，请参阅 智能体运行时。

仅限捆绑或受信任的本机插件使用此接口。此契约仍为实验性，因为参数类型有意镜像当前内置运行器。

何时使用 Harness ​

当某个模型家族有自己的原生会话运行时，而常规的 OpenClaw provider 传输层是错误抽象时，应注册 Agent Harness。

示例：

  • 原生编码代理服务器，拥有线程和压缩控制权
  • 必须流式输出原生计划/推理/工具事件的本地 CLI 或守护进程
  • 除了 OpenClaw 会话转录外，还需要自己的恢复 ID 的模型运行时

不要仅仅为了添加一个新的 LLM API 而注册 Harness。对于常规的 HTTP 或 WebSocket 模型 API，请构建 provider 插件。

OpenClaw 核心仍负责什么 ​

在 Harness 被选中之前，OpenClaw 已经解析了：

  • provider 和 model
  • 运行时认证状态
  • 思考级别和上下文预算
  • OpenClaw 转录/会话文件
  • 工作区、沙箱和工具策略
  • 渠道回复回调和流回调
  • 模型回退和实时模型切换策略

这种拆分是有意的。Harness 执行一次准备好的尝试；它不选择 provider、替换渠道投递或静默切换模型。

准备好的尝试还包括 params.runtimePlan，一个 OpenClaw 拥有的运行时决策策略包，必须跨 PI 和原生 Harness 共享：

  • runtimePlan.tools.normalize(...) 和 runtimePlan.tools.logDiagnostics(...) 用于 provider 感知的工具模式策略
  • runtimePlan.transcript.resolvePolicy(...) 用于转录净化和工具调用修复策略
  • runtimePlan.delivery.isSilentPayload(...) 用于共享的 NO_REPLY 和媒体投递抑制
  • runtimePlan.outcome.classifyRunResult(...) 用于模型回退分类
  • runtimePlan.observability 用于已解析的 provider/model/harness 元数据

Harness 可以使用该策略做出需要与 PI 行为一致的决策，但仍应将其视为主机拥有的尝试状态。不要修改它或在轮次内切换 provider/model。

注册 Agent Harness ​

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

typescript
import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

const myHarness: AgentHarness = {
  id: "my-harness",
  label: "My native agent harness",

  supports(ctx) {
    return ctx.provider === "my-provider"
      ? { supported: true, priority: 100 }
      : { supported: false };
  },

  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: "My Native Agent",
  description: "Runs selected models through a native agent daemon.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

选择策略 ​

OpenClaw 在 provider/model 解析后选择 Harness：

  1. 模型级别的运行时策略优先。
  2. provider 级别的运行时策略次之。
  3. auto 模式询问已注册的 Harness 是否支持已解析的 provider/model。
  4. 如果没有注册的 Harness 匹配，OpenClaw 使用 PI，除非 PI 回退被禁用。

插件 Harness 失败会表现为运行失败。在 auto 模式下，仅当没有注册的插件 Harness 支持解析的 provider/model 时，才会使用 PI 回退。一旦插件 Harness 声明了某次运行，OpenClaw 不会将同一轮次重新通过 PI 执行，因为可能改变认证/运行时语义或重复副作用。

整个会话或整个智能体的运行时固定设置会被选择忽略。这包括过期的会话 agentHarnessId 值、agents.defaults.agentRuntime、agents.list[].agentRuntime 和 OPENCLAW_AGENT_RUNTIME。/status 显示从 provider/model 路由选择的有效运行时。 如果选择的 Harness 出乎预期，启用 agents/harness 调试日志并检查网关的结构化 agent harness selected 记录。它包含选中的 Harness id、选择原因、运行时/回退策略，以及在 auto 模式下每个插件的支持结果。

捆绑的 Codex 插件注册了 codex 作为其 Harness id。核心将其视为普通插件 Harness id；Codex 特定的别名应放在插件或算子配置中，而不是共享的运行时选择器中。

Provider 与 Harness 配对 ​

大多数 Harness 还应注册一个提供者。提供者使模型引用、认证状态、模型元数据和 /model 选择对 OpenClaw 其余部分可见。然后 Harness 在 supports(...) 中声明该 provider。

捆绑的 Codex 插件遵循此模式：

  • 首选用户模型引用：openai/gpt-5.5
  • 兼容性引用：旧式 codex/gpt-* 引用仍接受，但新配置不应将其用作常规 provider/model 引用
  • Harness id：codex
  • 认证：合成 provider 可用性，因为 Codex Harness 拥有原生 Codex 登录/会话
  • 应用服务器请求：OpenClaw 将纯 model id 发送给 Codex，让 Harness 与原生应用服务器协议通信

Codex 插件是附加性的。普通 openai/gpt-* 智能体引用在官方 OpenAI provider 上默认选择 Codex Harness。较旧的 codex/gpt-* 引用仍然为兼容性选择 Codex provider 和 Harness。

关于算子配置、模型前缀示例和仅 Codex 配置，请参阅 Codex Harness。

OpenClaw 要求 Codex 应用服务器版本 0.125.0 或更高。Codex 插件检查应用服务器初始化握手并阻止较旧或无版本服务器，确保 OpenClaw 只与经过测试的协议表面交互。0.125.0 下限包括 Codex 0.124.0 中的原生 MCP hook 负载支持，同时将 OpenClaw 固定到更新的经过测试的稳定版本。

工具结果中间件 ​

捆绑的插件可以通过 api.registerAgentToolResultMiddleware(...) 附加运行时无关的工具结果中间件，前提是它们的清单在 contracts.agentToolResultMiddleware 中声明了目标运行时 id。此受信任接口用于在 PI 或 Codex 将工具输出反馈给模型之前执行的异步工具结果转换。

遗留的捆绑插件仍可使用 api.registerCodexAppServerExtensionFactory(...) 处理仅限 Codex 应用服务器的中间件，但新的结果转换应使用运行时无关的 API。仅限 PI 的 api.registerEmbeddedExtensionFactory(...) 钩子已被移除；PI 工具结果转换必须使用运行时无关的中间件。

终端结果分类 ​

拥有自己协议投影的原生 Harness 可以使用 openclaw/plugin-sdk/agent-harness-runtime 中的 classifyAgentHarnessTerminalOutcome(...)，当完成的轮次没有生成可见的助手文本时。该辅助函数返回 empty、reasoning-only 或 planning-only，使 OpenClaw 的回退策略能够决定是否在另一个模型上重试。它特意不分类提示错误、进行中的轮次以及有意的静默回复（如 NO_REPLY）。

原生 Codex Harness 模式 ​

捆绑的 codex Harness 是用于嵌入式 OpenClaw 智能体轮次的原生 Codex 模式。首先启用捆绑的 codex 插件，如果你的配置使用限制性允许列表，则需在 plugins.allow 中包含 codex。原生应用服务器配置应使用 openai/gpt-*；OpenAI 智能体轮次默认选择 Codex Harness。遗留的 openai-codex/* 路由应使用 openclaw doctor --fix 修复，遗留的 codex/* 模型引用仍然是原生 Harness 的兼容性别名。

当此模式运行时，Codex 拥有原生线程 id、恢复行为、压缩和应用服务器执行。OpenClaw 仍然拥有聊天渠道、可视转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex 应用服务器路径可以声明运行此轮次时，使用 provider/model agentRuntime.id: "codex"。显式插件运行时失败关闭；Codex 应用服务器选择失败和运行时失败不会通过 PI 重试。

运行时严格性 ​

默认情况下，OpenClaw 使用 auto provider/model 运行时策略：已注册的插件 Harness 可以声明 provider/model 对，当没有匹配时 PI 处理轮次。官方 OpenAI provider 上的 OpenAI 智能体引用默认指向 Codex。当缺少 Harness 选择应失败而非路由到 PI 时，使用显式 provider/model 插件运行时，如 agentRuntime.id: "codex"。选中的插件 Harness 失败始终硬失败。这不会阻塞显式 provider/model agentRuntime.id: "pi"。

对于仅 Codex 的嵌入式运行：

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

如果你希望一个 CLI 后端对应一个规范模型，将运行时放在该模型条目上：

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

每个智能体的覆盖使用相同的模型级形状：

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

像这样的遗留全局智能体运行时示例会被忽略：

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

使用显式插件运行时，当请求的 Harness 未注册、不支持已解析的 provider/model 或在产生轮次副作用之前失败时，会话会提前失败。这是 Codex 专用部署和需要证明 Codex 应用服务器路径实际在使用的实时测试的有意行为。

此设置仅控制嵌入式 Agent Harness。它不禁用图像、视频、音乐、TTS、PDF 或其他 provider 特定的模型路由。

原生会话与转录镜像 ​

Harness 可能保留原生会话 id、线程 id 或守护进程侧的恢复令牌。将该绑定显式关联到 OpenClaw 会话，并将用户可见的助手/工具输出镜像到 OpenClaw 转录中。

OpenClaw 转录保持兼容性层，用于：

  • 渠道可见的会话历史
  • 转录搜索和索引
  • 在稍后的轮次中切换回内置 PI Harness
  • 通用的 /new、/reset 和会话删除行为

如果你的 Harness 存储了侧车绑定，请实现 reset(...)，使 OpenClaw 在重置所属的 OpenClaw 会话时能清除它。

工具与媒体结果 ​

核心构造 OpenClaw 工具列表并将其传递到准备好的尝试中。当 Harness 执行动态工具调用时，通过 Harness 结果形状返回工具结果，而不是自行发送渠道媒体。

这使文本、图像、视频、音乐、TTS、审批和消息工具输出与 PI 支持的执行走相同的投递路径。

当前限制 ​

  • 公共导入路径是通用的，但某些尝试/结果类型别名仍带有 Pi 名称以保持兼容性。
  • 第三方 Harness 安装是实验性的。在需要原生会话运行时之前，优先选择 provider 插件。
  • 跨轮次支持切换 Harness。不要在轮次中间切换 Harness，即原生工具、审批、助手文本或消息发送开始之后。

相关文档 ​

常见问题 ​

如何注册一个自定义的 Agent Harness？ ​

导入 openclaw/plugin-sdk/agent-harness 中的 AgentHarness 类型，实现 supports 和 runAttempt 方法，然后在插件入口的 register 中调用 api.registerAgentHarness(myHarness)。确保 supports 返回一个包含 supported: true 的对象，并可选指定 priority。

Agent Harness 选择失败/PI 回退未生效怎么解决？ ​

检查 /status 查看实际选中的运行时 id，并启用 agents/harness 调试日志查看 agent harness selected 记录。常见原因包括：Harness 未注册、supports 未匹配当前 provider/model、PI 回退被禁用（如设置了 agentRuntime.id 为插件 id 但插件未注册）、或选择了旧式的全局 agentRuntime 设置（已被忽略）。确保使用 provider/model 级别的 agentRuntime.id 而不是 agents.defaults.agentRuntime。

Agent Harness 的运行时严格性设置有什么用？ ​

agentRuntime.id: "codex" 等显式设置可强制使用指定插件，当匹配失败时直接报错，不经过 PI 回退。适用于 Codex 专用部署或需要验证原生路径的测试。默认 auto 模式会先尝试插件，无匹配才回退 PI。注意该设置仅影响嵌入式 Agent Harness，不影响其他模型路由（如图像、TTS 等）。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策