# Clawzempic — Optimization Proxy for AI Agents

Drop-in proxy that makes your LLM API calls cheaper and more observable. Works with Anthropic (Claude) and OpenRouter (300+ models including GPT, Gemini, DeepSeek, Kimi, Grok, Llama, Mistral, and more). Change one URL, add two headers, save 70-95% on API costs.

## Supported Providers

| Provider | Key prefix | What you get |
|----------|-----------|--------------|
| **Anthropic** | `sk-ant-...` | Claude models with intelligent routing (simple/mid/complex tiers) + automatic prompt caching |
| **OpenRouter** | `sk-or-...` | 300+ models from every major provider. Use any model available on openrouter.ai |

You bring your own API key from either provider. Keys are used per-request and never stored unless you opt in.

## How it works

```
Your Agent  →  Clawzempic Proxy  →  Anthropic API  or  OpenRouter API
              (routes, caches,      (your key, your usage)
               observes)
```

**With Anthropic keys:** Clawzempic routes simple requests to cheaper Claude models (Haiku/Sonnet), injects prompt caching automatically, manages conversation memory, and passes complex requests to Opus untouched.

**With OpenRouter keys:** Clawzempic routes simple requests to cheaper models (e.g. Gemini Flash) and passes complex requests to your chosen model untouched. Same intelligent routing as Anthropic, now for 300+ OpenRouter models. Pin any request with `x-model-pinned: true` to bypass routing.

Both providers get: intelligent model routing, usage insights, spend tracking, anomaly detection, burst protection, memory management, and the full observability stack. Anthropic also gets automatic prompt caching.

## Quick Start (2 minutes)

### 1. Sign up

```bash
curl -s -X POST https://api.clawzempic.ai/v1/signup \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "agent_name": "my-agent", "framework": "custom", "promo_code": "LAUNCH100"}'
```

Response:

```json
{
  "client_id": "clwz_a1b2c3d4e5f6",
  "api_key": "sk-clwz-...",
  "proxy_url": "https://api.clawzempic.ai/v1/chat",
  "base_url": "https://api.clawzempic.ai",
  "plan": "free",
  "savings_cap_usd": 30,
  "setup": {
    "required_headers": {
      "x-api-key": "sk-clwz-...",
      "x-upstream-key": "YOUR_EXISTING_ANTHROPIC_OR_OPENROUTER_KEY",
      "x-upstream-provider": "anthropic (default) or openrouter"
    }
  }
}
```

Save your `api_key`. It is shown once.

### 2. Route traffic

Change your base URL to `https://api.clawzempic.ai` and add two headers:

| Header | Value | Required |
|--------|-------|----------|
| `x-api-key` | Your Clawzempic key (`sk-clwz-...`) | Yes |
| `x-upstream-key` | Your Anthropic (`sk-ant-...`) or OpenRouter (`sk-or-...`) key | Yes |
| `x-upstream-provider` | `anthropic` (default) or `openrouter` | Defaults to `anthropic` if omitted. Required when using an OpenRouter key or switching providers per-request |
| `x-model-pinned` | `true` | No. Set to bypass routing and use exactly the model you request |

The endpoint is `POST /v1/chat/completions` (OpenAI-compatible format).

### 3. Verify it works

```bash
curl -s https://api.clawzempic.ai/v1/insights \
  -H 'x-api-key: sk-clwz-YOUR_KEY'
```

Returns cost savings, model mix, cache hit rates, and recommendations after your first request.

## Framework Setup

### OpenClaw (v2026.2+)

The easiest way:

```bash
npx clawzempic --key YOUR_CLAWZEMPIC_KEY
```

The CLI auto-detects OpenClaw, patches `auth-profiles.json`, `models.json`, and `openclaw.json`.

**Manual setup:** Add a `clawzempic` profile to `~/.openclaw/auth-profiles.json`:

```json
{
  "version": 1,
  "profiles": {
    "clawzempic": {
      "type": "api_key",
      "provider": "anthropic",
      "key": "YOUR_CLAWZEMPIC_KEY",
      "baseUrl": "https://api.clawzempic.ai"
    }
  }
}
```

