Hermes Agent 可以通過 hermes model 的 Custom Endpoint 精靈接入 OpenAI-compatible Chat Completions 服務。
只有 hermes --version 和 hermes doctor 正常執行後，才繼續設定 Provider。下載或依賴安裝中斷時，請先解決安裝問題。

​
第一步：安裝 Hermes Agent

先閱讀 Hermes Agent 官方安裝文件，再使用官方安裝方式。macOS、Linux 或 WSL2 可以先把腳本下載到本機並檢查內容：
安裝器可能安裝 Python、uv、虛擬環境並更新 shell 設定。完成後重新開啟終端，再檢查：
如果安裝中斷，不要把“開始下載”當作安裝完成；先儲存輸出並區分網路、Python、uv 或依賴構建問題。

​
第二步：建立 Hermes 專用 API 金鑰

  1. 登入 BearLab 主控臺。
  2. 開啟“令牌管理”，新增一個只供 Hermes 使用的令牌。
  3. 選擇需要使用的模型分組。
  4. 複製令牌並妥善儲存；截圖時必須保持掩碼。

​
第三步：確認模型與協定

從回傳結果中複製準確的模型 ID。下文用 gpt-4o-mini 舉例，並選擇 chat_completions。如果目標模型只支援 Responses 或 Anthropic Messages，不能直接套用本頁協定。

​
第四步：選擇設定方式

​
方法 A：使用 CC Switch

  1. 在 CC Switch 頂部選擇 Hermes。
  2. 點擊“新增服務商”→“自訂設定”。
  3. API 模式選擇 OpenAI Chat Completions。
  4. API 端點填 https://bearlab.ai/v1，再填入 Hermes 專用 BearLab 金鑰。
CC Switch Hermes 分支中的 BearLab Provider 設定

CC Switch 中填寫 BearLab Hermes Provider；金鑰保持掩碼

點擊“新增模型”，填寫 /v1/models 實際回傳的模型 ID。第一個模型會寫入 Hermes 頂層 model.default；下圖使用 gpt-4o-mini。
CC Switch Hermes 分支中的 BearLab 模型設定

在 Hermes Provider 中新增 BearLab 預設模型

儲存後點擊“啟用”。卡片顯示“使用中”且出現“切換成功”，才表示 CC Switch 已把 BearLab 寫入 Hermes 設定。
CC Switch 已啟用 BearLab Hermes Provider

BearLab Hermes Provider 已啟用

CC Switch 會把金鑰寫入產生設定。不要展示“設定 JSON”中的 api_key，也不要提交 Hermes 設定；需要環境變數隔離時使用下面的官方精靈和手動檢查方法。

​
方法 B：使用 Hermes Custom Endpoint 精靈

執行：
在互動選單中選擇 Custom Endpoint，然後依次填寫：
  • Name：BearLab AI
  • Base URL：https://bearlab.ai/v1
  • API mode：chat_completions
  • API Key：BearLab 專用令牌
  • Default model：gpt-4o-mini
Base URL 不要追加 /chat/completions。精靈會把 API mode 寫入 ~/.hermes/config.yaml；不要依賴 URL 自動判斷協定。

​
第五步：檢查儲存後的設定

儲存後，設定結構應與下面一致。真實金鑰應放在環境變數或 ~/.hermes/.env，不要寫進 config.yaml：
將金鑰寫入 Hermes 的秘密文件時，只寫變數，不把該文件提交到程式碼倉庫：
Hermes 官方設定說明把 ~/.hermes/config.yaml 用於非秘密設定，把 ~/.hermes/.env 用於 API Key、Bot Token 和密碼。

​
第六步：選擇 BearLab 模型

再次執行 hermes model，在自訂 Provider 中選擇 BearLab，然後選擇 gpt-4o-mini。進入會話後也可以使用 Hermes 的模型切換命令：
確認目前 Provider 與模型已經切換，再傳送訊息。

​
第七步：傳送第一條訊息

在原生互動介面中傳送：
必須同時看到 Hermes 的正文回覆，並在 BearLab 主控臺找到同一時間、同一模型的請求記錄，才能認定接入完成。設定被儲存、模型出現在選單或 HTTP 請求開始傳送，都不能替代最終回覆。

​
第八步：再啟用工具與 Gateway

先保持工具、記憶、定時任務和 Gateway 關閉。普通文字成功後，再逐項啟用。Telegram、Discord、Slack 等 Gateway 需要外部帳號或 Bot Token，不要在 Provider 尚未通過基礎對話時同時設定。

​
常見問題

  • 安裝失敗：儲存安裝器輸出，分別檢查 GitHub 下載、Python、uv 和依賴構建。
  • Unknown provider：檢查 provider: custom:bearlab 與 custom_providers[].name 是否一致。
  • 提示 401：確認 BEARLAB_API_KEY 已被目前 Hermes 程式讀取，且 .env 沒有多餘引號或空格。
  • 提示 404：檢查 Base URL、模型 ID 和 api_mode: chat_completions。
  • 模型可選擇但對話失敗：關閉工具，只保留普通文字，再核對模型是否支援 Chat Completions。
  • Gateway 失敗：先回到普通 CLI 會話驗證 Provider，再單獨排查外部平臺憑證和配對。