RealRelay.ai
程式碼代理

nanobot 設定指南

把 RealRelay.ai 設為 nanobot 的自訂 OpenAI 相容供應商:安裝、在 config.json 中新增供應商與模型預設集、檢查設定並切換模型。

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

概覽

nanobot 是 HKUDS 推出的小型開源個人代理。它在你自己的電腦上執行,能處理檔案、記住偏好並執行排程任務;你可以透過瀏覽器、終端機或聊天應用程式與它對話。你要把 RealRelay.ai 加為自訂供應商,它使用 OpenAI Chat Completions API(/v1/chat/completions)。

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

  • 結尾要含 /v1 的基礎位址。nanobot 不會替自訂供應商猜測 URL,所以這個欄位是必填的。

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

nanobot 無法從 RealRelay.ai 讀取模型的上下文視窗。請依「設定」一節的說明,在模型預設集中設定。本頁介紹的是在 PyPI 上以 nanobot-ai 發布的 nanobot 代理,而非其他同名專案。

安裝

nanobot 需要 Python 3.11 或更新版本。官方安裝程式會替你選用一個獨立的 Python 環境,並在完成時開啟設定。如果你已經在使用 uv,請改為自行安裝套件。

macOS · Linux
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh
Windows PowerShell
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
uv (Python 3.11+)
uv tool install nanobot-ainanobot onboard

安裝程式會印出它用來執行 nanobot 的完整指令。請把它記下來:如果 nanobot 不在你的 PATH 中,下文所有地方都請改用那個指令。

設定

你可以在瀏覽器的 Settings → Models 中設定供應商:建立新的預設集,在 Provider 選單中選擇 Add provider,再輸入連線資訊。以下步驟則是直接在檔案中編輯同樣的設定。

  1. 1

    把金鑰存進環境變數

    這樣金鑰就不會出現在設定檔中。完成後請開啟新的終端機。

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"
    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")
  2. 2

    新增供應商與模型預設集

    把這些區塊合併到 ~/.nanobot/config.json,並保留檔案中既有的其他設定。如果檔案還不存在,請先執行 nanobot onboard。

    ~/.nanobot/config.json
    1{2  "providers": {3    "realrelay": {4      "apiKey": "${REALRELAY_API_KEY}",5      "apiBase": "https://www.realrelay.ai/v1"6    }7  },8  "modelPresets": {9    "primary": {10      "provider": "realrelay",11      "model": "z-ai/glm-5.2",12      "maxTokens": 8192,13      "contextWindowTokens": 20000014    }15  },16  "agents": {17    "defaults": {18      "modelPreset": "primary"19    }20  }21}
  3. 3

    重新啟動 nanobot

    nanobot 會在啟動時填入金鑰。如果 WebUI 或 gateway 已經在執行,請先停止再重新啟動。

  • realrelay 是你為這個供應商取的名稱。它必須與預設集中的 provider 相同,而且不能是 openai 這類內建供應商名稱。

  • ${REALRELAY_API_KEY} 會在啟動時從環境變數填入。這個值永遠不會寫回檔案。

  • 在這裡明確設定 provider 很重要。設定之後,nanobot 會照原樣送出 z-ai/glm-5.2。若維持 auto,nanobot 可能會把斜線之前的部分當成供應商名稱。

  • contextWindowTokens 是模型的視窗大小,maxTokens 限制單次回覆的長度。這裡顯示的值是安全的下限;請使用模型目錄頁面上的數字。

驗證

  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

    檢查 nanobot 的設定並送出一則訊息

    nanobot status 會檢查設定,但不會呼叫模型。它應在 Config 與 Workspace 旁顯示勾號,並顯示 primary 預設集,以及供應商為已設定狀態。第二個指令會送出一則訊息。

    Terminal
    nanobot statusnanobot agent -m "Reply with OK"
  3. 3

    檢查回覆

    只要收到正常的回答,就代表 nanobot 能載入設定並連到模型。該請求會出現在主控台的用量日誌中。接著再以 nanobot webui 在 WebUI 中試一次。

模型

每個模型都是一個具名的預設集。每個 RealRelay.ai 模型新增一個預設集,並各自設定上限:

~/.nanobot/config.json → modelPresets
1"claude": {2  "provider": "realrelay",3  "model": "anthropic/claude-sonnet-4-6",4  "maxTokens": 8192,5  "contextWindowTokens": 2000006}

以 /model 加上預設集名稱,即可把目前的工作階段切換過去。這個選擇只對該工作階段有效;新工作階段仍以 agents.defaults.modelPreset 為預設。

nanobot chat
/model claude

請不要把預設集命名為 default;這個名稱是保留字。若想在請求失敗時改用另一個預設集,請把它列在 agents.defaults.fallbackModels 中。適合代理使用的模型,列於選擇模型。

疑難排解

  • nanobot 在啟動時中止,並指出 REALRELAY_API_KEY。啟動 nanobot 的環境中沒有設定該變數。請設定它,開啟新的終端機後再重新啟動。

  • 401 或「invalid API key」。金鑰錯誤、頭尾多了空格,或是放在與預設集所用名稱不同的供應商底下。

  • 404。apiBase 缺少 /v1。請補上。

  • 找不到模型。模型 ID 與 GET /v1/models 傳回的不完全相同,或是預設集的 provider 為 auto,導致 nanobot 把請求送到別處。請把 provider 設為 realrelay。

  • 「provider not found」。預設集的 provider 與 providers 底下的鍵拼法不同。

  • JSON 解析錯誤。合併區塊後少了逗號或大括號。這裡的範例只是檔案的片段,不是整份檔案。

  • 修改沒有生效。你編輯檔案時 nanobot 已經在執行。請重新啟動 WebUI 或 gateway。

  • 在 nanobot agent 中可用,在聊天應用程式中卻不行。模型設定沒有問題。請以 nanobot channels status 檢查通道設定。