核心所有权

OpenClaw 在调用 runAttempt 之前准备的内容，以及宿主声明拥有工具策略、认证引导、绑定的原生会话或自身请求传输的狭窄契约。属于 Agent 宿主插件 参考的一部分。

核心仍负责什么¶

对于普通的具体模型回合，OpenClaw 在调用 runAttempt 之前准备这些输入：

• 提供商和模型，包括发现以及具体请求参数
• 运行时认证状态，除非宿主声明其拥有认证引导
• 思考级别和上下文预算
• OpenClaw 转录/会话文件
• 工作区、沙箱和工具策略
• 频道回复回调和流式回调
• 模型回退和实时模型切换策略

宿主运行已准备好的尝试；它不选择提供商、不替换频道投递，也不静默切换模型。锁定具体模型聊天不会跳过模型发现、认证准备或 Responses 参数。显式 pluginOwnerId 拥有会话控制；后续产生的 agentHarnessId 只是观察值，不是原生所有权声明。绑定的原生会话使用下面的独立所有权契约。

使用 params.hostCapabilities.createToolSurface(options) 构造 OpenClaw 工具。宿主捕获已接纳尝试的发布可用性，并在构建工具表面时应用它；宿主无需转发该事实，插件提供的选项也不能替换它。工具配置文件仍会过滤目录，并且每个可执行项仍绑定到宿主的实时权限。

本地执行的当前输入文件¶

已确认在 Gateway 宿主上进行非沙箱执行的宿主可调用 hostCapabilities.prepareInputAttachments({ placement: "local-host", maxChars, assertCurrent, signal })。宿主返回一个仅用于执行的说明，其中包含已验证可读的文档路径，并使用已接纳的输入及其捕获的媒体和工具策略。即使原生图像投影清除了普通媒体字段，它仍保留原始内容。用于转向时，传入当前 turn: { media, userTurnTranscriptRecorder }。路径元数据必须适合提供的原生输入预算。当完整说明无法容纳时，宿主会省略它，并保留原始请求和内联附件上下文。将该说明追加到当前原生输入中，而不重写 OpenClaw 的规范提示、转录或媒体引用。这种分离并不意味着宿主在回合后丢弃其原生输入：Codex 会将其保留在其原生对话历史中。准备好的路径不会替换后续回合中现有的执行和工具策略接纳。

此可选添加保留了已发布的 V2 宿主能力契约：旧宿主会省略它，因此插件在缺失时保留普通内联附件上下文。它不是远程传输、远程工作区根、已注册工作区适配器、沙箱或仅限工作区/无读取策略的回退。宿主必须从其有效连接确认放置位置，而不能从缺少工作区适配器来推断。提供的当前回合守卫和捕获的宿主权限会在等待的准备过程中以及返回路径之前进行检查。

宿主上的工作区文件¶

受信任的宿主插件可以使用从 openclaw/plugin-sdk/agent-workspace-runtime 导出的 AgentWorkspaceAccess，将现有的 agents.files.list/get/set 方法和 agents.update 身份形式绑定到已配置的远程工作区。它提供现有 SandboxFsBridge 的 stat、readFile 和 writeFile 方法；无需新的文件守护进程。

该绑定跨宿主回合持续。宿主配置工作区，并选择和认证远程目标；Gateway 不会播种第二个工作区。Gateway 保留其现有文档允许列表和授权。未配置的工作区保留本地访问。expectedHash 保留现有的尽力而为冲突检查：原生 shell 写入者不参与 Gateway 保存队列，传输失败可能导致写入结果未知。

引导加载需要桥接的 readFileWithSource 操作。它返回字节以及该读取固定的规范路径，因此现有会话过滤器可以识别受保护根 Memory 文件的别名。单独的路径查找是不够的。配置的额外文件 glob 也需要 readDirectory。缺失的能力会显式失败。压缩后的上下文也通过该绑定读取 AGENTS.md；不可用的宿主绝不会选择过期的本地副本。

