nanobot

在 config.json 中設定自訂 Provider 與模型預設，將 nanobot 接入 CoffeeRouter。

接入前準備

  • 安裝 Python 3.11 或更新版本。
  • 在 CoffeeRouter 控制台建立可用令牌，並記錄令牌允許使用的模型 ID。
  • CoffeeRouter OpenAI 相容基礎地址為 https://www.coffeerouter.ai/v1。

設定步驟

1. 安裝並初始化 nanobot

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 或 pip 安裝：

uv tool install nanobot-ai

python -m pip install nanobot-ai

完成後執行引導精靈：

nanobot onboard --wizard

2. 設定 CoffeeRouter 令牌

建議透過環境變數提供令牌。macOS、Linux 或 WSL 使用：

export COFFEEROUTER_API_KEY="sk-your-api-key"

Windows PowerShell 使用：

$env:COFFEEROUTER_API_KEY = "sk-your-api-key"

如果 nanobot 作為背景服務執行，還需要在服務程序的環境中持久設定該變數，不能只在目前終端中設定。

3. 新增 CoffeeRouter 服務商和模型預設

開啟 ~/.nanobot/config.json；Windows 中的等價路徑為 %USERPROFILE%\.nanobot\config.json。將以下欄位合併到精靈產生的設定中，請勿刪除已有的渠道或工具設定：

{
    "providers": {
        "coffeerouter": {
            "apiKey": "${COFFEEROUTER_API_KEY}",
            "apiBase": "https://www.coffeerouter.ai/v1"
        }
    },
    "modelPresets": {
        "coffeerouter-main": {
            "label": "CoffeeRouter",
            "provider": "coffeerouter",
            "model": "your-model-id"
        }
    },
    "agents": {
        "defaults": {
            "modelPreset": "coffeerouter-main"
        }
    }
}

將 your-model-id 替換為 CoffeeRouter 令牌可用模型清單中的完整模型 ID。${COFFEEROUTER_API_KEY} 會在 nanobot 啟動時從環境變數讀取，金鑰不會因讀取設定而被寫回檔案。

驗證接入

先檢查設定狀態：

nanobot status

再傳送一則測試訊息：

nanobot agent -m "Reply with: CoffeeRouter connected"

需要繼續互動時執行：

nanobot agent

常見問題

為什麼終端找不到 nanobot 命令？

重新開啟終端，並執行安裝器最後輸出的 PATH 設定命令。使用 uv 時，也可先執行 uv tool run --from nanobot-ai nanobot --version 驗證安裝，請勿假設所有系統都使用相同的 .local/bin 路徑。

為什麼回傳 401 或 API Key 無效？

確認目前程序能讀取 COFFEEROUTER_API_KEY，並檢查令牌是否完整、已啟用、未過期且有可用額度。背景服務需要單獨設定環境變數。

為什麼提示找不到模型？

modelPresets 中的 model 必須與 CoffeeRouter 令牌管理頁顯示的模型 ID 完全一致，且目前令牌必須擁有該模型權限。

是否可以直接在設定檔中填寫金鑰？

apiKey 支援直接填寫，但更建議使用 ${COFFEEROUTER_API_KEY} ，避免金鑰進入備份、版本庫或設定截圖。

安全提示

請勿分享 config.json、令牌、終端截圖或包含請求標頭的日誌。建議為 nanobot 建立獨立令牌，並限制可用模型、額度和 IP；不再使用時及時撤銷令牌。

官方資料