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 / TUI
  • Web / Chat
  • API Client
  • Telegram / Discord / Slack
  • 第三方业务系统

也就是说，Hermes Agent 不只能在本地终端中使用，还可以接入外部系统。

3.2 Agent 核心调度层

核心调度层负责：

  • 任务理解
  • 任务拆解
  • 模型调用
  • 工具选择
  • 执行控制
  • 上下文管理
  • 结果汇总

典型流程如下：

用户输入 → 任务理解 → 规划步骤 → 调用模型 → 选择工具 → 执行任务 → 返回结果

3.3 工具与执行层

Hermes Agent 支持多种执行后端：

后端 说明 适用场景
local 在本机执行任务 本地开发、快速测试
docker 在容器中执行任务 服务器部署、隔离运行
ssh 连接远程主机执行 远程运维场景
modal / daytona 云端沙箱或远程环境 高级开发环境
singularity / apptainer HPC / 科研环境 特殊计算环境

生产环境建议优先使用 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 安装基础依赖

sudo apt update
sudo apt install -y git ripgrep ffmpeg

5.2 执行安装脚本

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

5.3 初始化配置

安装完成后，建议执行以下命令：

hermes model
hermes tools
hermes doctor

命令说明：

命令 作用
hermes model 配置模型 Provider 和默认模型
hermes tools 配置可用工具
hermes doctor 检查运行环境

如果只是本地体验，到这里就可以开始使用。

6. Docker 部署 Hermes Agent

相比直接安装到系统中，Docker 更适合服务器长期运行。

6.1 创建数据目录

mkdir -p ~/.hermes

6.2 初始化 Hermes Agent

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

6.3 后台运行 Gateway

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

6.4 查看运行状态

docker ps

6.5 查看日志

docker logs -f hermes

6.6 健康检查

curl http://127.0.0.1:8642/health

如果服务正常，通常会返回类似：

{"status":"ok"}

7. Docker Compose 部署模板

如果准备长期运行，建议使用 Docker Compose。

7.1 docker-compose.yml 示例

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"
      - "9119:9119"
    volumes:
      - ${HOME}/.hermes:/opt/data
    environment:
      HERMES_DASHBOARD: "1"
      API_SERVER_ENABLED: "true"
      API_SERVER_HOST: "0.0.0.0"
      API_SERVER_KEY: "${API_SERVER_KEY}"
      API_SERVER_CORS_ORIGINS: "https://chat.example.com"
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

7.2 启动服务

docker compose up -d

7.3 查看日志

docker logs -f hermes

7.4 停止服务

docker compose down

7.5 升级镜像

升级前建议先备份数据目录：

tar -czf hermes-backup-$(date +%F).tar.gz ~/.hermes

然后执行：

docker compose pull
docker compose up -d

8. config.yaml 核心配置说明

Hermes Agent 的主要配置文件是：

~/.hermes/config.yaml

配置优先级一般可以理解为：

CLI 参数 > config.yaml > .env > 默认值

下面是一份示例配置：

model:
  provider: openai
  default: gpt-4o

terminal:
  backend: docker
  timeout: 180
  container_persistent: true

approvals:
  mode: smart
  timeout: 60

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200

security:
  allow_private_urls: false

8.1 model 配置

model:
  provider: openai
  default: gpt-4o

这里配置模型 Provider 和默认模型。

如果使用第三方 OpenAI-compatible 聚合平台，例如 UIUIAPI，可以继续使用 provider: openai，但是要在 .env 中修改 OPENAI_BASE_URL。

8.2 terminal 配置

terminal:
  backend: docker
  timeout: 180
  container_persistent: true

建议生产环境使用 Docker backend，降低直接操作宿主机的风险。

8.3 approvals 配置

approvals:
  mode: smart
  timeout: 60

审批模式建议使用 smart，不要随意关闭审批机制。

8.4 memory 配置

memory:
  memory_enabled: true
  user_profile_enabled: true

Memory 可以保存长期上下文和用户偏好，但也要注意隐私和数据安全。

8.5 security 配置

security:
  allow_private_urls: false

建议生产环境保持 allow_private_urls: false，降低 SSRF 和内网访问风险。

在这里插入图片描述

9. 接入 UIUIAPI 聚合平台

很多开发者不会直接调用官方 OpenAI API，而是使用 OpenAI-compatible 第三方聚合平台。

如果你使用的是 UIUIAPI 聚合平台，只需要重点修改两个配置：

OPENAI_API_KEY=sk-你的-uiuiapi-key
OPENAI_BASE_URL=https://sg.uiuiapi.com/v1

注意：OPENAI_BASE_URL 写到 /v1 即可，不要写成完整接口路径。

正确写法：

OPENAI_BASE_URL=https://sg.uiuiapi.com/v1

错误写法：

OPENAI_BASE_URL=https://sg.uiuiapi.com/v1/chat/completions

因为 OpenAI SDK 或 Hermes Agent 一般会自动拼接 /chat/completions 等路径。

10. .env 环境变量配置

建议将敏感信息放在 .env 文件中。

示例：

# UIUIAPI 聚合平台 Key
OPENAI_API_KEY=sk-你的-uiuiapi-key
OPENAI_BASE_URL=https://sg.uiuiapi.com/v1

# Hermes Agent API Server 配置
API_SERVER_ENABLED=true
API_SERVER_PORT=8642
API_SERVER_HOST=0.0.0.0
API_SERVER_KEY=change-me-very-long-random-string
API_SERVER_CORS_ORIGINS=https://chat.example.com

# Dashboard 配置
HERMES_DASHBOARD=1
HERMES_DASHBOARD_HOST=0.0.0.0
HERMES_DASHBOARD_PORT=9119

这里有两个 Key 很容易混淆。

10.1 OPENAI_API_KEY

