跳转至

注册

注册调用本身,以及已注册的 harness 可以添加的两项可选能力:一次全新的无工具推理调用,以及允许受信任的委托方执行一个现有的模型锁定会话的许可。属于 Agent harness 插件 参考的一部分。

注册 harness

导入: openclaw/plugin-sdk/agent-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: "My native 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: "effective route is not harness-compatible" };
  },

  async runAttempt(params) {
    // Start or resume your native thread.
    // Use params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent, and the other prepared attempt fields.
    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);
  },
});

在此通用示例中,authBootstrap 被有意省略。仅当 harness 满足 harness 拥有的 auth bootstrap 契约 时,才添加 authBootstrap: "harness"。

执行器控制器插件

具有由提供商管理的工作区的 harness 可以声明 workspaceEnvironment: { kind: "provider-hosted", label: "Provider workspace" }。Gateway 会将此元数据投影到已配置的模型/运行时选择上,以便 Control UI 能够区分托管工作区、本地文件夹和云工作器。仅对当前激活的托管配置声明它,不要用于自托管执行器。此展示元数据不授予任何可用性、身份验证、放置或文件同步能力;这些能力仍由其现有所有者负责。

harness 可以将自托管执行器的连接管理委托给另一个插件。使用 api.registerAgentExecutorController(...) 注册一个控制器。注册表根据注册插件的 ID 分配所有权;控制器不会选择其他 ID,也不会注册第二个 harness。

使用使用此控制器的运行时 ID 声明 activation.onAgentHarnesses,例如 ["my-harness"]。此清单提示会将插件包含在准备好的运行时注册表中,而无需注册 harness。仅启动激活并不会将该插件包含在每个模型选择的注册表中。

import type { AgentExecutorController } from "openclaw/plugin-sdk/agent-harness-runtime";

const controller: AgentExecutorController = {
  workspaceDirectory: "/srv/agent/workspace",
  async ensure(binding, context) {
    context.assertCurrent();
    await connectExecutor(binding, context.signal);
    context.assertCurrent();
  },
  async retire(binding, context) {
    context.assertCurrent();
    await disconnectExecutor(binding, context.signal);
    context.assertCurrent();
  },
};

api.registerAgentExecutorController(controller);

workspaceDirectory 是执行器上的绝对路径。它可以与 Gateway 的工作区不同。AgentExecutorBinding 包含 sessionKey、agentId、nativeSessionId、environmentId、remoteUrl 和 workspaceDirectory。ensure 会幂等地连接或重新连接该确切环境;retire 会幂等地释放该环境的连接。这两个操作都不会创建或删除原生 agent 会话。控制器拥有其传输、凭据和进程管理。对于 Agents API,每个原生会话拥有其直接执行器进程;多个会话可以共享同一主机和持久工作区。就绪检查和连接请求是分开的:harness 会为当前的 environment_connection 操作调用 ensure,包括在其输入提交等待期间,而不是在每一轮之前进行探测。

Harness 实现从 openclaw/plugin-sdk/agent-harness-runtime 导入 resolveAgentExecutorController(pluginId),并在已接受的调用期间解析显式配置的插件。解析仅使用该调用的注册表,并在所有者缺失、禁用或不可用时失败。它不会激活插件,也不会回退到进程全局注册表。当注册表代际或所有者退役,或其注册被替换时,句柄会过期;应在每次调用中解析新句柄,而不是跨轮次缓存一个句柄。

传入带有必需的 signal 和 assertCurrent 的 AgentExecutorContext。宿主会将调用方取消与注册表和插件生命周期结合,在每次操作前后检查权限,并在控制器调用 assertCurrent 时保留调用方的作用域。控制器实现必须遵守信号,并在 await 之后以及每个副作用之前重新检查权限。断言在操作完成时过期。

harness 保留会话绑定持久性、原生就绪检查、退役前的工作结算以及可重试的清理。执行器控制器不会授予重置无关会话或停止共享运行时的权限。

如果 harness 的 reset 无法结算必需的原生工作,则会从 openclaw/plugin-sdk/agent-harness-runtime 抛出 AgentHarnessSessionCleanupError。宿主会等待其他清理回调,然后在替换本地会话之前拒绝重置。普通重置钩子错误仍为尽力而为。回复驱动的重置在提交其会话边界之前使用相同的必需清理检查。

隔离完成

The optional runIsolatedCompletionV2(params) capability serves product paths that require one fresh prompt-only inference call with a literal empty model-callable tool surface. Core 传递提供商和模型 ID、prompt、截止时间控制以及一个已准备好的 authorization:

  • owner: "host" 包含精确的传输 model 和已解析的 auth。
  • owner: "harness" 包含已准备好的运行时身份验证计划,以及一个仅限该调用所选单个配置文件使用的凭据快照。Core 拥有自动回退顺序,并针对每个候选项分别调用 harness。

