mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-03 13:52:09 +03:00
docs: add AgentRouter setup guide (#2422)
Integrated into release/v3.8.0 — AgentRouter setup guide docs.
This commit is contained in:
Lenine Júnior
149
docs/AGENTROUTER.md
Normal file
149
docs/AGENTROUTER.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user