ClawProxy Documentation

Everything you need to set up ClawProxy, configure smart routing, and start saving on your AI costs. This guide covers the full API, dashboard features, and advanced configuration.

Getting Started

ClawProxy is an OpenAI-compatible proxy that sits between your AI agents and LLM providers. It automatically routes each request to the cheapest model capable of handling it, detects and kills runaway loops, and enforces hard spending limits.

How it works

Your agents send requests to ClawProxy instead of directly to OpenRouter/Anthropic/OpenAI. ClawProxy analyzes each request, applies your routing rules, forwards it to the optimal provider, logs the result, and returns the response. Your agents see no difference — the API is fully OpenAI-compatible.

Quick Setup

Get up and running in under 2 minutes.

1. Create an account

Sign up at clawproxy.ai/auth/signup. You'll get a free Starter plan with 10,000 requests/month.

2. Generate an API key

After completing onboarding, go to Settings → API Keys and generate your first key. It looks like cp_sk_a8f3x9d2e5b1c7f4...

3. Configure your agent

Point your agent to ClawProxy by updating the base URL and adding your key:

{
  "apiBaseUrl": "https://clawproxy.ai/api/proxy/v1",
  "customHeaders": {
    "x-clawproxy-key": "cp_sk_YOUR_KEY_HERE"
  }
}

Or use the Authorization header (Bearer token):

curl https://clawproxy.ai/api/proxy/v1/chat/completions \
  -H "Authorization: Bearer cp_sk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

4. Environment variables

For OpenClaw or similar agents, set these environment variables:

OPENCLAW_API_BASE_URL=https://clawproxy.ai/api/proxy/v1
OPENCLAW_CUSTOM_HEADERS=x-clawproxy-key:cp_sk_YOUR_KEY_HERE

API Reference

ClawProxy exposes an OpenAI-compatible API. Any tool or SDK that works with OpenAI will work with ClawProxy — just change the base URL.

Base URL

https://clawproxy.ai/api/proxy/v1

Authentication

Pass your API key using either method:

• Authorization: Bearer cp_sk_... header
• x-clawproxy-key: cp_sk_... header

POST /chat/completions

Create a chat completion. Supports all standard OpenAI parameters including streaming.

{
  "model": "anthropic/claude-sonnet-4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Explain quantum computing in one sentence."}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 500
}

Supported models

ClawProxy supports all models available on OpenRouter:

GET /models

List all available models. Proxied directly from OpenRouter.

Response format

Responses are identical to the OpenAI format. ClawProxy adds an x-clawproxy-model header showing the actual model used (may differ from requested if routing rules applied).

Smart Routing

ClawProxy analyzes the complexity of each request and routes it to the cheapest model that can handle it. This is the core feature that saves you 60-70% on LLM costs.

The classifier adds ~15ms per request. For most workloads, cheaper models respond faster, so total latency often decreases.

Custom Routing Rules

Override the automatic routing with your own rules. Go to Settings → Rules in the dashboard to create rules.

Rule types

• Model override — Force a specific model for matching requests (e.g., always use Opus for code review)
• Priority — Rules with higher priority are evaluated first
• Conditions — Match on model name, agent label, or request content

API: Manage rules

# List rules
GET /api/rules

# Create rule
POST /api/rules
{
  "name": "Always use Opus for code",
  "rule_type": "model_override",
  "conditions": {"model_pattern": "anthropic/*"},
  "action_value": "anthropic/claude-opus-4",
  "priority": 10
}

# Update rule
PUT /api/rules/{id}

# Delete rule
DELETE /api/rules/{id}

Loop Detection

When an agent gets stuck in a loop — sending the same request over and over — ClawProxy detects the pattern and kills it automatically. This prevents runaway costs that can reach hundreds of dollars overnight.

How it works

ClawProxy hashes each request (model + last 3 messages, truncated to 200 chars). If it sees more than 10 identical hashes in 60 seconds from the same user, it returns a 429 status and logs the event as loop_killed.

Response when loop detected

{
  "error": {
    "message": "Loop detected: identical request repeated 11 times in 60s",
    "type": "loop_detected",
    "code": 429
  }
}

Pro Team — Loop detection is available on Pro and Team plans.

Budget Controls

Set hard spending limits so you never get surprised by a bill. Go to Settings → General to configure budgets.

Daily budget

Maximum spend per day. When reached, non-essential requests return 429 budget_exceeded.

Monthly budget

Maximum spend per calendar month. Same behavior as daily budget.

Budget alerts

ClawProxy sends email alerts at 75% and 90% of your daily budget, so you can take action before hitting the limit.

API: Manage budgets

# Get current budgets
GET /api/settings

# Update budgets
PUT /api/settings
{
  "daily_budget": 5.00,
  "monthly_budget": 100.00
}

Pro Team — Spending limits are available on Pro and Team plans.

Analytics & Dashboard

The ClawProxy dashboard gives you full visibility into your AI spending.

Overview

See total spend, savings, request count, active agents, and model distribution at a glance.

Live feed

Real-time stream of every request passing through ClawProxy, including model used, tokens, cost, latency, and status.

Per-agent breakdown

Track costs per agent (API key). See which agents are costing the most and where you're saving.

Analytics API

# Overview stats
GET /api/analytics/overview?range=week&agent=all

# Recent requests (live feed)
GET /api/analytics/requests?limit=50

# Per-agent stats
GET /api/analytics/agents

Team Management

Invite team members to share your ClawProxy account. Each member gets their own API keys and can view analytics.

Inviting members

Go to Settings → Team and enter the email address of the person you want to invite. They'll receive an email with a link to join.

Roles

• Admin — Full access to all settings, billing, and team management
• Member — Can create API keys and view analytics, but can't manage billing or team

Team — Team management is available on the Team plan (up to 25 seats).

Plans & Pricing

FAQ