注册

注册调用本身，以及已注册挂接器可以添加的两项可选能力：一次全新的无工具推理调用，以及同意受信委托方执行一个锁定模型的既有会话。本文是 Agent 挂接器插件 参考文档的一部分。

注册挂接器¶

导入： 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 在此通用示例中被有意省略。仅当挂接器满足挂接器自有认证引导契约时，才添加 authBootstrap: "harness"。

隔离式补全¶

可选的 runIsolatedCompletionV2(params) 能力服务于此类产品路径：它们要求一次全新的、仅提示词的推理调用，且模型可调用的工具表面必须是字面意义上的空集。Core 会传入提供方 ID 和模型 ID、提示词、时限控制，以及一份已备好的 authorization：

• owner: "host" 包含精确的传输 model 和已解析的 auth。
• owner: "harness" 包含已备好的运行时认证方案，以及一份仅限为该调用选定的单个配置文件的凭据快照。Core 负责自动回退顺序，并为每个候选分别调用挂接器。

Agents API 是对字面空工具表面的已文档化例外：它会创建一个不含执行器、所提供函数、网络搜索、保险库或子代理的全新会话，但服务方可能保留内置辅助工具。此受限模式默认启用。拒绝带有工具的输出并不能阻止辅助工具在推理期间动作。要求字面零工具保证的调用方必须选择能提供该保证的运行时。

每次新的隔离式补全都使用其获准入的运行时代次的配置和 agent/workspace 目录。在该代次准备期间，显式指定的模型、认证配置文件和运行时选择保持固定不变。

主机授权调用必须使用所提供的模型和凭据，不得替换。使用共享的主机预备补全辅助工具的挂接器，会保留完全一致的路线、时限、采样选项和空工具表面。挂接器授权调用只能解析所提供的预备路线和作用域内的配置文件；若方案将认证交由挂接器处理，也可解析挂接器的原生账户。挂接器不得切换路线、复用原生线程、附加工具、调用代理生命周期钩子，或交付输出。

若提供了该函数，应在准备工作等待完成之后、每次凭据交接、推理请求或进程启动（包括重试）之前立即调用 params.assertCurrent()。它会重新校验调用方的实时授权，并在补全结束时失效。抛出断言会结束执行；不要将其视为凭据失败，也不要用其他配置文件重试。继续遵循 abortSignal；授权失效后，清理操作仍须保持可用。

返回 { assistant: AssistantMessage }。Core 仅接受带有 stop 或 length 停止原因的最终文本/思考内容；工具调用、失败停止和空输出均会被拒绝。标题请求会设置 outputTextPolicy: "strict-visible"：保持推理内容分离，不将含歧义的推理恢复为可见文本；空可见结果是有效的。主机预备辅助工具会将此策略映射为恢复之前的严格解析；省略该策略则保留普通恢复行为。基于 CLI 的标题调用也允许干净的空输出，而无需静默回复令牌；普通 CLI 调用仍会拒绝空响应。

较旧的外部挂接器可能忽略该策略；最终的标题过滤器无法恢复已被挂接器丢弃的来源信息，因此这并非普适的推理隐私保证。除已文档化的 Agents API 限制外，若挂接器无法强制隔离，则应省略该能力。要求隔离式补全的调用方之后会在调用该挂接器之前按失败关闭（fail closed）处理；OpenClaw 不会通过另一个运行时重放该请求。插件调用方通过 api.runtime.llm.complete({ execution: { mode: "isolated-agent-runtime" } }) 请求隔离执行；挂接器回调是提供方侧的强制 SPI，而非第二个调用方 API。

旧版 runIsolatedCompletion(params) 仅支持主机认证的能力已弃用，并将在 2026-10-12 之前继续对外部插件可用。对于挂接器自有或原生认证，请实现 V2 能力；仅存在旧版能力时，OpenClaw 绝不会自行编造主机凭据。

原生 Agent 服务器通常自带环境内置工具，即使 OpenClaw 发送的是空工具列表也是如此。请针对新一轮次禁用这些原生能力并做出证明，使用可序列化真正零工具请求的独立传输，或让该能力保持不受支持。Agents API 保留上述已文档化例外，直到其服务能够强制该边界为止。

审计证据遵循相同边界。OpenClaw 可以记录已注册插件的归属和运行准入，但无法从 ACP 更新或会话记录中主张外部原生副作用。若副作用完全发生在该运行时内部，则视为 unsupported，除非适配器在该动作之前调用 OpenClaw 拥有的回调。不要从原生工具状态事件中重构此回调。

委托执行¶

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

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