claw-llm-router: Instructions file for Codex

Claw LLM Router — Agent Instructions

What This Is

This is a plugin for OpenClaw — an AI chat application. The plugin acts as a cost-optimized LLM router that classifies user prompts by complexity (SIMPLE, MEDIUM, COMPLEX, REASONING) and routes them to the most cost-effective model for that tier. It runs as an in-process HTTP proxy inside the OpenClaw gateway.

OpenClaw sends chat completion requests to the router, which classifies the prompt, selects the appropriate provider/model, and forwards the request. If a provider fails, the router falls back through a chain of higher-tier models.

Testing & Code Quality

• npm run check must pass before completing any task — this runs format, lint, typecheck, and tests in sequence. If any step fails, fix it before committing.
• Run all checks: npm run check (format + lint + typecheck + tests)
• Run tests only: npm test
• Run formatting check: npm run format (fix with npm run format:fix)
• Run linting: npm run lint
• Run type checking: npm run typecheck
• Never commit with failing checks
• Formatting is enforced by CI. Always run npm run format (or npm run check) before committing. If formatting fails, fix it with npm run format:fix and include the formatting changes in your commit.
• Tests use Node.js built-in test runner (node:test)
• Test context: All test data should reflect realistic OpenClaw usage. Conversations are between user and assistant (the LLM) — not between named people (e.g., "Alice", "Bob"). Packed context uses OpenClaw's format: [Chat messages since your last reply - for context] with user:/assistant: prefixed messages, followed by [Current message - respond to this].

Project Structure

├── index.ts                  # Plugin entry, OpenClaw registration, before_model_resolve hook
├── proxy.ts                  # HTTP proxy server, request routing, fallback chain
├── classifier.ts             # Rule-based prompt classifier (15-dimension scoring)
├── tier-config.ts            # Tier-to-model config, API key loading from auth stores
├── models.ts                 # Model definitions, port/provider constants
├── provider.ts               # OpenClaw provider plugin definition
├── router-config.json        # Tier configuration (auto-generated, do not edit manually)
├── router-logger.ts          # RouterLogger class — centralized [router] log formatting
├── providers/
│   ├── types.ts              # LLMProvider interface, PluginLogger, ChatMessage
│   ├── openai-compatible.ts  # Google, OpenAI, Groq, Mistral, DeepSeek, etc.
│   ├── anthropic.ts          # Anthropic Messages API (direct API key only)
│   ├── gateway.ts            # OpenClaw gateway fallback (OAuth tokens)
│   ├── model-override.ts     # In-process override store (prevents recursion)
│   └── index.ts              # Provider registry, resolveProvider(), callProvider()
├── docs/
│   ├── ARCHITECTURE.md       # Provider strategy, OAuth override mechanism
│   ├── PROVIDERS.md          # Step-by-step guide for adding new providers
│   └── CLASSIFIER.md         # Classifier architecture, dimensions, weights, extraction
└── tests/