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

# Hermes Agent

> Nous Research 出的 Hermes Agent 对接 FortAPI

[Hermes Agent](https://github.com/NousResearch/hermes-agent) 是 Nous Research 出的多供应商 AI Agent 框架，支持 OAuth、API key、自定义 endpoint 等多种接入方式，可以接 Telegram / Discord / Slack / WhatsApp / Signal 等通讯平台。

对接 FortAPI 最稳妥的方式是用 Hermes 的 **"Custom endpoint"**（OpenAI 兼容）模式。

## 前置条件

<Steps>
  <Step title="FortAPI 账号 + API key">
    控制台 → **令牌** 创建一把 `sk-...`。
  </Step>

  <Step title="操作系统">
    Linux / macOS / WSL2 全支持。原生 Windows 仍是 early beta，遇到坑建议切 WSL2。
  </Step>
</Steps>

## 安装 Hermes

<Tabs>
  <Tab title="Linux / macOS / WSL2">
    一行安装：

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
    ```

    装完重载 shell：

    ```bash theme={null}
    source ~/.bashrc    # 如果用 zsh 则: source ~/.zshrc
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
    ```

    安装脚本会自动装 Python 3.11、uv、Node.js、ripgrep、ffmpeg、portable Git Bash。
  </Tab>
</Tabs>

验证：

```bash theme={null}
hermes --version
```

## 配置 FortAPI 端点

跑配置向导：

```bash theme={null}
hermes model
```

按下面顺序选：

<Steps>
  <Step title="选 'Custom endpoint'">
    向导会列出所有内置 provider（Nous Portal / OpenRouter / Anthropic / OpenAI / ...）。下拉到底部，选 **Custom endpoint (self-hosted / VLLM / etc.)**。
  </Step>

  <Step title="填 base URL">
    ```
    https://www.fortapi.com/v1
    ```

    <Warning>
      因为走的是 OpenAI 兼容协议，末尾 **必须** 带 `/v1`。
    </Warning>
  </Step>

  <Step title="填 API key">
    粘贴你的 FortAPI 令牌 `sk-...`。Hermes 会把它存到 `~/.hermes/.env`。
  </Step>

  <Step title="给 endpoint 起个名">
    比如 `FortAPI`。Hermes 会自动建一个对应的 credential pool。
  </Step>

  <Step title="选模型">
    向导会问要默认用哪个 model。常用：

    * `gpt-5`（OpenAI 系）
    * `claude-sonnet`（Anthropic 系，OpenAI 兼容协议下也能调）
    * `deepseek-chat`、`kimi-k2.5`、`glm-5` 等

    完整列表在主站 [价格](https://www.fortapi.com) 页。
  </Step>
</Steps>

向导写完会自动把配置存到 `~/.hermes/config.yaml`：

```yaml theme={null}
model:
  provider: "custom"
  default: "你的模型名"  # 可用模型名见主站价格页面
  base_url: "https://www.fortapi.com/v1"
```

## 第一次验证

启动 CLI：

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

进交互界面后随便问一句：

```
> 用一句中文介绍你自己
```

正常拿到回复 + FortAPI 控制台 → **日志** 有对应记录 = 成功。

## 切换模型

会话内：

```
/model 你的模型名
/model custom:任意-FortAPI-上的模型ID
```

或者退出会话，重跑 `hermes model` 改默认。

## 配置 Telegram / Discord 等渠道

模型对接完之后，跑 gateway 设置：

```bash theme={null}
hermes gateway setup
hermes gateway start
```

按向导填 Telegram Bot Token 等，gateway 跑起来后，发消息就会用 FortAPI 处理。详见 [Hermes Messaging Gateway 文档](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)。

## 常见问题

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    * 确认 `~/.hermes/.env` 里那一行 API key 是你的 **FortAPI** 令牌，没拼错。
    * 控制台 → **令牌** 看 key 状态。
  </Accordion>

  <Accordion title="404 / model not found">
    * 模型 ID 没在 FortAPI 上线。去主站 [价格](https://www.fortapi.com) 页看可用列表。
    * `base_url` 末尾要带 `/v1`。
  </Accordion>

  <Accordion title="为什么不用 Hermes 的 'Anthropic' 内置 provider？">
    Hermes 内置的 Anthropic 走 OAuth + Claude Max 订阅，对接第三方 Anthropic 兼容网关需要额外的 base URL 覆盖、不一定稳。**Custom endpoint（OpenAI 兼容）** 在 FortAPI 上是最直接的路径，Claude 系列模型同样可用。
  </Accordion>

  <Accordion title="想同时用 Nous Portal + FortAPI">
    Hermes 支持多 provider 共存。再跑 `hermes model` 加一个就行，会话内 `/model` 切换。
  </Accordion>

  <Accordion title="Tools / function calling 不工作">
    OpenAI 兼容协议下，function calling 完整透传。如果某个工具调用失败，先检查模型本身是否支持 tool use（`gpt-5`、`claude-sonnet` 都支持）。
  </Accordion>
</AccordionGroup>

## 进阶

* **Auxiliary models**：Hermes 的 vision / web search / MoA 用辅助模型，默认跟主模型走，要省钱可单独换便宜模型，参考 [Auxiliary Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)。
* **Credential pools**：多 key 轮询、自动 failover，配置见 [Credential Pools](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools)。