Agent 执行器插件

​

何时使用 harness

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

​

核心仍然负责什么

• provider 和 model
• 运行时认证状态，除非该 harness 声明它拥有认证引导
• thinking level 和 context budget
• OpenClaw 转录／会话文件
• workspace、sandbox 和工具策略
• 通道回复回调和流式回调
• 模型回退和实时模型切换策略

​

原生工具策略强制执行

​

Harness 拥有的认证引导

​

已验证的设置运行时工件

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

​

请求传输契约

• runtimePolicy.compatibleIds 列出了 provider 声明与该具体路由兼容的 runtime id。缺少该 policy 表示 provider 没有声明路由级兼容性；这并不代表可以假定支持。
• requestTransportOverrides: "none" 表示没有必须被复现的已编写 provider／model 请求覆盖。"present" 表示存在已编写的 headers、auth transport、proxy、TLS、local-service、private-network 行为或请求参数。该事实不会暴露这些值。

​

注册一个 harness

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

const myHarness: AgentHarnessV2 = {
  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，以及其他已准备好的 attempt 字段。
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "我的原生 Agent",
  description: "通过原生 agent 守护进程运行选定模型。",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

​

隔离式完成

• owner: "host" 包含精确的传输 model 和已解析的 auth
• owner: "harness" 包含准备好的运行时认证计划，以及限制为该调用所选单个 profile 的凭据快照。Core 负责自动回退顺序，并针对每个候选项分别调用 harness

​

委托执行

​

选择策略

1. Model 范围的运行时策略优先。
2. Provider 范围的运行时策略其次。
3. auto 会询问已注册的 harness 是否支持已解析出的有效 路由。仅凭 provider/model 前缀永远不会选择 harness。
4. 如果没有已注册的 harness 匹配，OpenClaw 会使用其内嵌运行时。

​

provider 与 harness 配对

• 优先用户模型 refs: openai/gpt-5.6-sol
• 兼容性 refs: 旧的 codex/gpt-* refs 仍然被接受，但新的 配置不应再将它们用作常规 provider/model refs
• harness id: codex
• 认证: 合成的 provider 可用性，因为 Codex harness 拥有 原生 Codex 登录/会话
• app-server 请求: OpenClaw 将裸模型 id 发送给 Codex，并让 harness 与原生 app-server 协议交互

​

工具结果中间件

​

终态分类

​

Agent-end 副作用

​

用户输入与工具界面

import type {
  AgentHarnessAttemptParamsV2,
  AgentHarnessSideQuestionParamsV2,
  EmbeddedRunAttemptParamsV2,
} from "openclaw/plugin-sdk/agent-harness-runtime";

​

原生 MCP 清单

​

原生 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": {
    "entries": {
      "codex-only": {
        "default": true,
        "model": "openai/gpt-5.6-sol",
        "models": {
          "openai/gpt-5.6-sol": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    }
  }
}

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

​

原生会话和转录镜像

• 频道可见的会话历史
• 转录搜索和索引
• 在后续轮次中切换回内置的 OpenClaw 执行框架
• 通用的 /new、/reset 以及会话删除行为

​

工具和媒体结果

​

终端工具结果

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

​

已结算工具的最终处理

• 使用精确的受限原生 transcript，或使用在已结算工具结果边界处冻结的完整应用 transcript；
• 不暴露工具、权限授予或用户输入能力、原生执行钩子、agents、skills、memory、调度、扩展或远程控制；
• 仅发送主机提供的最终处理提示；并且
• 如果其选择的 transcript/隔离策略无法强制执行这些限制，则安全失败。

​

当前限制

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

​

相关

• SDK 概览
• 运行时辅助工具
• 提供方插件
• Codex Harness
• 模型提供方。