插件运行时模型助手

运行主机拥有的文本完成，无需导入提供程序内部或重复 OpenClaw model/auth/base URL 准备工作。

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",});

直接提供者完成使用与代理轮流相同的身份验证配置文件健康策略来记录凭证失败，并尝试下一个合格的配置文件。每个配置文件每次完成最多尝试一次。显式 model@profile 引脚和提供商绑定的凭据保持固定状态。当池耗尽时，最后一个提供者错误仍然以 stopReason: "error" 解决；呼叫者应在使用文本之前检查该字段。成功的请求将清除该模型所选配置文件的失败状态。重试保留原始运行时租约并在分派前重复授权检查。

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

要通过配置的代理运行时需要新的推理，请显式选择隔离执行：

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,  },});

该模式只接受一条用户消息。核心派生已配置的 CLI 或harness所有者，启动新的上下文，不提供模型可调用工具，并且永远不会回退到直接提供程序传输。不受支持的运行时在推理之前失败。 result.execution.owner 报告所选所有者；当 CLI 无法报告时，令牌使用情况仍然不存在。

代理 API 对字面上的零工具保证有一个已记录的例外情况：尽管没有执行程序或提供的工具，但其受限会话可能会保留服务拥有的帮助程序。输出拒绝不能阻止这些助手在推理过程中采取行动。需要零工具的调用者必须选择强制执行该边界的运行时。参见隔离完成合约。

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

Provider 编排还可以在发出 HTTP 请求前获取已配置的本地服务生命周期：

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

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

传递准确配置的提供商 ID 和解析的请求基 URL。不要用适配器 ID 替换别名：单独的别名可以指向单独的本地 GPU 主机。除了 Ollama 和 LM Studio 适配器使用的 /v1 规范化之外，主机拒绝与配置的提供程序基础 URL 不匹配的端点。主机拥有启动序列化、就绪检查、请求租用、中止处理和空闲关闭。

此辅助工具使用与 OpenClaw 内置运行时相同的简单补全准备路径，以及宿主拥有的运行时配置快照。上下文引擎会接收与会话绑定的 llm.complete 能力，因此模型调用使用活动会话的 agent，不会静默回退到默认 agent。结果包含 provider/model/agent 归属信息，以及可用时规范化的令牌、缓存和估算成本用量。

当没有记录成本或 configured/eligible 目录定价可用时，将省略 usage.costUsd。默认填充的零费率并不建立免费使用。显式运营商零定价和提供商计费零总额仍为 0；记录的请求成本保留其原始定价等级。

直接完成可以为提供者本机约束输出设置 responseFormat。当提供者公开它们时，结果还包括具体的responseModel和终端stopReason。对安全敏感的呼叫者可以设置requiredAuthMode: "oauth"；然后，主机在分派之前拒绝选定的非 OAuth 凭证。隔离的代理运行时完成在分派之前拒绝这些直接提供者控制。

OpenAI 和 Azure 响应接受原始 JSON 架构作为 responseFormat，并将其包装在带有 type: "json_schema" 和名称 openclaw_response 的 text.format 中。保留原生 json_schema、json_object 和 text 格式；聊天完成样式的嵌套 json_schema 描述符针对响应进行扁平化，包括任何提供的 strict 值。

设置 reasoning 以请求对所选模型进行推理。主机接受标准思维级别（off、minimal、low、medium、high、xhigh、adaptive、max 和ultra）。直接完成映射 adaptive 到 medium 和 ultra 到 max；选定的提供商传输将每项工作映射到其支持的线路值。显式 off 达到提供商的残疾人思维策略；是否可以禁用思维取决于所选的模型和认证路径。

Codex 隔离完成通过本机模型的支持工作量映射传递显式推理级别。当省略推理时，这些有界调用将保持其省力的默认值。

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

resolveDefaultModelForAgent({ cfg, agentId }) 解析代理的默认配置。 resolveAllowedModelRef({ cfg, catalog, raw, defaultProvider, defaultModel, agentId }) 根据提供的目录和代理白名单解析模型名称或别名，返回 { ref, key } 或 { error }。它不选择或验证代理运行时；需要特定harness的呼叫者必须应用该单独的策略。

resolveModelRuntimePolicy({ config, provider, modelId, agentId?, sessionKey? }) 读取配置的运行时策略。它按顺序遵循确切的 agent/default 模型条目、提供者模型条目、提供者通配符条目和提供者策略。配置时，结果包括 policy 及其 source（"model" 或 "provider"）；当没有策略匹配时，结果为空对象。此查找不会选择隐式运行时默认值或检查harness可用性。

使用这些主机操作而不是将模型选择实现模块导入到插件的注册条目中。

模型和 provider 认证解析。

还提供同步配置文件操作：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,});