Hermes Agent 设置

配置 Hermes Agent 使用 AIDesk API。

Hermes Agent 是 Nous Research 开源的 AI 代理，可运行于终端，并支持对接 Telegram、Discord、Slack、WhatsApp、Signal 等消息平台。AIDesk 提供 OpenAI 兼容的 /v1 接口，因此可以作为自定义 Provider 直接接入，无需安装插件或修改源码。

前置条件

一个 AIDesk 账户和 API Key
已安装 Hermes Agent

前往创建 API Key

安装

如果尚未安装 Hermes Agent，可使用官方安装脚本（Linux / macOS / WSL2）：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

验证安装：

hermes --version

配置 AIDesk Provider

配置文件位于 ~/.hermes/config.yaml，在 providers: 段下新增 aidesk 条目。

编辑配置文件

不熟悉命令行编辑器？

可以直接使用系统图形化编辑器打开配置文件：

macOS：访达 → Shift+Cmd+G → 输入 ~/.hermes → 右键 config.yaml 用文本编辑打开
Windows：文件资源管理器地址栏输入 %USERPROFILE%\.hermes → 右键 config.yaml 用记事本打开

model:
  default: claude-sonnet-5-5
  provider: aidesk

providers:
  aidesk:
    base_url: https://api.aideskapp.com/v1
    api_key: sk-aidesk-YOUR_KEY
    type: openai
    default_model: claude-sonnet-5-5
    models:
      # Claude
      - claude-opus-5-5
      - claude-sonnet-5-5
      - claude-haiku-5-5
      # GPT / OpenAI
      - gpt-6-astra
      - gpt-6.1-sol
      - gpt-6-luna
      # Gemini
      - gemini-4-argon
      - gemini-3.8-flash
      # DeepSeek
      - deepseek-v4-pro
      - deepseek-flash

以上列表为常用模型子集。如需查看 AIDesk 支持的全部模型：

curl -H "Authorization: Bearer sk-aidesk-YOUR_KEY" \
  https://api.aideskapp.com/v1/models | jq -r '.data[].id'

将所需的 model ID 添加到 models: 段后重启 Hermes 即可。

使用环境变量（可选）

如不希望将 API Key 直接写入配置文件，可使用环境变量：

export AIDESK_API_KEY="sk-aidesk-YOUR_KEY"

然后在 config.yaml 中通过 key_env 替换 api_key：

providers:
  aidesk:
    base_url: https://api.aideskapp.com/v1
    key_env: AIDESK_API_KEY
    type: openai
    default_model: claude-sonnet-5-5
    models:
      - claude-opus-5-5
      - claude-sonnet-5-5
      - claude-haiku-5-5

字段说明

base_url必填
AIDesk 的 OpenAI 兼容端点，固定为 https://api.aideskapp.com/v1
api_key必填
你的 AIDesk API Key（也可用 key_env 引用环境变量）
type必填
协议类型，填 openai
default_model必填
默认模型，在未显式切换时使用
models可选
建议填写。提供给 /model 选择器的候选模型列表；若留空，选择器仅显示单个按钮

字段	必填	说明
base_url	必填	AIDesk 的 OpenAI 兼容端点，固定为 `https://api.aideskapp.com/v1`
api_key	必填	你的 AIDesk API Key（也可用 `key_env` 引用环境变量）
type	必填	协议类型，填 `openai`
default_model	必填	默认模型，在未显式切换时使用
models	可选	建议填写。提供给 /model 选择器的候选模型列表；若留空，选择器仅显示单个按钮

使用方式

修改配置后请重启 Hermes（CLI：退出并重新运行 hermes；Gateway：hermes gateway restart）。

终端（CLI）

打开模型选择器：

/model

也可以直接指定模型：

/model claude-opus-5-5
/model gpt-6.1-sol --global

添加 --global 会将变更写入 config.yaml 并持久化；不添加则仅作用于当前会话。

消息平台（Telegram / Discord / Slack / WhatsApp）

向机器人发送 /model，机器人会返回一个内联键盘，列出所有已配置凭证的 Provider。点击 AIDesk 即可进入分页模型列表（每页 8 个，支持 Prev / Next 翻页），点击模型完成切换。

常见问题

/model 中只显示一个按钮

原因为 providers.aidesk 下未配置 models: 列表
按照上文示例补全 models: 列表后重启 Hermes 即可
Hermes 的选择器仅在模型数量超过 8 个时启用分页

401 / 403 错误

前往控制台验证 API Key 是否有效
确认 API Key 配置在 providers.aidesk.api_key 下，而非配置文件顶层
设置环境变量后重启终端

Model not found

模型目录会持续更新，原先列表中的模型可能已被重命名或下线
重新调用 /v1/models 接口并更新 models: 列表即可

如何确认配置已生效

运行 hermes doctor 命令查看诊断报告
该命令会输出当前激活的 provider 和模型信息