Hermes Agent 阿里云部署手册 2026完整流程、参数配置与Token管控方案

一、前言

Hermes Agent 是一款面向AI智能体场景的调度与执行框架，具备多模型对接、任务流编排、会话管理、插件扩展等能力，常被部署在阿里云云服务器、函数计算等云资源之上，用于构建私有化AI服务、企业内部智能办公系统、自动化任务集群。2026年，随着AI智能体在云端落地场景不断增多，大量开发者与企业运维人员选择在阿里云环境中搭建Hermes Agent服务。

在实际部署过程中，环境依赖适配、云服务器端口放行、服务常驻运行、配置文件编写都是新手容易出错的环节。而框架内置的Token Plan模块，是实现调用鉴权、请求配额、访问频次、接口权限、IP访问管控的核心功能，合理配置该模块可以避免资源滥用、非法访问、调用超限等问题，是云端服务上线前必不可少的配置步骤。

本文结合2026年阿里云标准运行环境，以保姆级分步讲解的方式，完整介绍Hermes Agent的前期环境准备、阿里云服务器基础设置、源码部署、依赖安装、服务配置、进程常驻、功能调试，同时详解Token Plan的配置规则、多场景模板、配置重载、功能测试与日常运维。文中包含完整的终端指令、配置代码、脚本示例，全文不使用外部链接、表格、图片，无营销相关内容，无论是个人测试使用，还是企业正式上线服务，都可以按照步骤完成整套部署与配置工作。阿里云部署AI Agent：OpenClaw/Hermes Agent全网最简单，只需两步，详情👉访问阿里云OpenClaw/Hermes一键部署专题页面 了解。









👉访问订阅阿里云百炼Token Plan AI大模型服务 。支持多模型切换，用于多模态模型灵活调用，实现多模型、多工具、多场景下的额度共享与统一管理，兼顾灵活性、稳定性与安全性，大幅降低企业使用大模型的门槛与成本。

二、部署前期准备 阿里云环境与软件依赖

在阿里云服务器上部署Hermes Agent，需要先完成云服务器基础配置、系统环境检查、必备软件安装三大工作，提前规避网络、权限、版本不兼容等问题。

2.1 阿里云服务器基础要求

硬件层面，基础功能测试、个人单机使用，阿里云云服务器最低选择1核2G配置即可稳定运行；如果面向多用户并发调用、复杂任务编排、多插件同时运行，建议选择2核4G及以上规格，保障服务响应速度与稳定性。
操作系统优先选用CentOS 7/8、Ubuntu 20.04/22.04等主流Linux发行版本，Windows Server仅建议用于本地测试，生产环境统一使用Linux系统。
网络方面，需要在阿里云服务器安全组中放行服务监听端口，默认端口为3000，可根据自定义配置修改，同时保证服务器能够正常访问外网，用于拉取源码、下载第三方依赖包。

2.2 核心软件依赖清单

Hermes Agent 基于Node.js技术栈开发，整套运行环境依赖多款基础软件，所有软件均需要满足指定版本要求：

1. Node.js：强制要求18.x及以上LTS版本，低版本会出现语法解析失败、模块无法加载、服务启动报错等问题；
2. npm：随Node.js一同安装，作为默认包管理工具，用于安装项目依赖；
3. Git：版本控制工具，用于拉取Hermes Agent开源源码；
4. 数据库：框架默认内置轻量型数据库用于存储会话、Token规则、运行日志，单机测试无需额外安装数据库服务，企业多人高并发场景可外接MySQL、PostgreSQL；
5. 进程管理工具：推荐pm2，用于实现服务后台常驻、开机自启、日志查看、进程重启，是阿里云服务器运维的常用工具。

2.3 环境版本检查与软件升级

远程连接阿里云服务器后，首先执行指令检查当前已安装软件版本，判断环境是否达标。

# 检查Node.js版本
node -v
# 检查npm版本
npm -v
# 检查Git版本
git --version

