跳转至

模型辅助工具

调用模型、解析模型选择策略并解析提供商身份验证,而无需导入宿主内部实现。属于 插件运行时辅助功能 参考的一部分。

独立命令的受保护模型出口

withConfiguredModelEgress 来自 openclaw/plugin-sdk/secret-egress-runtime, 会为官方插件运行一个显式的独立命令,并使用与目标绑定的凭据哨兵。它会通过常规密钥解析器解析所选提供商已配置的 API 密钥 SecretRef,包括基于文件的密钥,并使用提供商的模型路由策略来确定其 443 端口上的 HTTPS 端点。它支持 OpenAI 兼容的 Responses 和 Completions 路由。OAuth、auth-profile 引用、自定义请求头和自定义请求传输不受支持。 这是一个仅限 JavaScript 的私有宿主绑定,面向捆绑发布和单独发布的官方插件,而不是第三方插件 API。

const { withConfiguredModelEgress } = await import("openclaw/plugin-sdk/secret-egress-runtime");
await withConfiguredModelEgress({ config, provider, model, signal }, async (egress) => {
  // Keep hostEnv on the credential-owning host for the authenticated bridge.
  // Send only sentinel, baseUrl, model, and public caBundle to the remote app.
  await runRemoteAppThroughBridge(egress, signal);
});

回调会接收 sentinel、baseUrl、model、allowedHosts、hostEnv 以及公开的 caBundle 内容。提供 onOutput(text, stream) 以接收实时输出,其中已解析的凭据会被脱敏,包括跨块拆分的值;将回调的 onOutputChunk 传递给命令运行器。调用方拥有自己的桥接和远程进程,必须遵守取消操作,并必须在回调结束前等待两者完成。取消会立即撤销代理访问权限;回调完成或失败会撤销访问权限、停止隔离代理,并删除其私有 CA 目录。凭据和代理授权永远不会进入共享密钥存储。

这是一个显式的命令作用域代理,使用现有的密钥出口实现。它不需要启用或重启 Gateway 的持久出口代理。仅在命令执行路径中导入该 SDK 模块;仅导入它并不会加载模型或密钥运行时代码。

已准备的简单补全

openclaw/plugin-sdk/simple-completion-runtime 辅助函数支持一次性准备模型,并反复使用该模型进行补全。成功的准备会保留其 model、auth 和 selection 字段所使用的提供商资源。宿主拥有这些资源,因此调用方可以复用结果而无需 disposer:

const result = await prepareSimpleCompletionModelForAgent({ cfg, agentId });
if ("error" in result) {
  throw new Error(result.error);
}
const prepared = result;
const response = await completeWithPreparedSimpleCompletionModel({
  model: prepared.model,
  auth: prepared.auth,
  cfg,
  context: { messages },
});

准备过程接受可选的 signal;取消可防止迟到的设置返回可用模型。资源清理可以在逻辑错误之后继续;宿主关闭会等待已接受的设置和清理工作。保留的结果在其宿主关闭之前保持由宿主拥有,宿主会等待已接受的补全工作后再释放提供商资源。重复的兼容准备会共享现有代次的资源。来自已关闭宿主的结果无法启动另一个补全;请在当前宿主下重新准备。

低层补全

来自 openclaw/plugin-sdk/llm 的 complete 和 completeSimple 辅助函数接受可选的第四个 assertCurrent 回调。它在传输设置之后、提供商分发之前立即运行。抛出错误或 options.signal 被中止都会阻止分发;该回调保持在提供商选项之外。现有的三参数调用仍然受支持。

同一 SDK 子路径中的 resolveOpenAIModelReasoningEfforts、resolveOpenAIReasoningEffortMap 和 resolveOpenAIReasoningEffortMapping 辅助函数会读取 OpenAI 模型的 effort 能力以及已配置的原生映射。

原生 harness 可以使用来自 openclaw/plugin-sdk/agent-harness-attempt-runtime 的 selectSupportedReasoningEffort,并传入其经过验证的 effort 顺序和受支持的 effort。它会保留受支持的请求;否则选择下一个更高的受支持 effort;如果没有更高的,则选择最高可用 effort。后端适配器保留协议验证和特殊模式处理。

模型命名空间

api.runtime.llm
运行宿主拥有的文本补全,而无需导入提供商内部实现或重复 OpenClaw 的模型/身份验证/base URL 准备。

