HermesAgent 配置星狐云 API 使用教程

HermesAgent 官方文档：https://hermes-agent.nousresearch.com/docs/

一、HermesAgent 是什么

HermesAgent 是由 NousResearch 开发的开源自主 AI 智能体，可以直接在终端（命令行）中运行，通过对话的方式完成各种复杂任务。

和普通 AI 聊天工具的区别：

普通 AI 聊天	HermesAgent
只能对话回答	可以直接执行操作
无法访问本地文件	可读写本地文件和目录
无法运行命令	可在终端执行命令
不记得上次对话	跨会话持久记忆
无法自动学习	自主创建和优化技能

核心功能：

终端操作：直接执行 shell 命令、运行脚本

文件操作：读写、搜索、修改本地文件

网页搜索：联网搜索并提取内容

持久记忆：记住跨会话的上下文和偏好

技能系统：自主创建可复用的技能脚本

消息平台：可接入 Telegram、Discord、Slack、WhatsApp 等作为 AI 机器人

语音模式：支持语音输入输出

适合人群：

开发者（代码生成、项目分析、自动化任务）

运维人员（服务器管理、脚本执行）

需要长期使用 AI 辅助工作的用户

二、系统要求

系统	支持情况
Linux	✅ 完整支持
macOS	✅ 完整支持
Windows 10/11（原生）	✅ 支持，使用 PowerShell 安装
WSL2（Windows 子系统）	✅ 完整支持（更稳定，推荐长期使用）
Android（Termux）	✅ 支持

Windows 用户：现在支持两种方式——PowerShell 原生安装（简单快速，推荐新手）和 WSL2 安装（更稳定，推荐长期重度使用）。两种方式均在本文中有详细说明。

三、安装 HermesAgent

Linux / macOS 安装

在终端中运行以下命令，安装程序会自动处理所有依赖（Python、Node.js 等）：

安装完成后，刷新一下终端环境变量：

验证安装成功：

Windows 安装（PowerShell 原生方式）

适合人群：不想折腾 WSL2 的 Windows 用户，快速上手首选。

第一步：以管理员身份打开 PowerShell

在开始菜单搜索 PowerShell，右键选择「以管理员身份运行」。

第二步：运行一键安装脚本

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

脚本会自动检测并安装所有依赖（Python、Node.js、Git、ripgrep 等），耐心等待即可。

第三步：完成初始配置向导

安装完成后会自动进入配置向导，选择第一项 Quick setup，然后：

选择模型供应商 → 选 Custom endpoint（自定义接口）

填入 Base URL：https://xinghuapi.com/v1

填入 API Key：你的星狐云令牌（sk- 开头）

填入模型名：claude-sonnet-4-6

消息平台（飞书/Telegram 等）暂时跳过，直接按回车

看到欢迎界面即代表安装成功。

第四步：修复「模型未被识别」问题（常见坑）

安装完成后如果发现模型名称没有正确显示，在对话框中输入斜杠命令手动指定：

/model

按提示重新选择或输入模型名（如 claude-sonnet-4-6），看到模型名称正确显示即设置成功。

验证安装：

hermes --version
hermes --tui

Windows 安装（WSL2 方式，更稳定）

适合人群：需要长期使用、或用到消息平台网关（飞书/Telegram）的用户。

第一步：安装 WSL2

以管理员身份打开 PowerShell，运行：

wsl --install

安装完成后重启电脑，重启后会自动进入 Ubuntu 设置，设置用户名和密码。

如果已安装 WSL 但版本较旧，运行 wsl --update 升级到 WSL2。

第二步：在 WSL2 终端中安装 HermesAgent

打开 Ubuntu 终端，运行：

第三步：配置星狐云 API

参考下面「四、配置星狐云 API」章节完成配置。

四、配置星狐云 API

安装完成后需要配置 AI 提供商。HermesAgent 支持任意 OpenAI 兼容的自定义接口，星狐云完全兼容。

方法一：命令行交互配置（推荐新手）

运行以下命令，按提示选择：

在菜单中选择：

Provider（提供商）→ 选 Custom endpoint（自定义接口）

填入 Base URL：https://xinghuapi.com/v1

填入 API Key：你的星狐云令牌（sk- 开头）

填入 Model：claude-sonnet-4-6（或其他模型名）

方法二：直接编辑配置文件（推荐）

打开配置文件 ~/.hermes/config.yaml（如果不存在会自动创建）：

设置添加以下内容：

保存后生效，无需重启。

可用模型名称

在 default 字段填入对应的模型 ID：

模型	Model ID	特点
Claude Sonnet 4.6	`claude-sonnet-4-6`	日常使用首选，性价比高
Claude Opus 4.6	`claude-opus-4-6`	最强性能，复杂任务
Claude Haiku 4.5	`claude-haiku-4-5-20251001`	速度最快，简单任务

完整模型列表和价格见星狐云文档：https://xinghuapi.apifox.cn

令牌创建建议

登录星狐云控制台 → API 令牌 → 添加令牌

分组：选 Claude Code专属分组 或 Claude Code专属2分组（最稳定）

额度：选无限额度

⚠️ 注意：base_url 必须加 /v1，HermesAgent 会直接在后面拼接 /chat/completions。字段名必须用下划线格式（base_url、api_key），camelCase 格式会被静默忽略。

五、基本使用

启动对话

第一次对话示例

启动后直接输入你的需求，例如：

帮我分析一下当前目录里有哪些文件，主要文件是什么？

帮我查看磁盘使用情况，找出最大的 5 个目录

帮我写一个 Python 脚本，批量重命名当前目录下的图片文件

HermesAgent 会自动调用工具执行操作，而不只是给你代码让你自己跑。

常用命令

命令	说明
`hermes`	开始新对话
`hermes --tui`	TUI 界面模式
`hermes --continue`	继续上次对话
`hermes -c`	同上（简写）
`hermes model`	切换模型或提供商
`hermes setup`	重新运行完整配置向导
`hermes doctor`	诊断配置问题
`hermes update`	更新到最新版本

对话中的斜杠命令

命令	说明
`/help`	查看所有可用命令
`/tools`	查看可用工具列表
`/model`	对话中临时切换模型
`/save`	保存当前对话
`/personality pirate`	切换 AI 人格（示例）

六、进阶功能

接入消息平台（Telegram / Discord 等）

可以把 HermesAgent 配置成一个 AI 机器人，在 Telegram 等平台上使用：

支持平台：Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant

技能系统

搜索和安装社区技能：

语音模式

安装语音依赖后可以语音输入：

MCP 服务器集成

在 ~/.hermes/config.yaml 中添加：

七、常见问题

启动后回复为空或报错

运行 hermes model 重新确认提供商、模型名和 API Key 是否正确。

自定义接口有响应但内容异常

检查：

base_url 是否包含 /v1（必须是 https://xinghuapi.com/v1）

模型名称是否正确（参考上面的模型 ID 表格）

令牌分组是否支持该模型

`hermes: command not found`

运行 source ~/.bashrc（或 source ~/.zshrc）刷新环境变量，再试。

`hermes --continue` 找不到上次对话

运行 hermes sessions list 查看所有会话列表，确认当前用的是否同一个 profile。

配置修改后不生效

运行 hermes config check 检查配置格式是否正确，再运行 hermes doctor 诊断问题。

Windows 专项问题排查

模型名称没有正确识别

安装向导完成后，在对话中输入 /model 手动重新选择模型，看到正确的模型名称显示后即可正常使用。

接入飞书/消息平台后机器人不响应（Windows 原生安装）

Windows 原生安装接入飞书时，可能遇到以下两个兼容性问题，按顺序修复：

问题一：status.py 的 Windows 兼容性 Bug

hermes gateway 启动后无响应，原因是 status.py 中 os.kill(pid, 0) 在 Windows 会抛出 WinError 11，原代码未捕获导致进程退出。

