Plugin SDK Agent Harness

概述

Agent Harness 是单次准备好的 OpenClaw Agent 轮次的低级执行器。它不是模型 Provider、不是 Channel、也不是工具注册表。仅用于捆绑或受信任的原生插件，合约仍为实验性。

适用场景： 模型家族有自己的原生会话运行时，且普通 OpenClaw Provider 传输是错误的抽象时（如原生编码 Agent 服务器、本地 CLI/守护进程、需要自己 resume ID 的模型运行时）。

不适用场景： 仅添加新 LLM API 时，应构建 Provider 插件。

核心 API

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

AgentHarness 接口

type AgentHarness = {
  id: string;
  label: string;
  supports(ctx): { supported: boolean; priority?: number };
  runAttempt(params): Promise<AgentHarnessAttemptResult>;
  reset?(sessionKey: string): Promise<void>;
};

注册方法

api.registerAgentHarness(myHarness);

选择策略（优先级）

1. 模型作用域运行时策略优先
2. Provider 作用域运行时策略次之
3. auto 模式询问已注册 harness 是否支持解析的 provider/model
4. 无匹配时使用 PI（除非禁用 PI 回退）

核心仍拥有的内容

在 harness 被选中之前，OpenClaw 已解析：provider 和 model、运行时认证状态、思考级别和上下文预算、OpenClaw 转录/会话文件、工作区/沙箱/工具策略、Channel 回复回调和流式回调。

runtimePlan 策略包

• runtimePlan.tools.normalize(...) — Provider 感知工具 Schema 策略
• runtimePlan.transcript.resolvePolicy(...) — 转录清理和工具调用修复策略
• runtimePlan.delivery.isSilentPayload(...) — 共享 NO_REPLY 和媒体投递抑制
• runtimePlan.outcome.classifyRunResult(...) — 模型回退分类

工具结果中间件

api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});

使用示例

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) {
    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);
  },
});

Codex-only 配置示例

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

相关页面

• concepts/plugin-sdk-overview — SDK 注册 API
• concepts/plugin-sdk-runtime — 运行时辅助工具
• concepts/plugin-sdk-provider-plugins — Provider 插件（普通 HTTP API 用这个）
• agent-runtimes — 运行时类型用户视角