```typescript
const result = await api.runtime.llm.complete({
  messages: [{ role: "user", content: "Summarize this transcript." }],
  purpose: "my-plugin.summary",
  maxTokens: 512,
  temperature: 0.2,
  reasoning: "high",
});
```

`maxTokens` 和 `temperature` 是建议性的采样提示。所选提供商、CLI 或 harness 会在其传输暴露等效控制时应用它们,否则可能忽略它们。它们不会削弱执行模式的隔离保证。

若要要求通过已配置的 agent runtime 进行全新推理,请显式选择隔离执行:

```typescript
const result = await api.runtime.llm.complete({
  messages: [{ role: "user", content: "Return one JSON value." }],
  systemPrompt: "You are a JSON-only function.",
  model: "openai/gpt-6-astra",
  execution: {
    mode: "isolated-agent-runtime",
    authProfileId: "openai:work",
    timeoutMs: 30_000,
  },
});
```

此模式恰好接受一条用户消息。Core 会推导已配置的 CLI 或 harness 所有者,启动全新上下文,不提供模型可调用的工具,并且从不回退到直接提供商传输。不受支持的运行时会在推理前失败。`result.execution.owner` 报告所选所有者;当 CLI 无法报告 token 用量时,该用量保持缺失。

Agents API 有一个已记录的例外,针对字面意义上的零工具保证: 其受限会话即使没有执行器或提供的工具,也可能保留服务拥有的辅助工具。输出拒绝无法阻止这些辅助工具在推理期间执行操作。要求零工具的调用方必须选择强制该边界的运行时。参见 隔离完成契约。

    完成失败会在抛出的错误上公开一个稳定的 `code`。隔离调用方可以区分授权、无效的隔离输入、不支持或不可用的运行时、中止、超时、被拒绝的输出以及其他完成失败,而无需匹配消息文本。

    提供方编排也可以在发出 HTTP 请求之前获取已配置的本地服务生命周期:

    ```typescript
    const lease = await api.runtime.llm.acquireLocalService(
      {
        providerId,
        baseUrl,
        headers,
      },
      signal,
    );
    try {
      // Send and fully consume the provider request.
    } finally {
      await lease?.release();
    }
    ```

    `acquireLocalService(...)` 是一个稳定的、通用的提供方服务 SDK 契约。宿主从
    `models.providers.<providerId>.localService` 解析进程配置;调用方不能提供命令、参数、环境变量或生命周期策略。进程生成、就绪状态、诊断和空闲停止策略仍属于宿主内部。

    传入精确配置的提供方 ID 和已解析的请求基础 URL。不要用适配器 ID 替换别名:不同的别名可能指向不同的本地 GPU 宿主。宿主会拒绝与配置的提供方基础 URL 不匹配的端点,除了 Ollama 和 LM Studio 适配器使用的 `/v1` 规范化。宿主负责启动串行化、就绪检查、请求租约、中止处理和空闲关闭。

    该辅助函数使用与 OpenClaw 内置运行时和宿主拥有的运行时配置快照相同的简单完成准备路径。上下文引擎接收与会话绑定的 `llm.complete` 能力,因此模型调用使用活动会话的代理,而不会静默回退到默认代理。结果包括提供方/模型/代理归属,以及在可用时的规范化 token、缓存和估算成本使用情况。

    当没有记录的成本或已配置/符合条件的目录定价可用时,会省略 `usage.costUsd`。默认填充的零费率不会确立免费使用。显式操作员零定价和提供方计费的零总额保持为 `0`;记录请求成本保留其原始定价层级。

    直接完成可以设置 `responseFormat`,用于提供方原生约束输出。当提供方公开它们时,结果还包括具体的 `responseModel` 和终止 `stopReason`。安全敏感调用方可以设置 `requiredAuthMode: "oauth"`;宿主随后会在分发前拒绝所选的非 OAuth 凭据。隔离代理运行时完成会在分发前拒绝这些直接提供方控制。

    OpenAI 和 Azure Responses 接受原始 JSON Schema 作为 `responseFormat`,并将其包装在 `text.format` 中,带有 `type: "json_schema"` 和名称 `openclaw_response`。原生 `json_schema`、`json_object` 和 `text` 格式会被保留;Chat Completions 风格的嵌套 `json_schema` 描述符会被展平用于 Responses,包括任何提供的 `strict` 值。

    设置 `reasoning` 以请求所选模型的推理努力。宿主接受规范思考级别(`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive`、`max` 和 `ultra`)。直接完成将 `adaptive` 映射到 `medium`,将 `ultra` 映射到 `max`;所选提供方传输将每个努力映射到其支持的线路值。显式 `off` 会到达提供方的禁用思考策略;思考是否可以禁用取决于所选模型和认证路由。

    Codex 隔离完成通过原生模型的支持努力映射传递显式推理级别。当省略 reasoning 时,这些有界调用保持其低努力默认值。

