RealRelay.ai
程式碼代理

OpenClaw 設定指南

把 RealRelay.ai 設為 OpenClaw 的自訂 OpenAI 相容供應商:安裝、新增 models.providers 項目、確認 Gateway 看得到它並選擇模型。

建立 API 密鑰瀏覽模型目錄
協定
OpenAI Chat Completions
基礎位址
https://www.realrelay.ai/v1
官方文件
docs.openclaw.ai
已對照工具官方文件核對
2026-10
實驗性. 尚未在 RealRelay.ai 上完整端對端測試。步驟依據該工具的官方文件；若某一步失敗，請附上錯誤訊息聯絡支援。

概覽

OpenClaw 是一款自行架設的助理。一個名為 Gateway 的背景程序在你自己的電腦上執行,把記憶與工作階段都保存在本機,並透過儀表板或你連接的聊天應用程式回應你。RealRelay.ai 不是它內建的供應商,所以要把 RealRelay.ai 加為使用 OpenAI Chat Completions API(/v1/chat/completions)的自訂供應商。

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

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

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

這套設定依據 OpenClaw 的文件撰寫,但尚未在 RealRelay.ai 上完整端對端跑過。正式依賴它之前,請先完成「驗證」一節中的檢查。

安裝

請使用 OpenClaw 的安裝程式。它會在缺少 Node.js 時自動安裝,接著安裝 OpenClaw,然後啟動設定精靈。你可以先用任一供應商完成精靈,之後再切換到 RealRelay.ai;也可以直接關閉精靈,依下一節操作。

macOS · Linux · WSL2
curl -fsSL https://openclaw.ai/install.sh | bash
Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

OpenClaw 另提供 Windows 桌面應用程式 Windows Hub。下載連結請見安裝頁面。

npm (Node.js 24.16+)
npm install -g openclaw@latest --allow-scripts=openclawopenclaw onboard --install-daemon

若使用 npm 11.15 或更舊的版本,請省略 --allow-scripts=openclaw。

--install-daemon 會把 Gateway 安裝為背景服務,所以關閉終端機後它仍會繼續執行。

設定

你可以自行編輯設定檔,完整掌控模型清單;也可以讓設定精靈替你寫入。

  1. 1

    把金鑰存在 Gateway 讀得到的地方

    Gateway 以背景服務執行,看不到你在終端機中 export 的變數。請改把金鑰放進 OpenClaw 自己的環境變數檔。請把 sk-*** 換成你的金鑰。

    ~/.openclaw/.env
    REALRELAY_API_KEY=sk-***
  2. 2

    新增供應商

    把以下內容合併到 ~/.openclaw/openclaw.json。這個檔案是 JSON5 格式,允許註解與結尾逗號。請保留精靈寫入的其他設定。

    ~/.openclaw/openclaw.json
    1{2  models: {3    mode: "merge",4    providers: {5      realrelay: {6        baseUrl: "https://www.realrelay.ai/v1",7        apiKey: "${REALRELAY_API_KEY}",8        api: "openai-completions",9        models: [10          {11            id: "z-ai/glm-5.2",12            name: "z-ai/glm-5.2",13            reasoning: false,14            input: ["text"],15            contextWindow: 200000,16            maxTokens: 32768,17          },18        ],19      },20    },21  },22  agents: {23    defaults: {24      model: { primary: "realrelay/z-ai/glm-5.2" },25    },26  },27}
  3. 3

    重新啟動 Gateway

    Gateway 會監看設定檔,並自動套用大部分變更。但它只在啟動時讀取環境變數檔,所以加入金鑰後請重新啟動一次。

    Terminal
    openclaw gateway restart

執行 openclaw onboard 並選擇自訂供應商選項,或一次傳入所有參數。加上 --secret-input-mode ref 時,精靈儲存的是指向 CUSTOM_API_KEY 的參照,而不是金鑰本身。

Terminal
1export CUSTOM_API_KEY="sk-***"2openclaw onboard --non-interactive --accept-risk \3  --auth-choice custom-api-key \4  --custom-base-url "https://www.realrelay.ai/v1" \5  --custom-model-id "z-ai/glm-5.2" \6  --custom-compatibility openai \7  --custom-text-input \8  --secret-input-mode ref