Then set your default model in `~/.openclaw/openclaw.json`:

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "clawzempic/claude-sonnet-4-6"
      }
    }
  }
}
```

Restart: `openclaw gateway restart`

### Nanobot

Set these env vars (or add to Doppler):

```bash
NANOBOT_PROVIDERS__ANTHROPIC__API_KEY=sr_YOUR_CLAWZEMPIC_KEY
NANOBOT_PROVIDERS__ANTHROPIC__API_BASE=https://api.clawzempic.ai
```

Nanobot's litellm provider auto-detects the `sr_` prefix and routes through Clawzempic.

### LangChain / LangGraph (Anthropic)

```python
from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(
    model="claude-sonnet-4-6",
    anthropic_api_url="https://api.clawzempic.ai",
    default_headers={
        "x-api-key": "sk-clwz-YOUR_CLAWZEMPIC_KEY",
        "x-upstream-key": "sk-ant-YOUR_ANTHROPIC_KEY",
    },
)
```

### LangChain / LangGraph (OpenRouter — any model)

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="google/gemini-2.5-flash",  # or deepseek/deepseek-r1, meta-llama/llama-4-maverick, etc.
    openai_api_base="https://api.clawzempic.ai/v1",
    openai_api_key="sk-or-YOUR_OPENROUTER_KEY",
    default_headers={
        "x-api-key": "sk-clwz-YOUR_CLAWZEMPIC_KEY",
        "x-upstream-key": "sk-or-YOUR_OPENROUTER_KEY",
        "x-upstream-provider": "openrouter",
    },
)
```

### Python (Anthropic SDK)

```python
import anthropic

client = anthropic.Anthropic(
    api_key="sk-ant-YOUR_ANTHROPIC_KEY",
    base_url="https://api.clawzempic.ai",
    default_headers={
        "x-api-key": "sk-clwz-YOUR_CLAWZEMPIC_KEY",
        "x-upstream-key": "sk-ant-YOUR_ANTHROPIC_KEY",
    },
)
```

### Python (OpenAI SDK — works with OpenRouter)

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-or-YOUR_OPENROUTER_KEY",
    base_url="https://api.clawzempic.ai/v1",
    default_headers={
        "x-api-key": "sk-clwz-YOUR_CLAWZEMPIC_KEY",
        "x-upstream-key": "sk-or-YOUR_OPENROUTER_KEY",
        "x-upstream-provider": "openrouter",
    },
)

response = client.chat.completions.create(
    model="deepseek/deepseek-r1",
    messages=[{"role": "user", "content": "Hello"}],
)
```

### curl (Anthropic)

```bash
curl -s -X POST https://api.clawzempic.ai/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: sk-clwz-YOUR_KEY' \
  -H 'x-upstream-key: sk-ant-YOUR_ANTHROPIC_KEY' \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 256
  }'
```

### curl (OpenRouter — any model)

```bash
curl -s -X POST https://api.clawzempic.ai/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: sk-clwz-YOUR_KEY' \
  -H 'x-upstream-key: sk-or-YOUR_OPENROUTER_KEY' \
  -H 'x-upstream-provider: openrouter' \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 256
  }'
```

## What You Get

### Free Tier ($0/mo)

- Free forever. No credit card needed. No trial period.
- **Anthropic:** intelligent 4-tier model routing (simple/mid/complex/reasoning) + automatic prompt caching
- **OpenRouter:** intelligent model routing (routes simple → cheap models, complex → your model) + cost tracking
- **Both:** conversation windowing, memory management, usage insights, spend alerts, anomaly detection, burst protection, security scanning
- $30 savings cap per month. After that, requests pass through directly to your upstream provider (still works, no optimization)

### Pro Tier ($29/mo)

- Unlimited optimized spend
- Priority support
- Everything in Free
- Upgrade: `POST /v1/billing/checkout` with your `x-api-key` header

## Popular OpenRouter Models

Any model on openrouter.ai works. Some popular choices:

| Model | Model ID | Use case |
|-------|----------|----------|
| GPT-4.1 | `openai/gpt-4.1` | General purpose |
| Gemini 2.5 Flash | `google/gemini-2.5-flash` | Fast + cheap |
| Gemini 2.5 Pro | `google/gemini-2.5-pro` | Complex reasoning |
| DeepSeek R1 | `deepseek/deepseek-r1` | Code + math |
| Kimi K2.5 | `moonshotai/kimi-k2.5` | Long context |
| Grok 3 | `x-ai/grok-3-beta` | General purpose |
| Llama 4 Maverick | `meta-llama/llama-4-maverick` | Open source |
| Mistral Large | `mistralai/mistral-large` | European alternative |
| Claude Opus 4.6 | `anthropic/claude-opus-4-6` | Via OpenRouter instead of direct |

Pass any valid OpenRouter model ID in the `model` field of your request. Model IDs and availability change — see [openrouter.ai/models](https://openrouter.ai/models) for the current list.

## API Reference

All endpoints use `https://api.clawzempic.ai` as the base URL.

