← Mehk3y Hermes 接入 XAPI 教程

本教程面向零技术基础用户，手把手教你安装 Hermes Agent 并接入 XAI XAPI 中转网关。Hermes 是 Nous Research 出品的开源自进化 AI Agent，拥有跨会话记忆、自动技能学习、多平台消息网关（Telegram / Discord / Slack / WhatsApp / Signal）等能力。

⚠️ 重要前提：Hermes Agent 要求模型至少支持 64,000 tokens 的上下文窗口。上下文过小的模型会在启动时被拒绝。XAI XAPI 上的大部分旗舰模型（gpt-5.4、claude-opus-4-6、gemini-2.5-pro 等）都满足此要求。
什么是 Hermes Agent

Hermes Agent 和 Claude Code / Codex 不同——它不只是一个编程助手，而是一个 持久运行的个人 AI Agent。

它能跨会话保留记忆、自动学习并沉淀技能，并通过 Telegram / Discord / Slack / WhatsApp / Signal / 微信 等渠道与你对话。如果部署在 VPS、云服务器或后台服务中，就不依赖你本地电脑一直开着。

第零步 · Windows 用户必读 — 推荐安装 WSL2
🍎 macOS / 🐧 Linux 用户请直接跳到第一步。

Hermes Agent 现在已有原生 Windows early beta 支持，但官方仍建议 Windows 用户优先使用 WSL2，这是目前更稳的路径。WSL2 是微软官方提供的 Linux 子系统，可以在 Windows 上跑 Linux 环境。

方式一一条命令搞定（推荐）

适用于 Windows 10 2004+ 或 Windows 11。以 管理员身份 打开 PowerShell（右键开始菜单 → Windows PowerShell（管理员）），执行：

wsl --install

系统会自动安装 WSL2 和默认的 Ubuntu 发行版。安装完成后 需要重启电脑。

方式二手动安装（旧版 Windows 10）
# 1. 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# 2. 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
# 3. 重启后，设置 WSL 默认版本为 2
wsl --set-default-version 2
首次启动 WSL

重启电脑后，在开始菜单找到 Ubuntu 并打开，首次启动会要求你设置用户名和密码：

Enter new UNIX username: yourname
New password: ********
Retype new password: ********
💡 密码输入时 不会显示任何字符（没有星号也没有圆点），这是 Linux 的正常行为，正常输入并回车即可。
验证 WSL2 是否安装成功

在 PowerShell 中执行：

wsl -l -v

应该看到类似输出：

NAME      STATE    VERSION
* Ubuntu  Running  2

确认 VERSION 列显示 2 即可。

⚠️ 后续所有命令都在 WSL 的 Ubuntu 终端中执行，不是在 Windows 的 CMD 或 PowerShell 中！
第一步 · 一键安装 Hermes Agent

Hermes Agent 提供了一键安装脚本，自动处理所有依赖（Python 3.11、Node.js、uv、ripgrep、ffmpeg 等），无需手动安装任何东西。

执行安装

打开终端（macOS / Linux）或 WSL Ubuntu 终端（Windows），执行：

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

如果你坚持使用原生 Windows early beta，请在 PowerShell 中执行：

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)
💡 这条命令会自动完成：安装 Python 3.11 和 uv 包管理器、克隆 Hermes Agent 代码仓库、创建虚拟环境并安装所有依赖、设置全局 hermes 命令、启动交互式配置向导。

安装过程大约需要 3-5 分钟，取决于网络速度。最好使用魔法。

验证安装

安装完成后，执行以下命令确认一切正常：

# 检查 hermes 命令是否可用
hermes version
# 运行诊断检查
hermes doctor

Python Environment · Required Packages · Directory Structure 这些条目都显示绿色 ✓，说明安装成功。

第二步 · 配置 XAI XAPI 作为模型供应商

安装脚本结束时会自动启动配置向导。如果你错过了，或者想重新配置，可以随时执行：

hermes model
方式一交互式向导（推荐）
  1. 执行 hermes model，进入模型选择界面。
  2. 在 Provider 列表中选择 "Custom / OpenAI-compatible endpoint"（自定义 OpenAI 兼容端点）。
  3. 按提示填写 Base URL 和 API Key（见下方说明）。
  4. 确认后，Hermes 会自动验证连接。

填入 Base URL：

• https://api-xai.ainaibahub.com/v1  用 GPT 系列

• https://api-xai.ainaibahub.com  用其他模型

💡 Key 输入时 不会显示任何字符，这是 Linux 的正常行为，正常复制并回车即可。
📋 复制：在 Linux 中点击鼠标右键即可粘贴，之后回车，不能按 Ctrl+V。
方式二手动编辑配置文件
nano ~/.hermes/config.yaml

找到或添加以下内容：

# ═══ XAI XAPI 模型配置 ═══
model:
  default: gpt-5.4
  provider: custom
  base_url: https://api-xai.ainaibahub.com/v1
  api_key: sk-Xvs...  # 替换为你的真实密钥

保存后退出（Ctrl+O → 回车 → Ctrl+X）。

方式三通过环境变量
echo 'OPENAI_API_KEY=sk-Xvs...' >> ~/.hermes/.env
echo 'OPENAI_BASE_URL=https://api-xai.ainaibahub.com/v1' >> ~/.hermes/.env

然后运行 hermes model，选择 Custom endpoint 并指定模型名。官方当前更推荐通过 hermes model 或 config.yaml 保存模型配置，避免旧环境变量残留造成混淆。

第三步 · 启动并验证
启动 Hermes
hermes

你会看到一个欢迎界面，显示当前使用的模型、可用工具和已安装的技能。

发送第一条消息

在 Hermes 终端中直接输入：

你好！请介绍一下你自己，并告诉我你现在用的是什么模型。

