GateRouter 文件

快速開始

1. 建立 API 密鑰

1. 前往 gaterouter.ai，選擇登入模式，授權登入
2. 進入控制台 → 進入設定 → 進入 API 密鑰 → 建立密鑰

2. 自動路由（選用）

自動路由預設開啟，控制方式：

進入控制台 → 進入設定 → 進入路由 → 自動路由開關

啟用後，GateRouter 會自動為每個請求選擇最佳模型。若你偏好自行選擇模型，可略過此步驟，直接指定模型（如 anthropic/claude-sonnet-4.6）。

標準接入

與 OpenAI API 完全相容，支援 Python、Node.js、curl 等生態工具。

替換 Base URL ( https://api.gaterouter.ai/openai/v1 )與 API 密鑰即可使用。

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 接入

若您已安裝好 OpenClaw，請依以下步驟接入 GateRouter。

接入 GateRouter

方式 1：Web 控制台設定

1. 啟動 Web 控制台

在終端機中執行以下指令：

openclaw dashboard

瀏覽器會自動開啟控制台頁面（通常為 http://127.0.0.1:18789）。如果瀏覽器沒有自動開啟，請手動造訪該網址。

2. 進入設定頁面

選擇 設定 → Raw 模式。

3. 新增 GateRouter 設定

在 JSON 中新增 env，並將 GATEROUTER_API_KEY 替換為您的 GateRouter API 密鑰：

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

新增 models，將 baseUrl 設為 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,
        },
      ],
    },
  },
},

將原本的 "agents": {...} 區塊替換為：

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

4. 儲存並套用設定

Web 控制台：設定完成後，點擊右上角 Save 儲存，再點擊 Update。

5. 驗證接入成功

在 OpenClaw Chat 介面傳送測試訊息，例如：Hello。若設定成功，系統會呼叫 GateRouter API → 自動路由至最佳模型 → 回傳結果。

方式 2：編輯檔案設定

1. 找到 openclaw.json 檔案

macOS：

開啟 Finder，快速鍵：Command + Shift + G

輸入：~/.openclaw

按 Enter，即可看到 openclaw.json。

Windows：

路徑：C:\Users\你的使用者名稱\.openclaw\openclaw.json

2. 新增 GateRouter 設定

在 JSON 中新增 env，並將 GATEROUTER_API_KEY 替換為您的 GateRouter API 密鑰：

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

新增 models，將 baseUrl 設為 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
        }
      ]
    }
  }
},

替換原 "agents": {...}, 部分：

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

3. 儲存及驗證設定

儲存設定檔後，在終端機中執行以下指令檢視內容，確認設定正確：

cat ~/.openclaw/openclaw.json

4. 驗證接入成功

在本地終端機中執行以下指令，即可透過命令列開始對話：

openclaw tui

也可在終端機中執行以下指令，在 OpenClaw Chat 介面進行對話：

openclaw dashboard

可選設定

自動模型路由

GateRouter 推薦將 primary 設為 gaterouter/auto。

根據價格、延遲、可用性，自動選擇最佳模型。

指定模型

若需固定模型，例如：primary 設為 gaterouter/deepseek/deepseek-v3.2

常見問題

1. 當僅 OpenAI 系列模型請求成功，而其他模型均請求失敗

   目前我們提供接入的模型均支援 OpenAI 通用協定。請在 OpenClaw 接入設定中，將 api 設為 openai-completions（參見上文範例）。若 OpenAI 系列模型可用而其他模型均失敗，請優先檢查 providers 設定項中的 api 類型。

2. 提示找不到模型或回覆為空

   請確認：模型 ID 拼寫是否正確；設定中的 provider 名稱與引用時是否一致；設定中的 reasoning 參數必須設為 false。

Cursor 接入

若您已安裝 Cursor，請依下列步驟接入 GateRouter。

1. 開啟 Cursor 設定

右上角選單 → Settings。

2. 進入 Models 設定

在左側選單中：

• 找到並開啟 Models。
• 點選 View All Models，滑到最底部，點選 Add Custom Model。
• 填寫具體模型 ID，例如：deepseek/deepseek-v3.2。不能填寫auto。

3. 新增 GateRouter 設定

填寫接入資訊：

• 展開 API Keys。
• 填寫您的 GateRouter API 密鑰。
• 填寫 GateRouter 的 Base URL：https://api.gaterouter.ai/openai/v1

4. 儲存並關閉 Settings 頁面。

5. 在 Cursor 中使用 GateRouter

在 Chat、Composer、Agent 等對話介面中，於模型下拉選單選擇已新增的 GateRouter 模型即可使用。

Claude Code 接入

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 接入

