@openclaw/ai 包

@openclaw/ai 是 OpenClaw 模型执行层可发布的库形式：提供商中立的消息/工具/流契约、验证、诊断、事件流、隔离的运行时注册表，以及针对八个内置 API 家族的惰性适配器（Anthropic Messages、OpenAI Completions、OpenAI Responses、Azure OpenAI Responses、ChatGPT/Codex Responses、Google Generative AI、Google Vertex、Mistral Conversations）。

它在每次发布时与根 openclaw 包一起发布，并固定到相同版本。其精确版本固定的直接依赖在安装时解析；该包不附带 npm lockfile。安装 openclaw 会自动安装匹配的 @openclaw/ai，库使用者可以直接依赖它，而无需任何 OpenClaw 应用代码。

快速开始¶

import { createLlmRuntime } from "@openclaw/ai";
import { registerBuiltInApiProviders } from "@openclaw/ai/providers";

const runtime = createLlmRuntime();
registerBuiltInApiProviders(runtime.registry);

// `model` (a model descriptor), `messages`, and `apiKey` are supplied by you;
// see `examples/ai-chat` for concrete values.
const stream = runtime.streamSimple(model, { messages }, { apiKey });
for await (const event of stream) {
  if (event.type === "text_delta") process.stdout.write(event.delta);
}
const result = await stream.result();

仓库中 examples/ai-chat 提供了一个可运行版本。

设计契约¶

• 默认实例作用域。 导入该包不会在全局注册任何内容。createApiRegistry() / createLlmRuntime() 返回隔离的实例；registerBuiltInApiProviders(registry) 使某个注册表启用内置传输。提供商 SDK 模块在首次使用时惰性加载。
• 宿主策略通过注入而非捆绑。 请求 fetch 防护（例如 SSRF 策略）、工具结果重放文本中的密钥脱敏、OpenAI strict-tool 默认值以及诊断日志记录，都是使用 configureAiTransportHost 配置的 AiTransportHost 端口。库的默认值不生效；OpenClaw 在其流外观中安装其真实实现。
• 统一的事件流标识。 @openclaw/ai/event-stream 是 OpenClaw 核心、agent-core 和外部使用者共享的规范 EventStream 构造函数。
• internal/* 子路径不是 API。 它们仅用于 OpenClaw 应用本身，不提供 semver 保证。
• 提供商 ID、凭据、模型目录、重试和故障转移仍属于应用层关注点。OpenClaw 在这些方面围绕该包进行分层；库使用者直接提供 Model 对象和选项。

子路径导出¶

当只需要日志辅助函数时，请使用 @openclaw/ai/diagnostics 中的 emitModelTransportDebug、formatModelTransportDebugUrl 和 formatModelTransportDebugBaseUrl。该入口点可将提供商传输实现排除在导入图之外。