EcoClaw

Name: EcoClaw
Rating: 3.5 (1 reviews)
Author: ynulihao

By ynulihao ⭐ 3 stars 👁 52 views ▲ 0 votes

EcoClaw: Save 90%+ on LLM Costs for OpenClaw with One Plugin

GitHub

Install

npm install

#

Configuration Example

{
  "openrouterApiKey": "sk-or-v1-your-key",
  "httpProxy": "http://127.0.0.1:7890",
  "httpsProxy": "http://127.0.0.1:7890",
  "noProxy": "127.0.0.1,localhost"
}

README

<p align="center">
  <img src="assets/logo.png" height="200" alt="EcoClaw">
</p>

<h2 align="center">
  EcoClaw: Save 90%+ on LLM Costs with One Plugin<br>
  <sub>Automatically pick the cheapest model that gets the job done — powered by real benchmark data.</sub>
</h2>

<p align="center">
  English | <a href="README_zh.md">简体中文</a>
</p>

<p align="center">
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js >= 20"></a>
  <a href="https://github.com/nicepkg/openclaw"><img src="https://img.shields.io/badge/OpenClaw-Plugin-blue" alt="OpenClaw Plugin"></a>
</p>

<p align="center">
  <a href="#-overview"><img src="https://img.shields.io/badge/🌐_Overview-blue?style=for-the-badge" alt="Overview"></a>
  <a href="#-how-it-works"><img src="https://img.shields.io/badge/⚙️_How_It_Works-orange?style=for-the-badge" alt="How It Works"></a>
  <a href="#-cost-strategies"><img src="https://img.shields.io/badge/🎯_Cost_Strategies-green?style=for-the-badge" alt="Cost Strategies"></a>
  <a href="#-quick-start"><img src="https://img.shields.io/badge/🚀_Quick_Start-red?style=for-the-badge" alt="Quick Start"></a>
</p>

---

## 🌐 Overview

