> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# @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-shrinkwrap.json`，因此其传递依赖树会在安装时锁定。安装 `openclaw` 会自动安装匹配的 `@openclaw/ai`；库使用者可以直接依赖它，而无需任何 OpenClaw 应用代码。

## 快速开始

```js theme={"theme":{"light":"min-light","dark":"min-dark"}}
import { createLlmRuntime } from "@openclaw/ai";
import { registerBuiltInApiProviders } from "@openclaw/ai/providers";

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

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 严格工具默认值以及诊断日志均为 `AiTransportHost` 端口，并通过 `configureAiTransportHost` 配置。该库的默认实现不执行任何操作；OpenClaw 会在其流式传输门面中安装实际实现。
* **统一的事件流标识。** `@openclaw/ai/event-stream` 是 OpenClaw 核心、agent-core 和外部使用者共享的规范 `EventStream` 构造函数。
* **`internal/*` 子路径并非 API。** 它们仅供 OpenClaw 应用自身使用，不提供任何语义化版本保证。
* 提供商 ID、凭据、模型目录、重试和故障转移仍属于应用层关注事项。OpenClaw 会围绕此软件包添加这些功能；库使用者则直接提供 `Model` 对象和选项。

## 子路径导出

| 子路径              | 内容                                                                   |
| ---------------- | -------------------------------------------------------------------- |
| `.`              | 契约、`createApiRegistry`、`createLlmRuntime`、`configureAiTransportHost` |
| `./providers`    | `registerBuiltInApiProviders`、`resetApiProviders`                    |
| `./types`        | 模型/消息/工具/流式传输类型                                                      |
| `./validation`   | 工具参数验证                                                               |
| `./diagnostics`  | 诊断契约                                                                 |
| `./event-stream` | 共享的 `EventStream` 实现                                                 |
| `./internal/*`   | OpenClaw 内部使用，不提供语义化版本保证                                             |