Agents API 是字面空工具面的已记录例外:它创建一个没有执行器、提供的函数、网络搜索、保险库或子 agent 的全新会话,但服务可能保留内置辅助工具。此受限模式默认启用。拒绝包含工具的输出并不能阻止辅助工具在推理期间采取行动。需要字面零工具保证的调用方必须选择提供该保证的运行时。

每个新的隔离完成使用其已准入运行时代次的配置以及 agent/workspace 目录。在该代次准备期间,显式的模型、auth-profile 和运行时选择保持固定。注册表准备选择提供商和 harness 所有者,包括其声明的 harness 依赖项。准备过程不会仅因为 agent 选择了它们就添加 memory 或 context-engine 插件,也不会添加无关的启动插件,并且不会采用 Gateway agent 能力。

主机授权的调用必须使用提供的模型和凭据,不得替换。使用共享主机准备完成辅助工具的 harness 会保留精确的路由、截止时间、采样选项和空工具面。harness 授权的调用只能解析所提供的已准备路由和范围限定的配置文件,或者当计划将 auth 留给 harness 时,解析 harness 的原生账户。harness 不得切换路由、复用原生线程、附加工具、调用 agent 生命周期钩子或交付输出。

要在 utility-model 设置中报告相同的执行路由,harness 可以添加 resolveIsolatedCompletionRuntime({ authorizationOwner }),其中 owner 为 "host" 或 "harness"。当该授权所有者使用共享主机准备完成辅助工具时,返回 "openclaw";当 harness 执行调用时,返回 "self"。如果没有此钩子,设置将报告 harness 本身。保持选择器同步且无副作用,并在隔离分发中复用它,使报告的路由跟随执行。

当提供时,在准备 await 之后、每次凭据交接、推理请求或进程启动之前(包括重试)立即调用 params.assertCurrent()。它会重新验证调用方的实时权限,并在完成结束时过期。抛出的断言会终止执行;不要将其视为凭据失败,也不要使用另一个配置文件重试。继续遵守 abortSignal;权限过期后清理必须仍然可用。

返回 { assistant: AssistantMessage }。Core 仅接受带有 stop 或 length 停止原因的终结文本/思考内容;工具调用、失败停止和空输出会被拒绝。标题请求设置 outputTextPolicy: "strict-visible":将推理保持分离,不要将模糊的推理恢复为可见文本;空的可见结果是有效的。主机准备辅助工具会将此策略映射为恢复前的严格解析。省略则保留普通恢复行为。基于 CLI 的标题调用也允许干净的空输出,无需静默回复 token;普通 CLI 调用仍会拒绝空响应。较旧的外部 harness 可能忽略该策略;最终标题过滤器无法恢复 harness 已丢弃的溯源,因此这不是通用的推理隐私保证。除了已记录的 Agents API 限制外,如果 harness 无法强制隔离,则省略该能力。需要隔离完成的调用方随后会在调用该 harness 之前失败关闭;OpenClaw 不会通过另一个运行时重放请求。插件调用方通过 api.runtime.llm.complete({ execution: { mode: "isolated-agent-runtime" } }) 请求隔离执行;harness 回调是提供商侧的强制 SPI,而不是第二个调用方 API。

旧版 runIsolatedCompletion(params) 仅主机授权能力已弃用,并将在 2026-10-12 之前继续对外部插件可用。为 harness 拥有或原生身份验证实现 V2;当仅存在旧版能力时,OpenClaw 绝不会虚构主机凭据。

原生 agent 服务器通常具有常驻内置工具,即使 OpenClaw 发送空工具列表也是如此。对于新轮次,禁用并证明这些原生能力,使用能够序列化真正零工具请求的独立传输,或保持该能力不受支持。Agents API 保留上述已记录例外,直到其服务能够强制该边界。

审计证据遵循相同边界。OpenClaw 可以记录已注册插件的所有权和运行准入,但不能从 ACP 更新或转录中声称外部原生副作用。完全位于该运行时内部的副作用为 unsupported,除非适配器在操作前调用 OpenClaw 拥有的回调。不要从原生工具状态事件重建回调。

委托执行

harness 所有者可以将 delegatedExecutionPluginIds 设置为需要执行现有模型锁定会话的受信任插件 ID,例如语音传输继续 Codex 支持的对话。这是静态所有者同意,而不是核心允许列表。保持其范围狭窄。

委托方仅接收工作准入和嵌入式执行。OpenClaw 要求精确的已存储会话密钥、存储路径和会话 ID;modelSelectionLocked: true;以及匹配的 agentHarnessId 和 agentHarnessRuntimeOverride 值。然后,运行通过 harness 所有者进行范围限定。会话创建、修补、重置、删除、归档和 Gateway 变更仍仅限所有者。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw