GateRouter Documentation

Getting Started

1. Create an API key

1. Go to gaterouter.ai, choose login method, and authorize
2. Go to Console → Settings → API keys → Create a key

2. Auto routing (optional)

Auto routing is enabled by default. To control it:

Console → Settings → Routing → Auto routing toggle

Once enabled, GateRouter automatically selects the best model for each request. If you prefer to pick models yourself, skip this step and specify models directly (e.g. anthropic/claude-sonnet-4.6).

Standard Setup

Fully compatible with the OpenAI API. Supports Python, Node.js, curl, and tools across the ecosystem.

Replace the Base URL ( https://api.gaterouter.ai/openai/v1 ) and API key to start using it.

from openai import OpenAI

client = OpenAI(
    api_key="GATEROUTER_API_KEY",  # get GATEROUTER_API_KEY from gaterouter.ai (API Key)
    base_url="https://api.gaterouter.ai/openai/v1",
)

completion = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "system", "content": "system prompt"},
        {"role": "user", "content": "how are you?"}
    ],
)

# get the response from LLM (role=assistant)
print(completion.choices[0].message.content)

{
    "id": "243c850e-214c-431e-977f-ebaf4aa95f56",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Hello! Nice to meet you. How can I help you?"
            },
            "finish_reason": "stop"
        }
    ],
    "created": 1773408946,
    "model": "deepseek.v3-v1:0",
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 15,
        "total_tokens": 20
    }
}

OpenClaw Setup

If you already have OpenClaw installed, follow the steps below to connect GateRouter.

Connect GateRouter

Method 1: Web console

1. Start the web console

In a terminal, run:

openclaw dashboard

The browser will open the console (usually http://127.0.0.1:18789). If the browser does not open automatically, please visit that address manually.

2. Go to configuration page

Select Config → Raw mode.

3. Add GateRouter configuration

Add env and set GATEROUTER_API_KEY to your GateRouter API Key:

env: {
    vars: {
      GATEROUTER_API_KEY: 'sk-or-v1-xxxxxxxxxxxxxxxx',
    },
  },

Add models with baseUrl set to https://api.gaterouter.ai/openai/v1:

models: {
  mode: 'merge',
  providers: {
    gaterouter: {
      baseUrl: 'https://api.gaterouter.ai/openai/v1',
      apiKey: '${GATEROUTER_API_KEY}',
      api: 'openai-completions',
      models: [
        {
          id: 'gaterouter/auto',
          name: 'Gaterouter Auto',
          api: 'openai-completions',
          reasoning: false,
          input: ['text'],
          cost: {
            input: 0,
            output: 0,
            cacheRead: 0,
            cacheWrite: 0,
          },
          contextWindow: 200000,
          maxTokens: 8192,
        },
      ],
    },
  },
},

Replace the original "agents": {...} section with:

agents: {
  defaults: {
    model: {
      primary: 'gaterouter/auto',
    },
    models: {
      'gaterouter/auto': {
        alias: 'Gaterouter Auto',
      },
    },
  },
},

4. Save and apply configuration

Web console: Click Save in the top right, then Update.

5. Verify connection

In OpenClaw Chat, send a test message such as "Hello". If configured correctly GateRouter API is called → auto-routed to the best model → response is returned.

Method 2: Edit config file

1. Locate the openclaw.json file

macOS:

Open Finder, press Command + Shift + G

Enter: ~/.openclaw

Press Enter to see openclaw.json.

Windows:

Path: C:\Users\<YourUsername>\.openclaw\openclaw.json

2. Add GateRouter configuration

Add env and set GATEROUTER_API_KEY to your GateRouter API Key:

"env": {
  "vars": {
    "GATEROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxx"
  }
},

Add models with baseUrl set to https://api.gaterouter.ai/openai/v1:

"models": {
  "mode": "merge",
  "providers": {
    "gaterouter": {
      "baseUrl": "https://api.gaterouter.ai/openai/v1",
      "apiKey": "${GATEROUTER_API_KEY}",
      "api": "openai-completions",
      "models": [
        {
          "id": "gaterouter/auto",
          "name": "Gaterouter Auto",
          "api": "openai-completions",
          "reasoning": false,
          "input": ["text"],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 200000,
          "maxTokens": 8192
        }
      ]
    }
  }
},

Replace the original "agents": {...}, section with:

"agents": {
  "defaults": {
    "model": {
      "primary": "gaterouter/minimax/minimax-m2.5"
    },
    "models": {
      "gaterouter/auto": {
        "alias": "Gaterouter Auto"
      }
    }
  }
},

3. Save and verify configuration

After saving the config file, run the following in a terminal to view the file and confirm it is correct:

cat ~/.openclaw/openclaw.json

4. Verify connection

Run the following in a local terminal to start a CLI conversation:

openclaw tui

Or run the following to use OpenClaw Chat in the browser:

openclaw dashboard

Optional configuration

Auto model routing

GateRouter recommends setting primary to gaterouter/auto.

Automatically selects the best model by price, latency, and availability.

Use a specific model

To use a fixed model, e.g. set primary to gaterouter/deepseek/deepseek-v3.2

FAQ

1. Only OpenAI models succeed; other models fail

   Models available through GateRouter use the OpenAI-compatible protocol. In OpenClaw integration settings, set the api field to openai-completions (as in the examples above). If OpenAI-family models work but all others fail, check the providers entry: the api type.

2. Model not found or empty response

   Confirm the model ID spelling is correct; the configured provider name matches what you reference; and reasoning must be set to false.

Cursor Setup

If you already have Cursor installed, follow these steps to connect GateRouter.

1. Open Cursor Settings

Use the menu in the top-right corner → Settings.

2. Models

In the left sidebar:

• Open Models.
• Choose View All Models, scroll to the bottom, then Add Custom Model.
• Enter the specific model ID, e.g. deepseek/deepseek-v3.2. Do not use auto.

3. Add GateRouter

Configure API access:

• Expand API Keys.
• Paste your GateRouter API key.
• Set Base URL to https://api.gaterouter.ai/openai/v1

4. Save and close the Settings page.

5. Use GateRouter in Cursor

In Chat, Composer, or Agent, choose your GateRouter model from the model dropdown.

Claude Code Setup

export ANTHROPIC_BASE_URL="https://api.gaterouter.ai/anthropic"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"
claude

export ANTHROPIC_BASE_URL="https://api.gaterouter.ai/anthropic"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.gaterouter.ai/anthropic",
    "ANTHROPIC_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxx"
  }
}

env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY claude

export ANTHROPIC_MODEL="anthropic/claude-sonnet-4.6"

export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-4.6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-4.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-4.5"

export ANTHROPIC_CUSTOM_MODEL_OPTION="anthropic/claude-sonnet-4.6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet (GateRouter)"

claude

Hermes Setup

Prerequisites

• Create an API key in the GateRouter Console.
• If you use auto routing, enable it under Settings → Routing in the console.

Option 1: Terminal setup

1. Choose model and custom endpoint

Run in your terminal:

hermes model

In the menu, choose Custom endpoint and fill in the fields:

If you are asked for context length, press Enter to leave it blank (Hermes will detect it).

2. (Optional) Local web dashboard

To edit configuration in the browser, run:

hermes dashboard

3. Verify

hermes chat "Hello"

Success means the request reached GateRouter and smart routing or your chosen model returned a result.

You can also run hermes doctor to verify the connection.

Option 2: Edit configuration files

1. File locations

macOS / Linux

• ~/.hermes/config.yaml, main config (model, provider, base_url, api_key, etc.)
• ~/.hermes/.env, secrets and env vars (recommended)

Windows

• C:\Users\<username>\.hermes\config.yaml
• C:\Users\<username>\.hermes\.env

2. Save the API key in .env (pick one)

Option A (same name as GateRouter)

# GateRouter API 密钥
GATEROUTER_API_KEY=sk-or-v1_xxxxxxxxxxxxxxxxxxxxx

