RealRelay.ai
程式碼代理

OpenCode 設定指南

把 RealRelay.ai 設為 OpenCode 的自訂 OpenAI 相容供應商:安裝、在 opencode.json 中新增供應商區塊、檢查連線,並連同上限一起加入模型。

建立 API 密鑰瀏覽模型目錄
協定
OpenAI Chat Completions · OpenAI Responses
基礎位址
https://www.realrelay.ai/v1
官方文件
opencode.ai
已對照工具官方文件核對
2026-10

概覽

OpenCode 是在終端機中執行的開源程式碼代理。它會讀取你的專案、編輯檔案並執行指令。你把 RealRelay.ai 加為它的自訂供應商後,它會把請求送到 Chat Completions 端點 /v1/chat/completions。

  • 一組 API 金鑰,在主控台的 API 金鑰頁面取得。

  • 結尾要含 /v1 的基礎位址。OpenCode 會在後面加上 /chat/completions。

  • 一個模型 ID,完全依照 GET /v1/models 列出的寫法,例如 z-ai/glm-5.2。該模型必須支援工具呼叫。

本頁適用於 OpenCode 1,也就是 opencode.ai/docs 所記載的目前穩定版。OpenCode 2 預覽版的供應商設定結構不同,所以下方的檔案不適用於它。

安裝

請使用 OpenCode 官方文件中的任一種方式。每種方式安裝的都是同一個 opencode 指令。

macOS · Linux · WSL
curl -fsSL https://opencode.ai/install | bashopencode --version
Homebrew (macOS · Linux)
brew install anomalyco/tap/opencode

OpenCode 建議使用它自己的 tap。一般的 brew install opencode formula 由 Homebrew 維護,更新頻率較低。

npm
npm install -g opencode-ai
Windows PowerShell
choco install opencode# orscoop install opencode

如果 opencode --version 印出版本號,就代表安裝成功。OpenCode 的文件建議使用 WezTerm、Alacritty、Ghostty 或 Kitty 等現代終端機。

設定

  1. 1

    把金鑰存進環境變數

    設定檔會從 REALRELAY_API_KEY 讀取金鑰,所以檔案本身不含任何機密。

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"

    執行 source ~/.zshrc,或開啟新的終端機。

    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")

    關閉並重新開啟終端機,讓它讀到新的變數。

  2. 2

    把 RealRelay.ai 加為供應商

    把以下內容放進全域設定。若只想在單一專案中使用,請改把同樣的內容放進專案根目錄的 opencode.json。

    ~/.config/opencode/opencode.json
    1{2  "$schema": "https://opencode.ai/config.json",3  "provider": {4    "realrelay": {5      "npm": "@ai-sdk/openai-compatible",6      "name": "RealRelay.ai",7      "options": {8        "baseURL": "https://www.realrelay.ai/v1",9        "apiKey": "{env:REALRELAY_API_KEY}"10      },11      "models": {12        "z-ai/glm-5.2": {13          "name": "z-ai/glm-5.2",14          "limit": {15            "context": 200000,16            "output": 3200017          }18        }19      }20    }21  },22  "model": "realrelay/z-ai/glm-5.2"23}

  • realrelay 是供應商 ID。名稱可以任取,但每個模型參照都以它開頭,例如 realrelay/z-ai/glm-5.2。

  • npm 決定 OpenCode 載入哪個用戶端。@ai-sdk/openai-compatible 會送出 Chat Completions 請求。

  • OpenCode 啟動時,{env:REALRELAY_API_KEY} 會被替換成該變數的值。如果沒有設定這個變數,金鑰就是空的,請求會以 401 失敗。

  • models 底下的每個鍵,都是送到 RealRelay.ai 的模型 ID。limit 用來告訴 OpenCode 上下文視窗與最大輸出量,因為 RealRelay.ai 的模型清單中不含這些資訊。

  • model 設定新工作階段的預設模型。

你也可以不用環境變數,改用 OpenCode 的 /connect 指令儲存金鑰。選擇 Other,並輸入與檔案中相同的供應商 ID。接著移除 apiKey 那一行。

