Clawbuddy

Name: Clawbuddy
Rating: 3.5 (1 reviews)
Author: haochen2115

By haochen2115 👁 4 views ▲ 0 votes

A cost-optimization plugin for OpenClaw

GitHub

Install

npm install
npm

Configuration Example

{
  "mode": "mode2",                    // mode1 | mode2
  "proxy": {
    "port": 18790,                    // proxy port
    "dashboard_port": 18791           // dashboard port
  },
  "primary_api": {                    // Primary API (auto-read from OpenClaw)
    "provider": "zai",
    "base_url": "https://open.bigmodel.cn/api/coding/paas/v4",
    "api_key": "...",
    "model": "glm-5-turbo"
  },
  "cheap_api": {                      // Cheap small model
    "provider": "ollama",
    "base_url": "http://localhost:11434/v1",
    "api_key": "ollama",
    "model": "qwen3.5:9b"
  },
  "validation": {
    "min_tasks_to_start": 3,          // Min tasks to start validation
    "certify_after_n_passes": 5,      // Certify after N passes
    "schedule": "idle"                // idle | manual
  },
  "skills": {
    "auto_generate": true,            // Auto-generate Skills
    "trigger_after_n_failures": 3,    // Trigger after N failures
    "output_dir": "~/.openclaw/workspace/skills/"
  }
}

README

# ClawBuddy 🦞

> Cost-optimization buddy for OpenClaw. Make your AI assistant cheaper over time.

