Tactician

Name: Tactician
Rating: 3.5 (1 reviews)
Author: joshuaswarren

By joshuaswarren ⭐ 1 stars 👁 31 views ▲ 0 votes

Intelligent model routing for OpenClaw with quota prediction, task classification, and automatic optimization

GitHub

Install

npm install &&

Configuration Example

{
  "plugins": {
    "openclaw-tactician": {
      "mode": "dry-run",
      "providers": {
        "anthropic": {
          "quotaSource": "self-tracked",
          "quotaType": "tokens",
          "tier": "premium",
          "resetSchedule": { "type": "weekly", "dayOfWeek": 3, "hour": 7 }
        },
        "openai-codex": {
          "quotaSource": "self-tracked",
          "quotaType": "messages",
          "tier": "premium",
          "resetSchedule": { "type": "fixed", "fixedDate": "2026-02-09T14:36:00Z" }
        },
        "openrouter": {
          "quotaSource": "api",
          "quotaType": "budget",
          "tier": "budget"
        }
      }
    }
  }
}

README

# openclaw-tactician

[![npm version](https://badge.fury.io/js/openclaw-tactician.svg)](https://badge.fury.io/js/openclaw-tactician)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Intelligent model routing for OpenClaw with quota prediction, task classification, and automatic optimization.

## What It Does

**Smart Router** helps you get the most out of your LLM quotas by:

- **Predicting exhaustion** - Know when you'll run out of tokens before it happens
- **Analyzing workloads** - Identify which cron jobs and agents can use cheaper models
- **Automatic optimization** - Shift workloads to appropriate models based on task complexity
- **Local model support** - Route simple tasks to MLX, Ollama, or other local servers
- **Budget tracking** - Monitor spend on pay-per-token providers like OpenRouter

## Quick Start

### 1. Install

```bash
cd ~/.openclaw/extensions
git clone https://github.com/joshuaswarren/openclaw-tactician.git
cd openclaw-tactician
npm install && npm run build
```

### 2. Enable in openclaw.json

```json
{
  "plugins": {
    "openclaw-tactician": {
      "mode": "dry-run",
      "providers": {
        "anthropic": {
          "quotaSource": "self-tracked",
          "quotaType": "tokens",
          "tier": "premium",
          "resetSchedule": { "type": "weekly", "dayOfWeek": 3, "hour": 7 }
        },
        "openai-codex": {
          "quotaSource": "self-tracked",
          "quotaType": "messages",
          "tier": "premium",
          "resetSchedule": { "type": "fixed", "fixedDate": "2026-02-09T14:36:00Z" }
        },
        "openrouter": {
          "quotaSource": "api",
          "quotaType": "budget",
          "tier": "budget"
        }
      }
    }
  }
}
```

### 3. Restart Gateway

```bash
kill -USR1 $(pgrep openclaw-gateway)
```

### 4. Check Status

```bash
openclaw router status
```

## Usage

### CLI Commands

```bash
# Show provider status and usage
openclaw router status [provider]

# Predict quota exhaustion
openclaw router predict [--hours=24]

# List configured providers
openclaw router providers

# Manually set usage (e.g., after checking your account)
openclaw router set-usage <provider> <percent|tokens>
# Examples:
openclaw router set-usage anthropic 79%
openclaw router set-usage openai-codex 91%

# Reset quota counter after provider reset
openclaw router reset <provider>

# Analyze crons/agents for optimization opportunities
openclaw router analyze [--type=all|crons|agents]

# Generate and optionally apply optimizations
openclaw router optimize [--apply] [--safe-only]

# Detect local model servers
openclaw router detect-local

# Get or set operation mode
openclaw router mode [manual|dry-run|auto]
```

### Conversational Interface

Chat with OpenClaw using these capabilities:

```
"What's my token usage looking like?"
→ Calls router_status tool

"When will I run out of Codex tokens?"
→ Calls router_predict tool

"Which of my cron jobs could use cheaper models?"
→ Calls router_analyze tool

"Optimize my model usage"
→ Calls router_optimize tool (with confirmation)

"Move everything off Anthropic"
→ Calls router_shift tool
```

## Operation Modes

| Mode | Behavior |
|------|----------|
| `manual` | CLI only. No automatic changes. |
| `dry-run` | Preview optimizations. Ask before applying. (Default) |
| `auto` | Automatically apply safe (reversible) optimizations. |

## Provider Usage Fetching

### Direct API Fetchers (Real-Time Usage)

This plugin can fetch real-time usage from provider APIs, similar to [CodexBar](https://github.com/steipete/CodexBar):

| Provider | Status | Method | Environment Variables |
|----------|--------|--------|----------------------|
| **Claude** | ✅ Working | Web API | `CLAUDE_SESSION_KEY`, `CLAUDE_COOKIES` |
| **Codex** | ✅ Working | OAuth | Auto from `~/.codex/auth.json` |
| **Kimi** | ✅ Working | API | `KIMI_AUTH_TOKEN` |
| **Z.ai** | ✅ Working | API | `Z_AI_API_KEY` |
| **OpenRouter** | ✅ Working | API | Auto from provider config |
| **Copilot** | ⚠️ Partial | GitHub API | Auto from `gh` CLI or `GITHUB_TOKEN` |
| **Gemini** | ✅ Working | OAuth | Auto from `~/.gemini/oauth_creds.json` |

### Fetching Usage

```bash
# Fetch from a specific provider
openclaw router fetch claude
openclaw router fetch kimi
openclaw router fetch zai
openclaw router fetch codex
openclaw router fetch gemini

# Check credential status
openclaw router credentials
```

### Provider Setup

#### Claude (Anthropic)

Claude requires browser cookies to fetch usage. The session key alone isn't enough - Cloudflare requires `cf_clearance`.

**Getting the cookies:**
1. Open https://claude.ai in your browser
2. Open DevTools → Application → Cookies → claude.ai
3. Copy `sessionKey` (starts with `sk-ant-sid01-`)
4. Copy `cf_clearance` (Cloudflare token)

**Environment variables:**
```bash
export CLAUDE_SESSION_KEY="sk-ant-sid01-..."
export CLAUDE_COOKIES="sessionKey=sk-ant-sid01-...; cf_clearance=..."
```

**Usage data returned:**
- Session (5hr): Percentage used, reset time
- Weekly (7d): Percentage used, reset time
- Opus: Separate tracking for Opus model

#### Kimi

Kimi requires a browser session JWT, NOT the API key.

**Important:** `KIMI_API_KEY` (starts with `sk-kimi-`) is for the coding API which has no usage endpoint.

**Getting the token:**
1. Open https://kimi.com in your browser and log in
2. Open DevTools → Application → Cookies → kimi.com
3. Copy the `kimi-auth` cookie value (it's a JWT)

**Environment variable:**
```bash
export KIMI_AUTH_TOKEN="eyJ..."
```

#### Z.ai (Zhipu/GLM)

Z.ai uses a standard API key for usage tracking.

**Environment variable:**
```bash
export Z_AI_API_KEY="your-api-key"
```

**Regions:**
- Global: `api.z.ai` (default)
- China: Set `Z_AI_REGION=china` to use `open.bigmodel.cn`

#### Codex (OpenAI)

Codex uses OAuth credentials stored by the Codex CLI.

**Setup:**
1. Install and run `codex` CLI
2. Authenticate via the CLI
3. Credentials are stored at `~/.codex/auth.json`

No environment variables needed - the plugin reads from the auth file.

#### GitHub Copilot

Uses GitHub OAuth token.

**Sources (checked in order):**
1. `GITHUB_TOKEN` environment variable
2. `gh auth token` (GitHub CLI)
3. `~/.config/gh/hosts.yml`

#### Gemini (Google)

Gemini uses OAuth credentials stored by the Gemini CLI. Supports **multiple accounts** for quota rotation on free tier.

**Single Account Setup:**
1. Install and run `gemini` CLI
2. Authenticate via the CLI
3. Credentials are stored at `~/.gemini/oauth_creds.json`

**Multi-Account Setup (for free tier rotation):**

Configure multiple accounts in `openclaw.json`:

```json
"google": {
  "quotaSource": "api",
  "accounts": [
    { "name": "personal", "credentialsPath": "~/.gemini/oauth_creds.json" },
    { "name": "work1", "credentialsPath": "~/.gemini/accounts/work1.json" },
    { "name": "work2", "credentialsPath": "~/.gemini/accounts/work2.json" }
  ]
}
```

**Setting up additional accounts:**
1. Run `gemini` in a temp directory to authenticate with a different Google account
2. Copy the credentials to a unique path: `cp ~/.gemini/oauth_creds.json ~/.gemini/accounts/work1.json`
3. Repeat for each account

**Usage data returned (per account):**
- Pro models: Usage percentage, reset time
- Flash models: Usage percentage, reset time
- Tier: Your subscription tier (if available)

**Note:** Gemini CLI tokens expire and cannot be auto-refreshed. Re-run `gemini` CLI when tokens expire.

### Self-Tracked Providers

For providers without usage APIs (like Google Gemini), we track usage ourselves via the `llm_end` hook:

1. **We don't know your actual limits** - Set them manually with `router set-usage`
2. **Tracking starts from zero** - Historical usage before plugin install is unknown
3. **Reset timing may drift** - We reset when configured, not when your provider does

**Recommended workflow:**
```bash
# Check your provider's dashboard for current usage, then sync:
openclaw router set-usage google 45%
```

### Quota Types

| Type | Unit | Example Providers |
|------|------|-------------------|
| `tokens` | Input + output tokens | Anthropic, OpenAI API |
| `messages` | Conversations/completions | OpenAI Codex (tier-based) |
| `requests` | API calls per day | Google free tier |
| `budget` | USD spend | OpenRouter |

### Self-Tracked Providers

For providers without usage APIs, we track usage ourselves via the `llm_end` hook:

1. **We don't know your actual limits** - Set them manually with `router set-usage`
2. **Tracking starts from zero** - Historical usage before plugin install is unknown
3. **Reset timing may drift** - We reset when configured, not when your provider does

**Recommended workflow:**

```bash
# Check your provider's dashboard for current usage
# Then sync the plugin:
openclaw router set-usage anthropic 79%
openclaw router set-usage openai-codex 91%
```

## Configuration Reference

```json
{
  "plugins": {
    "openclaw-tactician": {
      // Operation mode: manual, dry-run, auto
      "mode": "dry-run",

      // Enable debug logging
      "debug": false,

      // Provider-specific configuration
      "providers": {
        "anthropic": {
          // How to track: api, manual, unlimited, self-tracked
          "quotaSource": "self-tracked",
          // What the limit measures: tokens, requests, messages, budget
          "quotaType": "tokens",
          // Optional: set a limit for warnings (omit if unknown)
          // "limit": 10000000,
          // When quota resets
          "resetSchedule": {
            "type": "weekly",    // daily, weekly, monthly, fixed
            "dayOfWeek": 3,      // 0=Sunday (for weekly)
            "hour": 7,           // Hour of reset (0-23)
            "timezone": "America/Chicago"
          },
          // Cost tier: premium, standard, budget, free, local
          "tier": "premium",
          // Priority within tier (higher = preferred)
          "priority": 100
        },
        "openrouter

... (truncated)

tools