若检测到Node.js版本低于18.x，需要执行升级操作，以CentOS、Ubuntu通用升级方案为例：

# 全局安装Node版本管理工具n
sudo npm install -g n
# 安装并切换至长期支持版
sudo n lts

升级完成后，重新打开终端再次执行node -v，确认版本更新成功。如果服务器网络访问外部镜像较慢，可以提前配置npm国内镜像源，加速后续依赖下载：

# 配置npm镜像源
npm config set registry https://registry.npmmirror.com

2.4 阿里云安全组端口放行

登录阿里云控制台，进入对应云服务器的安全组配置页面，添加入方向规则，放行服务使用的端口。默认端口3000，协议选择TCP，授权对象可设置为全部IP，也可指定固定IP段提升安全性。端口放行完成后，外部设备才能正常访问Hermes Agent提供的接口服务。

零基础部署AI Agent：OpenClaw/Hermes Agent喂饭级步骤流程

第一步：👉点击打开访问阿里云OpenClaw/Hermes Agent一键部署专题页面。

👉访问订阅阿里云百炼Token Plan AI大模型服务 。支持多模型切换，用于多模态模型灵活调用，实现多模型、多工具、多场景下的额度共享与统一管理，兼顾灵活性、稳定性与安全性，大幅降低企业使用大模型的门槛与成本。

第二步：👉打开选择阿里云轻量应用服务器，配置参考如下：

• 镜像：OpenClaw(或Hermes Agent)镜像（已经购买服务器的用户可以重置系统重新选择镜像）
• 实例：内存必须2GiB及以上。
• 地域：默认美国（弗吉尼亚），目前中国内地域（除香港）的轻量应用服务器，联网搜索功能受限。
• 时长：根据自己的需求及预算选择。

第三步：打开访问阿里云百炼大模型控制台，找到密钥管理，单击创建API-Key。

前往轻量应用服务器控制台，找到安装好OpenClaw的实例，进入「应用详情」放行18789端口、配置百炼API-Key、执行命令，生成访问OpenClaw的Token。

• 端口放通：需要放通对应端口的防火墙，单击一键放通即可。
• 配置百炼API-Key，单击一键配置，输入百炼的API-Key。单击执行命令，写入API-Key。
• 配置OpenClaw/Hermes：单击执行命令，生成访问OpenClaw/Hermes的Token。
• 访问控制页面：单击打开网站页面可进入OpenClaw/Hermes对话页面。

阿里云百炼Coding Plan API-Key 获取、配置保姆级教程：

创建API-Key，推荐访问订阅阿里云百炼Coding Plan，阿里云百炼Coding Plan每天两场抢购活动，从按tokens计费升级为按次收费，可以进一步节省费用！

• 购买后，在控制台生成API Key。注：这里复制并保存好你的API Key，后面要用。
  
• 回到轻量应用服务器-控制台，单击服务器卡片中的实例 ID，进入服务器概览页。
  
• 在服务器概览页面单击应用详情页签，进入服务器详情页面。
  
• 端口放通在OpenClaw使用步骤区域中，单击端口放通下的执行命令，可开放获取OpenClaw 服务运行端口的防火墙。
  
• 这里系统会列出我们第一步中创建的阿里云百炼 Coding Plan的API Key，直接选择就可以。
  
• 获取访问地址单击访问 Web UI 面板下的执行命令，获取 OpenClaw WebUI 的地址。
  
  

三、Hermes Agent 源码拉取与项目初始化

本章节依次完成部署目录规划、源码克隆、项目依赖安装、基础运行参数配置，是整个部署流程的核心环节。

3.1 规划项目部署目录

在阿里云服务器中统一规划目录，便于后期运维、文件管理、版本更新，这里选择系统常用目录作为部署根目录：

# 创建项目根目录
mkdir -p /usr/local/hermes-agent
# 进入创建好的目录
cd /usr/local/hermes-agent