前置條件

• 已在 GateRouter 控制台 建立 API 金鑰。
• 若使用自動路由，請在控制台 設定 → 路由 中開啟 自動路由。

方式一：終端機設定

1. 選擇模型與自訂端點

在終端機執行：

hermes model

在選單中選擇 Custom endpoint，依提示填寫：

若詢問 context length（上下文長度），直接按 Enter 留空即可（由 Hermes 自動偵測）。

2.（選用）本機 Web 管理介面

若希望以瀏覽器編輯設定，可執行：

hermes dashboard

3. 驗證

hermes chat "Hello"

成功表示請求已到達 GateRouter，並由智能路由或你指定的模型回傳結果。

也可執行 hermes doctor 驗證是否連線成功。

方式二：直接編輯設定檔

1. 檔案位置

macOS / Linux

• ~/.hermes/config.yaml，主要設定（模型、provider、base_url、api_key 等）
• ~/.hermes/.env，金鑰與敏感環境變數（建議）

Windows

• C:\Users\<使用者名稱>\.hermes\config.yaml
• C:\Users\<使用者名稱>\.hermes\.env

2. 在 .env 中儲存金鑰（擇一）

寫法 A（與 GateRouter 命名一致）

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

寫法 B（與 Hermes 自訂端點常見約定一致）

Hermes 對自訂端點在未單獨設定 model.api_key 時，會退回使用 OPENAI_API_KEY。可將 GateRouter 金鑰寫入：

OPENAI_API_KEY=sk-or-v1_xxxxxxxxxxxxxxxxxxxxx

3. 在 config.yaml 中設定 model

自動路由（auto）

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

若使用 寫法 B，可將 api_key 留空或刪除該欄位，讓 Hermes 使用 OPENAI_API_KEY。

Hermes 會在載入設定時展開 ${VAR}（變數須已存在於環境中，通常由 ~/.hermes/.env 注入）。

固定模型範例

模型 ID 須與 GateRouter 模型列表 一致）：

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

4. 儲存後驗證

儲存後用 hermes chat "Hello" 測試 GateRouter 連線來驗證。

多線路 / 多模型

若同一組 GateRouter 金鑰下需要 多條邏輯線路（例如一條用 auto、一條固定 deepseek/deepseek-v3.2），可在 config.yaml 中設定 custom_providers（名稱僅允許字母、數字、連字號等；建議用連字號，例如 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

切換方式

1. 終端機：再次執行 hermes model，在選單中選擇對應命名線路或 Custom endpoint。
2. 對話中（TUI）：使用 Hermes 官方文件中的 /model 語法，例如：

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

（實際名稱以 custom_providers[].name 為準；三段為 custom:<設定名>:<模型 id>。）

常見問題

QClaw 接入

若您已安裝 QClaw，請依下列步驟接入 GateRouter。

對話式完成設定

1. 在對話中輸入以下內容，請將 apiKey 替換為您的 GateRouter API 密鑰：

幫我新增一個 provider
名稱：GateRouter
apiKey: sk-or-v1-xxxxxxxxxxxxxxxx
baseUrl: https://api.gaterouter.ai/openai/v1
模型（可傳多個）： 1、auto  2、deepseek/deepseek-v3.2

QClaw 會自動新增成功並重新啟動後生效。

2. 驗證是否成功

直接輸入：「幫我驗證一下 GateRouter 設定有沒有生效」。對話應回覆「GateRouter provider 已成功新增！」（實際文案以介面為準。）

3. 切換到 GateRouter 使用

直接輸入：「切換到 GateRouter 下面的 auto」。對話應回覆「已切換成功！」（實際文案以介面為準。）

AutoClaw 接入

1. 設定入口

點選左下角偏好設定，選擇模型與 API，再點選新增自訂模型。

2. 新增模型

• 服務商選擇自訂。
• 新增 GateRouter 支援的模型 ID，例如 deepseek/deepseek-v3.2。
• 填寫顯示名稱，例如：GateRouter(deepseek-v3.2)。
• 填寫 API Key，例如：sk-or-v1-xxxxxxxxxxxxxxxx。
• 填寫 Base URL：https://api.gaterouter.ai/openai/v1

3. 測試設定是否成功

點選連通測試，若顯示「測試成功」，表示設定成功。

4. 使用模型

• 點選新增按鈕，儲存成功後返回應用程式。
• 在聊天框下方切換模型，選擇已設定的 GateRouter(deepseek-v3.2)，即可使用。

API 參考

端點

模型

模型 ID 格式：provider/model-name。版本號使用 .（如 4.6），而非 -。

更多模型可前往模型頁面查看

故障排除