Hermes Agent 完整安装配置教程(含免费百炼Token+微信接入)

本教程适用于 Ubuntu/Debian 系统（兼顾避坑，解决 pip 报错、模型空响应、微信接入等问题），全程复制命令即可完成，无需复杂操作，适合新手。

一、Hermes 安装（一键安装）

1. 安装 Hermes 核心程序

复制以下命令，粘贴到终端并执行（自动下载并安装最新版本）：

curl -fsSL https://get.hermes.chat | bash

安装成功后，显示如下画面

安装好后，需要配置模型

2. 解决后续依赖报错（提前规避）

避免后续配置微信时出现依赖缺失、pip 报错（如 externally-managed-environment），提前安装系统级依赖：

sudo apt update && sudo apt install -y python3-qrcode python3-pil

无需额外安装 pip 或虚拟环境，该命令直接通过系统包管理器安装，完全规避环境冲突。

三、百炼 Token 配置（核心，解决模型空响应）

Hermes 本身不提供模型，需对接阿里云百炼模型，配置前需先获取百炼 API Key，再配置到 Hermes 中。

1. 获取百炼 API Key

登录阿里云百炼控制台：https://bailian.console.aliyun.com/，续费用户可点击https://www.aliyun.com/minisite/goods?userCode=laet0q51领取75折优惠链接
左侧菜单栏找到「API-KEY 管理」，点击「创建 API-KEY」，输入名称（任意）后提交。
复制生成的 API Key（格式：sk-xxxxxxxxxxxxxxxxxxxxxxxx），仅显示一次，务必保存好，丢失需重新创建。

2. Hermes 配置百炼 Token（两种方式，选一种即可）

方式 1：交互式配置（推荐，新手友好）

hermes model

执行命令后，按以下步骤选择/输入：

选择模型提供商：Custom endpoint (OpenAI compatible)
输入百炼 Base URL（必须用这个正确地址，避免空响应）：https://dashscope.aliyuncs.com/compatible-mode/v1
输入刚才保存的百炼 API Key（sk-xxxxxx）
选择默认模型（推荐选 qwen-turbo，轻量且响应快，仅支持以下4种：qwen-turbo / qwen-plus / qwen-max / qwen-long）
一路回车确认，配置自动保存。

方式 2：手动编辑配置文件（适合熟悉终端操作的用户）

编辑 Hermes 配置文件 ~/.hermes/config.yaml：

nano ~/.hermes/config.yaml

将以下内容粘贴到文件中（替换 API Key 为你的百炼 Key），保存并退出（按 Ctrl+O 保存，Ctrl+X 退出）：

model:   provider: custom   base_url: https://dashscope.aliyuncs.com/compatible-mode/v1   api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxx  # 替换为你的百炼 API Key   default: qwen-turbo  # 可选：qwen-plus / qwen-max / qwen-long

3. 测试模型配置（必做，避免后续微信接入后无响应）

输入hello hermes，测试模型是否能正常响应：

说明百炼 Token 配置成功；若仍报错“Empty response”，检查以下3点：

Base URL 是否为：https://dashscope.aliyuncs.com/compatible-mode/v1
API Key 是否正确（无多余空格、未遗漏字符）
默认模型是否为 qwen-turbo 等支持的4种之一

四、微信接入（个人号，扫码即用）

模型配置正常后，即可接入微信，实现微信发消息、AI 自动回复，全程无需复杂配置。

1. 配置微信网关

hermes gateway setup

执行命令后，按以下步骤操作：

选择平台：WeChat (ilink / ClawBot)（按上下键选择，回车确认）
会要求微信扫码绑定
选择私聊授权方式（推荐默认选项，最安全省心）：Use DM pairing approval (recommended)，回车确认
后续所有选项均按回车默认即可，配置自动保存。

2. 启动微信机器人

hermes gateway start

执行命令后，终端会生成一个二维码，用微信小号（建议用小号，避免主号封号风险）扫码登录，登录成功后，终端会提示“Gateway started successfully”。

3. 微信使用测试

4. 微信网关常用命令（可选）

# 后台运行微信网关（关闭终端也能正常使用） hermes gateway start --daemon  # 重启微信网关（出现异常时使用） hermes gateway restart  # 停止微信网关 hermes gateway stop  # 查看微信网关日志（排查不回复等问题） hermes gateway logs

五、常见问题排查（避坑重点）

1. 报错“pip: command not found”或“externally-managed-environment”

无需使用 pip 安装依赖，直接执行以下命令安装系统级依赖即可：

sudo apt update && sudo apt install -y python3-qrcode python3-pil

2. 模型测试报错“Empty response from model”

核心原因：Base URL 错误、API Key 错误或模型名错误，按以下步骤修正：

重新配置模型：hermes model
确保 Base URL 为：https://dashscope.aliyuncs.com/compatible-mode/v1
核对 API Key 无误，模型名选择 qwen-turbo

3. 微信扫码后不回复、无反应

重启微信网关：hermes gateway restart
检查模型是否正常：hermes chat -q "测试"
确保微信小号未被限制登录，重新扫码登录一次。

4. 微信机器人被骚扰、滥用

重新执行 hermes gateway setup，将私聊授权方式改为「Only allow listed user IDs」，添加白名单用户，仅允许指定微信使用。