Hermes Agent 接入 MoxAI 教程：通过 Custom Endpoint 使用多渠道 AI Agent

本文整理自 MoxAI 帮助中心，并改写为博客教程，适合希望把 AI Agent、AI 编程助手或桌面客户端接入 MoxAI 的用户参考。

项目介绍

Hermes Agent 是由 Nous Research 出品的开源终端 AI Agent，在你的终端中提供强大的工具调用、文件读写和代码执行能力。通过内置的 Custom Endpoint 能力，Hermes 可以无缝接入任何 OpenAI 兼容 API — 包括 MoxAI，全程无需写任何代码或插件。

• 官方主页：https://hermes-agent.nousresearch.com
• 快速开始：https://hermes-agent.nousresearch.com/docs/getting-started/quickstart
• GitHub：https://github.com/NousResearch/hermes-agent

Hermes Agent 完全开源，你可以在 Hermes Agent 的 GitHub 仓库 浏览源码、提交 Issue 或参与贡献。本教程涵盖安装、配置，以及将 Hermes Agent 对接 MoxAI 的完整步骤。

⚡ 极速配置推荐

我们强烈推荐您使用全新的一键配置命令行，免去手动修改配置文件和环境变量的繁琐步骤。只需在终端运行以下命令，即可自动配置完成

npx -y moxai-config

配置完成后直接运行即可。如需手动安装与配置，可继续阅读下文的传统图文指南。

🌟 核心特性

智能代理能力

• 工具调用：原生支持工具调用、文件读写和代码执行
• 持久记忆：支持后台常驻运行，拥有长期记忆
• 技能系统：通过 hermes skills 命令搜索和安装技能包
• 多界面支持：支持命令行和 TUI（终端 UI）两种模式

多渠道集成

• 消息网关：通过 hermes gateway 统一管理所有渠道
• 多平台支持：可接入 Telegram、Discord、Slack、WhatsApp 等消息应用
• 持续在线：作为后台服务常驻运行

开放的模型生态

• 自定义 Provider：内置 Custom Endpoint 支持，可接入任何 OpenAI 兼容 API
• 交互式配置：通过 hermes model 命令以交互菜单方式完成配置，无需编辑配置文件
• 灵活切换：支持在对话中通过 /model 命令随时切换模型

📦 接入前准备

准备信息

• 已安装 Hermes Agent（见下方安装步骤）
• 一个可用的 MoxAI 地址（必须以 /v1 结尾）
• 一个可用的 MoxAI API Key（在控制台生成）
• 想使用的模型名称（如 claude-sonnet-4-6、gemini-2.5-flash 等，需与 MoxAI 控制台中的模型 ID 完全一致）

模型上下文要求

Hermes Agent 要求所使用的模型至少支持 64K tokens 的上下文窗口。选择模型时请确认它满足此要求，否则可能出现 context 不足的报错。

🚀 第一步：安装 Hermes Agent

Linux / macOS / WSL2

在终端中运行官方一键安装脚本：

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

安装完成后，重新加载终端环境变量：

source ~/.bashrc

如果你使用的是 zsh（macOS 默认），请改为：

source ~/.zshrc

Windows

Windows 用户注意

Hermes Agent 本身不直接支持 Windows 原生环境，你需要先安装 WSL2（Windows Subsystem for Linux 2），然后在 WSL2 终端中运行上方的 Linux/macOS 安装命令。

WSL2 安装参考：https://learn.microsoft.com/windows/wsl/install

验证安装

输入以下命令验证 Hermes 是否安装成功：

hermes --version

如果显示版本号，说明安装成功 🎉。

🔧 第二步：配置 MoxAI（核心步骤）

这是整个接入流程中最关键的一步。Hermes Agent 提供了 交互式菜单，用户无需写任何代码或手动编辑配置文件，只需根据提示填入 MoxAI 的 URL、Key 和模型名即可。

在终端中运行：

hermes model

这会打开一个交互式菜单，使用键盘上下方向键选择选项，回车确认。

操作流程

配置步骤

1. 选择 Provider

用方向键滚动到 Custom Endpoint（或类似的「自定义端点」选项），按回车确认。

2. 填写 Base URL

输入你的 MoxAI 地址，例如：

https://api.moxai.ai

⚠️ 地址必须以 /v1 结尾，这是最常见的配置错误来源。

3. 填写 API Key

输入你在 MoxAI 控制台生成的 API Key，例如：

sk-xxxxxxxxxxxxxxxx

4. 填写模型名称

输入你想使用的模型，例如：

claude-sonnet-4-6

模型名称必须与 MoxAI 控制台中的模型 ID 完全一致，否则会报模型不存在的错误。

5. 确认保存

按提示确认，配置完成。

关键配置说明

配置项说明示例Base URLMoxAI 地址，必须以 /v1 结尾https://api.moxai.aiAPI KeyMoxAI 控制台生成的令牌sk-xxxxxxxxxxxxxxxxModel模型名称，需与 MoxAI 实际暴露的模型 ID 一致claude-sonnet-4-6

✅ 第三步：验证是否接入成功

配置完成后，直接启动 Hermes 开始对话：

hermes

或使用更现代的 TUI 模式（终端图形界面）：

hermes --tui

随便输入一条测试消息，例如：

你好，告诉我今天星期几

如果模型正常返回回复，说明接入成功 🎉。

查看和切换模型

在对话中直接输入以下命令，可以查看当前使用的模型，并快速切换：

/model

你也可以随时再次运行 hermes model 来覆盖之前的配置，重新填入新的 URL、Key 或模型名。

❓ 常见问题

问题解决方案回复为空或报错检查 Base URL 是否以 /v1 结尾提示模型不存在确认模型名称与 MoxAI 控制台中的模型 ID 完全一致提示 API Key 无效在 MoxAI 控制台重新生成一个 Key，然后再次运行 hermes model不知道怎么进入配置菜单在终端输入 hermes model 并回车想切换模型重新运行 hermes model，或在对话中输入 /model提示 context 不够Hermes 要求模型至少支持 64K tokens，请更换支持更大上下文的模型想修改之前的配置再次运行 hermes model，会覆盖之前的设置Windows 上无法安装Hermes 不原生支持 Windows，请先安装 WSL2，在 WSL2 终端中执行安装命令

🎯 后续进阶（可选）

接入 MoxAI 成功后，你还可以继续探索 Hermes Agent 的更多能力：

启动消息网关

将 Hermes 连接到 Telegram、Discord、Slack 等消息应用：

hermes gateway setup

搜索并安装技能

Hermes 内置技能商店，可以一键扩展能力：

hermes skills search <关键词>

查看所有可用命令

hermes --help

小贴士

接入 MoxAI 后，所有 Hermes Agent 的后续能力（消息网关、技能调用、后台常驻等）都会通过 MoxAI 调用你选择的模型，无需再为每个功能单独配置模型提供商。

更多配置细节可参考 MoxAI 帮助中心原文。