Hermes Agent 全流程部署指南涵盖一键安装（Linux/macOS/WSL2及Windows PowerShell）、百炼Token配置、config.yaml手动编辑、微信接入、费用控制（max_tokens与temperature设置）及微信限流熔断配置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已决定部署 Hermes Agent，但对从初始安装、模型配置到运行成本控制的全流程缺乏系统认知，则可能面临环境报错、API 调用失败、Token 消耗失控或平台接入中断等问题。以下是覆盖全链路的操作指南：
一、多平台一键安装（Linux/macOS/WSL2）
该方法通过官方维护的安装脚本自动拉取最新版 Hermes 核心、检测系统依赖并完成初始化，适用于绝大多数类 Unix 环境，避免手动处理 Python 版本冲突与权限问题。
1、打开终端，执行安装命令：curl -fsSL https://get.hermes.chat | bash
2、等待脚本自动完成下载、解压、依赖检查与二进制安装
3、安装成功后，终端将显示欢迎横幅及 hermes --version 命令提示
4、立即执行 source ~/.bashrc 或 source ~/.zshrc 以加载新命令路径
二、Windows PowerShell 安装（含自动依赖补全）
此方式专为 Windows 用户设计，脚本内建 Git、Python 3.11、Node.js 与 ripgrep 的静默安装逻辑，无需预先配置开发环境，规避“找不到 python.exe”或“pip 不可用”等常见阻断错误。
1、以管理员身份启动 PowerShell
2、执行安装命令：irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
3、脚本将依次下载并安装全部前置依赖，进度条完成后自动调用 hermes setup
4、若首次运行未识别模型，需在 CLI 中输入 /model 并手动选择已支持模型名称（如 qwen-turbo）
三、百炼 Token 配置（防空响应关键步骤）
Hermes 默认不绑定任何模型服务，必须显式配置兼容 OpenAI 协议的百炼 endpoint 与 API Key，否则所有对话将返回空响应或 timeout 错误；Base URL 必须使用阿里云 DashScope 兼容模式地址，不可替换为普通 v1 地址。
1、访问 https://bailian.console.aliyun.com/，登录阿里云账号
2、左侧导航栏点击「API-KEY 管理」→「创建 API-KEY」，填写任意名称后提交
3、复制生成的 sk-xxxxxxxxxxxxxxxxxxxxxxxx 密钥（仅显示一次，丢失需重置）
4、在终端中运行 hermes model，按提示依次输入：
— 模型提供商：选择 Custom endpoint (OpenAI compatible)
— Base URL：https://dashscope.aliyuncs.com/compatible-mode/v1
— API Key：粘贴上一步复制的密钥
— 默认模型：推荐 qwen-turbo（轻量、低延迟、计费成本最低）
四、手动编辑 config.yaml 配置（适合批量部署场景）
当需在多台服务器统一部署相同模型参数，或需跳过交互式向导直接固化配置时，应直接修改 YAML 文件，确保字段层级与缩进严格符合规范，避免因空格缺失导致解析失败。
1、执行命令打开配置文件：nano ~/.hermes/config.yaml
2、删除原有 model 区块，粘贴以下内容（注意保留两个空格缩进）：
model:
provider: custom
base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxx
default: qwen-turbo
3、按 Ctrl+O 保存，Ctrl+X 退出编辑器
4、验证配置是否生效：hermes model list 应显示 qwen-turbo 为 active 状态
五、微信平台接入配置（含依赖修复）
微信网关依赖 Python QRCode 与 PIL 库生成登录二维码及图像处理，若未提前安装系统级包，启动 gateway 时将抛出 ImportError，导致二维码无法渲染、扫码登录失败。
1、在安装 Hermes 后、启动 gateway 前，执行系统依赖安装：sudo apt update && sudo apt install -y python3-qrcode python3-pil
2、运行微信网关配置向导：hermes gateway setup
3、在渠道列表中选择 WeChat，后续按提示填写 AppID 与 AppSecret
4、来源选项填 wechat，连接方式保持默认 http，用户 ID 留空表示不限制
5、完成配置后，执行 hermes gateway start，终端将输出带边框的二维码图片
六、费用控制核心策略（按 token 精确计量）
百炼模型计费基于实际输入 + 输出 token 总数，Hermes 默认未启用响应长度限制与上下文截断，长对话、冗余记忆加载、未过滤的附件解析均会导致 token 暴增；必须通过配置强制约束单次调用上限。
1、编辑 ~/.hermes/config.yaml，在 model 区块下新增两行：
max_tokens: 512
temperature: 0.3
2、max_tokens 设为 512 可有效抑制模型生成超长回复，降低输出侧费用占比约 60%
3、temperature 降至 0.3 减少发散性推理，提升回答确定性，避免无效 token 消耗
4、定期查看 ~/.hermes/logs/llm_usage.log，该文件按日期记录每次请求的 in_tokens / out_tokens 数值
七、微信消息限流与错误熔断配置
微信官方接口对单个 AppID 的 QPS 有硬性限制（通常为 20 次/秒），若 Hermes 在多会话并发触发高频请求，将收到 429 Too Many Requests 响应，导致消息堆积、用户感知卡顿；需在网关层主动限速并启用失败重试退避。
1、进入微信网关配置目录：cd ~/.hermes/gateways/wechat
2、编辑 config.json，定位到 rate_limit 字段
3、将 "requests_per_second": 20 修改为 "requests_per_second": 8
4、在同文件中添加重试策略键值："retry_backoff_ms": 2000
5、保存后重启网关：hermes gateway restart