**EcoClaw** is a cost-saving plugin for [OpenClaw](https://github.com/nicepkg/openclaw). It automatically picks the cheapest model that gets the job done for each prompt, based on real benchmark scores from [PinchBench](https://pinchbench.com/?view=graphs).

### 🌟 Highlights

- **Save up to 98% on LLM costs** — Automatically matches each task to a cheap, capable model using real benchmark data across 23 task categories and 3 cost strategies.
- **Zero-Config, Always Up-to-Date** — Works out of the box; benchmark scores auto-refresh every 6 hours.
- **Automatic Fallback** — If a model fails (429/5xx), automatically retries with backups.

<!-- Auto-generated by temp/gen-stats.ts — do not edit manually -->

### 📊 How Much Can You Save?

| Strategy | Avg Quality | Avg Cost | vs. Using Top Model for Everything |
|---|---:|---:|---|
| Always `claude-opus-4.6` | 89.4% | $2.98 | baseline |
| **EcoClaw best** | 94.7% | $0.58 | +5.2pp quality, **80% cheaper** |
| **EcoClaw balanced** | 93.6% | $0.12 | +4.2pp quality, **96% cheaper** |
| **EcoClaw eco** | 90.8% | $0.07 | +1.4pp quality, **98% cheaper** |


<!-- End of auto-generated stats -->

## ⚙️ How It Works

```
User Prompt
    │
    ▼
┌─────────────────────────────────────────────┐
│  ① CLASSIFY                                 │
│  prompt → embedding → cosine similarity     │
│  against 23 pre-computed task vectors       │
│  → task category                            │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  ② SCORE                                    │
│  task category + cost strategy              │
│  → weighted score (quality × w + cost × w)  │
│  → rank all models                          │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  ③ SELECT                                   │
│  top model + 2 fallbacks → OpenRouter       │
│  → stream response back to user             │
│  (auto-retry on 429/5xx)                    │
└─────────────────────────────────────────────┘
```

## 🎯 Cost Strategies

| Model ID | Strategy | Quality | Cost | Description |
|----------|----------|---------|------|-------------|
| `ecoclaw/best` | Quality-first | 99% | 1% | Picks the best model per task — still up to 80% cheaper than always using the top model |
| `ecoclaw/balance` | Balanced (default) | 50% | 50% | Sweet spot: 96% cheaper with near-top quality |
| `ecoclaw/eco` | Cost-first | 20% | 80% | Maximum savings — up to 98% cheaper |

## 🚀 Quick Start

### Prerequisites

- **Node.js** >= 20 (`httpProxy` / `httpsProxy` outbound proxy support requires Node.js 24.5+)
- **OpenRouter API Key** — for embedding computation and model calls
- **OpenClaw** >= 2026.3

### Install & Run

```bash
# 1. Clone & install
git clone [email protected]:ynulihao/EcoClaw.git && cd EcoClaw
npm install

# 2. Configure API Key / outbound proxy
#    Option A (recommended): secrets.local.json
cat > secrets.local.json <<'EOF'
{
  "openrouterApiKey": "sk-or-v1-your-key",
  "httpProxy": "http://127.0.0.1:7890",
  "httpsProxy": "http://127.0.0.1:7890",
  "noProxy": "127.0.0.1,localhost"
}
EOF
#    Option B: environment variables
export OPENROUTER_API_KEY=sk-or-v1-...
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=127.0.0.1,localhost

# 3. Pull benchmark snapshot (verify OpenRouter connectivity)
npm run pull:snapshot

# 4. Build the plugin (auto-generates embedding vectors first)
npm run build

# 5. Install into OpenClaw (dev mode, symlink)
openclaw plugins install -l .

# 6. Restart gateway & select model
openclaw gateway restart
openclaw models set ecoclaw/balance
```

> `secrets.local.json` is excluded by `.gitignore` and will never be committed.

### Slash Commands

| Command | Description | Example |
|---------|-------------|---------|
| `/route <prompt>` | Preview which model a prompt would be matched to | `/route Write a blog post` |

## 🔧 Configuration

### API Key & Outbound Proxy

Priority: `secrets.local.json` > environment variables `OPENROUTER_API_KEY`, `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`

```json
{
  "openrouterApiKey": "sk-or-v1-your-key",
  "httpProxy": "http://127.0.0.1:7890",
  "httpsProxy": "http://127.0.0.1:7890",
  "noProxy": "127.0.0.1,localhost"
}
```

`httpProxy`, `httpsProxy`, and `noProxy` map to `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`.
If `httpsProxy` is omitted, EcoClaw falls back to `httpProxy`.

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OPENROUTER_API_KEY` | No* | — | OpenRouter API key (used when `secrets.local.json` is absent) |
| `HTTP_PROXY` | No | — | Outbound HTTP proxy for PinchBench/OpenRouter requests |
| `HTTPS_PROXY` | No | `HTTP_PROXY` | Outbound HTTPS proxy |
| `NO_PROXY` | No | `127.0.0.1,localhost` (when proxy is enabled) | Hosts that bypass the outbound proxy |
| `ECOCLAW_PROXY_PORT` | No | `8403` | Local proxy port |
| `ECOCLAW_EMBEDDING_MODEL` | No | `openai/text-embedding-3-small` | Embedding model for build & runtime |

> \* API key must be provided via either `secrets.local.json` or environment variable.
>
> Outbound proxy support is implemented with Node core `proxyEnv` and is verified on Node.js 24.5+.

## 🛠️ Development

### Build Commands

```bash
npm run pull:snapshot      # Pull PinchBench data snapshot (requires API Key)
npm run build              # Build (auto-runs build:embeddings first)
npm run build:embeddings   # Regenerate embedding vectors only (requires API Key)
npm run dev                # Watch mode build
```

### Test

```bash
npm test                   # Run tests
npm run test:watch         # Watch mode tests
npm run typecheck          # Type checking
```

### Project Structure

```
EcoClaw/
├── src/
│   ├── index.ts                 # Plugin entry, registers provider & slash commands
│   ├── config.ts                # Environment variables & config constants
│   ├── models.ts                # Model definitions (ecoclaw/best|auto|eco)
│   ├── proxy.ts                 # Local HTTP proxy (intercept, select model, forward)
│   └── router/
│       ├── classifier.ts        # Embedding nearest-neighbor classifier
│       ├── embedding-engine.ts  # Embedding API & cosine similarity
│       ├── embedding-data.gen.ts# Pre-computed embedding vectors (auto-generated)
│       ├── selector.ts          # Benchmark-score-based model selector
│       ├── profiles.ts          # Cost strategy profiles (best/balanced/eco)
│       └── index.ts             # Module exports
├── src/data/
│   ├── cache.ts                 # Benchmark data cache (6h TTL)
│   ├── fetcher.ts               # PinchBench API data fetcher
│   └── snapshot.json            # Offline benchmark snapshot
├── scripts/
│   ├── build-embeddings.ts      # Generate embedding vectors from task descriptions
│   ├── pull-snapshot.ts         # Pull PinchBench data snapshot
│   └── print-selections.ts     # Print model selections per category × strategy
├── openclaw.plugin.json         # OpenClaw plugin metadata
├── tsconfig.json
└── tsup.config.ts
```

## 📄 Uninstall

```bash
openclaw plugins uninstall EcoClaw
```

> For dev-mode (`-l`) installs, uninstalling only removes the symlink from OpenClaw config — your source directory is not deleted.

> After uninstalling, run `openclaw onboard` to re-select your model provider.

## Acknowledgments

This project is built on top of [PinchBench](https://pinchbench.com/?view=graphs). Thanks to the PinchBench team for providing high-quality LLM evaluation data.

## Research & Citation

EcoClaw is built on our team's long-term research in LLM model routing. If you find this work useful, please star our related projects and consider citing our papers.

[![Avengers](https://img.shields.io/badge/Avengers-⭐-blue?style=flat-square&logo=github)](https://github.com/ZhangYiqun018/Avengers)
[![AvengersPro](https://img.shields.io/badge/AvengersPro-⭐-blue?style=flat-square&logo=github)](https://github.com/ZhangYiqun018/AvengersPro)
[![LLMRouterBench](https://img.shields.io/badge/LLMRouterBench-⭐-blue?style=flat-square&logo=github)](https://github.com/ynulihao/LLMRouterBench)

```bibtex
@inproceedings{zhang2025avengers,
  title        = {The Avengers: A Simple Recipe for Uniting Smaller Language Models to Challenge Proprietary Giants},
  author       = {Zhang, Yiqun and Li, Hao and Wang, Chenxu and Chen, Linyao and Zhang, Qiaosheng and Ye, Peng and Feng, Shi and Wang, Daling and Wang, Zhen and Wang, Xinrun and Xu, Jia and Bai, Lei and O

... (truncated)

tools