原生清单
harness 向 OpenClaw 控制面暴露的只读目录:带有就绪状态的原生模型行,以及由进程内 MCP 运行时之外拥有的 MCP 工具清单。属于 Agent harness 插件 参考的一部分。
原生模型清单¶
loadModelCatalog(params) 为提供的 agent、workspace 和 config 快照列出模型。由原生模型选择拥有的行会将 nativeRuntime 设置为 harness ID,并省略 host 的 api 和 baseUrl 声明。Core 不会使用 host 路由中的传输或能力来增强这些行。
返回 { entries, outcomes },以在行旁边报告无密钥的发现结果。结果使用 provider 目录状态 ready、auth-rejected 和 unavailable;仅目录层面的认证拒绝会设置 rejectionScope: "catalog"。不要包含原始原生错误或凭据数据。失败的 provider 保留其先前行,而成功的同级项会更新。空的成功结果(包括已禁用或缺失的 app)会清除该 runtime 的先前结果。Core 会独立于 API provider 认证,将这些事实与原生 runtime 一起保留。针对 2026.9.5 SDK 构建的插件仍支持普通行数组。
意外抛出的发现错误会保持 host 的通用部分失败行为。host 不会根据 runtime 名称或任意异常文本推断 provider 或认证拒绝;harness 必须提供其自身的已知 provider 结果。
可选的同步 readModelCatalogReadiness(params) 仅返回 { accountType: string },用于覆盖该确切范围和模型的当前原生账户观察。保留原生账户类型;它并不意味着 host 凭据或 OAuth 刷新生命周期。对于缺失、失败、被取代或已释放的观察,返回 undefined。就绪状态必须保留在物理原生所有者处,并在使用时重新验证;切勿将其序列化到目录行上、在此回调中执行 I/O,或从先前成功的一轮中推断。Gateway 使用此元数据用于原生拥有的选择器行;编写的 host 路由、凭据和 profile 锁仍使用 host 就绪状态。这不是执行授权,所有运行时兼容性和权限检查仍然适用。
服务层级选择器策略¶
可选的同步 filterModelServiceTiers 钩子会缩小为 harness runtime 显示的服务层级:
filterModelServiceTiers(params: {
config: OpenClawConfig;
agentId?: string;
provider: string;
modelId: string;
serviceTiers: readonly string[];
}): readonly string[];
Gateway 在解析账户和路由服务层级证据后调用此钩子,既针对所选模型行,也针对替代 runtime 选项。提供的 config 是已准备目录的快照。在 harness 中解释插件特定策略;core 不读取私有插件 config。
返回一个子集,且不修改输入或执行 I/O 或发现。Core 将结果与已解析的层级求交集,保留其顺序并忽略新增的层级。如果没有该钩子,层级保持不变。未知层级的可用性仍保持未知,并且不会调用该钩子。这仅影响选择器元数据;harness 在执行一轮时仍必须执行其策略。
原生 MCP 清单¶
在 OpenClaw 进程内 MCP 运行时之外拥有 MCP 连接的 harness 可以实现 loadMcpToolCatalog(params)。该回调用于只读控制面,例如 composer 的 Tool 访问视图。它接收权威的会话身份、runtime config、workspace 和稀疏的会话 MCP 覆盖。mcpServerNames 是有界的 OpenClaw 配置服务器集合,harness 可以表示其会话策略。仅针对该集合返回 OpenClaw 的 McpToolCatalog 结构。
仅使用已绑定的原生进程和线程。返回 undefined 表示没有可用的实时目录;不要仅为回答清单而启动新的 harness 进程。保留原始 server/tool 名称,使用 assignMcpCatalogSafeServerNames(...) 分配防冲突的 server 名称,并将仅由会话拒绝隐藏的工具保留在 sessionDeniedTools 中。Core 在暴露行之前仍会应用最终的 OpenClaw 工具策略和 schema 兼容性检查。
用于物化工具视图的 SessionMcpRuntime 实现应提供 joinCleanup()。它会等待已从该确切 runtime 请求的清理,包括未发布或正在退役的服务器,如果任何拥有的清理失败或无法确认,则拒绝。它必须为后续调用者保留该失败,同时不关闭仍被另一轮租用的传输。仅一个已完成的尽力而为 dispose() 并不是清理证据。
该方法对现有 SDK 实现是可选的;自动一次性恢复会将缺失的方法视为不确定的清理。当外层 runtime 单独拥有并验证进程生命周期时,不拥有传输的原生 facade 可以立即 resolve。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw