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

# 如何将 Hermes Agent 与 Atlas Cloud 集成？

> 将 Hermes Agent 连接到 Atlas Cloud：在 ~/.hermes/.env 中存储 Atlas Cloud 密钥，选择 provider: custom，将 base URL 设置为 https://api.atlascloud.ai/v1，并从 /v1/models 中选择一个 live model 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 模型列表](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new) 的模型 ID。将这些信息填入 Hermes Agent 当前的 `model:` 配置后，代理即可通过 Atlas Cloud 运行，无需特定提供商的 SDK。

> **关键要点**
>
> * 使用官方安装程序安装 Hermes Agent，然后将 Atlas Cloud 密钥保存在 `~/.hermes/.env` 中，而非版本控制中。
> * 将 Hermes Agent 配置为 `provider: custom` 和 `base_url: https://api.atlascloud.ai/v1`。
> * 在选择模型前，先查询 `/v1/models`。模型名称变化比集成代码更快，因此实时响应比从教程中复制旧 ID 更安全。
> * 在启动长期运行的代理前，运行 `hermes doctor`，然后使用 `hermes` 测试首次对话。
> * Atlas Cloud 的统一 API 使得后续可以在不重建 Hermes 集成的情况下更换语言模型。

## Hermes Agent 和 Atlas Cloud 是什么？

[Hermes Agent](https://github.com/NousResearch/hermes-agent) 是由 Nous Research 构建的开源自改进代理。它包含终端界面、持久化记忆、技能、定时自动化、消息网关，并支持多种推理提供商。当前的 Hermes 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 可以将其视为自定义提供商，并向其发送正常的聊天补全流量。

当你希望 Hermes 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 密钥。当账户权限允许时，使用专用密钥；分离代理流量使得后续轮换和使用审查更便捷。

将密钥存储在 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`。

对于持久化代理，从通用型、支持工具的模型开始，而不是仅优化最低的 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
```

然后启动代理：

```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 对代理的实际价值：模型评估变成配置更改，而非新的 SDK 集成。

## 此设置何时适用

Atlas Cloud 集成非常适合以下情况：

*   你希望 Hermes Agent 通过一个账户访问多个模型系列。
*   你预计会随时间评估或更换主模型。
*   你想要一个 OpenAI 兼容的端点，而不是特定于提供商的客户端代码。
*   你未来的 Hermes 技能可能需要访问同一平台上的图像或视频模型。

如果代理将永久使用一个提供商，且你不需要 Atlas Cloud 更广泛的模型目录，那么直接与模型提供商集成可能更简单。正确的选择取决于灵活性及集中访问是否比可能的最短单提供商设置更重要。

## 最终检查清单

在让 Hermes Agent 无人值守运行之前，验证所有五项：

-   Atlas Cloud 密钥存储在版本控制之外。
-   `provider` 设置为 `custom`。
-   `base_url` 确切为 `https://api.atlascloud.ai/v1`。
-   `model.default` 匹配来自实时模型端点的 ID。
-   `hermes doctor` 和一次简单对话均成功。

完成这些检查后，Hermes Agent 已与 Atlas Cloud 集成。现在，你可以在不更改其工具、记忆、技能或用户界面的情况下，在同一代理后评估不同的语言模型。

## 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。