Option B (common Hermes custom-endpoint convention)

If model.api_key is not set for a custom endpoint, Hermes falls back to OPENAI_API_KEY. Put your GateRouter key there:

OPENAI_API_KEY=sk-or-v1_xxxxxxxxxxxxxxxxxxxxx

3. Configure model in config.yaml

Auto routing (auto)

model:
  default: auto
  provider: custom
  base_url: https://api.gaterouter.ai/openai/v1
  api_key: ${GATEROUTER_API_KEY}

If you use Option B, leave api_key blank or remove it so Hermes uses OPENAI_API_KEY.

Hermes expands ${VAR} when loading config (variables must exist in the environment, usually from ~/.hermes/.env).

Fixed model example

The model ID must match the GateRouter model list.

model:
  default: deepseek/deepseek-v3.2
  provider: custom
  base_url: https://api.gaterouter.ai/openai/v1
  api_key: ${GATEROUTER_API_KEY}

4. Verify after saving

After saving, run hermes chat "Hello" to verify the GateRouter connection.

Multiple routes / models

If you need multiple logical routes under one GateRouter key (e.g. one with auto and one fixed to deepseek/deepseek-v3.2), add custom_providers in config.yaml (names: letters, digits, hyphens; e.g. gaterouter-auto):

model:
  default: auto
  provider: custom
  base_url: https://api.gaterouter.ai/openai/v1
  api_key: ${GATEROUTER_API_KEY}

custom_providers:
  - name: gaterouter-auto
    base_url: https://api.gaterouter.ai/openai/v1
    api_key: ${GATEROUTER_API_KEY}
    model: auto

  - name: gaterouter-deepseek
    base_url: https://api.gaterouter.ai/openai/v1
    api_key: ${GATEROUTER_API_KEY}
    model: deepseek/deepseek-v3.2

How to switch

1. Terminal: run hermes model again and pick the named route or Custom endpoint.
2. In chat (TUI): use the /model syntax from the Hermes docs, for example:

/model custom:gaterouter-auto:auto
/model custom:gaterouter-deepseek:deepseek/deepseek-v3.2

(Names follow custom_providers[].name; format is custom:<profile name>:<model id>.)

FAQ

QClaw Setup

If you already have QClaw installed, follow these steps to connect GateRouter.

Configure in chat

1. In the chat, send the message below. Replace the apiKey value with your GateRouter API key.

Help me add a new provider
Name: GateRouter
apiKey: sk-or-v1-xxxxxxxxxxxxxxxx
baseUrl: https://api.gaterouter.ai/openai/v1
Models (you can pass multiple): 1. auto  2. deepseek/deepseek-v3.2

QClaw will add the provider and restart automatically.

2. Verify

Ask: “Help me verify that my GateRouter configuration is working.” The assistant should reply with something like “GateRouter provider was added successfully!” (exact wording may vary.)

3. Switch to GateRouter

Ask: “Switch to auto under GateRouter.” The assistant should reply with something like “Switched successfully!” (exact wording may vary.)

AutoClaw Setup

1. Open the configuration entry

Click Preferences in the bottom-left, go to Models & API, then click Add custom model.

2. Add a model

• Set the provider to Custom.
• Enter a GateRouter-supported model ID, e.g. deepseek/deepseek-v3.2.
• Enter a display name, e.g. GateRouter(deepseek-v3.2).
• Enter your API Key, e.g. sk-or-v1-xxxxxxxxxxxxxxxx.
• Base URL: https://api.gaterouter.ai/openai/v1

3. Test the configuration

Click the connection test. If you see “Test successful”, the setup is correct.

4. Use the model

• Click Add. After it saves, return to the app.
• Below the chat input, switch the model to your configured GateRouter(deepseek-v3.2) to use it.

API Reference

Endpoints

Models

Model ID format: provider/model-name. Version numbers use . (e.g. 4.6), not -.

For more models, visit the Models page.

Troubleshooting