1. 前言随着大模型应用不断发展AI Agent 已经不再只是“聊天机器人”的概念。真正有价值的 Agent应该具备任务规划、工具调用、长期记忆、API 接入、自动化执行和可持续运行能力。Hermes Agent 是 Nous Research 推出的开源 AI Agent 框架。它不仅支持本地 CLI/TUI 使用还可以通过 Gateway 接入 Telegram、Discord、Slack 等消息平台并且可以开启 API Server对外提供 OpenAI-compatible API。简单来说Hermes Agent 更像是一个AI Agent Runtime而不是一个普通 Chat UI。本文会从实战角度介绍Hermes Agent 是什么Hermes Agent 的核心架构本地安装方法Docker 和 Docker Compose 部署方式config.yaml 核心配置说明如何接入 UIUIAPI 聚合平台API Server 如何调用常见问题排查生产环境部署建议2. Hermes Agent 是什么Hermes Agent 可以理解为一个支持长期运行的智能体框架。它具备以下能力支持 CLI/TUI 终端交互支持多种大模型 Provider支持 OpenAI-compatible API支持工具调用支持长期记忆 Memory支持 Skills 技能系统支持 Gateway 消息平台接入支持 Docker、local、SSH 等执行后端支持 API Server 对外服务支持日志、健康检查和运行状态管理和普通聊天工具相比Hermes Agent 最大的区别是它可以执行任务而不只是回答问题。例如你可以让它分析日志、整理文件、调用 API、执行脚本、生成报告甚至接入团队消息平台做自动化助手。3. Hermes Agent 核心架构可以将 Hermes Agent 的架构拆成四层用户入口层 ↓ Agent 核心调度层 ↓ 工具与执行层 ↓ 状态与数据层3.1 用户入口层用户入口层负责接收请求常见入口包括CLI / TUIWeb / ChatAPI ClientTelegram / Discord / Slack第三方业务系统也就是说Hermes Agent 不只能在本地终端中使用还可以接入外部系统。3.2 Agent 核心调度层核心调度层负责任务理解任务拆解模型调用工具选择执行控制上下文管理结果汇总典型流程如下用户输入 → 任务理解 → 规划步骤 → 调用模型 → 选择工具 → 执行任务 → 返回结果3.3 工具与执行层Hermes Agent 支持多种执行后端后端说明适用场景local在本机执行任务本地开发、快速测试docker在容器中执行任务服务器部署、隔离运行ssh连接远程主机执行远程运维场景modal / daytona云端沙箱或远程环境高级开发环境singularity / apptainerHPC / 科研环境特殊计算环境生产环境建议优先使用 Docker backend避免 Agent 直接在宿主机执行高风险操作。3.4 状态与数据层Hermes Agent 会保存配置、记忆、技能、会话和日志。常见数据目录如下~/.hermes/ ├── config.yaml ├── .env ├── auth.json ├── SOUL.md ├── memories/ ├── skills/ ├── cron/ ├── sessions/ ├── logs/ └── state.db这个目录非常重要。Docker 部署时必须持久化挂载否则容器重建后配置和记忆都会丢失。4. 安装方式对比Hermes Agent 支持多种安装方式安装方式适合场景优点注意事项一行安装脚本本地快速体验简单快速企业环境需审计脚本Docker服务器运行环境一致便于升级必须挂载数据目录Docker Compose长期运行配置清晰易维护不建议多实例写同一目录源码安装二次开发灵活性高依赖管理复杂Nix / NixOS声明式运维可复现性强学习成本较高推荐选择本地体验一行安装脚本 服务器部署Docker Compose 生产验证Docker Compose 反向代理 日志监控 数据备份5. 本地快速安装 Hermes Agent以 Ubuntu / Debian / WSL2 环境为例。5.1 安装基础依赖sudoaptupdatesudoaptinstall-ygitripgrep ffmpeg5.2 执行安装脚本curl-fsSLhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh|bashsource~/.bashrc5.3 初始化配置安装完成后建议执行以下命令hermes model hermes tools hermes doctor命令说明命令作用hermes model配置模型 Provider 和默认模型hermes tools配置可用工具hermes doctor检查运行环境如果只是本地体验到这里就可以开始使用。6. Docker 部署 Hermes Agent相比直接安装到系统中Docker 更适合服务器长期运行。6.1 创建数据目录mkdir-p~/.hermes6.2 初始化 Hermes Agentdockerrun-it--rm\-v~/.hermes:/opt/data\nousresearch/hermes-agent setup6.3 后台运行 Gatewaydockerrun-d\--namehermes\--restartunless-stopped\-v~/.hermes:/opt/data\-p8642:8642\nousresearch/hermes-agent gateway run6.4 查看运行状态dockerps6.5 查看日志dockerlogs-fhermes6.6 健康检查curlhttp://127.0.0.1:8642/health如果服务正常通常会返回类似{status:ok}7. Docker Compose 部署模板如果准备长期运行建议使用 Docker Compose。7.1 docker-compose.yml 示例services:hermes:image:nousresearch/hermes-agent:latestcontainer_name:hermesrestart:unless-stoppedcommand:gateway runports:-8642:8642-9119:9119volumes:-${HOME}/.hermes:/opt/dataenvironment:HERMES_DASHBOARD:1API_SERVER_ENABLED:trueAPI_SERVER_HOST:0.0.0.0API_SERVER_KEY:${API_SERVER_KEY}API_SERVER_CORS_ORIGINS:https://chat.example.comdeploy:resources:limits:memory:4Gcpus:2.07.2 启动服务dockercompose up-d7.3 查看日志dockerlogs-fhermes7.4 停止服务dockercompose down7.5 升级镜像升级前建议先备份数据目录tar-czfhermes-backup-$(date%F).tar.gz ~/.hermes然后执行dockercompose pulldockercompose up-d8. config.yaml 核心配置说明Hermes Agent 的主要配置文件是~/.hermes/config.yaml配置优先级一般可以理解为CLI 参数 config.yaml .env 默认值下面是一份示例配置model:provider:openaidefault:gpt-4oterminal:backend:dockertimeout:180container_persistent:trueapprovals:mode:smarttimeout:60memory:memory_enabled:trueuser_profile_enabled:truememory_char_limit:2200security:allow_private_urls:false8.1 model 配置model:provider:openaidefault:gpt-4o这里配置模型 Provider 和默认模型。如果使用第三方 OpenAI-compatible 聚合平台例如 UIUIAPI可以继续使用provider: openai但是要在.env中修改OPENAI_BASE_URL。8.2 terminal 配置terminal:backend:dockertimeout:180container_persistent:true建议生产环境使用 Docker backend降低直接操作宿主机的风险。8.3 approvals 配置approvals:mode:smarttimeout:60审批模式建议使用smart不要随意关闭审批机制。8.4 memory 配置memory:memory_enabled:trueuser_profile_enabled:trueMemory 可以保存长期上下文和用户偏好但也要注意隐私和数据安全。8.5 security 配置security:allow_private_urls:false建议生产环境保持allow_private_urls: false降低 SSRF 和内网访问风险。9. 接入 UIUIAPI 聚合平台很多开发者不会直接调用官方 OpenAI API而是使用 OpenAI-compatible 第三方聚合平台。如果你使用的是 UIUIAPI 聚合平台只需要重点修改两个配置OPENAI_API_KEYsk-你的-uiuiapi-keyOPENAI_BASE_URLhttps://sg.uiuiapi.com/v1注意OPENAI_BASE_URL写到/v1即可不要写成完整接口路径。正确写法OPENAI_BASE_URLhttps://sg.uiuiapi.com/v1错误写法OPENAI_BASE_URLhttps://sg.uiuiapi.com/v1/chat/completions因为 OpenAI SDK 或 Hermes Agent 一般会自动拼接/chat/completions等路径。10. .env 环境变量配置建议将敏感信息放在.env文件中。示例# UIUIAPI 聚合平台 KeyOPENAI_API_KEYsk-你的-uiuiapi-keyOPENAI_BASE_URLhttps://sg.uiuiapi.com/v1# Hermes Agent API Server 配置API_SERVER_ENABLEDtrueAPI_SERVER_PORT8642API_SERVER_HOST0.0.0.0API_SERVER_KEYchange-me-very-long-random-stringAPI_SERVER_CORS_ORIGINShttps://chat.example.com# Dashboard 配置HERMES_DASHBOARD1HERMES_DASHBOARD_HOST0.0.0.0HERMES_DASHBOARD_PORT9119这里有两个 Key 很容易混淆。10.1 OPENAI_API_KEYOPENAI_API_KEY是模型平台 Key。如果使用 UIUIAPI 聚合平台这里填写 UIUIAPI 平台生成的 API Key。调用链路是Hermes Agent → UIUIAPI 聚合平台 → 大模型服务10.2 API_SERVER_KEYAPI_SERVER_KEY是 Hermes Agent 自己对外提供 API Server 时使用的访问密钥。调用链路是外部应用 → Hermes Agent API Server简单理解OPENAI_API_KEYHermes Agent 调模型用 API_SERVER_KEY别人调用 Hermes Agent 用11. API 调用示例这里要区分两种调用方式。第一种是直接调用 UIUIAPI 聚合平台。第二种是调用 Hermes Agent 自己暴露的 API Server。11.1 直接调用 UIUIAPI 聚合平台curlhttps://sg.uiuiapi.com/v1/chat/completions\-HAuthorization: Bearer sk-你的-uiuiapi-key\-HContent-Type: application/json\-d{ model: gpt-4o, messages: [ {role: user, content: 请介绍 Hermes Agent 的核心能力。} ] }11.2 调用 Hermes Agent API Servercurlhttp://localhost:8642/v1/chat/completions\-HAuthorization: Bearer change-me-very-long-random-string\-HContent-Type: application/json\-d{ model: hermes-agent, messages: [ {role: user, content: 请检查当前部署是否存在风险。} ], stream: false }两者区别如下调用对象地址Key作用UIUIAPI 聚合平台https://sg.uiuiapi.com/v1/chat/completionsOPENAI_API_KEY直接调用大模型Hermes Agent API Serverhttp://localhost:8642/v1/chat/completionsAPI_SERVER_KEY调用 Agent 服务12. Python SDK 调用示例12.1 Python 调用 UIUIAPI 聚合平台fromopenaiimportOpenAI clientOpenAI(api_keysk-你的-uiuiapi-key,base_urlhttps://sg.uiuiapi.com/v1,)respclient.chat.completions.create(modelgpt-4o,messages[{role:user,content:请介绍 Hermes Agent 的核心能力。}],)print(resp.choices[0].message.content)12.2 Python 调用 Hermes Agent API ServerfromopenaiimportOpenAI clientOpenAI(api_keychange-me-very-long-random-string,base_urlhttp://localhost:8642/v1,)respclient.chat.completions.create(modelhermes-agent,messages[{role:user,content:帮我总结当前系统运行风险。}],)print(resp.choices[0].message.content)13. 反向代理配置建议生产环境不建议直接将8642端口暴露到公网。推荐结构用户 / 前端应用 ↓ HTTPS Nginx / OpenResty ↓ 内网 Hermes Agent API Server简单 Nginx 反代示例server { listen 443 ssl http2; server_name hermes.example.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location / { proxy_pass http://127.0.0.1:8642; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 300s; proxy_send_timeout 300s; proxy_read_timeout 300s; } }如果 API Server 需要流式响应可以补充proxy_buffering off; proxy_cache off;14. 生产环境安全建议Hermes Agent 具备工具调用和执行任务能力安全边界一定要比普通聊天接口更严格。14.1 不要直接裸露 API Server不要直接把8642端口开放给公网。建议使用HTTPSIP 白名单Basic AuthBearer TokenNginx 限流访问日志审计14.2 不要关闭审批机制不要随意使用完全无审批模式尤其是在团队环境和生产环境中。建议approvals:mode:smart14.3 使用 Docker 隔离执行环境建议terminal:backend:docker避免 Agent 直接操作宿主机关键目录。14.4 禁止默认访问内网地址建议security:allow_private_urls:false这样可以降低 SSRF 风险。14.5 密钥不要写入文章和截图包括OPENAI_API_KEYAPI_SERVER_KEYBot TokenWebhook Secret数据库密码示例中统一使用sk-xxxxx或change-me-very-long-random-string。15. 常见问题排查15.1 Docker 容器启动失败查看容器状态dockerps-a查看日志dockerlogs-fhermes常见原因镜像拉取失败数据目录权限异常端口被占用环境变量配置错误15.2 API Server 无法访问检查健康状态curlhttp://127.0.0.1:8642/health检查环境变量API_SERVER_ENABLEDtrueAPI_SERVER_HOST0.0.0.0API_SERVER_PORT8642如果本机能访问外部不能访问重点检查Docker 端口映射防火墙规则云服务器安全组Nginx 反向代理配置15.3 UIUIAPI 聚合平台调用失败重点检查OPENAI_BASE_URLhttps://sg.uiuiapi.com/v1OPENAI_API_KEYsk-你的-uiuiapi-key常见问题Base URL 写错API Key 无效模型名不存在聚合平台渠道不可用当前账号余额不足请求模型和后台模型映射不一致15.4 模型名错误如果后台支持的是gpt-4o配置里就不要写成GPT4o gpt-4o-latest gpt_4o模型名必须和聚合平台后台保持一致。15.5 Dashboard 打不开检查配置HERMES_DASHBOARD1HERMES_DASHBOARD_HOST0.0.0.0HERMES_DASHBOARD_PORT9119检查端口映射ports:-9119:911915.6 多实例共享数据目录异常不要让多个 Hermes Agent 实例同时写同一个/opt/data。错误方式实例 A / 实例 B / 实例 C → 同一个 /opt/data推荐方式实例 A → /data/hermes-a 实例 B → /data/hermes-b 实例 C → /data/hermes-c16. 推荐生产部署结构推荐结构如下用户 / 前端 / 消息平台 ↓ Nginx / OpenResty / Traefik ↓ Hermes Agent Docker Compose ↓ UIUIAPI 聚合平台 ↓ OpenAI / Claude / Gemini / DeepSeek 等模型在这个结构中Nginx 负责 HTTPS、限流、访问控制Hermes Agent 负责任务规划、工具调用、记忆和执行UIUIAPI 聚合平台负责模型接入、Key 管理和模型路由底层模型服务负责实际推理这样的分层更清晰也更适合后期扩展。17. 上线检查清单部署完成后建议逐项检查是否使用 Docker Compose 部署/opt/data是否已经持久化.env是否没有泄露OPENAI_BASE_URL是否写成https://sg.uiuiapi.com/v1OPENAI_API_KEY是否为 UIUIAPI 平台 KeyAPI_SERVER_KEY是否足够复杂API Server 是否放在反向代理后面是否限制私有地址访问是否启用日志查看和健康检查是否有数据目录备份策略是否避免多个实例共享同一个数据目录模型名称是否和聚合平台后台一致是否测试过/health是否测试过/v1/chat/completions18. 界智通(jieagi)总结Hermes Agent 不是一个普通的 AI 聊天工具而是一个可以长期运行、保存状态、调用工具、接入 API 和消息平台的 AI Agent Runtime。对于个人开发者它可以作为本地 AI 助手。对于运维人员它可以辅助日志分析、部署检查、故障初筛和自动化任务。对于拥有 UIUIAPI 这类聚合平台的开发者它可以作为模型服务之上的 Agent 执行层。部署 Hermes Agent 时需要特别注意三点第一数据目录必须持久化。第二API Key 和 API Server Key 不能混淆。第三生产环境必须做好安全隔离、反向代理、日志监控和备份。如果只是体验可以从本地安装开始。如果准备长期运行建议直接使用 Docker Compose并通过 Nginx 或 OpenResty 做入口代理。这样 Hermes Agent 才能从一个测试工具逐步变成真正可维护的智能体服务。 版权声明本文由界智通(jieagi)团队原创转载请注明出处。我们专注于AI工具的深度评测和实用教程关注我们不迷路