llm_router

Minimal OpenClaw-first LLM router.

For the end-to-end runtime walkthrough of how the router itself works, see docs/REQUEST_FLOW.md. For real-host verification steps, see docs/RUNBOOKS/production-openclaw.md. Keep machine-specific production access notes in a private docs-internal/ folder, not in the public repo.

Included in this reset:

• local OpenAI-compatible proxy
• simple prompt classifier
• x402 payment retry client
• OpenClaw plugin with /wallet

Not included yet:

• advanced routing heuristics
• weighted scoring
• provenance receipts
• complex fallback chains

Dev

npm install
npm run typecheck
npm run dev:proxy

Production Install

Install the published package into OpenClaw:

openclaw plugins install @rungate/llmrouter
openclaw gateway restart

Or use the installer script from this repo:

bash scripts/install-openclaw.sh

Recommended production environment:

INFERENCE_PROVIDER_BASE_URL=https://api.rungate.ai
X402_NETWORK=eip155:8453

llm_router remains local-only in this setup. OpenClaw still talks to the local proxy at http://127.0.0.1:3000/v1; the remote upstream is configured by environment.

If INFERENCE_PROVIDER_BASE_URL is unset, the router defaults to https://api.rungate.ai. If X402_NETWORK is unset, the router defaults to eip155:8453.

Local OpenClaw Install

For local unpublished development, install from a packaged tarball:

npm run build
npm pack
openclaw plugins install ./rungate-llmrouter-0.1.0.tgz
openclaw gateway restart

For Docker/tempclaw-style testing, stage the tarball into the container and install it there with:

openclaw plugins install /staging/rungate-llmrouter-0.1.0.tgz

The installer script is for real OpenClaw installs, not tempclaw. Tempclaw should keep using the explicit install flow so restart and verification stay visible.

For a real production-host smoke, follow docs/RUNBOOKS/production-openclaw.md.

Environment

For local development, override the production default upstream:

LLM_ROUTER_HOST=127.0.0.1
LLM_ROUTER_PORT=3000
INFERENCE_PROVIDER_BASE_URL=http://127.0.0.1:8787
X402_NETWORK=eip155:84532

OpenClaw Models

• llmrouter/auto
• llmrouter/simple
• llmrouter/coding
• llmrouter/reasoning

Image requests still route automatically to the vision-capable upstream model through llmrouter/auto.

Release Workflow

npm run typecheck
npm run test
npm run build
npm pack

Publish to npm is handled by GitHub Actions when a GitHub Release is published with a tag matching v<package.json version>.

Recommended release flow:

npm version patch
git push origin main
git push origin --tags

Then publish a GitHub Release for that tag. The workflow will run typecheck, test, build, and npm publish.

Repository setup required:

• add a repo secret named NPM_TOKEN
• the token must have publish access to @rungate/llmrouter

Use npm pack as the final local sanity check before creating the GitHub Release. The packed artifact should contain the built plugin entrypoint in dist, the plugin manifest, and only runtime files.