3.2 克隆项目源码

使用Git工具拉取完整的Hermes Agent源码，执行以下指令：

# 克隆源码仓库
git clone git://hermes-agent/main.git
# 进入项目根目录
cd hermes-agent
# 查看目录文件，确认源码完整性
ls -la

如果服务器无法访问外部Git地址，可以提前在本地下载源码压缩包，通过文件上传工具将压缩包上传至阿里云服务器，再执行解压操作：

# 解压源码压缩包
unzip hermes-agent.zip
cd hermes-agent

3.3 安装项目全部依赖

进入项目根目录后，执行依赖安装指令，自动下载项目所需的第三方模块、插件包：

# 安装生产环境所有依赖
npm install

等待依赖全部安装完成，无报错即代表当前环节执行正常。若出现依赖安装失败、模块缺失，优先检查网络状态与npm镜像配置，清理缓存后重试：

# 清理npm缓存
npm cache clean --force
# 重新安装依赖
npm install

3.4 全局基础配置文件修改

项目核心配置文件为根目录下 app.config.js，该文件负责定义服务端口、运行环境、数据库连接、日志级别、跨域规则、最大并发数等全局参数，使用编辑器打开文件进行修改：

vim app.config.js

提供标准可用配置模板，可根据阿里云服务器使用场景自定义调整参数：

module.exports = {
   
  // 服务监听端口，需与阿里云安全组放行端口保持一致
  serverPort: 3000,
  // 运行环境：development 开发环境 / production 生产环境
  runEnv: "production",
  // 日志输出等级，生产环境建议设置为warn或error，减少日志输出
  logLevel: "info",
  // 开启跨域访问，允许前端、第三方服务跨域调用接口
  enableCors: true,
  // 服务最大并发连接数，根据服务器配置调整
  maxConcurrent: 30,
  // 数据库配置，单机测试使用内置数据库
  database: {
   
    dbType: "local",
    storagePath: "./data/db"
  },
  // 接口请求超时时间，单位毫秒
  requestTimeout: 300000
};

修改完成后，保存并退出编辑器。如果需要外接MySQL数据库，补充数据库地址、账号、密码、数据库名等对应参数，并提前在MySQL中创建空数据库。

四、Hermes Agent 服务启动、常驻运行与连通性测试

配置完成后，分为临时启动、后台常驻启动两种模式，分别适用于调试与正式上线场景，同时配套接口测试指令，验证服务是否正常运行。

4.1 临时前台启动（调试专用）

前台启动模式下，服务会占用当前终端，关闭终端服务随即停止，主要用于初次调试、查看实时报错日志：

# 前台启动Hermes Agent
npm run start

启动成功后，终端会输出启动日志，显示服务监听在配置的端口上。若启动过程中出现报错，根据日志提示排查依赖、端口、配置文件等问题。

4.2 后台常驻启动（生产环境正式使用）

阿里云服务器正式部署必须使用后台常驻模式，这里使用pm2进程管理工具，先完成工具全局安装：

# 全局安装pm2进程管理工具
npm install -g pm2

使用pm2启动项目，并设置进程名称，方便后续管理：

# 后台启动服务，命名为hermes-agent
pm2 start npm --name "hermes-agent" -- run start
# 设置服务器开机自启，重启云服务器后服务自动运行
pm2 startup
pm2 save

日常运维常用pm2指令，覆盖查看进程、查看日志、重启、停止等操作：

# 查看当前所有pm2托管进程
pm2 list
# 查看hermes-agent实时运行日志
pm2 logs hermes-agent
# 重启服务
pm2 restart hermes-agent
# 停止服务
pm2 stop hermes-agent
# 删除进程托管
pm2 delete hermes-agent

4.3 服务连通性接口测试

服务启动完成后，使用curl指令访问健康检查接口，验证阿里云服务器上的服务可正常响应。在任意终端执行以下指令：