在 PowerShell 中运行以下修复命令（将 <用户名> 替换为你的 Windows 用户名）：

python -c "
path = r'C:\Users\<用户名>\AppData\Local\hermes\hermes-agent\gateway\status.py'
with open(path, 'r', encoding='utf-8') as f:
    content = f.read()
content = content.replace(
    'except (ProcessLookupError, PermissionError):',
    'except (ProcessLookupError, PermissionError, OSError):'
)
with open(path, 'w', encoding='utf-8') as f:
    f.write(content)
print('Done')
"

问题二：config.yaml 缺少飞书配置段

修复后若机器人仍不响应，运行以下命令（将 <用户名> 替换为你的 Windows 用户名）：

# 允许所有人发消息（解除白名单限制）
Add-Content "$env:LOCALAPPDATA\hermes.env" "`nFEISHU_GROUP_POLICY=open" -Encoding UTF8

# 修正 config.yaml 中的配置键
(Get-Content "$env:LOCALAPPDATA\hermes\config.yaml" -Raw -Encoding UTF8) `
  -replace "feishu:\r?\n  require_mention: false", "feishu:`n  default_group_policy: open" |
  Set-Content "$env:LOCALAPPDATA\hermes\config.yaml" -Encoding UTF8 -NoNewline

修复后以详细日志模式重启网关：

$env:PYTHONUTF8 = "1"
hermes gateway run -vv

日志无报错即代表配置生效。

网关日志中文/符号乱码（Windows）

启动网关时加上环境变量：

$env:PYTHONUTF8 = "1"
hermes gateway

运行 `hermes gateway` 报错缺少 lark-oapi（飞书集成）

HermesAgent 使用内置 venv 中的 Python，需要将依赖安装进对应的 venv（将 <用户名> 替换为你的用户名）：

# 找到 hermes 可执行文件位置
Get-Command hermes | Select-Object -ExpandProperty Source

# 安装 lark-oapi 进 venv
uv pip install lark-oapi --python "C:\Users\<用户名>\AppData\Local\hermes\hermes-agent\venv\Scripts\python.exe"

八、快速上手小结

Linux / macOS：

Windows（PowerShell 原生）：

# 1. 以管理员身份打开 PowerShell，安装
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

# 2. 安装向导选 Quick setup，填入星狐云 API 信息
# Base URL: https://xinghuapi.com/v1
# API Key: sk-你的令牌密钥
# Model: claude-sonnet-4-6

# 3. 启动
hermes --tui

# 4. 如果模型未被识别，在对话中输入 /model 手动指定

# 5. 遇到问题
hermes doctor

更多详细文档：https://hermes-agent.nousresearch.com/docs/
星狐云 API 文档：https://xinghuapi.apifox.cn

HermesAgent配置星狐云 API 使用教程

HermesAgent 配置星狐云 API 使用教程#

一、HermesAgent 是什么#

二、系统要求#

三、安装 HermesAgent#

Linux / macOS 安装#

Windows 安装（PowerShell 原生方式）#

Windows 安装（WSL2 方式，更稳定）#

四、配置星狐云 API#

方法一：命令行交互配置（推荐新手）#

方法二：直接编辑配置文件（推荐）#

可用模型名称#

令牌创建建议#

五、基本使用#

启动对话#

第一次对话示例#

常用命令#

对话中的斜杠命令#

六、进阶功能#

接入消息平台（Telegram / Discord 等）#

技能系统#

语音模式#

MCP 服务器集成#

七、常见问题#

启动后回复为空或报错#

自定义接口有响应但内容异常#

hermes: command not found#

hermes --continue 找不到上次对话#

配置修改后不生效#

Windows 专项问题排查#

模型名称没有正确识别#

接入飞书/消息平台后机器人不响应（Windows 原生安装）#

网关日志中文/符号乱码（Windows）#

运行 hermes gateway 报错缺少 lark-oapi（飞书集成）#

八、快速上手小结#