对于自动 Memory 上下文，同一读取还会为工作区挂载内的文件返回 workspaceRelativePath。Memory Core 使用其现有规则和 Gateway 来源记录对该来源进行分类，而不探测 Gateway 本地文件。其他 Memory 插件必须声明 supportsWorkspaceMemoryReadSources 并消费分类器的 readSources 输入；否则自动远程 Memory 上下文会被排除。缺失的来源元数据不能选择本地副本。

异步 Skill 准备可以使用绑定的可选 loadSkills 回调。它在 Harness 上读取工作区拥有的 Skill 根，而捆绑的和 Gateway 安装的插件根保留在 Gateway 上。回调返回原生发现事实和 Harness 平台/二进制可用性；Gateway 仍会应用配置和过滤器。本地工作区以及没有 loadSkills 的仅文档绑定保留本地发现，包括在文档服务停止之后。一旦绑定提供 loadSkills，不可用的远程 Skill 访问会显式失败。

此绑定提供远程文档和引导访问。它不会启用远程 OpenClaw worker，也不会移动其 agent 循环。记忆搜索与维护、技能、附件和主机配置需要在移除工作区同步之前进行单独的集成和验证。

远程工作区的输入附件¶

受信任的 Gateway 插件可以在其现有的 AgentWorkspaceAccess 绑定上提供 prepareTurnAttachments。Core 会从 openclaw/plugin-sdk/agent-workspace-runtime 调用 prepareAgentWorkspaceAttachments，以解析已获准的输入文件，并在 harness 尝试或 Codex 转向之前调用此能力。它仅将返回的 Harness-path 注释附加到执行输入中。原始媒体引用和转录文本保留在 Gateway 上，用于图像水合和重放。

createWorkspaceAttachmentPreparer 通过现有的文件系统桥接和 createFileExclusive 实现此回调。它仅读取 Gateway 的媒体存储，传输输入文件而不替换现有的 Harness 副本，并保留现有的 50 MiB 暂存配额以及更高的已配置限制。主机通过其自身后端提供 createBridge(assertCurrent, signal)；在每个传输命令之前检查该授权和信号。

已启用但失败的传输会阻止分发。没有此可选回调的绑定保留其现有输入处理，包括内联图像；它们不会获得自动文件传输。未配置的本地工作区保持不变。此接口不会配置后端或获取凭据。每个主机适配器提供其自身已授权的桥接。

仅限主机执行¶

启动非沙箱本地应用的 harness 声明 executionEnvironment: "host-only"。Core 会在原生准备和调用之前拒绝需要沙箱、已沙箱化、仅限工作区以及不受支持的会话权限上下文。该 harness 不会实现第二个沙箱策略，也不会静默地将工作目录重新解释为限制。

Control UI 可以向管理员提供针对可选沙箱化的显式按聊天恢复操作。Gateway 拥有该变更，并重新验证原始会话和权限状态；能力声明绝不会授予移除必需沙箱或其他已配置限制的权限。

原生工具策略执行¶

仅当 runAttempt 在原生工具和内置工具、OpenClaw 工具、请求方和已配置的 MCP 服务器、应用、委派以及恢复的线程中强制执行每个显式 OpenClaw 工具策略层时，才设置 conversationToolPolicySupport: "exact"。Core 会将 params.pluginHarnessToolPolicyRestricted 作为已准备好的决策传递，表示必须隔离原生表面。

如果原生表面同时公开多个能力，请在 conversationToolPolicyNativeTools 中声明其规范的 OpenClaw 工具名称。Core 会将每个要求与有效工具配置文件和提供商配置文件进行检查，包括 agent 覆盖和 alsoAllow。缺失的能力会设置相同的限制标志。例如，Codex 声明其 shell 和文件系统工具，因此 messaging 和 minimal 配置文件会禁用原生代码模式，而 coding 和 full 会保持其可用。此声明不会放宽显式允许列表、拒绝列表、沙箱策略或运行时上限。对于独立强制执行原生可用性的 harness，省略它会保留现有配置文件处理。