ClawBuddy is a cost-optimization plugin for [OpenClaw](https://github.com/openclaw/openclaw). It works as a transparent proxy that intercepts OpenClaw API calls, collects data in the background, validates cheap model capabilities, and auto-generates Skills — gradually migrating expensive large model calls to cheaper small models **without sacrificing task quality**.

## How It Works

```
User → OpenClaw → ClawBuddy proxy (:18790) → Primary API (e.g. glm-5-turbo)
                         ↓
                ┌──────────────────────┐
                │   Background (async)  │
                │                      │
                │  Mode 1: Data collection   │
                │  Mode 2: Mock validation   │ ← cheap model (e.g. qwen3.5:9b) + skills
                └──────────────────────┘
```

ClawBuddy launches a local OpenAI-compatible proxy server and modifies the OpenClaw config to point API requests to it. Fully transparent to OpenClaw — it just sees a normal model provider.

## Two Modes

### 📦 Mode 1: Data Distiller

**Pure data collection**, zero intrusion.

- All requests forwarded to the primary model as usual, zero UX change
- Automatically collects complete input/output for every request
- Chains multi-turn requests from the same session into complete task traces
- Auto-labels each task with a cheap model (e.g. "file organization", "code refactoring")
- Export as JSONL / LLaMA-Factory format for fine-tuning your own small model

**Best for**: Users with GPU resources who want to fundamentally improve small model capabilities through training.

### 🧪 Mode 2: Mock Validator + Skill Generator (Recommended)

**Sandbox validation + auto Skill generation**, training-free cost reduction.

Core loop:

```
Use primary model (glm-5-turbo) for daily tasks
    ↓ Background collects task traces
Run the same task with cheap model (qwen3.5:9b) in a mock sandbox
    ↓ Primary model judges the result
pass → Accumulate pass records
fail → Analyze failure → Auto-generate OpenClaw Skill → Re-validate with Skill
    ↓ Task type accumulates N passes
Dashboard notification → "Poetry writing" validated, suggest switching to cheap model
    ↓ User enables offload with one click
```

The primary model is only called at three low-frequency points: generating mock environments, judging results, and generating Skills. Daily labeling is handled entirely by the cheap model.

**Best for**: Users without GPUs or who prefer prompt engineering over model training.

## Quick Start

### Installation

```bash
git clone https://github.com/haochen2115/clawbuddy.git
cd clawbuddy
npm install
npm run build
npm link  # Makes 'clawbuddy' command available globally
```

### Usage

One command to start, one to stop:

```bash
# Start (auto-backup OpenClaw config, inject proxy, launch services)
clawbuddy start

# Stop (Ctrl+C or run from another terminal)
clawbuddy stop
```

That's it. After starting, use OpenClaw as usual. Open `http://localhost:18791` for the Dashboard.

`start` automatically:
1. Backs up OpenClaw config (first launch only)
2. Injects proxy provider into OpenClaw (OpenClaw hot-reloads, no restart needed)
3. Launches proxy server + dashboard

`stop` (or Ctrl+C) automatically:
1. Stops all services
2. **Precisely restores** OpenClaw config (only removes proxy-related fields, preserves other changes)

### Configuration

Default config works out of the box, but you can customize via CLI flags:

```bash
# Specify mode (default: mode2)
clawbuddy start --mode mode1

# Specify cheap model
clawbuddy start --cheap-provider ollama --cheap-model qwen3.5:9b

# Or edit config file
clawbuddy config set mode mode1
clawbuddy config set cheap_api.model qwen3.5:9b
clawbuddy config show
```

### Export Training Data

```bash
# Export all
clawbuddy export --format jsonl --output ./training_data.jsonl

# Filter by task label
clawbuddy export --label "file organization" --output ./file_org.jsonl

# Export as LLaMA-Factory format
clawbuddy export --format llamafactory --output ./dataset/
```

### Manage Offload (Mode 2)

```bash
# Check status
clawbuddy status

# Enable / disable offload
clawbuddy offload enable "poetry writing"
clawbuddy offload disable "poetry writing"
clawbuddy offload list
```

## Dashboard

Local Web Dashboard at `http://localhost:18791` with 6 panels:

| Panel | Function |
|-------|----------|
| **Overview** | Mode, task counts, recent validations |
| **Task Types** | Label list, frequency, phase, manual validation trigger |
| **Data** | Training data stats, label distribution chart, export |
| **Validation** | Per-label validation details: pass/fail/reason |
| **Skills** | Auto-generated Skills list, view/delete |
| **Router** | Control which task types use cheap model offload |

### 📊 Overview

See task counts, request volume, task type count, and validated count at a glance. Recent validation records with pass/fail reasons shown at the bottom.

![Overview](docs/screenshots/overview.png)

### 🏷️ Task Types

All auto-classified task labels. View collection count, current phase (collecting → validating → validated → offloaded), pass/fail counts per type, with manual validation trigger.

![Task Types](docs/screenshots/labels.png)

### 📁 Data

Browse all collected training data. Filter by label or date, preview user messages and assistant responses. Pie chart shows label distribution. One-click export to JSONL or LLaMA-Factory format.

![Data](docs/screenshots/data.png)

### ✅ Validation

Detailed validation records. Each entry shows: time, task type, cheap model used, result (pass/fail/not_mockable), and the primary model's specific judgment — e.g. "small model didn't maintain the Banana persona tone" or "small model correctly understood the task intent".

![Validation](docs/screenshots/validation.png)

### 🧠 Skills

Auto-generated OpenClaw Skills. When the cheap model repeatedly fails at a task type, the primary model analyzes failure patterns and generates targeted SKILL.md files to help the cheap model perform better next time.

![Skills](docs/screenshots/skills.png)

### 🔀 Router Control

Core operations panel. View each task type's routing status (🔵 primary / 🟢 cheap), pass rate, and one-click "Enable Offload" to switch to cheap model or "Disable Offload" to switch back. Supports manual switching at any phase.

![Router Control](docs/screenshots/router.png)

## Architecture

```
clawbuddy/
├── src/
│   ├── index.ts              # CLI (commander)
│   ├── proxy/
│   │   ├── server.ts         # Hono HTTP server (:18790)
│   │   ├── router.ts         # Route decision (primary / cheap)
│   │   ├── filter.ts         # Request filter (task / system-level)
│   │   └── token-cache.ts    # OAuth token cache (for background tasks)
│   ├── config/
│   │   ├── init.ts           # init / restore / config management
│   │   └── types.ts          # Type definitions
│   ├── store/
│   │   └── db.ts             # SQLite (better-sqlite3)
│   ├── collector/
│   │   ├── collector.ts      # Request collection + session chaining
│   │   ├── labeler.ts        # Cheap model labeling + merging
│   │   └── exporter.ts       # JSONL / LLaMA-Factory export
│   ├── validator/
│   │   ├── sandbox.ts        # Mock environment management
│   │   ├── mock-gen.ts       # Primary model generates setup scripts
│   │   ├── runner.ts         # Cheap model runs in sandbox
│   │   ├── judge.ts          # Primary model judges results
│   │   ├── scheduler.ts      # Async validation scheduler
│   │   ├── primary-call.ts   # Shared primary model caller (with auth)
│   │   └── trace-compress.ts # Task trace compression (truncate system prompts)
│   ├── skills/
│   │   ├── analyzer.ts       # Failure pattern analysis
│   │   ├── generator.ts      # SKILL.md generation
│   │   └── evidence.ts       # Evidence pool + pattern detection
│   └── dashboard/
│       ├── api.ts            # REST API
│       └── static/index.ts   # Single-page Dashboard
├── docs/
│   └── screenshots/          # Dashboard screenshots
```

## Configuration

ClawBuddy config file is at `~/.clawbuddy/config.json`:

```jsonc
{
  "mode": "mode2",                    // mode1 | mode2
  "proxy": {
    "port": 18790,                    // proxy port
    "dashboard_port": 18791           // dashboard port
  },
  "primary_api": {                    // Primary API (auto-read from OpenClaw)
    "provider": "zai",
    "base_url": "https://open.bigmodel.cn/api/coding/paas/v4",
    "api_key": "...",
    "model": "glm-5-turbo"
  },
  "cheap_api": {                      // Cheap small model
    "provider": "ollama",
    "base_url": "http://localhost:11434/v1",
    "api_key": "ollama",
    "model": "qwen3.5:9b"
  },
  "validation": {
    "min_tasks_to_start": 3,          // Min tasks to start validation
    "certify_after_n_passes": 5,      // Certify after N passes
    "schedule": "idle"                // idle | manual
  },
  "skills": {
    "auto_generate": true,            // Auto-generate Skills
    "trigger_after_n_failures": 3,    // Trigger after N failures
    "output_dir": "~/.openclaw/workspace/skills/"
  }
}
```

## Cheap Model Options

ClawBuddy is compatible with any OpenAI-compatible API:

| Provider | Example | Notes |
|----------|---------|-------|
| **Ollama** | `--cheap-provider ollama --cheap-model qwen3.5:9b` | Local, zero cost |
| **Ollama (large)** | `--cheap-provider ollama --cheap-model qwen3.5:27b` | Local, better quality |
| **vLLM** | `--cheap-base-url http://localhost:8000/v1` | Self-hosted inference |
| **Zhipu AI** | `--cheap-base-url https://open.bigmodel.cn/api/...` | Cheap Chinese API |
| **Gemini Flash** | `--cheap-base-url ...` | Google's cheap model |

## Data Format

Exported JSONL format:

```jsonl
{"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}], "metadata": {"task_label": "poetry writing", "sessi

... (truncated)

tools