Summary

Extract OpenClaw's normalized model execution contracts and API-family transports into publishable, reusable npm packages while keeping existing OpenClaw provider, config, auth, plugin, and transcript behavior unchanged.

Problem to solve

The reusable message, tool, stream, usage, and validation contracts already exist under the private @openclaw/llm-core and @openclaw/llm-runtime workspace packages, but provider transports still live under src/llm and depend back on OpenClaw host policy. Consumers cannot reuse OpenClaw's model execution layer without depending on the full application, and the current global registry/import-side-effect shape is unsafe as a public library.

Proposed solution

• Make the core/runtime packages publishable with complete package metadata, license, notices, documentation, and isolated tarball tests.
• Replace the public process-global registry API with instance-scoped runtime composition while retaining an OpenClaw-owned default compatibility instance.
• Separate API-family transports from provider-company control-plane integrations. MiniMax, for example, should continue composing the shared Anthropic Messages transport.
• Move pure transport helpers downward or inject narrow host ports for fetch policy, diagnostics, and activity tracking.
• Keep OpenClaw config, auth profiles, catalogs, onboarding, plugin hooks, model refs, transcripts, and lazy loading unchanged.
• Migrate one canonical implementation at a time; no long-lived dual runtime or fallback path.
• Consolidate duplicated transport tests and reduce production/test LOC where the extracted ownership boundary permits it.

Alternatives considered

• Replatforming onto Vercel AI SDK or Pi during extraction: combines a runtime replacement with an ownership refactor and risks OpenClaw-specific replay, reasoning, tool, and Codex behavior.
• Publishing the current private packages unchanged: does not include provider transports and exposes a mutable process-global registry.
• Extracting whole provider plugins: exports OpenClaw-specific auth, onboarding, config, usage, doctor, and failover contracts instead of a reusable model execution API.

Impact

• Affected: OpenClaw core, provider plugins, external package consumers, package/release validation.
• Severity: architectural limitation rather than current user-visible failure.
• Frequency: every attempt to reuse or independently test OpenClaw's model execution layer.
• Consequence: duplicated integrations, full-application dependencies, and a larger regression surface for provider changes.

Evidence/examples

• packages/llm-core already owns normalized types, validation, diagnostics, and event streams.
• packages/llm-runtime already owns provider registration and dispatch, but through a global registry.
• extensions/minimax maps its text models to anthropic-messages, demonstrating that vendor identity and wire protocol are separate axes.
• src/plugins/types.ts combines product/control-plane hooks that should remain OpenClaw-owned.

Additional information

Compatibility gates must cover existing configs, provider/model ids, auth profiles, tool-call and reasoning replay, stream events, usage, cancellation, timeout/retry behavior, startup laziness, Node 22/24, Bun, and published OpenClaw install/update paths.