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
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
docs: add AgentRouter setup guide (#2422)
Lenine Júnior8bd125ed2f3d
diff --git a/docs/AGENTROUTER.md b/docs/AGENTROUTER.mdnew file mode 100644index 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