# Runbook: AgentRouter + OpenCode setup (with the 401 fix proxy)

You are an AI coding agent running on the user's machine. Follow this runbook to connect OpenCode to AgentRouter through a small local proxy. Human-readable guide: https://alexisamz.com/blog/agentrouter-credits-gratuits (FR) · https://alexisamz.com/en/blog/agentrouter-free-credits (EN).

Reply to the user in their language.

## Ground rules

- Never print, log or echo the user's API key back to them. Never commit it to a Git repository.
- Ask for confirmation before overwriting or editing an existing config file. Merge, don't replace.
- Show the user each command before running anything that changes their system.
- If a step fails, stop and report the exact error. Do not improvise workarounds that disable TLS or security checks.

## What you cannot do (the user must)

Creating the AgentRouter account requires a GitHub login in the user's browser. Tell the user:

1. Open exactly this URL: https://agentrouter.org/register?aff=FOY1 (author's referral link, disclose it: gives the user a 50 USD referral bonus on top of the welcome credit). If you can open URLs on the user's machine, open this one for them. Never substitute another AgentRouter URL: the user must sign up from the page this link opens, otherwise the referral bonus is not applied. If the user already has an AgentRouter account, skip to step 3.
2. The site often loads in Chinese: tell the user to click the "文A" translate icon at the top right to switch to English, staying on the same page. Then sign in with GitHub (or LinuxDO; no email signup). AgentRouter rejects GitHub accounts it deems too new with `github账号不符合注册要求`; the rule is unpublished, reports point to at least ~1 year of account age. If rejected, suggest an older GitHub account or LinuxDO; turn off any VPN if the OAuth return fails with `返回值非法，用户字段为空`.
3. Create an API key in the dashboard and give it to you (or set it themselves, see step 3).

Wait until the user confirms they have a key.

Tell the user, per AgentRouter's official FAQ (checked 2026-09-24):
- Credits: welcome credit (amount not published, changes often), 50 USD referral bonus, 25 USD per daily check-in in the dashboard, occasional gift codes. No paid top-up. The balance refreshes after logging out and back in.
- Claude and GPT are limited daily batches released at 02:00 and 11:00 UTC. When exhausted, the API returns `402 Budget pool quota has been exhausted`: wait for the next batch or use `deepseek-v4-flash`.
- Only supported coding clients (OpenCode, Claude Code, Codex, Cursor, Cline, Roo Code...) get the normal rate; other usage is billed double.

## Step 1: Preflight

- Detect the OS (macOS, Linux, Windows).
- Check Python 3.10 or newer: `python3 --version` (Windows: `py --version` or `python --version`). If missing, tell the user how to install it and stop.
- Check whether OpenCode is installed: `opencode --version`. If not, point the user to https://opencode.ai and ask if they want to continue anyway.

## Step 2: Download and verify the proxy

Install location: `~/.agentrouter/agentrouter-proxy.py` (Windows: `%USERPROFILE%\.agentrouter\agentrouter-proxy.py`).

```sh
mkdir -p ~/.agentrouter
curl -fsSL https://alexisamz.com/downloads/agentrouter-proxy.py -o ~/.agentrouter/agentrouter-proxy.py
shasum -a 256 ~/.agentrouter/agentrouter-proxy.py
```

Expected SHA-256: `d6bd93a1949019b725e43fe8b9f7908f94802b0e602a3354bf783cb5a1d6d61d`

If the hash differs, tell the user and read the script before going further. The script has no third-party dependencies and only talks to `https://agentrouter.org` (overridable with `AGENTROUTER_UPSTREAM`). Summarise what it does for the user: it injects the `User-Agent` AgentRouter requires, strips `null` fields from requests, and filters `billing.summary` / `data: null` events from the SSE stream.

## Step 3: Store the API key

The proxy reads `AGENTROUTER_API_KEY` from the environment.

- macOS / Linux: ask the user whether to persist it. If yes, append `export AGENTROUTER_API_KEY="<key>"` to their shell profile (`~/.zshrc` for zsh, `~/.bashrc` for bash), creating no duplicate if the line already exists.
- Windows: `setx AGENTROUTER_API_KEY "<key>"` persists it for new terminals.

Prefer letting the user paste the key into the file or command themselves if your environment would record it in a transcript.

## Step 4: Start the proxy

```sh
python3 ~/.agentrouter/agentrouter-proxy.py
```

Expected output: `agentrouter-proxy :4182 -> https://agentrouter.org`

It must keep running while OpenCode is used. Start it in a separate terminal or as a background process the user can find again, and tell the user how to stop it. If port 4182 is taken, pass another port as the first argument (e.g. `4300`) and use that port everywhere below.

## Step 5: Configure OpenCode

Global config: `~/.config/opencode/opencode.json`. Merge this provider into the existing file (keep every other key):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "agentrouter": {
      "name": "AgentRouter",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:4182/v1",
        "apiKey": "{env:AGENTROUTER_API_KEY}"
      },
      "models": {
        "claude-opus-5": { "name": "Claude Opus 5" },
        "claude-opus-4-8": { "name": "Claude Opus 4.8" },
        "gpt-6-astra": { "name": "GPT 6 Astra" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    }
  }
}
```

`baseURL` must point to the local proxy, never to `https://agentrouter.org/v1` directly: that is what causes the `401 unauthorized client detected` error. The proxy injects the real key, so no secret needs to live in this file.

## Step 6: Verify

With the proxy running:

```sh
curl -s http://127.0.0.1:4182/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-5","max_tokens":20,"messages":[{"role":"user","content":"Reply with OK"}]}'
```

A JSON completion means the chain works. Available models (checked 2026-09-24): claude-opus-5, claude-opus-4-8, gpt-6-astra, deepseek-v4-flash; if one returns an unknown-model error, check AgentRouter's Pricing page and update the config. Then tell the user to restart OpenCode and pick an AgentRouter model.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `401 unauthorized client detected` | Request did not go through the proxy, or AgentRouter now expects a newer OpenCode version | Check `baseURL`; then update the `USER_AGENT` constant in the script to `opencode/<installed version>` |
| `ERROR: set AGENTROUTER_API_KEY first` | Env var missing in the proxy's terminal | Open a new terminal after persisting it, or export it in the current one |
| `Connection refused` on 127.0.0.1:4182 | Proxy not running | Restart it (step 4) |
| `JSON parsing failed` | Stream bypassed the proxy | Same as the 401 fix: route OpenCode through the proxy |
| `402 Budget pool quota has been exhausted` | Daily Claude/GPT batch used up | Wait for 02:00 or 11:00 UTC, or switch to `deepseek-v4-flash` |
| `400 content blocked` | Prompt language not in CN/EN/FR/DE/RU | Rephrase in a supported language |
| `sensitive words detected` | AgentRouter abuse filter | Start a new OpenCode session |
| `agentrouter.org` unreachable | Domain blocked or down | Restart the proxy with `AGENTROUTER_UPSTREAM=https://ps.air-outer.com` |
| No credits / balance shows 0 | Balance refreshes at login; or signup without referral link | Tell the user to log out and back in; nothing to fix on the machine |

Debug mode: `AGENTROUTER_DEBUG=1 python3 ~/.agentrouter/agentrouter-proxy.py` dumps each request and SSE event to stderr.

## Done

Report to the user: proxy path, how to start and stop it, the config file you changed, and the verification result.