OPENAI_API_KEY 是模型平台 Key。

如果使用 UIUIAPI 聚合平台，这里填写 UIUIAPI 平台生成的 API Key。

调用链路是：

Hermes Agent → UIUIAPI 聚合平台 → 大模型服务

10.2 API_SERVER_KEY

API_SERVER_KEY 是 Hermes Agent 自己对外提供 API Server 时使用的访问密钥。

调用链路是：

外部应用 → Hermes Agent API Server

简单理解：

OPENAI_API_KEY：Hermes Agent 调模型用
API_SERVER_KEY：别人调用 Hermes Agent 用

11. API 调用示例

这里要区分两种调用方式。

第一种是直接调用 UIUIAPI 聚合平台。

第二种是调用 Hermes Agent 自己暴露的 API Server。

11.1 直接调用 UIUIAPI 聚合平台

curl https://sg.uiuiapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的-uiuiapi-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "请介绍 Hermes Agent 的核心能力。"}
    ]
  }'

11.2 调用 Hermes Agent API Server

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-very-long-random-string" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes-agent",
    "messages": [
      {"role": "user", "content": "请检查当前部署是否存在风险。"}
    ],
    "stream": false
  }'

两者区别如下：

调用对象 地址 Key 作用
UIUIAPI 聚合平台 https://sg.uiuiapi.com/v1/chat/completions OPENAI_API_KEY 直接调用大模型
Hermes Agent API Server http://localhost:8642/v1/chat/completions API_SERVER_KEY 调用 Agent 服务

12. Python SDK 调用示例

12.1 Python 调用 UIUIAPI 聚合平台

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的-uiuiapi-key",
    base_url="https://sg.uiuiapi.com/v1",
)

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "请介绍 Hermes Agent 的核心能力。"}
    ],
)

print(resp.choices[0].message.content)

12.2 Python 调用 Hermes Agent API Server

from openai import OpenAI

client = OpenAI(
    api_key="change-me-very-long-random-string",
    base_url="http://localhost:8642/v1",
)

resp = client.chat.completions.create(
    model="hermes-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 端口开放给公网。

建议使用：

  • HTTPS
  • IP 白名单
  • Basic Auth
  • Bearer Token
  • Nginx 限流
  • 访问日志审计

14.2 不要关闭审批机制

不要随意使用完全无审批模式，尤其是在团队环境和生产环境中。

建议：

approvals:
  mode: smart

14.3 使用 Docker 隔离执行环境

建议：

terminal:
  backend: docker

避免 Agent 直接操作宿主机关键目录。

14.4 禁止默认访问内网地址

建议：

security:
  allow_private_urls: false

这样可以降低 SSRF 风险。

14.5 密钥不要写入文章和截图

包括：

  • OPENAI_API_KEY
  • API_SERVER_KEY
  • Bot Token
  • Webhook Secret
  • 数据库密码

示例中统一使用 sk-xxxxx 或 change-me-very-long-random-string。

15. 常见问题排查

15.1 Docker 容器启动失败

查看容器状态：

docker ps -a

查看日志：

docker logs -f hermes

常见原因：

  • 镜像拉取失败
  • 数据目录权限异常
  • 端口被占用
  • 环境变量配置错误

15.2 API Server 无法访问

检查健康状态：

curl http://127.0.0.1:8642/health

检查环境变量：

API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642

如果本机能访问，外部不能访问，重点检查：

  • Docker 端口映射
  • 防火墙规则
  • 云服务器安全组
  • Nginx 反向代理配置

15.3 UIUIAPI 聚合平台调用失败

重点检查：

OPENAI_BASE_URL=https://sg.uiuiapi.com/v1
OPENAI_API_KEY=sk-你的-uiuiapi-key

常见问题：

  • Base URL 写错
  • API Key 无效
  • 模型名不存在
  • 聚合平台渠道不可用
  • 当前账号余额不足
  • 请求模型和后台模型映射不一致

15.4 模型名错误

如果后台支持的是：

gpt-4o

配置里就不要写成：

GPT4o
gpt-4o-latest
gpt_4o

模型名必须和聚合平台后台保持一致。

15.5 Dashboard 打不开

检查配置：

HERMES_DASHBOARD=1
HERMES_DASHBOARD_HOST=0.0.0.0
HERMES_DASHBOARD_PORT=9119

检查端口映射：

ports:
  - "9119:9119"

15.6 多实例共享数据目录异常

不要让多个 Hermes Agent 实例同时写同一个 /opt/data。

错误方式：

实例 A / 实例 B / 实例 C → 同一个 /opt/data

推荐方式：

实例 A → /data/hermes-a
实例 B → /data/hermes-b
实例 C → /data/hermes-c

16. 推荐生产部署结构

推荐结构如下：

用户 / 前端 / 消息平台
        ↓
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/v1
  • OPENAI_API_KEY 是否为 UIUIAPI 平台 Key
  • API_SERVER_KEY 是否足够复杂
  • API Server 是否放在反向代理后面
  • 是否限制私有地址访问
  • 是否启用日志查看和健康检查
  • 是否有数据目录备份策略
  • 是否避免多个实例共享同一个数据目录
  • 模型名称是否和聚合平台后台一致
  • 是否测试过 /health
  • 是否测试过 /v1/chat/completions

18. 界智通(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工具的深度评测和实用教程，关注我们不迷路！

# docker # 容器 # 运维 # 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

AI时代：工程师如何驾驭GPT-5.5革命

avatar AtomGit开源社区
cover

【ROS2有线多机通讯】基于CycloneDDS的有线组网与发现机制优化

avatar AtomGit开源社区
cover

从 TDD 到 SDD：当“代码”不再是核心资产，软件工程正在发生什么变化？

avatar AtomGit开源社区