如果能正常收到回复，说明 XAI XAPI 已成功接入。

第四步 · 切换模型
hermes model

然后重新选择 Provider 和模型名即可。

⚠️ gpt-4.1-nano、nova-micro 等超轻量模型的上下文窗口可能不足 64K，不建议在 Hermes 中使用。推荐 gpt-5.4（1M）或 gemini-2.5-pro（2M）。
第五步（可选） · 配置消息网关

Hermes 的一大亮点是可以通过 Telegram / Discord / Slack / WhatsApp / 微信 等平台与你的 Agent 对话。若你把 gateway 跑在 VPS、云服务器或系统服务里，它就能作为长期在线的后台 Agent 使用。

💡 配置消息网关不是必须的。如果你只想在终端里用 Hermes，跳过这一步即可。
安装过程中如有任何报错，可直接交给 Hermes、Claude Code 等 AI 工具帮你修复。
配置网关
hermes gateway setup
网关Discord 配置
你需要准备

• 一个 Discord 账号

• 一个你有管理权限的 Discord 服务器

• 创建一个频道，或将 bot 添加到已有频道

  1. 创建 Discord Application：访问 https://discord.com/developers/applications，点击 New Application，起名（如 Hermes Agent）→ 左侧 Bot → Add Bot → 确认 → Reset Token，复制生成的 Bot Token。
  2. 开启必要的 Intents：在 Bot 页面下方 Privileged Gateway Intents 部分，打开三个开关：
    ✅ Presence Intent   ✅ Server Members Intent   ✅ Message Content Intent（必须打开，否则 Bot 读不到消息内容）。
  3. 配置环境变量（也可让 hermes 自动配置）。编辑 ~/.hermes/.env： 
    DISCORD_BOT_TOKEN=MTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DISCORD_ALLOWED_USERS=123456789012345678,987654321098765432
  4. 邀请 Bot 到服务器：复制生成的链接，在浏览器中打开，选择要邀请 Bot 的服务器，点击授权即可。
  5. 运行配置向导： 
    hermes gateway setup   # 选择 Discord
hermes gateway run
💡 Discord 用户 ID 获取方式：在 Discord 设置中打开「开发者模式」（设置 → 高级 → 开发者模式），然后右键点击自己头像 → 复制用户 ID。
💡 Discord 行为说明：在服务器频道中，默认需要 @提及 Bot 才会回复。若想某频道无需 @提及就响应，在 .env 中设置 DISCORD_FREE_RESPONSE_CHANNELS=频道ID。
📌 频道 ID 获取：主页面找到你要添加 bot 的频道，右键 → 复制服务器/频道 ID。
网关微信配置
你需要准备

• 一个个人微信账号

• Python 依赖：aiohttp、cryptography

• 可选：qrcode（终端显示二维码用）

  1. 安装依赖： 
    pip install aiohttp cryptography
# 可选：安装完整消息网关依赖，便于终端显示二维码
pip install 'hermes-agent[messaging]'
  2. 运行配置向导： 
    hermes gateway setup
    选择 Weixin，向导会：

    ① 请求 iLink Bot API 生成 QR 码

    ② 在终端显示二维码（或提供 URL）

    ③ 等待你用微信扫码

    ④ 手机上确认登录

    ⑤ 自动保存账号凭证到 ~/.hermes/weixin/accounts/

    成功后会看到：微信连接成功，account_id=your-account-id。

  3. 写入环境变量：编辑 ~/.hermes/.env 
    WEIXIN_ACCOUNT_ID=your-account-id
# 通常由二维码登录自动保存；手动配置时才需要填写
WEIXIN_TOKEN=your-bot-token
  4. 启动网关： 
    hermes gateway run
    在微信中对话需要 一直打开这个窗口，关闭就会退出。
⚠️ 注意事项：
• 微信接入使用的是腾讯 iLink Bot API（个人微信），不是企业微信
• 二维码登录连接的是 iLink bot identity，不是完整可控的普通个人微信号
• 私聊通常更可靠；普通微信群消息可能不会被 iLink 传给 Hermes，群聊不通时不是配置一定错了
• 通过长轮询接收消息，不需要公网服务器或 Webhook
• 建议用 备用微信号，避免影响个人号使用
常见问题 FAQ
Q1 · 安装脚本报错 curl: command not found 
# Ubuntu / Debian / WSL
sudo apt update && sudo apt install -y curl
# macOS（通常已预装）
brew install curl
Q2 · hermes model 中没有 "Custom endpoint" 选项 
hermes update

更新后重新运行 hermes model。

Q3 · 连接 XAI XAPI 时报错 401

1. API Key 是否完整（以 sk- 开头，前后无空格）

2. Base URL 是否正确：https://api-xai.ainaibahub.com/v1

3. 子账户是否已启用且有余额

Q4 · 启动时提示 "context window too small"

换一个上下文更大的模型，推荐 gpt-5.4（1M）或 gemini-2.5-pro（2M）。

Q5 · WSL 中网络很慢 / 无法连接 
export http_proxy=$https_proxy
export https_proxy=http://$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):你的代理端口

或者关掉 Windows 上的代理后重试。

Q6 · 想从 OpenClaw 迁移到 Hermes 
# 预览会迁移什么
hermes claw migrate --dry-run
# 执行迁移
hermes claw migrate
Q7 · 如何让 Hermes 在后台持久运行？ 
# 启动网关（后台运行）
hermes gateway start
# 或使用 systemd（Linux）
hermes gateway install-service
附录 · 注意事项清单

⚙️ 安装相关

🔌 配置相关

🧪 验证相关

📬 还有问题？欢迎联系 XAI XAPI 客服团队，或前往 Hermes 官方文档 查阅更多信息。