mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-03 15:01:33 +00:00
f6131a4fbf
* build(deps): remove npm shrinkwrap; mirror pnpm lock into transient package locks npm 12 removed shrinkwrap (command + tarball/root loading). Delete all 82 committed npm-shrinkwrap.json files and stop publishing lockfiles; keep pnpm-lock.yaml as the single reviewed dependency boundary. The generator becomes scripts/generate-npm-package-lock.mjs and feeds plugin bundling via a transient package-lock.json + npm ci (works on npm 11 and 12). Tarball validation treats the published 2026.7.2 beta train as a shrinkwrap transition; self-update npm detection now uses install topology instead of the shipped shrinkwrap. * fix(deps): repair lint, deadcode, and test-type lanes for the npm 12 migration - sort integrity comparisons with an explicit comparator (oxlint) - keep resolveBunGlobalNodeModules module-local (knip unused-export gate) - model npm pack --json as npm<=11 array / npm 12 name-keyed object - default calver destructuring in the tarball test fixture
72 lines
3.7 KiB
Markdown
72 lines
3.7 KiB
Markdown
---
|
|
summary: "The @openclaw/ai npm package: reusable model transports, isolated runtimes, and host policy ports"
|
|
title: "@openclaw/ai package"
|
|
read_when:
|
|
- You want to reuse OpenClaw's model transports in another application
|
|
- You are changing packages/ai or the AI transport host ports
|
|
- You are reviewing what the openclaw release publishes to npm besides the root package
|
|
---
|
|
|
|
`@openclaw/ai` is the publishable library form of OpenClaw's model execution
|
|
layer: provider-neutral message/tool/stream contracts, validation, diagnostics,
|
|
event streams, an isolated runtime registry, and lazy adapters for the eight
|
|
built-in API families (Anthropic Messages, OpenAI Completions, OpenAI
|
|
Responses, Azure OpenAI Responses, ChatGPT/Codex Responses, Google Generative
|
|
AI, Google Vertex, Mistral Conversations).
|
|
|
|
It publishes alongside the root `openclaw` package on every release, pinned to
|
|
the same version. Its exact-pinned direct dependencies resolve at install time;
|
|
the package ships no npm lockfile. Installing `openclaw` installs the matching
|
|
`@openclaw/ai` automatically, and library consumers can depend on it directly
|
|
without any OpenClaw application code.
|
|
|
|
## Quick start
|
|
|
|
```js
|
|
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();
|
|
```
|
|
|
|
A runnable version lives in the repository at `examples/ai-chat`.
|
|
|
|
## Design contract
|
|
|
|
- **Instance-scoped by default.** Importing the package registers nothing
|
|
globally. `createApiRegistry()` / `createLlmRuntime()` return isolated
|
|
instances; `registerBuiltInApiProviders(registry)` opts one registry into the
|
|
built-in transports. Provider SDK modules load lazily on first use.
|
|
- **Host policy is injected, not bundled.** Request fetch guarding (for
|
|
example SSRF policy), secret redaction of tool-result replay text, OpenAI
|
|
strict-tool defaults, and diagnostics logging are `AiTransportHost` ports
|
|
configured with `configureAiTransportHost`. The library defaults are inert;
|
|
OpenClaw installs its real implementations in its stream facade.
|
|
- **One event-stream identity.** `@openclaw/ai/event-stream` is the canonical
|
|
`EventStream` constructor shared by OpenClaw core, agent-core, and external
|
|
consumers.
|
|
- **`internal/*` subpaths are not API.** They exist for the OpenClaw
|
|
application itself and carry no semver guarantee.
|
|
- Provider ids, credentials, model catalogs, retries, and failover remain
|
|
application concerns. OpenClaw layers those around this package; a library
|
|
consumer supplies a `Model` object and options directly.
|
|
|
|
## Subpath exports
|
|
|
|
| Subpath | Contents |
|
|
| ---------------- | ------------------------------------------------------------------------------ |
|
|
| `.` | Contracts, `createApiRegistry`, `createLlmRuntime`, `configureAiTransportHost` |
|
|
| `./providers` | `registerBuiltInApiProviders`, `resetApiProviders` |
|
|
| `./types` | Model/message/tool/stream types |
|
|
| `./validation` | Tool argument validation |
|
|
| `./diagnostics` | Diagnostics contracts |
|
|
| `./event-stream` | Shared `EventStream` implementation |
|
|
| `./internal/*` | OpenClaw-internal, no semver guarantee |
|