# 本地测试访问
curl http://127.0.0.1:3000/health
# 外网测试，替换为阿里云服务器公网IP
curl http://服务器公网IP:3000/health

接口返回正常状态信息，代表服务部署完成、网络连通正常，基础部署环节全部结束。

五、Token Plan模块功能说明与配置准备

Token Plan是Hermes Agent内置的资源管控与访问鉴权核心模块，在云端多用户服务场景中起到关键作用。该模块依托独立配置文件管理所有访问令牌，实现调用鉴权、请求次数限制、Token额度管控、IP黑白名单、接口权限划分、令牌时效管理等功能，能够有效保障云端服务安全，合理分配服务器资源。

5.1 Token Plan核心功能介绍

1. 身份鉴权：所有外部接口调用必须携带合法Token，无令牌或令牌错误直接拦截请求；
2. 额度管控：限制单枚Token每日、每月的最大请求次数与大模型Token消耗总量，防止资源被耗尽；
3. 权限划分：区分不同Token可访问的接口，隔离管理员接口与普通业务接口；
4. IP限制：绑定指定IP地址，仅允许白名单内设备调用，提升云端服务安全性；
5. 时效控制：为Token设置生效时间与过期时间，适配临时测试、短期合作等场景。

5.2 配置文件路径与创建方式

Hermes Agent的Token Plan规则统一存储在项目根目录下的 token_plan.json 文件中，文件格式为标准JSON。若项目目录中不存在该文件，手动创建并编辑：

# 进入项目根目录
cd /usr/local/hermes-agent/hermes-agent
# 创建Token配置文件
touch token_plan.json
# 使用编辑器打开配置文件
vim token_plan.json

该文件支持多条规则并存，每一条JSON对象对应一枚独立的访问Token以及配套的管控策略。

六、Token Plan多场景配置模板与代码示例

结合阿里云云端部署的不同使用场景，分别提供个人自用、团队分组、IP白名单加固、临时时效令牌四类配置模板，所有模板可直接修改参数后投入使用。

6.1 基础单Token配置（个人单机使用）

适用于个人开发者、单机测试场景，仅做基础鉴权，配置简单，无严格IP限制，设置基础调用额度：

[
  {
   
    "token": "hm-own-2026-abcdef123456",
    "remark": "个人自用访问令牌",
    "status": true,
    "daily_req_limit": 1200,
    "daily_token_quota": 60000,
    "monthly_token_quota": 1200000,
    "ip_white_list": [],
    "allow_interface": ["*"],
    "deny_interface": [],
    "valid_start": "",
    "valid_expire": ""
  }
]

参数说明：
token：自定义访问令牌字符串，客户端调用接口时用于鉴权；
status：令牌状态，true为启用，false为禁用；
daily_req_limit：单日最大接口请求次数；
daily_token_quota：单日大模型Token消耗上限；
monthly_token_quota：单月总消耗上限；
ip_white_list：IP白名单，空数组代表不限制访问IP；
allow_interface：允许访问的接口，*代表全部放行；
deny_interface：禁止访问的接口列表；
valid_start、valid_expire：令牌生效与过期时间，为空则代表永久有效。

6.2 多用户分组配置（企业团队多人使用）

企业团队部署场景下，区分普通成员与管理员账号，设置不同额度与接口权限，隔离高危管理接口：

[
  {
   
    "token": "hm-user-001-789xyz",
    "remark": "团队普通成员",
    "status": true,
    "daily_req_limit": 600,
    "daily_token_quota": 25000,
    "monthly_token_quota": 600000,
    "ip_white_list": [],
    "allow_interface": ["/api/chat", "/api/task/run"],
    "deny_interface": ["/api/admin/*"],
    "valid_start": "",
    "valid_expire": ""
  },
  {
   
    "token": "hm-admin-001-root",
    "remark": "团队管理员",
    "status": true,
    "daily_req_limit": 6000,
    "daily_token_quota": 250000,
    "monthly_token_quota": 6000000,
    "ip_white_list": [],
    "allow_interface": ["*"],
    "deny_interface": [],
    "valid_start": "",
    "valid_expire": ""
  }
]