### Chat Completions

```
POST /v1/chat/completions
```

OpenAI-compatible chat completions. Requires `x-api-key` and `x-upstream-key` headers. Set `x-upstream-provider: openrouter` if using an OpenRouter key.

Response headers:
- `X-Router-Model` — actual model used (may differ from requested if using Anthropic routing)
- `X-Router-Reason` — why that model was chosen
- `X-Router-Provider` — `anthropic` or `openrouter`
- `X-Clawzempic` — `optimized` or `passthrough`
- `X-Clawzempic-Alert` — spend alerts (threshold-80, threshold-95, passthrough-entered, burst-detected)

Supports streaming (`"stream": true`).

### Signup

```
POST /v1/signup
Content-Type: application/json

{"agent_name": "my-bot", "framework": "openclaw"}
```

- `email` — **required**, valid email address. Used for billing, spend alerts, and magic login links
- `agent_name` — optional, alphanumeric + spaces/hyphens/underscores, max 100 chars
- `framework` — optional, one of: `openclaw`, `nanobot`, `langchain`, `autogpt`, `custom`
- `promo_code` — optional, applies a promo code to raise your free tier savings cap. Invalid codes are silently ignored.
- `referral_code` — optional, freeform string for attribution tracking
- Duplicate emails rejected (409). Email verification required for dashboard access.
- Returns: `client_id`, `api_key`, `proxy_url`, `setup` instructions

### Insights

```
GET /v1/insights?period=7d
x-api-key: sk-clwz-...
```

Periods: `24h`, `7d`, `30d`. Returns:

- `summary` — total requests, cost, tokens, latency, passthrough count
- `model_mix` — breakdown by model (requests, cost, percentage)
- `savings` — baseline vs actual cost, amount and percentage saved
- `caching` — cache hit rate, read/write tokens, estimated savings
- `daily_trend` — per-day request and cost trend
- `anomalies` — days with unusually high spend
- `recommendations` — actionable suggestions
- `usage_limit` — current spend vs limit (free tier)

Cached for 5 minutes.

### Billing

```
GET  /v1/billing/status          # plan, spend, subscription status
POST /v1/billing/checkout        # create Stripe checkout session (upgrade to Pro)
POST /v1/billing/portal          # Stripe billing portal (manage subscription)
POST /v1/billing/key/rotate      # rotate your Clawzempic API key
```

All require `x-api-key` header.

### Dashboard Auth

```
POST /v1/auth/session            # get a dashboard session token (requires x-api-key)
POST /v1/auth/magic              # request magic login link (requires email in body)
```

### Agent Discovery

```
GET /.well-known/agent.json      # A2A protocol service descriptor
```

Machine-readable service description including capabilities, pricing, signup endpoint, and required headers.

## Response Headers to Watch

| Header | Meaning | Action |
|--------|---------|--------|
| `X-Clawzempic: optimized` | Request went through optimization pipeline | Normal operation |
| `X-Clawzempic: passthrough` | Free tier limit reached, forwarding directly | Consider upgrading |
| `X-Clawzempic-Alert: threshold-80` | 80% of free tier spent | Budget awareness |
| `X-Clawzempic-Alert: threshold-95` | 95% of free tier spent | Upgrade soon |
| `X-Clawzempic-Alert: passthrough-entered` | Now in passthrough mode | No more savings until reset |
| `X-Clawzempic-Alert: burst-detected` | High request volume detected | Check for loops |

## Model Routing

Clawzempic scores every request's complexity and routes to the optimal model per tier:

| Tier | Anthropic | OpenRouter (default) | When | Typical share |
|------|-----------|---------------------|------|---------------|
| Simple | Claude Haiku | Gemini 2.5 Flash | Greetings, short questions, simple lookups | ~75% |
| Mid | Claude Sonnet | Your requested model | Most moderate tasks, standard tool use | ~18% |
| Complex | Claude Opus | Your requested model | Analysis, debugging, multi-step reasoning | ~5% |
| Reasoning | Claude Sonnet | Your requested model | Deep analysis, proofs, multi-step logic | ~2% |

**Routing is on by default for all providers.** To opt out per-request, add `x-model-pinned: true` header. To customize or disable routing, use the Settings API or the portal.

### Settings API

```
GET  /v1/settings                 # View current settings + defaults
PATCH /v1/settings                # Update routing config
```

Requires `x-api-key` header. Example:

```bash
# Disable routing
curl -X PATCH https://api.clawzempic.ai/v1/settings \
  -H 'x-api-key: sk-clwz-YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"routing": {"enabled": false}}'

# Set custom model for simple tier
curl -X PATCH https://api.clawzempic.ai/v1/settings \
  -H 'x-api-key: sk-clwz-YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"routing": {"models": {"simple": "meta-llama/llama-4-maverick"}}}'
```

### Settings Portal

Log in with your email at `https://www.clawzempic.ai/dash` to manage routing settings in a web UI.

## Errors

| Status | Code | Meaning |
|--------|------|---------|
| 400 | `MISSING_UPSTREAM_KEY` | Add `x-upstream-key` header with your Anthropic or OpenRouter key |
| 400 | `INVALID_UPSTREAM_PROVIDER` | `x-upstream-provider` must be `anthropic` or `openrouter` |
| 401 | — | Invalid or missing `x-api-key` |
| 429 | — | Rate limit exceeded |
| 502 | `UPSTREAM_ERROR` | Your upstream provider returned an error (check your key) |
| 502 | `UPSTREAM_REDIRECT` | Upstream returned a redirect (blocked for security) |

## Security

Five security layers protect your agent traffic:

1. **Injection Detection** — Multi-layer detection identifies prompt injection attempts in tool results and user content; suspicious content flagged with warnings
2. **Prompt Extraction Protection** — Per-request canary tokens detect system prompt extraction attempts; leaks automatically redacted
3. **Tool Call Blocking** — Outbound tool calls inspected against pattern library covering 5 attack categories; dangerous operations (RCE, destructive commands, data exfiltration) blocked
4. **Credential Redaction** — API keys, tokens, SSH keys, connection strings automatically detected and redacted from inbound and outbound content
5. **Runtime Pattern Library** — New attack patterns added without redeployment

Additional:
- Your upstream API key (`x-upstream-key`) is used per-request and never stored unless you opt in via `PATCH /v1/settings`
- Clawzempic keys (`sk-clwz-...`) are stored as SHA-256 hashes
- All traffic is TLS 1.3 (Cloudflare)
- Rate limiting on all endpoints
- Request metadata (tokens, cost, model) stored for insights; full conversations not stored long-term

## Support

- **Docs:** [api.clawzempic.ai/docs](https://api.clawzempic.ai/docs)
- **Status page:** [status.clawzempic.ai](https://status.clawzempic.ai)
- **Email:** [support@clawzempic.ai](mailto:support@clawzempic.ai)

## FAQ

**Does Clawzempic see my conversations?**
Yes, requests pass through the proxy for optimization and observability. Conversations are not stored long-term. Request metadata (tokens, cost, model) is logged for your insights dashboard.

**Will my bot behave differently?**
Simple requests may be routed to faster, cheaper models (both Anthropic and OpenRouter). Complex requests always use your chosen model. Pin any request with `x-model-pinned: true` to bypass routing. Customize tier models at `/v1/settings` or via the portal.

**What if Clawzempic goes down?**
Your bot gets a 502 error. Implement a fallback to call your upstream provider directly.

**Which models work?**
Anthropic: all Claude models (Haiku, Sonnet, Opus). OpenRouter: any model available on openrouter.ai (300+ models from OpenAI, Google, Meta, DeepSeek, Mistral, xAI, and more).

**Can I switch providers per-request?**
Yes. Each request specifies its own `x-upstream-key` and `x-upstream-provider`. You can mix Anthropic and OpenRouter calls within the same account.

**Do I need separate accounts for Anthropic and OpenRouter?**
No. One Clawzempic account works with both providers. Just change the headers per-request.