Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

docs: add AgentRouter setup guide (#2422)

Lenine Júnior8bd125ed2f3d
diff --git a/docs/AGENTROUTER.md b/docs/AGENTROUTER.md
new file mode 100644
index 0000000000..2333bc0883
--- /dev/null
+++ b/docs/AGENTROUTER.md
@@ -0,0 +1,149 @@
+# AgentRouter Setup Guide
+
+[AgentRouter](https://agentrouter.org) is an Anthropic-compatible relay that resells
+Claude and other models, often at lower prices than the direct Anthropic API. It is
+designed as a drop-in `ANTHROPIC_BASE_URL` replacement for the official Claude Code
+client, so it only accepts traffic that matches the Claude Code wire image (specific
+User-Agent, `anthropic-beta` flags, Stainless SDK headers, etc.).
+
+OmniRoute supports AgentRouter through the **Claude Code compatible** provider type
+(`anthropic-compatible-cc-*`), which speaks the Anthropic Messages API with the
+correct wire image. A generic `openai-compatible-chat` provider pointing at
+`https://agentrouter.org` will **not** work — the upstream WAF rejects requests that
+do not look like Claude Code.
+
+---
+
+## Prerequisites
+
+- An AgentRouter account and API key. New signups get free credits via the affiliate
+ link in the project [README](../README.md).
+- OmniRoute running with the `ENABLE_CC_COMPATIBLE_PROVIDER` feature flag enabled
+ (see below).
+
+## 1. Enable the CC-compatible provider type
+
+The Claude Code compatible provider type is gated behind a feature flag because it
+sends traffic that closely mirrors the official Claude Code client. Enable it by
+setting an environment variable before starting OmniRoute:
+
+```bash
+ENABLE_CC_COMPATIBLE_PROVIDER=true
+```
+
+Docker example:
+
+```bash
+docker run -d --name omniroute \
+ --restart unless-stopped \
+ -p 20128:20128 \
+ -v omniroute-data:/app/data \
+ -e ENABLE_CC_COMPATIBLE_PROVIDER=true \
+ diegosouzapw/omniroute:latest
+```
+
+After restarting, the dashboard exposes an **Add Claude Code Compatible** option in
+addition to the existing OpenAI-compatible and Anthropic-compatible flows.
+
+## 2. Create the provider in the dashboard
+
+1. Open **Dashboard → Providers → Add Provider**.
+2. Choose **Add Claude Code Compatible** (only visible when the flag above is set).
+3. Fill in the fields:
+
+| Field | Value |
+| --------- | -------------------------------------------------------------- |
+| Name | `AgentRouter` (or any label) |
+| Prefix | `agentrouter` (friendly alias shown in logs and the dashboard) |
+| Base URL | `https://agentrouter.org` |
+| Chat path | `/v1/messages?beta=true` (default — leave as-is) |
+
+> The canonical model identifier still uses the full provider node ID
+> (`anthropic-compatible-cc-{uuid}/{model}`). The **Prefix** is just a display
+> alias resolved by `src/lib/usage/callLogs.ts` for friendlier log output.
+
+4. (Optional) Paste your API key in the **Validate** field and click **Check** to
+ confirm connectivity before saving.
+5. Click **Add**.
+
+Once created, open the provider and add a **Connection** with your AgentRouter API
+key (`sk-...`). The connection's `test_status` should turn `active`.
+
+## 3. Use it through a combo or directly
+
+Reference the model using your provider's prefix as the namespace:
+
+```bash
+curl -X POST http://localhost:20128/v1/chat/completions \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "agentrouter/claude-opus-4-6",
+ "messages": [{"role": "user", "content": "hello"}],
+ "max_tokens": 100
+ }'
+```
+
+The canonical model ID `anthropic-compatible-cc-{uuid}/claude-opus-4-6` also works
+and is what shows up in the database and combo configuration.
+
+Or add it to a combo for routing, fallback, and quota management like any other
+provider.
+
+---
+
+## Wire image details
+
+For reference, the cc-compatible bridge sends the following on each upstream
+request (see `open-sse/services/claudeCodeCompatible.ts`):
+
+| Header | Value |
+| ------------------------------------------- | ------------------------------------------------------------------------ |
+| `Authorization` | `Bearer <api-key>` |
+| `User-Agent` | `claude-cli/2.1.137 (external, sdk-cli)` |
+| `anthropic-version` | `2023-06-01` |
+| `anthropic-beta` | `claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24` |
+| `anthropic-dangerous-direct-browser-access` | `true` |
+| `x-app` | `cli` |
+| `X-Stainless-*` | Various Stainless SDK headers (lang, package version, OS, arch, etc.) |
+
+This is what allows requests to pass the upstream WAF / client whitelist.
+
+---
+
+## Troubleshooting
+
+**`{"error":{"message":"unauthorized client detected, ..."}}`** — Your request did
+not match the Claude Code wire image. This happens when the provider is configured
+as `openai-compatible-chat` instead of `anthropic-compatible-cc`, or when the
+`ENABLE_CC_COMPATIBLE_PROVIDER=true` flag was not set at startup.
+
+**`{"error":{"message":"无效的令牌","type":"new_api_error"}}` (HTTP 401)** —
+"Invalid token". The wire image is correct but the API key is rejected. Generate a
+new key in the AgentRouter dashboard and update the connection.
+
+**`{"error":{"code":"content-blocked","type":"agent_router_api_error"}}`
+(HTTP 400)** — AgentRouter's moderation hook rejected the request content, or the
+key's plan does not permit the requested model. Try a different prompt or model;
+contact AgentRouter support if a benign prompt is consistently blocked.
+
+**`[400]: content-blocked` only on specific models** — Most AgentRouter plans only
+allow a subset of models (e.g. `claude-opus-4-6`). Other model IDs return
+`unauthorized_client_error` even though the key is valid. Check which models your
+plan covers in the AgentRouter dashboard.
+
+**`Invalid JSON response from provider (reset after Ns)` from the omniroute logs** —
+The upstream returned a non-JSON body (typically an HTML error page from the WAF).
+This usually means the request never reached the AgentRouter backend — recheck that
+the provider ID starts with `anthropic-compatible-cc-` (note the trailing dash —
+see `CLAUDE_CODE_COMPATIBLE_PREFIX` in `open-sse/services/claudeCodeCompatible.ts`)
+and the feature flag is enabled.
+
+---
+
+## See also
+
+- [`docs/PROVIDERS.md`](./PROVIDERS.md) — Other provider integration notes
+- [`docs/reference/FREE_TIERS.md`](./reference/FREE_TIERS.md) — Free-tier provider
+ catalog
+- [`open-sse/services/claudeCodeCompatible.ts`](../open-sse/services/claudeCodeCompatible.ts)
+ — Wire image implementation