该配置中，普通成员无法访问所有管理员接口，同时下调调用额度，实现团队资源分层管理。

6.3 IP白名单配置（对外服务安全加固）

阿里云公网部署对外提供服务时，开启IP白名单，仅允许指定服务器、设备IP访问，防止令牌泄露后被非法调用：

[
  {
   
    "token": "hm-outside-cooper",
    "remark": "外部合作方专用令牌",
    "status": true,
    "daily_req_limit": 900,
    "daily_token_quota": 35000,
    "monthly_token_quota": 900000,
    "ip_white_list": ["112.xx.xx.xx", "192.168.2.10"],
    "allow_interface": ["/api/chat"],
    "deny_interface": [],
    "valid_start": "",
    "valid_expire": ""
  }
]

填写对应的客户端公网IP后，非白名单内的IP发起请求会直接被服务拦截。

6.4 时效型临时Token配置（短期测试、临时合作）

设置固定的生效与过期时间，适用于短期测试、临时对外合作，到期后令牌自动失效，无需手动修改配置：

[
  {
   
    "token": "hm-temp-test-999",
    "remark": "临时测试令牌",
    "status": true,
    "daily_req_limit": 400,
    "daily_token_quota": 12000,
    "monthly_token_quota": 240000,
    "ip_white_list": [],
    "allow_interface": ["*"],
    "deny_interface": [],
    "valid_start": "2026-06-01 00:00:00",
    "valid_expire": "2026-09-01 00:00:00"
  }
]

时间格式严格使用年-月-日 时:分:秒，服务会自动判断令牌是否在有效期内。

七、配置重载、功能测试与基础运维

修改完成token_plan.json文件后，不需要重启整个Hermes Agent服务，可通过内置接口在线重载配置，同时通过接口调用验证鉴权、配额、权限规则是否生效。

7.1 在线重载Token配置

执行管理员接口，刷新Token Plan规则，让新配置立即生效：

# 替换为你的服务器公网IP或本地IP
curl http://服务器IP:3000/api/admin/reload-token

接口返回执行成功，代表所有令牌规则、配额、权限已完成加载。

7.2 正常Token调用测试

携带配置好的令牌发起业务接口请求，验证鉴权功能正常：

# 携带Token调用对话接口
curl -H "Authorization: Bearer hm-own-2026-abcdef123456" http://服务器IP:3000/api/chat -X POST -d '{"content":"测试阿里云Hermes Agent Token配置"}'

接口正常返回业务数据，说明令牌鉴权通过，基础调用流程正常。

7.3 规则拦截测试

依次验证各类限制规则：

1. 持续高频发起请求，超过daily_req_limit设置值，接口返回调用次数超限提示；
2. 使用普通成员Token访问/api/admin开头的接口，触发权限拦截；
3. 使用未加入白名单的IP访问绑定IP的Token，请求直接拒绝；
4. 使用已过期的临时Token，接口提示令牌失效。

7.4 日常运维常用操作

7.4.1 临时禁用令牌

不需要删除配置文件内容，仅将对应规则内的status字段改为false，重载配置后令牌立即失效：

[
  {
   
    "token": "hm-own-2026-abcdef123456",
    "remark": "个人自用访问令牌",
    "status": false
  }
]

7.4.2 查看令牌使用统计

通过统计接口，查看所有Token的当日请求量、额度消耗情况，便于资源监控：

curl -H "Authorization: Bearer 管理员Token" http://服务器IP:3000/api/admin/token-stat

7.4.3 清理过期规则

定期检查valid_expire字段，删除配置文件中已过期、不再使用的Token规则，精简配置内容，避免冗余数据影响服务解析效率。

八、常见故障排查与解决方案

结合阿里云服务器部署场景，梳理部署、配置、运行阶段的高频问题与对应解决办法。