!!! warning

    模型覆盖需要操作员通过配置中的 `plugins.entries.<id>.llm.allowModelOverride: true` 选择加入。`plugins.entries.<id>.llm.allowedModels` 限制这些覆盖;`plugins.entries.<id>.llm.allowedCompletionModels` 单独限制每个完成,包括宿主解析的默认值。对于直接完成,`model@profile` 覆盖仍然是已授权模型覆盖的一部分。隔离的 `model@profile` 覆盖和 `execution.authProfileId` 需要 `plugins.entries.<id>.llm.allowAuthProfileOverride: true`。跨代理完成需要 `plugins.entries.<id>.llm.allowAgentIdOverride: true`。

??? note "api.runtime.modelConfig"

同步模型选择策略,无需准备模型或启动会话。

`resolveDefaultModelForAgent({ cfg, agentId })` 解析代理的已配置默认值。`resolveAllowedModelRef({ cfg, catalog, raw, defaultProvider, defaultModel, agentId })` 根据提供的目录和代理允许列表解析模型名称或别名,返回 `{ ref, key }` 或 `{ error }`。它不会选择或验证代理运行时;需要特定 harness 的调用方必须应用该独立策略。

`resolveModelRuntimePolicy({ config, provider, modelId, agentId?, sessionKey? })` 读取已配置的运行时策略。它按顺序遵循精确代理/默认模型条目、提供方-模型条目、提供方通配符条目和提供方策略。结果在配置时包括 `policy` 及其 `source`(`"model"` 或 `"provider"`),或在无策略匹配时包括空对象。此查找不会选择隐式运行时默认值或检查 harness 可用性。

请改用这些主机操作,而不是将模型选择实现模块导入插件的注册入口。

api.runtime.modelAuth

模型和提供商身份验证解析。

同步配置文件操作也可用:resolveProviderIdForAuth、ensureAuthProfileStore、resolveAuthProfileOrder、listProfilesForProvider 和 isProviderApiKeyConfigured。它们使用规范的主机身份验证策略。读取代理配置文件时,请提供所属代理目录,并在非交互式配置文件检查时使用 readOnly: true 和 allowKeychainPrompt: false。配置文件存储和已解析的凭据不得记录日志。

能力工厂应仅构造描述符。将凭据检查和解析保留在需要它们的回调中,而不是在注册提供商时执行。

const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });

// Request-ready auth, including provider runtime exchanges (e.g. OAuth refresh)
const runtimeAuth = await api.runtime.modelAuth.getRuntimeAuthForModel({ model, cfg });

const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
  provider: "openai",
  cfg,
});

预置补全 SDK 兼容性

新的插件代码请优先使用 api.runtime.llm.complete。现有 openclaw/plugin-sdk/simple-completion-runtime 的调用方可以继续通过 prepareSimpleCompletionModelForAgent 准备模型,并通过 completeWithPreparedSimpleCompletionModel 执行它。

执行器接受可选的 options.headers 和 options.sessionId 字段。省略这些字段的调用保持相同的调用形式。对于 HTTPS OpenCode 端点,独立补全会在每次调用时获得一个新的不透明 x-opencode-session 路由头。显式的模型或调用方路由头会抑制生成,无论头名称大小写如何。调用方头优先于模型头。

提供的 sessionId 会保留其现有的提供商会话和缓存行为。除非显式头覆盖它,否则它还会提供 OpenCode 路由头。生成的路由值仅保留在头中:它不会创建会话、转录、提示缓存或 WebSocket 会话的所有权。现有传输重试会复用该调用的头;执行器不添加重试策略。

这些预置结果没有释放方法。其原始 Gateway 或 CLI 主机会在关闭前保留模型资源;独立调用方会在进程生命周期内保留它们。已关闭的主机会拒绝新的准备和执行。关闭过程会等待已接受的提供商回调和取消工作,然后释放预置资源,即使补全已经返回。

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