跳转至

后台任务

在后台启动代理工作:通过钩子分发面向外部内容和子代理运行的回合。属于插件运行时辅助工具参考的一部分。

后台工作命名空间

api.runtime.hooks

为不受信任的外部内容触发器(例如邮件监视器)分发隔离的代理回合。与 api.runtime.subagent.run(...) 不同,钩子分发会包装外部内容,对同一会话的运行进行串行化,并通过 Gateway 报告完成情况。插件回合共享 cron 执行预算,且无需 HTTP hooks 端点。当启用 HTTP hooks 时,该共享预算中仍保留一个槽位用于 HTTP 工作。

const result = await api.runtime.hooks.dispatchHookAgentTurn({
  name: "IMAP inbox",
  agentId: "mail",
  sessionKey: "hook:imap:account:123:456",
  message: "Summarize the new email and identify any requested actions.",
  externalContentSource: "email",
  deliver: true,
  thinking: "low", // optional
  timeoutSeconds: 60, // optional
  idempotencyKey: "account:123:456", // optional
});

if (!result.ok) {
  api.logger.warn(`Hook agent turn was rejected: ${result.reason}`);
}

agentId 为必填项,sessionKey 必须以 hook: 开头,且不能包含空白字符或控制字符。externalContentSource 目前仅接受 "email";外部内容包装无法禁用。将 deliver 设置为 false 可在不广播的情况下记录完成状态。成功准入返回 { ok: true, runId };被拒绝的准入返回 { ok: false, reason }。

此能力仅对捆绑插件和受信任的官方插件安装可用。它不需要启用或配置 HTTP hooks 端点。

api.runtime.subagent

启动并管理后台子代理运行。

对于无需保留会话或回复投递的无工具完成请求,请使用 complete(...):

const { text } = await api.runtime.subagent.complete({
  agentId: "research", // required configured agent that owns this work
  message: "Summarize these notes.",
  extraSystemPrompt: "Return a concise summary.", // optional
  timeoutMs: 30_000, // optional; defaults to 30 seconds
  // model: "openai/gpt-5.6-luna", // optional authorized override
  // signal: abortController.signal, // optional cancellation
});

agentId 和 message 为必填项。extraSystemPrompt、model、timeoutMs 和 signal 为可选项。当省略 model 时,所选代理将提供其配置的默认模型和凭据所有者。结果为 { text: string };无需创建会话、轮询消息、删除会话或投递完成通知。配置的运行时必须支持全新的、无工具的隔离推理;不支持的运行时会在推理前失败。

完成请求使用共享后台队列,在三个运行的总预算内,每个插件最多可运行三个。取消会立即移除排队中的工作。正在运行的工作会保留其槽位,直到底层运行时清理完成,之后被拒绝;在取消、超时或运行时退役后,迟到的输出不会被返回。调用需要有活跃的 Gateway 绑定和插件身份。请求作用域内的调用保留调用者的操作员作用域和代理访问权限;在操作员工具调用期间启动的完成请求会在该调用结束时被取消。模型覆盖保留以下现有的子代理授权和 allowedModels 策略。

当需要会话或代理工具界面时,请使用 run(...):

// Start a subagent run
const { runId, sessionKey } = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  toolsAlsoAllow: ["my_plugin_progress"],
  promptMode: "minimal", // optional bounded subagent prompt
  provider: "openai", // optional override
  model: "gpt-6-astra", // optional override
  deliver: false,
  completionDelivery: "current-requester", // optional, before_dispatch hooks only
});

// Wait for completion
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });

// Read session messages
const { messages } = await api.runtime.subagent.getSessionMessages({
  sessionKey: "agent:main:subagent:search-helper",
  limit: 10,
});

// Delete a session
await api.runtime.subagent.deleteSession({
  sessionKey: "agent:main:subagent:search-helper",
});

由 Gateway 支持的运行会在 runId 旁边返回规范的、已接受的 sessionKey。该字段仅在 TypeScript 结果中为可选项,以便显式自定义运行时保持兼容。