接著把同一個變數加進環境變數檔,讓背景執行的 Gateway 能解析它,然後重新啟動 Gateway。供應商名稱由精靈自行決定;openclaw models list 會顯示它。

~/.openclaw/.env
CUSTOM_API_KEY=sk-***

  • realrelay 是供應商名稱。你可以改用其他名稱,但它必須與 agents.defaults.model.primary 中的前綴相同。

  • mode: "merge" 會把 RealRelay.ai 加在 OpenClaw 內建供應商旁邊,而不是取代它們。

  • Gateway 載入設定時,會從環境變數讀取 "${REALRELAY_API_KEY}",所以金鑰永遠不會出現在 openclaw.json 中。

  • api: "openai-completions" 會送出 Chat Completions 請求。請保持原樣:RealRelay.ai 上大多數模型只在這個端點上提供。

  • contextWindow 與 maxTokens 告訴 OpenClaw 模型能接收與回傳多少內容。RealRelay.ai 不會回報這些數值,所以請依模型目錄頁面設定。這裡顯示的值對 z-ai/glm-5.2 是安全的。

  • primary 模型必須出現在該供應商的 models 清單中。只列在 agents.defaults.models 底下,並不會讓它變成可用。

驗證

  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

    檢查 Gateway 與模型清單

    openclaw gateway status 應回報 Gateway 正在執行。openclaw models status 會顯示預設模型,它應以 realrelay/ 開頭;而 openclaw models list 應包含你的模型。openclaw dashboard 會在瀏覽器中開啟儀表板。

    Terminal
    1openclaw gateway status2openclaw models status3openclaw models list4openclaw dashboard
  3. 3

    送出訊息

    在儀表板的聊天中送出一則簡短訊息。收到回覆即確認整條路徑暢通,而該請求也會出現在主控台的用量日誌中。

模型

在聊天中,以 /model 加上模型參照,即可切換目前的工作階段。若要變更新工作階段的預設模型,請使用 openclaw models set。模型參照的格式是供應商名稱、一個斜線,再接完整的 RealRelay.ai 模型 ID,所以其中會有兩個斜線。

OpenClaw chat
/model realrelay/z-ai/glm-5.2
Terminal
openclaw models set realrelay/z-ai/glm-5.2

OpenClaw 只提供你在供應商底下列出的模型。每個想用的模型新增一個項目,並各自設定上限:

~/.openclaw/openclaw.json → models.providers.realrelay.models
{ id: "z-ai/glm-5.2", name: "z-ai/glm-5.2", contextWindow: 200000, maxTokens: 32768 },{ id: "deepseek/deepseek-v4-pro", name: "deepseek/deepseek-v4-pro", contextWindow: 200000, maxTokens: 32768 },

如果省略 contextWindow,OpenClaw 會假設為 200,000 token。如果省略 maxTokens,它不會送出輸出上限,而是套用模型的預設值。哪些模型適合代理使用,請見選擇模型。

疑難排解

  • 401 或「Invalid token」。Gateway 看不到金鑰。請確認金鑰位於 ~/.openclaw/.env,而不只是在終端機中 export,然後重新啟動 Gateway。工作目錄中的 .env 檔案不算數:OpenClaw 會忽略其中的供應商金鑰。

  • 404。baseUrl 缺少 /v1,或已經以 /chat/completions 結尾。它應以 /v1 結尾,後面不接任何內容。

  • 「Unknown model」或沒有使用預設模型。primary 的前綴與供應商名稱不符,或該模型不在供應商的 models 清單中。模型 ID 區分大小寫。

  • 變更預設模型後,某個工作階段仍使用舊模型。既有的工作階段會沿用它啟動時的模型。請在該工作階段中執行 /model default。

  • 400 並提到 reasoning_effort:發生在你標示為 reasoning: true 的模型上。請為該模型關閉這個欄位:

    ~/.openclaw/openclaw.json → models.providers.realrelay.models
    1{2  id: "z-ai/glm-5.2",3  reasoning: true,4  compat: { supportsReasoningEffort: false },5},

  • 長對話中出現上下文錯誤。contextWindow 大於模型的實際上限。請調低到模型目錄頁面上的數值。

  • 儀表板中看不出明顯問題。以 openclaw gateway stop 停止背景服務,然後在前景執行 Gateway 觀察它的日誌。完成後,以 openclaw gateway start 重新啟動服務。

    Terminal
    openclaw gateway --port 18789