> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmeasy.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent 自定义模型接入 LLMEasy 指南

> 在 Hermes Agent 中使用 LLMEasy，通过 GPT 分组模型和 OpenAI-compatible 协议完成配置。

Hermes Agent 是面向本地终端工作流的 AI Agent。它可以作为日常开发助手使用，也可以结合技能、MCP、任务调度和子 Agent 处理更长的自动化任务。

接入 LLMEasy 时，请使用 **GPT 分组** API Key，并通过 OpenAI-compatible endpoint 调用模型。

<Info>
  本文仅覆盖 Hermes Agent 的 GPT 分组接入方式。模型 ID 请以<a href={"https://www.llmeasy.ru/pricing"}>模型广场</a>显示为准。
</Info>

## 前置条件

* 已获取 LLMEasy API Key（<a href={"https://www.llmeasy.ru/register"}>注册并获取</a>）
* API Key 属于 **GPT 分组**
* 已从<a href={"https://www.llmeasy.ru/pricing"}>模型广场</a>复制要使用的 GPT 分组模型 ID
* macOS、Linux 或 Windows WSL2 环境

## 安装 Hermes Agent

<Tabs>
  <Tab title="macOS / Linux / WSL2">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows">
    Windows 用户建议优先使用 WSL2。原生 PowerShell 支持取决于 Hermes Agent 当前版本；如果你使用原生 Windows 环境，请按 Hermes 安装器的当前提示操作。
  </Tab>
</Tabs>

## 配置步骤

<Tabs>
  <Tab title="交互式配置">
    <Steps>
      <Step title="运行模型选择器">
        ```bash theme={null}
        hermes model
        ```
      </Step>

      <Step title="选择 OpenAI 或 OpenAI Compatible provider">
        在 provider 列表中，选择 **OpenAI** 或 **OpenAI Compatible**。
      </Step>

      <Step title="填写 LLMEasy 配置">
        按提示依次输入：

        * **Base URL**：`https://www.llmeasy.ru/v1`
        * **API Key**：你的 LLMEasy API Key
        * **Model**：从<a href={"https://www.llmeasy.ru/pricing"}>模型广场</a>复制的 **GPT 分组模型 ID**
      </Step>

      <Step title="重启 Hermes Agent">
        修改配置后，请退出当前 Hermes Agent 会话，再重新启动。
      </Step>

      <Step title="启动 Hermes Agent">
        ```bash theme={null}
        hermes
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="命令行配置">
    如果你更适合复制命令，可以直接写入 Hermes Agent 配置。

    ```bash theme={null}
    hermes config set llm.provider openai
    hermes config set llm.base_url "https://www.llmeasy.ru/v1"
    hermes config set llm.api_key "YOUR_LLMEASY_API_KEY"
    hermes config set llm.model "YOUR_GPT_MODEL_ID"
    ```

    将 `YOUR_LLMEASY_API_KEY` 替换为你的 LLMEasy API Key，将 `YOUR_GPT_MODEL_ID` 替换为<a href={"https://www.llmeasy.ru/pricing"}>模型广场</a>中的 GPT 分组模型 ID。

    配置完成后运行：

    ```bash theme={null}
    hermes
    ```
  </Tab>

  <Tab title="环境变量">
    如果你不想把 API Key 写入 Hermes Agent 配置，可以在当前 shell 中导出环境变量。

    ```bash theme={null}
    export OPENAI_API_BASE="https://www.llmeasy.ru/v1"
    export OPENAI_API_KEY="YOUR_LLMEASY_API_KEY"
    export HERMES_MODEL="YOUR_GPT_MODEL_ID"
    hermes
    ```

    这组环境变量只对当前 shell 会话生效。新开终端后需要重新导出，或写入你自己的 shell profile。
  </Tab>
</Tabs>

## 功能速查

| 能力              | 用途               |
| --------------- | ---------------- |
| Terminal UI     | 在终端中直接和 Agent 交互 |
| Skills          | 为重复任务沉淀可复用流程     |
| MCP             | 连接本地或远程工具能力      |
| Scheduled tasks | 配置定时任务和周期性工作流    |
| Subagents       | 将复杂任务拆给不同子 Agent |
| Message gateway | 把 Agent 接入更多消息入口 |

## 从 OpenClaw 迁移

如果你已经使用 OpenClaw，可以先在 Hermes Agent 当前版本中检查是否提供迁移命令。迁移前建议先做 dry run。

```bash theme={null}
hermes claw migrate --dry-run
```

确认无误后再执行正式迁移：

```bash theme={null}
hermes claw migrate
```

迁移后仍建议检查 Hermes Agent 中的 **Base URL**、API Key 和模型 ID，确保它们分别对应 `https://www.llmeasy.ru/v1`、你的 LLMEasy API Key，以及 GPT 分组模型 ID。

## 排障提示

* 无响应或请求失败时，先确认 **Base URL** 是否正好是 `https://www.llmeasy.ru/v1`。这里通常不要再拼接 `/chat/completions`。
* 报模型不存在时，确认 **Model** 是否来自<a href={"https://www.llmeasy.ru/pricing"}>模型广场</a>中的 GPT 分组。
* 报鉴权失败时，确认 API Key 没有复制空格，并且属于 **GPT 分组**。
* 修改配置后仍走旧模型时，退出当前 Hermes Agent 会话并重新运行 `hermes`。
* 接入 LLMEasy 时通常不需要额外设置 `User-Agent` 或其他 headers。只有当你还接了自定义网关、租户路由、审计或缓存服务时，再按对应上游服务的官方文档补充。

<Note>
  请不要把真实 API Key 提交到仓库。团队共享配置时，优先使用环境变量或本机配置。
</Note>

## 相关 FAQ

* [MCP 和 API Key / Base URL 有什么区别？](/zh/faq/concepts/mcp-vs-api-key-base-url)
* [Codex CLI 中 model\_provider、base\_url 和 wire\_api 是什么？](/zh/faq/codex/model-provider-base-url-wire-api)
* [Cline 如何配置 OpenAI-compatible API？](/zh/faq/cline/openai-compatible-api)
* [OpenClaw 接入 LLMEasy 指南](/zh/ai-tools/openclaw)