openclaw-runware-provider

OpenClaw plugin that wires Runware (a unified OpenAI-compatible endpoint proxying Claude, GPT, Gemini, Qwen, GLM, MiniMax, Kimi, Gemma, …) into OpenClaw as a first-class provider. Published as @teith/openclaw-runware-provider on npm.

The plugin is the inference contract between the Runware-hosted managed OpenClaw service (driven by openclaw-manager) and the OpenClaw gateway running inside each per-tenant pod. The manager installs this package into the pod via OpenClawInstance.spec.plugins; the plugin discovers the model catalog live from GET /v1/models on every gateway start.

Configuration

The plugin is configured entirely through environment variables — no config file, no CLI onboarding step. The managed deployment injects these from a per-instance Kubernetes Secret; for local development, export them in the shell before launching the gateway.

| Variable | Required | Default | Purpose | |--------------------|----------|-------------------------------|------------------------------------------------------------------| | RUNWARE_API_KEY | yes | — | Bearer token used for /v1/models and inference | | RUNWARE_BASE_URL | no | https://api.runware.ai/v1 | Endpoint override (e.g. https://api.runware.dev/v1 for staging) |

RUNWARE_API_KEY resolution prefers process.env over openclaw's runtime resolveProviderApiKey(...) — env is the source of truth in the managed deployment, and openclaw's resolver can return stale values from internal credential caches.

What the plugin does

• Registers runware as an OpenAI-compatible provider in OpenClaw via the providerCatalogEntry manifest hook (the surface openclaw 2026.5.x actually calls; mirrors the bundled ollama plugin).
• Fetches /v1/models on every catalog resolution. TTL-cached for 5 minutes; concurrent requests are deduplicated; the last-known-good catalog is served on transient upstream failures.
• Forwards per-model context_length and max_output_tokens from Runware's extended /v1/models response into each model's contextWindow/maxTokens in the OpenClaw catalog — so e.g. Opus 4.7 reports its real 1M window, GPT 5.4 its 1.05M window, etc. Models where Runware leaves those fields null (currently the older Runware-owned rows like qwen-instruct, xai-grok-4-3) fall back to conservative defaults (200K context, 32K output).
• Uses each model's curated name from /v1/models when present (e.g. "Opus 4.7" instead of the id-humanized "Anthropic Claude Opus 4 7").
• Injects extra_body: { reasoning_effort: "high" } into every chat completions request so reasoning-capable models stream thinking content.

Architecture

src/
├── index.ts                  plugin entry — register(api) callback
├── provider-discovery.ts     default export consumed by providerCatalogEntry
├── models.ts                 shared model-building primitives + env resolution
├── catalog.ts                TTL-cached /v1/models fetcher with dedup
└── openclaw-api.ts           local type stubs for the openclaw runtime API

models.ts is the single source of truth. Both index.ts (register(api) flow, declared but currently not invoked by openclaw 2026.5.x for external plugins) and provider-discovery.ts (providerCatalogEntry flow, the one openclaw actually calls) share its resolveApiKey, resolveBaseUrl, buildProvider, and buildCatalogRows helpers — so the picker catalog and the inference provider always reflect the same /v1/models snapshot.

The plugin does not import from the openclaw npm package at runtime; the API surface is described locally in openclaw-api.ts.

Development

pnpm install
pnpm test         # vitest, 24 tests
pnpm typecheck
pnpm build        # tsc → ./dist

dist/ is committed to git and shipped in the npm tarball because openclaw installs plugins with npm install --ignore-scripts and cannot run a build step inside the operator's init container.

Release

pnpm test && pnpm clean && pnpm build
# bump version in package.json
git commit -am "Release vX.Y.Z"
git tag vX.Y.Z
git push origin main --tags
npm publish --access public

Bumping the version requires a matching bump of cfg.plugin_package in openclaw-manager/src/openclaw_manager/config.py (and the chart values) — the manager pins to an exact version so the install is reproducible across instances.