跳转至

@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 严格工具默认值以及诊断日志记录,都是使用 configureAiTransportHost 配置的 AiTransportHost 端口。库的默认值是无操作的;OpenClaw 在其流外观中安装其真实实现。
  • 统一的事件流标识。 @openclaw/ai/event-stream 是 OpenClaw 核心、agent-core 和外部使用者共享的规范 EventStream 构造函数。
  • internal/* 子路径不是 API。 它们仅服务于 OpenClaw 应用本身,不提供 semver 保证。
  • 提供商 ID、凭据、模型目录、重试和故障转移仍属于应用层面的关注点。OpenClaw 在这些方面围绕该包进行分层;库使用者直接提供 Model 对象和选项。

子路径导出

子路径 内容
. 契约、createApiRegistry、createLlmRuntime、configureAiTransportHost
./providers registerBuiltInApiProviders、resetApiProviders
./types 模型/消息/工具/流类型
./validation 工具参数校验
./diagnostics 诊断契约、传输日志记录和已清理的 URL 格式化
./event-stream 共享的 EventStream 实现
./internal/* OpenClaw 内部使用,不提供 semver 保证

当你只需要日志辅助函数时,请使用 @openclaw/ai/diagnostics 中的 emitModelTransportDebug、formatModelTransportDebugUrl 和 formatModelTransportDebugBaseUrl。此入口点可避免将提供商传输实现引入导入图。

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