<!-- Canonical URL: https://ask.atlascloud.ai/zh-TW/integrate-hermes-agent-atlascloud -->

# 如何將 Hermes Agent 與 Atlas Cloud 整合？

> 將 Hermes Agent 連接到 Atlas Cloud，方法是將 Atlas Cloud 金鑰儲存在 ~/.hermes/.env 中，選擇提供者：自訂，將基礎 URL 設定為 https://api.atlascloud.ai/v1，並從 /v1/models 中選擇一個即時模型 ID。

Hermes Agent 可以將 [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud) 作為自訂的 OpenAI 相容推論提供者。整合需要三樣東西：一個 Atlas Cloud API 金鑰、基礎 URL `https://api.atlascloud.ai/v1`，以及一個 [來自 Atlas Cloud 模型清單的模型 ID](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new)。一旦將這些設定到 Hermes Agent 目前的 `model:` 設定中，Agent 即可透過 Atlas Cloud 運行，無需使用提供者特定的 SDK。

> **重點摘要**
>
> * 使用官方安裝程式安裝 Hermes Agent，然後將 Atlas Cloud 金鑰存放在 `~/.hermes/.env` 中，而非原始碼控制中。
> * 將 Hermes Agent 設定為 `provider: custom` 和 `base_url: https://api.atlascloud.ai/v1`。
> * 在選擇模型之前，先查詢 `/v1/models`。模型名稱的變更速度比整合程式碼還快，因此使用即時回應比從教學中複製舊 ID 更安全。
> * 在啟動長期運行的 Agent 之前，先執行 `hermes doctor`，然後使用 `hermes` 測試第一段對話。
> * Atlas Cloud 的統一 API 讓您可以在日後更換語言模型，而無需重新建置 Hermes 整合。

## 什麼是 Hermes Agent 和 Atlas Cloud？

[Hermes Agent](https://github.com/NousResearch/hermes-agent) 是由 Nous Research 所開發的開源、自我改進的 Agent。它包含終端機介面、持久記憶體、技能、排程自動化、訊息閘道，以及支援多個推論提供者。目前的 Hermes Agent 文件強調，可以在不重寫 Agent 的情況下更換模型。

[Atlas Cloud 的主要平台](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud) 透過統一的 API 提供數百種語言、影像、影片和音訊模型。對 Hermes Agent 而言，重要的部分是它與 OpenAI 相容的推論介面：Hermes 可以將 Atlas Cloud 視為自訂提供者，並向其發送一般的聊天完成流量。

當您希望 Hermes Agent 保持獨立於單一模型供應商時，這種搭配非常有用。Agent 設定保持穩定，而所選的 Atlas Cloud 模型則可以根據需求、價格或可用性的變化而改變。

## 開始之前

您需要：

1. 一個 Linux、macOS、WSL2 或支援的 Windows 環境。
2. 一個正常運作的 Hermes Agent 安裝。
3. 一個 Atlas Cloud 帳戶和 API 金鑰。
4. 足夠的 Atlas Cloud 餘額或帳戶存取權限，以使用您選擇的模型。

請勿將真實的 API 金鑰貼到公開的儲存庫、問題、螢幕截圖或共享的設定檔中。Hermes Agent 支援本機 `.env` 檔案，專門用於將機密資訊與一般設定分開。

## 步驟 1：安裝 Hermes Agent

在 Linux、macOS 或 WSL2 上，使用 Nous Research 發布的安裝程式：

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

安裝後重新載入 shell：

```bash
source ~/.zshrc
```

如果您使用 Bash，請改為重新載入 `~/.bashrc`。然後確認 CLI 可用：

```bash
hermes --help
```

官方專案也透過其 PowerShell 安裝程式支援原生 Windows。請遵循目前的 [Hermes Agent 安裝文件](https://hermes-agent.nousresearch.com/docs/)，而不是自行將 Unix 指令轉換為 PowerShell。

## 步驟 2：建立 Atlas Cloud API 金鑰

登入 Atlas Cloud 控制台，並為此 Hermes Agent 部署建立一個 API 金鑰。當您的帳戶控制允許時，請使用專用金鑰；將 Agent 流量分開，可讓後續的金鑰輪換和使用量檢視更容易。

將金鑰儲存在 Hermes Agent 的本機環境檔案中：

```bash
printf '\nOPENAI_API_KEY=%s\n' 'replace-with-your-atlas-cloud-key' >> ~/.hermes/.env
```

在本地端替換預留位置。如果 `config.yaml` 檔案會進行備份、同步或提交，則請勿在其中包含真實金鑰。

為什麼使用 `OPENAI_API_KEY`？Hermes Agent 目前的客製化提供者路徑會在設定明確的 OpenAI 相容基礎 URL 時解析該環境變數。Atlas Cloud 在該相容介面上使用 bearer token 認證。

## 步驟 3：取得即時的 Atlas Cloud 模型 ID

不要猜測模型 ID。請查看 [Atlas Cloud 模型清單](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new)，然後向 API 查詢目前的目錄：

```bash
export ATLASCLOUD_API_KEY='replace-with-your-atlas-cloud-key'

curl https://api.atlascloud.ai/v1/models \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
```

選擇一個支援您 Hermes 部署所需行為的文字模型，特別注意工具使用、推理能力、上下文長度和預期延遲。複製 API 回傳的確切 `id`。

對於持久性的 Agent，請從通用且具備工具能力的模型開始，而不是只針對最便宜的 token 價格進行最佳化。在整合正常運作後，您可以測試較低成本的模型，用於摘要或其他例行任務。

## 步驟 4：將 Hermes Agent 指向 Atlas Cloud

開啟 `~/.hermes/config.yaml`，並設定目前的頂層 `model:` 區段：

```yaml
model:
  default: "replace-with-a-live-atlas-cloud-model-id"
  provider: "custom"
  base_url: "https://api.atlascloud.ai/v1"
```

將金鑰保留在 `~/.hermes/.env` 中；YAML 檔案只需要提供者、端點和模型 ID。

這點很重要，因為較舊的 Hermes Agent 範例可能使用 `inference:` 區塊。目前的官方設定範例使用 `model:`。如果您安裝的版本行為不同，請先執行 `hermes update`，並查閱該版本隨附的設定文件，然後再變更更多設定。

## 步驟 5：診斷設定

執行 Hermes Agent 的內建檢查：

```bash
hermes doctor
```

然後啟動 Agent：

```bash
hermes
```

發送一個不需要外部工具的小型測試請求，例如：

```text
請回覆您正在使用的模型名稱，然後總結此 Hermes 工作階段中有哪些可用的工具。
```

正常的串流回應即表示 Hermes 可以驗證、連線到 Atlas Cloud 端點，並呼叫所設定的模型。

## 常見的整合問題

### 認證錯誤

檢查 `OPENAI_API_KEY` 是否存在於 `~/.hermes/.env` 中，且包含的 Atlas Cloud 金鑰沒有多餘的引號或空格，並且正在被您執行的同一個 Hermes 安裝所載入。如果金鑰已暴露，請輪換它。

### 未知模型錯誤

再次呼叫 `https://api.atlascloud.ai/v1/models` 並複製確切的即時 ID。除非 API 回應本身使用較短的格式，否則請勿移除提供者前綴或縮短識別碼。

### Hermes 呼叫了錯誤的提供者

確認啟用中的設定包含以下兩項：

```yaml
provider: "custom"
base_url: "https://api.atlascloud.ai/v1"
```

選擇內建的提供者可能會將請求路由到該提供者自己的端點，而非 Atlas Cloud。

### 設定符合舊教學但失敗

Hermes Agent 正在快速發展。請將您的檔案與目前的 [官方設定參考](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) 進行比較，並使用 `hermes config get` 檢查啟用中的設定檔。特別要驗證您的版本是否預期使用目前的 `model:` 結構。

## 如何在不重建整合的情況下更換模型

一旦將 Atlas Cloud 設定為自訂提供者，更換模型只需要從 [即時模型目錄](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new) 取得新的 ID：

1. 查詢 `/v1/models`。
2. 更新 `~/.hermes/config.yaml` 中的 `model.default`。
3. 執行 `hermes doctor`。
4. 開始一段新的測試對話。

端點和憑證處理保持不變。這就是統一 API 對 Agent 的實際價值：模型評估變成了設定變更，而不是新的 SDK 整合。

## 此設定適用的情況

Atlas Cloud 整合在以下情況非常適合：

* 您希望 Hermes Agent 透過一個帳戶存取多個模型系列。
* 您預計會隨著時間評估或更換主要模型。
* 您想要一個 OpenAI 相容的端點，而不是提供者特定的客戶端程式碼。
* 您未來的 Hermes 技能可能需要從同一個平台存取影像或影片模型。

如果 Agent 將永久使用單一提供者，而且您不需要 Atlas Cloud 更廣泛的模型目錄，那麼直接與模型提供者整合可能更簡單。正確的選擇取決於彈性和集中存取是否比擁有最短的單一提供者設定更重要。

## 最終檢查清單

在讓 Hermes Agent 無人值守運行之前，請確認以下五個項目：

- Atlas Cloud 金鑰儲存在版本控制之外。
- `provider` 設定為 `custom`。
- `base_url` 完全為 `https://api.atlascloud.ai/v1`。
- `model.default` 與即時模型端點回傳的 ID 相符。
- `hermes doctor` 和一段簡單的對話都成功執行。

完成這些檢查後，Hermes Agent 就已與 Atlas Cloud 整合。您現在可以在同一個 Agent 背後評估不同的語言模型，而無需變更其工具、記憶體、技能或使用者介面。

## FAQ

### Hermes Agent 是否有內建的 Atlas Cloud 提供者？

不需要專用的 Atlas Cloud 提供者。Hermes Agent 可以透過其自訂的 OpenAI 相容提供者，使用 Atlas Cloud 的基礎 URL 和 API 金鑰進行連線。

### Hermes Agent 的 Atlas Cloud 基礎 URL 是什麼？

使用 https://api.atlascloud.ai/v1 作為 OpenAI 相容的基礎 URL。

### 我應該在哪裡儲存 Atlas Cloud API 金鑰？

將它儲存在 ~/.hermes/.env 中，作為 OPENAI_API_KEY，並確保真實金鑰不出現在設定檔、螢幕截圖和版本控制中。

### Hermes Agent 應該使用哪個 Atlas Cloud 模型？

查詢 https://api.atlascloud.ai/v1/models，並選擇一個符合工具使用、推理、上下文、延遲和成本需求的當前文字模型。

### 我如何驗證整合？

執行 hermes doctor，使用 hermes 指令啟動 Hermes，並發送一個小型測試提示。身份驗證或未知模型錯誤通常指向 API 金鑰、基礎 URL 或模型 ID。