Agent harness plugins

​

何时使用 harness

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

​

核心仍负责的内容

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

​

Harness 负责的身份验证引导

​

已验证的设置运行时工件

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

​

请求传输契约

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

​

注册 harness

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

const myHarness: AgentHarness = {
  id: "my-harness",
  label: "我的原生 agent 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);
  },
});

​

委托执行

​

选择策略

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

​

提供商与 harness 配对

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

​

工具结果中间件

​

终止结果分类

​

智能体结束时的副作用

​

用户输入和工具表面

​

Native Codex harness 模式

​

运行时严格性

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

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

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

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

​

原生会话和转录副本

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

​

工具和媒体结果

​

工具终止结果

• 如果存在协议调用 ID，请传入该 ID、规范工具名称，以及 经准备或钩子重写后实际传递给工具的参数。
• 当验证、审批或其他防护机制 在工具实现开始前阻止调用时，请设置 executionStarted: false。一旦可能已发生分派， 应保守地报告 true。
• 报告 outcome: "success" 或 outcome: "failure"。请包含运行时提供的结构化 失败字段，而不是根据显示文本推断失败。
• 仅对未使用 OpenClaw 工具 定义的原生工具使用 nativeMutation。在此提供协议所属的变更和重放事实；不要 将 OpenClaw 的变更分类器复制到 harness 中。

​

已结算工具最终处理

• 使用确切的受限原生转录，或完整且冻结至已结算工具结果边界的应用 转录；
• 不暴露任何工具、权限授予或用户输入能力、原生执行 钩子、智能体、Skills、记忆、调度、扩展或远程控制；
• 仅发送宿主提供的最终处理提示；并且
• 如果所选的转录/隔离策略无法实施 这些限制，则采用失败关闭策略。

​

当前限制

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

​

相关内容

• SDK 概览
• 运行时辅助函数
• 提供商插件
• Codex harness
• 模型提供商