具有独立管理的原生表面的 harness 还可以使用规范的 OpenClaw 工具名称声明 conversationToolPolicySafeDenyTools。仅当每个展开的拒绝项都是该已审计安全列表中的已知核心工具，并在 params.pluginHarnessToolPolicySafeDeniedTools 中传递匹配的名称时，Core 才会保留原生表面。harness 必须禁用这些名称的任何原生等效项。有限允许列表、未声明或未知的工具名称、通配符，以及包含任何未声明名称的组，仍然是原生表面限制。省略该列表可保留保守行为，即每个显式限制都会隔离原生表面。由于省略会失败关闭，新工具无法静默放宽策略边界。

当任何原生能力都可以绕过这些层时，省略该声明。然后 OpenClaw 会在调用 harness 之前显式拒绝被明确限制的轮次。操作员可以将会话切换到嵌入式运行时或升级 harness。具有限制性直接策略的 Channel /btw 旁路问题会被 core 拒绝，并且不受此声明覆盖。

对于已知且可操作的拒绝，AgentHarnessPreflightError 接受可选的 userMessage。Core 会在聊天表面上渲染此所有者编写的公开文案，而不附带冗长设置或通用的重试/重置建议。将技术上下文保留在错误的 message 和 cause 中；对于诊断失败，省略 userMessage。

Harness 拥有的身份验证引导¶

默认情况下，core 在调用 harness 之前解析提供商凭据。能够通过自身原生运行时进行身份验证的受信任 harness 可以在其静态 AgentHarness 注册上设置 authBootstrap: "harness"。然后 Core 可以委托凭据引导，而不是仅因为缺少通用提供商凭据就拒绝路由。已准备好的路由和显式配置文件要求仍然适用。

当存在兼容的、显式选择或排序的 OpenClaw 身份验证配置文件及其作用域存储时，Core 仍会转发该配置文件。harness 必须在发出模型请求之前解析该配置文件或其原生凭据，将密钥限定在尝试范围内，并呈现可操作的身份验证失败。不要仅在有时拥有身份验证的 harness 上设置此能力。此静态引导能力与已绑定原生会话的模型和连接的所有权不同。

已绑定原生会话的所有权¶

可选的 resolveSessionRuntimeOwnership({ config, agentId, sessionId, sessionKey, storePath, readPreviousSessionId, assertCurrent }) 回调报告私有绑定所有权。Core 仅在验证持久会话身份后，在精确固定的 harness 上调用它。sessionId 和 assertCurrent 是必需的；其余参数是可选的。同步返回：

• { model: "native", auth: "native" } 当绑定通过其原生连接同时拥有模型选择和身份验证时。
• { model: "native", auth: "host" } 当它拥有模型选择但仍需要宿主身份验证准备时。
• undefined 当不存在匹配的原生模型绑定时。对于已验证的原生运行框架固定，已实现的回调返回 undefined 是所有者不可用错误：显式失败，不进行常规发现或创建新的原生线程。重试前重新附加原始原生会话。

省略回调会为第三方运行框架保留常规的具体模型/身份验证准备。具体插件拥有的聊天从不查询它；仅运行时请求或模型锁定无法建立原生所有权。配对节点 Codex 会话使用其所属节点处理器；缺失的本地绑定不得将错误路由的延续变成本地运行。

仅当两个值都来自同一绑定时，才包含 modelRef: { provider, model }。不要从外部配置、凭据或用法推断缺失值。宿主身份验证所有权在凭据准备前需要此元组；原生身份验证待定分支可以省略它，直到其原生所有者选择模型。

仅当运行框架在每次推理分发前绑定实际原生选择（包括恢复后）时，才声明 nativeModelPolicySupport: "exact"。使用 hostCapabilities.bindModelExecution({ provider, model }) 或下面的保留源操作。观察返回的取消信号，在等待准备之后以及传输写入和结果结算之前立即重新检查其断言，并在执行清理后释放它。获取绑定时，签发宿主必须处于活动状态。签发的绑定保留原始源直到释放；宿主关闭会阻止新的直接获取，但不会撤销已接受的原生工作。显式 Stop、会话和传输权限，以及真实源或模型策略撤销仍然适用。缓存的恢复前模型不是不同恢复模型的权限。当操作员具有模型策略时，缺少支持会拒绝原生拥有的推理。当运行没有操作员源时，该方法返回 undefined；普通宿主操作检查和原生回合结算保留其现有生命周期。宿主仅向声明精确支持的运行框架暴露直接模型绑定器。其他运行框架通过其现有源能力保留未知模型保护；引入模型策略会取消该未限定工作。