waitForRun(...) 返回规范的 Gateway 等待结果。status 为 "ok"、"error"、"timeout" 或 "pending";pending 是正常的非终止观测结果,而不是异常。可选的 error、startedAt、endedAt、stopReason、livenessState、yielded、pendingError、timeoutPhase、providerStarted 和 terminalReply 元数据会保留,以便调用者区分观测超时与终止结果。timeoutMs 限制等待调用的时长;它不会取消运行。

Warning

在授权的 Gateway 请求之外,模型覆盖需要操作员通过配置中的 plugins.entries.<id>.subagent.allowModelOverride: true 选择启用。未选择启用的插件可以使用配置的模型,但覆盖请求会被拒绝。

plugins.entries.<id>.subagent.allowedModels 可以将覆盖限制为规范的 provider/model 目标。同样的策略适用于 complete;请求作用域内的调用保留其已认证客户端的覆盖权限。检查使用目标代理的模型配置(包括精确配置的模型 ID),并应用于插件的初始覆盖。配置的默认值、操作员安装的模型路由钩子以及自动模型回退保留各自的选择策略。

toolsAlsoAllow 将调用插件注册的、精确且唯一拥有的工具添加到工作器的常规工具面。运行时拒绝核心工具以及与另一插件共享的名称。配置档和运营者工具策略仍然适用,包括显式允许列表和拒绝列表。

所有者授权的命令启动可以将其捕获的断言作为 subagent.run({ ..., assertCurrent }) 传递;Gateway 在运行准入时应用它。受管理的 worktrees.create({ ..., commitGuard }) 通过其现有创建所有者接受同一断言。撤销会阻止待处理的启动或 worktree 写入,而已接受的工作保留其清理和完成职责。

promptMode: "minimal" 选择有界的子代理提示,而不是完整对话提示。插件运行时仅暴露此模式;省略时保留完整提示。当运行必须具有精确的空工具面时,也使用 disableTools: true。

completionDelivery: "current-requester" 默认关闭,并且仅在 before_dispatch 钩子正在处理经过身份验证的入站请求时可用。OpenClaw 在调用插件之前捕获规范请求者会话和投递路由,然后通过常规公告路径投递子代理完成。插件不能提供或覆盖请求者谱系或目标字段。在该请求者绑定的钩子上下文之外的调用会被拒绝。

deleteSession(...) 可以删除由同一插件通过 api.runtime.subagent.run(...) 创建的会话。删除任意用户或运营者会话仍需要管理员范围的 Gateway 请求。

原生 harness 完成投递

捆绑的 harness 使用 openclaw/plugin-sdk/agent-harness-completion 通过现有的请求者完成投递所有者路由原生子结果。deliverAgentHarnessCompletion 需要主机签发的 AgentHarnessCompletionScope 和一个存活的 isSourceSessionAdmissionAllowed 回调。保持该回调绑定到精确的原生分配及其当前父级。请求者身份和准入会在等待路由之后、新副作用之前重新检查。原生运行时历史、取消和提交回执仍由 harness 拥有;没有通用任务注册表或受管理流程 API。

对于分离的原生工作,在准入父级注册期间、发布注册或启动原生子工作之前,等待 captureAgentHarnessCompletionCustody(scope)。准备阶段保留原始请求者生命周期,并在返回保管权之前拒绝替换或撤销。每个已接受的子分配通过 retain() 保留其自身的持有,并在投递其结果时将其作为 completionCustody 传递。当其注册或分配结束时释放每个持有。该持有保留原始运营者上限和请求者生命周期;它不授予通用工具访问权限,也不会在撤销或 Gateway 关闭后继续存在。

将 createAgentHarnessCompletionEventSink(...) 绑定到相同的完成保管权和用于精确原生分配的 isSourceCurrent 回调。在原生终端持久化和首次完成交接稳定后,在休眠投递重试之前调用 completionCustody.settleExecution()。这会释放执行排空义务,同时保留完成投递权限。重启后,恢复必须从存活注册中捕获新的保管权并验证其请求者;存储的历史记录从不授予权限。

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