General principles

Coding agents fall into three protocol families. Check which one your tool uses before wiring it up:

  • OpenAI Chat Completions compatible: most tools. Base URL is <your-gateway>/v1, API key is your OpenTokenRouter key.
  • OpenAI Responses: Codex CLI. Base URL is <your-gateway>/v1.
  • Anthropic Messages: Claude Code. Base URL is <your-gateway> (no /v1).

Model IDs come from the Live settlement rows on the home page, or from /v1/models.

Codex CLI

Use a dedicated profile; full steps are in the Client Setup guide. The core file ~/.codex/opentokenrouter.config.toml:

model_provider = "opentokenrouter"

[model_providers.opentokenrouter]
name = "OpenTokenRouter"
base_url = "<your-gateway>/v1"
env_key = "OPENTOKENROUTER_API_KEY"
wire_api = "responses"

Run: export OPENTOKENROUTER_API_KEY=sk-YOUR_KEY && codex --profile opentokenrouter --model MODEL_ID.

Claude Code

Full steps are in the Client Setup guide. Core:

export ANTHROPIC_BASE_URL="<your-gateway>"
export ANTHROPIC_AUTH_TOKEN="sk-YOUR_KEY"
claude

Cursor

  1. Open Settings → Models.
  2. Add or select an OpenAI-compatible provider in the API Key area and enter your API key.
  3. Set Override OpenAI Base URL to <your-gateway>/v1.
  4. Enable the model IDs you want to use (from /v1/models).

Note: some built-in Cursor features still use official services; custom models only affect chat and code generation requests.

Windsurf

  1. Click the model selector at the bottom-left → Add custom model.
  2. Choose an OpenAI-compatible provider, set Base URL to <your-gateway>/v1.
  3. Enter the API key and model ID, save, and select it.

Cline

  1. Open Settings → API Provider.
  2. Choose OpenAI Compatible.
  3. Set Base URL to <your-gateway>/v1 and API key to your key.
  4. Enter an available model ID.

Roo Code

Same flow as Cline (also a VS Code extension): Settings → API Provider → OpenAI Compatible, Base URL <your-gateway>/v1, key, and model ID.

OpenCode

Edit ~/.config/opencode/opencode.json and add an OpenAI-compatible provider:

{
  "provider": {
    "opentokenrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenTokenRouter",
      "options": {
        "baseURL": "<your-gateway>/v1",
        "apiKey": "{env:OPENTOKENROUTER_API_KEY}"
      }
    }
  }
}

Run: export OPENTOKENROUTER_API_KEY=sk-YOUR_KEY && opencode --provider opentokenrouter.

Aider

export OPENAI_API_BASE="<your-gateway>/v1"
export OPENAI_API_KEY="sk-YOUR_KEY"
aider --model MODEL_ID

Or pass flags directly: aider --openai-api-base <your-gateway>/v1 --openai-api-key sk-YOUR_KEY.

Continue

Edit ~/.continue/config.json and add an OpenAI-compatible model:

{
  "models": [{
    "title": "OpenTokenRouter",
    "provider": "openai",
    "model": "MODEL_ID",
    "apiBase": "<your-gateway>/v1",
    "apiKey": "sk-YOUR_KEY"
  }]
}

FAQ

  • 400 protocol error: the tool's protocol does not match the route (do not point Responses clients at chat/completions).
  • 401: wrong or missing API key.
  • Model unavailable: the ID must come from /v1/models and be marked Live settlement.
  • Interrupted stream / slow first token: do not buffer SSE at a local proxy.