Hermes Agent

Hermes Agent 是一款執行在終端機中的代理程式，可在使用者授權後讀寫檔案、執行命令並呼叫工具。

本教學介紹如何使用 Hermes Agent 自帶的 Custom Endpoint，無需借助其他設定工具，串接 AGTCloud 的 Chat Completions 介面並完成基本對話驗證。檔案操作、網頁搜尋、MCP、Skills 等擴充能力不在本教學的驗證範圍內。

準備工作

開始前，請確認你已經：

準備好 Hermes Agent 支援的作業系統和終端機環境；
註冊並登入 AGTCloud；
在 API Keys 頁面建立 AGTCloud API Key；
從模型廣場複製目前 API Key 可見且支援 Chat Completions 的模型 ID；
準備一個不包含敏感程式碼和正式環境憑證的測試目錄。

安裝 Hermes Agent

選擇與你的執行環境對應的官方安裝方式。macOS 首版支援 Apple Silicon；Intel Mac、Homebrew 和 PyPI 安裝不屬於目前官方支援範圍。

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安裝完成後，重新開啟終端機並檢查版本與執行環境：

hermes version
hermes doctor

hermes doctor 會檢查安裝、設定和常見執行環境問題。如果終端機提示找不到 hermes，請先重新開啟終端機，再確認安裝目錄已經加入 PATH。其他平台限制請檢視 Hermes Agent 官方平台支援說明。

設定 AGTCloud

Hermes Agent 提供模型服務供應商設定精靈。請在一般終端機中執行以下命令，不要在已經開啟的 Hermes 對話內執行：

hermes model

選擇 Custom Endpoint

在 Provider 清單中選擇 Custom endpoint。不同版本的完整名稱可能顯示為 Custom endpoint (self-hosted / VLLM / etc.)。

填寫 AGTCloud 連線資訊

按照目前版本的精靈依次填寫：

Hermes Agent 欄位	填寫內容
`Provider Name`（如有）	`AGTCloud`
`API Base URL`	`https://api.agtcloud.cn/v1`
`API Key`	`your-api-key`
`API / Wire Mode`	`Chat Completions` 或 `chat_completions`
`Model`	`MODEL_ID`
`Context Length`	首次設定建議留空，由用戶端嘗試自動辨識

將 your-api-key 替換為 AGTCloud API Key，並將 MODEL_ID 替換為目前 API Key 可見的模型 ID。

儲存設定

確認精靈摘要後儲存。一般設定會寫入 ~/.hermes/config.yaml，API Key 等敏感值由 Hermes Agent 儲存到 ~/.hermes/.env。

Base URL 必須包含 /v1

請直接使用 https://api.agtcloud.cn/v1。不要只填寫 API Origin，也不要填寫完整的 /v1/chat/completions 請求地址或再次追加 /v1。

優先使用官方設定精靈

Hermes Agent 的設定欄位可能隨版本演進。使用 hermes model 可以讓目前版本自行寫入正確的 Provider 和傳輸模式，不需要手動編輯 YAML，也不要把真實 API Key 寫入共享設定範例。

檢查設定

完成精靈後，可以使用以下命令檢查目前設定：

hermes config
hermes config get model
hermes config check

hermes config 開啟或顯示目前設定入口；
hermes config get model 檢查目前模型設定；
hermes config check 檢查設定格式和必要欄位。

檢查輸出時不要複製或分享完整 API Key。如果設定仍指向其他 Provider，請重新執行 hermes model 並完成 Custom Endpoint 設定。

啟動並驗證連線

進入安全測試目錄

cd /path/to/safe/test-project

首次連線不要在包含正式環境憑證、客戶資料或未公開原始碼的目錄中進行。

啟動 Hermes Agent

hermes

也可以使用 hermes chat 啟動互動式工作階段。

完成基本對話驗證

在輸入欄位中傳送：

請只回覆：AGTCloud 連線成功。不要呼叫任何工具。

能夠正常收到回覆，說明 Base URL、API Key、模型和基本 Chat Completions 連線已經建立。本步會產生正常的 API 用量。

可選驗證工具呼叫

如果所選模型支援工具呼叫，可以在包含 README.md 的測試目錄中傳送：

請只讀取 README.md，並用三點概括專案用途。不要修改檔案，也不要執行其他命令。

保持預設人工審核，先檢查 Hermes Agent 準備執行的操作，再決定是否允許。

首次使用不要關閉操作審核

不要使用 --yolo，也不要將危險操作審核設定為關閉。Hermes Agent 可以執行命令和存取檔案，首次驗證應逐項確認工具請求。

切換模型

需要新增新模型、修改 Endpoint 或更換 API Key 時，請退出目前工作階段並執行：

hermes model

在已經開啟的工作階段中，可以使用 /model 在已經設定的 Provider 和模型之間切換。/model 不負責建立新的 Custom Endpoint；如果目標模型尚未設定，請先使用終端機命令 hermes model。

MODEL_ID 只是預留位置。請一律使用模型廣場中目前 API Key 可見的完整模型 ID，不要依賴可能隨版本變化的固定推薦模型。

常見問題

現象	優先檢查	處理方式
找不到 `hermes` 命令	安裝結果和 `PATH`	重新開啟終端機，執行 `hermes version`；仍無結果時重新執行對應系統的官方安裝命令
`hermes doctor` 報告異常	Python、系統工具和安裝目錄	按診斷結果修復目前環境，不要混用多個 Hermes Agent 安裝來源
傳回 `401`	API Key 內容和權杖狀態	重新複製有效 API Key，並確認填寫內容沒有多餘空格
傳回 `403`	權杖權限、模型權限和帳戶狀態	在控制台檢查 API Key 狀態及目前帳戶的模型可用範圍
傳回 `404`	Base URL、重複 `/v1` 和模型 ID	使用 `https://api.agtcloud.cn/v1`，不要填寫完整 Endpoint，並重新複製完整模型 ID
模型不可用	目前 Key 可見模型和協議支援	選擇目前 API Key 可見且支援 Chat Completions 的模型
仍使用其他 Provider	`hermes model` 的目前選擇和儲存結果	重新執行精靈，選擇 Custom Endpoint，並透過 `hermes config check` 檢查設定
對話正常但工具失敗	模型工具呼叫能力和回應格式	換用支援工具呼叫的模型；先關閉複雜工具，只驗證一個唯讀操作
上下文長度辨識失敗	模型中繼資料和手動填寫值	重新執行 `hermes model`；只有掌握模型真實限制時才手動填寫上下文長度
擴充工具缺少憑證	輔助工具的獨立服務設定	這些能力可能需要額外服務和憑證，不屬於 AGTCloud 主對話模型 Key 的設定範圍

遇到無法定位的問題時，執行 hermes doctor 和 hermes config check，並記錄請求時間、API Base URL、模型 ID、HTTP 狀態和去識別化錯誤資訊，然後檢視錯誤與疑難排解。不要提交完整 API Key。

安全建議

不要把 API Key 寫入專案檔案、Git 倉庫、命令歷程、截圖、記錄或共享設定；
首次使用應在安全測試目錄中進行，並逐項檢查檔案、命令和網路存取請求；
不要透過 --yolo 或設定項目關閉危險操作確認；
處理不可信程式碼時，可以使用 Docker 等隔離環境降低風險，但仍需檢查掛載目錄和憑證；
API Key 疑似洩漏時，立即在控制台停用或刪除，然後建立新 Key。