8.1 源码克隆失败、网络超时

问题表现：Git克隆源码长时间无响应、提示连接失败。
解决方案：检查阿里云服务器外网连通性，更换Git镜像；也可本地下载源码压缩包，通过文件上传工具上传至服务器解压部署。

8.2 依赖安装报错、模块缺失

问题表现：执行npm install出现报错，服务启动提示模块找不到。
解决方案：确认Node.js版本为18.x及以上；切换npm国内镜像；执行npm cache clean --force清理缓存后重新安装依赖。

8.3 服务启动失败，提示端口被占用

问题表现：启动日志提示端口3000已被占用。
解决方案：查找占用端口的进程并结束，或修改app.config.js中的端口号，同时同步更新阿里云安全组放行端口。

# 查找占用3000端口的进程
netstat -tulpn | grep 3000
# 终止对应进程
kill -9 进程ID

8.4 外网无法访问服务，本地可以正常访问

问题表现：服务器本地curl测试正常，外网设备无法连接。
解决方案：检查阿里云安全组，确认已放行对应端口；关闭服务器本地防火墙，或添加防火墙端口放行规则。

8.5 Token鉴权一直失败

问题表现：携带Token请求接口，始终返回鉴权失败。
解决方案：核对请求头内Token字符串与配置文件完全一致；检查规则内status是否为true；确认已执行配置重载接口；排查请求头格式是否符合要求。

8.6 IP白名单规则不生效

问题表现：非白名单IP依然可以正常调用接口。
解决方案：检查服务器是否配置反向代理，若存在代理，需要在框架配置中开启代理IP识别功能，获取真实客户端IP。

8.7 额度限制失效，可无限调用

问题表现：超过设置的请求次数、Token额度后，依然能够正常调用。
解决方案：检查token_plan.json文件是否存在JSON语法错误，修正格式后重新执行配置重载。

九、阿里云生产环境安全与优化建议

1. 令牌安全管理：定期轮换所有访问Token，禁止将令牌硬编码在前端页面、公开脚本中，降低泄露风险；
2. 权限最小化原则：普通用户令牌仅开放业务所需接口，严格限制管理员接口的访问范围；
3. 数据备份：定期备份app.config.js、token_plan.json以及本地数据库文件，防止配置与数据丢失；
4. 日志监控：结合阿里云日志服务或本地日志工具，监控接口访问日志，及时发现异常高频请求、恶意访问；
5. 版本迭代：定期拉取项目最新源码更新版本，修复已知漏洞，同步框架新功能；
6. 资源监控：查看阿里云服务器CPU、内存、带宽使用率，根据负载及时升级服务器配置。

十、总结

本文完整讲解了2026年阿里云环境下Hermes Agent从前期环境准备、云服务器配置、源码部署、依赖安装、服务常驻运行，到Token Plan规则编写、配置重载、功能测试、故障排查的全流程。Hermes Agent作为轻量化AI智能体调度框架，部署流程简洁、适配性强，非常适合在阿里云服务器上搭建私有化AI服务、企业内部智能任务系统。

Token Plan作为核心管控模块，是云端服务安全运行的关键，借助配额限制、IP白名单、接口权限、时效管控等能力，可以实现多用户、多场景的资源标准化管理。整套部署流程中，Node版本、安全组端口、JSON配置格式、Token字符串匹配是最容易出现问题的环节，严格按照文中指令与配置模板执行，能够大幅降低部署难度。

在实际落地使用时，个人用户可选用基础配置满足测试与自用需求；企业团队根据人员规模划分多级Token权限与资源配额；对外服务场景务必开启IP白名单加固安全防护。同时配合pm2实现服务常驻与开机自启，做好日常日志监控、数据备份与令牌轮换，能够保障Hermes Agent在阿里云环境中长期稳定运行。熟练掌握这套部署与配置方案后，即可基于Hermes Agent在云端搭建完整的AI智能体服务体系。