对于可在前台完成后选择模型的已接受工作，在宿主活动时获取 hostCapabilities.retainSourceAuthority()。其 bindModelExecution(...) 操作使用相同的原始源，直到该工作释放保留的能力。每个模型绑定拥有其保留，并必须在分发清理后释放；关闭保留的工作会取消其模型绑定。实时的 modelPolicyRequired 事实支持连接预检；缺失的事实表示未知，而非无限制。实时的 sourceIdentity 是不透明相等性令牌，用于检查活动输入是否共享同一原始源；它从不授予执行权限。当其工作结算时释放保留权限，而不是将创建者的权限永久附加到可重用的原生线程。

同步读取现有私有绑定。在读取前后调用 assertCurrent()。不要发现模型、回收一个世代、启动客户端、进行身份验证或修改绑定。断言在回调返回时过期。此所有权事实既不是执行权限，也不是凭据就绪。

如果当前绑定缺失，readPreviousSessionId?.() 从调用方选择的存储中读取此确切物理会话的最新前驱。当行缺失或已被替换时，它返回 undefined。它不接受参数，并在所有权回调返回时过期。仅在绑定未命中时使用它，而不是加载通用会话运行时或跨等待准备携带血统快照；当前绑定无需读取血统。前驱标识一个待检查的绑定，而不是回收或执行它的权限。

Codex 实现从 preserveNativeModel 报告原生模型所有权。它仅为独立的私有监督连接报告原生身份验证；在托管连接上保留模型会使身份验证保留在宿主。原生身份验证绑定使用其已验证的连接，而不是测试无关的外部模型路由/身份验证元数据或转发宿主配置。原生连接策略仍然适用。显式的每次运行提供商流参数会被拒绝而不是丢弃；使用具体模型聊天来应用它们。

对于宿主身份验证绑定，实际原生元组控制模型、身份验证和请求传输准备。显式配置锁定仍然严格；自动配置轮换仍然可用。该元组上的已编写设置和显式每次运行参数必须由固定运行时支持，而不是静默丢弃或通过另一个运行时重定向。

核心将转向和待定问题权限绑定到最终准备好的模型路由，使用回复的原始调用方策略快照作为其指纹和传入消息投影。原生所有权或模型选择钩子不会替换该快照或授权不同的调用方。

核心将可选的 expectedSessionRuntimeOwnership 带入尝试，包括宿主身份验证绑定的 modelRef。这是一个非授权比较，不是绑定、凭据或保留能力。在预检期间、绑定租约下，以及在恢复后针对就绪线程进行推理前重新验证。变更的宿主身份验证元组会拒绝过期的已准备凭据，同时保留新观察到的绑定。原生身份验证连接可以跟随其原生所有者的模型变更。缺失或变更的所有权绝不能启动替换线程。

同一同步读取提供会话行、事件和会话范围聊天元数据。原生身份验证元数据仅针对会话的渲染模型省略不适用的宿主可用性字段；它不会设置 available: true 或修改共享目录。待定原生分支在存在原生元组之前仍可能显示已配置的占位符。

一次尝试可以报告来自其就绪原生线程的 runtimeModelSelection: { provider, model }。Core 仅在已准备好的原生所属运行中接受此诊断。它会将所选模型与响应/计费归属分开记录，因此宿主终结器的模型不会覆盖原生会话的选择。

已验证的设置运行时产物¶

能够为首次运行设置提供推理的本地 harness 必须证明完成探测的实现。当 params.captureRuntimeArtifact 为 true 时，返回一个带有稳定 id 和内容指纹的不透明 result.runtimeArtifact。注册一个匹配的 runtimeArtifact.validate(...) 能力，以重新检查该绑定，且不加载不同的 harness 或扫描不相关的插件。