OpenCode
1/connect2# Select provider → Other3# Enter provider id → realrelay4# Enter your API key → sk-***

驗證

  1. 1

    直接呼叫端點

    用你的金鑰執行這段指令。若收到含 choices 陣列的 JSON 回覆,就代表位址、金鑰與模型都沒問題。

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/chat/completions" \2  -H "Authorization: Bearer sk-***" \3  -H "content-type: application/json" \4  -d '{"model": "z-ai/glm-5.2", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'
  2. 2

    確認 OpenCode 看得到供應商

    第一個指令應會把你的模型列為 realrelay/…。第二個指令會送出一則訊息並印出回覆。

    Terminal
    opencode models realrelayopencode run -m "realrelay/z-ai/glm-5.2" "Reply with OK"
  3. 3

    在專案中啟動工作階段

    執行 /models 並選擇 RealRelay.ai 的模型,然後送出一則簡短訊息。該請求會出現在主控台的用量日誌中。

    OpenCode
    cd /path/to/your/projectopencode/models

模型

OpenCode 只會顯示你在供應商底下列出的模型。要新增模型,請再加一筆含 ID 與上限的項目,然後以 /models 選取,或以 opencode -m realrelay/<model-id> 啟動。

~/.config/opencode/opencode.json → provider.realrelay.models
1"z-ai/glm-5.2": {2  "name": "z-ai/glm-5.2",3  "limit": { "context": 200000, "output": 32000 }4},5"<another-model-id>": {6  "name": "<another-model-id>",7  "limit": { "context": 128000, "output": 16000 }8}

這些範例中的上限是安全的起始值。請把 limit.context 與 limit.output 設為模型目錄頁面上的實際數值,讓 OpenCode 在正確的時機壓縮對話。

少數 OpenAI 模型是在 Responses 端點 /v1/responses 上提供。OpenCode 透過 @ai-sdk/openai 用戶端連到這個端點。請為這些模型另外新增一個使用同一組金鑰的供應商,其他模型則繼續使用 Chat Completions 供應商:

~/.config/opencode/opencode.json → provider
1"realrelay-responses": {2  "npm": "@ai-sdk/openai",3  "name": "RealRelay.ai (Responses)",4  "options": {5    "baseURL": "https://www.realrelay.ai/v1",6    "apiKey": "{env:REALRELAY_API_KEY}"7  },8  "models": {9    "openai/gpt-5.3-codex": {10      "name": "openai/gpt-5.3-codex",11      "limit": { "context": 400000, "output": 128000 }12    }13  }14}

哪些模型適合代理使用、哪些模型由 Responses 端點提供,請見選擇模型。

疑難排解

  • /models 中沒有該供應商或模型。JSON 沒有載入成功,或 models 對應表是空的。請檢查 OpenCode 實際解析到的是哪份設定;對於相同的鍵,專案中的 opencode.json 會覆寫全域檔案。

    Terminal
    opencode auth listopencode debug config

  • 401。金鑰是空的或錯誤。請確認在啟動 OpenCode 的終端機中已設定 REALRELAY_API_KEY。如果你用的是 /connect,opencode auth list 應會顯示你的供應商 ID,而且它必須與檔案中的 ID 相同。

  • 404。基礎位址缺少 /v1,或已經以 /chat/completions 結尾。請使用以 /v1 結尾的位址。

  • 找不到模型。models 底下的鍵必須與 GET /v1/models 傳回的 ID 完全相同,包括斜線之前的部分。

  • 在只支援 Responses 的模型上,或在你移到 Responses 供應商的模型上出現錯誤。只有「選擇模型」中列出的模型在 /v1/responses 上提供。其他模型請留在 @ai-sdk/openai-compatible 供應商。

  • 對話不斷變長,直到請求被拒絕。limit.context 沒有設定,或大於模型的實際視窗。請依模型目錄頁面設定,並執行 /compact。

  • 代理描述了要做的修改,卻沒有實際動手。模型沒有呼叫工具。請挑選支援工具呼叫的模型。