已验证的 OpenClaw 继续运行也会传递 params.expectedRuntimeArtifact。harness 必须将其与自己所获取的确切原生进程进行比较，如果二者不同，则在启动或恢复原生线程之前失败。普通 agent 轮次会省略这两个字段，因此内容哈希不会进入常规请求热路径。远程/WebSocket harness 需要服务器证明契约后才能参与；单靠版本字符串不能构成产物身份。

准备好的尝试还包含 params.runtimePlan，这是一个 OpenClaw 拥有的策略包，用于运行时决策；它必须在 OpenClaw 和原生 harness 之间保持共享：

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

Harness 可以为需要与 OpenClaw 行为保持一致的决策使用该计划，但应将其视为宿主拥有的尝试状态：不要修改它，也不要在一轮之内使用它切换 provider/模型。

对于模型可见的回复策略，来自 openclaw/plugin-sdk/agent-harness-runtime 的 buildHarnessVisibleReplyGuidance 接受已准备好的投递模式、实际消息工具的可用性，以及解析后的 requireExplicitMessageTarget 事实。请为每一轮提供这些事实。使用独立静态提示词的 harness 可以使用同一接缝的 buildUiPresentationPrompt 来获得稳定的 UI 引导，同时将投递和目标指令保留在后期上下文中。

对于辅助会话控制调用，来自 openclaw/plugin-sdk/model-session-runtime 的 resolveSessionModelRef 解析当前模型选择。来自 openclaw/plugin-sdk/agent-harness-runtime 的 prepareAgentRuntimeAuth 从调用方已加载的 auth 快照中选择其 auth 路由和有顺序的凭据尝试。在具体化凭据时，保留所选尝试的 profile、API 和回退限制；这能使控制调用与 agent 轮次保持在同一计费路由上。

对于同时支持独立执行和 Gateway 执行的工具，来自 openclaw/plugin-sdk/agent-harness-runtime 的 hasGatewayToolRoutingContext() 报告调用方或宿主进程是否拥有 Gateway 路由。本地嵌入的 RPC 上下文不计为运行中的 Gateway。调用方或环境绑定在其 Gateway 退役后仍然存在，因此分发可以拒绝过期的调用。该辅助函数不检查凭据、不授予权限，也不保证 Gateway 可用。

请求传输契约¶

supports(ctx) 在 ctx.modelProvider 中接收已解析的模型传输。两个不含机密的 provider 自有事实描述了所选路由：

• runtimePolicy.compatibleIds 列出 provider 声明与该具体路由兼容的运行时 id。策略缺失意味着 provider 未声明路由级兼容性；这并不等于可以假定支持。
• requestTransportOverrides: "none" 表示无需复现任何已编写的 provider/model 请求覆盖。"present" 表示存在已编写的 headers、auth 传输、代理、TLS、本地服务、私有网络行为或请求参数。该事实不会暴露这些值。

当 harness 无法复现准备好的传输时，返回 { supported: false, reason }。不要在完成选择后通过读取原始配置来推断支持。仅当内置运行时能够在不丢弃已编写行为的情况下复现确切准备好的请求时，才添加 fallbackRuntime: "openclaw"。Core 随后会对显式选择、持久化选择以及多路由重试集合使用该回退。对于必须保持故障关闭的 provider、路由或身份验证失败，请勿添加该字段。

当 auth 准备产生多条重试路由时，一个 harness 必须在分发前支持所有这些路由。如果没有插件能拥有完整集合，隐式选择将使用 OpenClaw；显式或持久化的插件选择则故障关闭，除非该插件声明了无损的 OpenClaw 回退。

每轮时间上下文¶

拥有自己模型提示词的原生 harness 可以使用来自 openclaw/plugin-sdk/agent-harness-runtime 的 buildTemporalContextText。它会渲染与内置 OpenClaw 运行时相同的当前本地日期和时区。当配置了 agents.defaults.userTimezone 时使用该配置，否则使用宿主时区。

请在每一轮调用它，并在已知最终工具面之后调用。仅当该确切工具面包含 session_status 时才传递 sessionStatusAvailable: true；这样可以在工具不可用的提示词中省略精确时间提示。请通过原生运行时现有的每轮应用或开发者上下文携带结果，而不是将其附加到稳定的线程指令中。