Hermes Agent Docker 部署笔记 —— 接入 MiniMax

fengchengwu20122026-06-15 11:24

一、项目概况

Hermes 是一个多平台 AI Agent 框架，支持 CLI / Telegram / Discord / Slack / WhatsApp / 飞书等多种交互渠道。它通过 OpenAI 兼容 API 接入各种大语言模型（LLM），并内置终端沙箱、浏览器自动化、技能系统等能力。

当前部署选型：

项目 选择
运行环境 Docker（nikolaik/python-nodejs:python3.11-nodejs20）
LLM 模型 MiniMax-M3
LLM 接入点 https://api.minimaxi.com/v1（国内线路）
交互渠道 CLI + 飞书
数据持久化 Docker Volume（./data → /opt/data）

二、目录结构

复制代码 
hermes/
├── config.yaml          # Hermes 主配置文件
├── config.yaml.bak      # 配置备份
├── .env                 # 环境变量（API Key 等敏感信息）
├── SOUL.md              # Agent 人设/灵魂说明书
├── start.sh             # Docker 启动脚本
└── data/                # 持久化数据目录（挂载入容器）
    ├── auth.json        # 认证凭据
    ├── bin/             # 二进制/脚本
    ├── cache/           # 缓存
    ├── config.yaml      # 容器内配置副本
    ├── cron/            # 定时任务
    ├── gateway.pid      # 网关进程 ID
    ├── hooks/           # 钩子脚本
    ├── logs/            # 日志
    ├── memories/        # 持久记忆
    ├── plans/           # 执行计划
    ├── platforms/       # 平台适配
    ├── sandboxes/       # 沙箱环境
    ├── sessions/        # 会话记录
    ├── skills/          # 技能模块
    ├── skins/           # 皮肤/主题
    ├── state.db         # SQLite 状态数据库
    └── workspace/       # 工作区

三、Docker 部署配置

3.1 启动脚本 (start.sh)

bash 复制代码 
#!/bin/bash
cname="hermes"
iname="hermes-agnet:260416"

# 检查容器是否存在，若存在则移除
if docker ps -a --format '{{.Names}}' | grep -q "^${cname}$"; then
    echo "[docker] removing existing container ${cname}..."
    docker rm -f "${cname}"
fi

# 运行容器
docker run -itd --restart=always \
    --name "${cname}" \
    -v $(pwd)/data/:/opt/data \
    "${iname}"

关键参数解读：

  • -itd：交互式 TTY + 后台运行（daemon）
  • --restart=always：容器退出时自动重启，确保 7×24 在线
  • --name hermes：固定容器名，便于管理
  • -v $(pwd)/data/:/opt/data：将宿主机当前目录下的 data/ 挂载到容器的 /opt/data，实现数据持久化
  • 镜像 hermes-agnet:260416 是本地构建的 Hermes 镜像

3.2 容器启动依赖

启动前需要确保 .env 文件中已填写必要的 API Key：

bash 复制代码 
# MiniMax（国内线路）
MINIMAX_CN_API_KEY=your_api_key_here

# 飞书（可选）
FEISHU_APP_ID=cli_xxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx

四、MiniMax 接入配置

4.1 模型配置 (config.yaml)

yaml 复制代码 
model:
  default: MiniMax-M3           # 默认模型
  provider: mimimax             # 注意：provider 名称为 "mimimax"
  base_url: https://api.minimaxi.com/v1   # 国内线路 API 地址

⚠️ 注意 ：provider 字段值为 mimimax 而非 minimax（官方拼写），这是 Hermes 源码中定义的 provider key，需保持一致。

4.2 环境变量 (.env)

MiniMax 提供两条线路，根据网络环境选择：

bash 复制代码 
# 国内线路（当前使用）→ base_url: https://api.minimaxi.com/v1
MINIMAX_CN_API_KEY=your_api_key_here

# 国际线路 → base_url: https://api.minimax.io/v1
MINIMAX_API_KEY=your_api_key_here

Hermes 的 API Key 解析逻辑：

  • 若 base_url 指向 api.minimaxi.com → 使用 MINIMAX_CN_API_KEY
  • 若 base_url 指向 api.minimax.io → 使用 MINIMAX_API_KEY
  • 两者都未设置 → 服务启动失败

4.3 MiniMax API 兼容性

MiniMax 提供与 OpenAI 兼容的 /v1/chat/completions 端点，Hermes 通过统一的 OpenAI-compatible client 接入，无需额外适配。截至撰写时支持的 MiniMax 模型包括：

  • MiniMax-M3 --- 当前使用
  • MiniMax-M2.5
  • MiniMax-Text-01

五、Agent 核心配置

5.1 对话参数

yaml 复制代码 
agent:
  max_turns: 90              # 单次对话最大轮次
  gateway_timeout: 1800      # 网关超时 30 分钟
  reasoning_effort: medium   # 推理深度：medium（可选 low/medium/high）
  tool_use_enforcement: auto # 工具调用由模型自行决定

5.2 终端沙箱

yaml 复制代码 
terminal:
  backend: local                                  # 本地执行（可改为 docker/modal/singularity）
  docker_image: nikolaik/python-nodejs:python3.11-nodejs20
  timeout: 180                                    # 命令执行超时 180s
  persistent_shell: true                          # 保持 shell 上下文
  lifetime_seconds: 300                           # 空闲 300s 后回收

当前 backend: local 表示命令直接在宿主机执行。若需要沙箱隔离，可改为 docker 或 modal。

5.3 上下文压缩

yaml 复制代码 
compression:
  enabled: true
  threshold: 0.5        # 使用 50% 上下文窗口时触发压缩
  target_ratio: 0.2     # 压缩至原始大小的 20%
  protect_last_n: 20    # 保护最近 20 条消息不被压缩

5.4 记忆系统

yaml 复制代码 
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200      # 每条记忆最大字符数
  user_char_limit: 1375        # 用户档案最大字符数
  nudge_interval: 10           # 每 10 轮触发记忆更新

数据持久化在 data/memories/ 目录下，容器重启不丢失。

5.5 检查点（Checkpoints）

yaml 复制代码 
checkpoints:
  enabled: true
  max_snapshots: 50            # 最多保留 50 个快照

允许 Agent 在执行长任务时自动保存中间状态，出错后可回滚。

六、多平台接入

yaml 复制代码 
platform_toolsets:
  cli:          [hermes-cli]
  telegram:     [hermes-telegram]
  discord:      [hermes-discord]
  whatsapp:     [hermes-whatsapp]
  slack:        [hermes-slack]
  signal:       [hermes-signal]
  homeassistant:[hermes-homeassistant]
  qqbot:        [hermes-qqbot]

当前已启用：CLI + 飞书 （通过 .env 中的飞书凭据）。

七、个性系统（Personalities）

Hermes 内置了 13 种人设，在 config.yaml 中已预设，可通过 display.personality 切换：

yaml 复制代码 
display:
  personality: kawaii   # 当前使用 kawaii 风格

内置人设一览：

key 风格
helpful 友好助手
concise 简洁高效
technical 技术专家
creative 创意脑洞
teacher 耐心老师
kawaii ✨萌萌二次元
catgirl 猫娘 nya~
pirate 海盗船长
shakespeare 莎翁腔调
surfer 加州冲浪手
noir 黑色电影
uwu 软萌 uwu
philosopher 哲学沉思
hype 🔥全开狂热

SOUL.md 中定义的自定义人格（幽默码农）会覆盖预设人格。

八、常用运维操作

启动

bash 复制代码 
cd /home/wucf/docker/hermes
bash start.sh

查看日志

bash 复制代码 
docker logs -f hermes

进入容器

bash 复制代码 
docker exec -it hermes bash

重启

bash 复制代码 
docker restart hermes

停止并清理

bash 复制代码 
docker stop hermes && docker rm hermes

查看状态

bash 复制代码 
docker ps -a --filter "name=hermes"

九、踩坑备忘录

  1. Provider 拼写 ：config.yaml 中 provider 是 mimimax（少一个 n），这是 Hermes 源码中的内置 key，不要自行修正。

  2. API Key 前缀匹配 ：MiniMax 的 API Key 不遵循 sk-minimax- 前缀，Hermes 通过 base_url 来路由到对应 provider。确保 base_url 和 MINIMAX_CN_API_KEY 环境变量线路一致（都用国内 api.minimaxi.com 或都用国际 api.minimax.io），否则认证会失败。

  3. 国内线路域名的 i ：国内线路是 api.minimaxi.com（多一个 i），国际线路是 api.minimax.io------不要搞混。

  4. Docker 镜像名称 ：start.sh 中镜像名为 hermes-agnet:260416（agnet 是 agent 的拼写错误），实际镜像名需要与此一致，或修改脚本中的 iname 变量。

  5. 数据持久化 ：data/ 目录包含 SQLite 数据库、记忆文件、会话记录、技能模块等，务必确保挂载正确，否则容器重建后数据全部丢失。

  6. 飞书 WebSocket 模式 ：.env 中 FEISHU_CONNECTION_MODE=websocket，无需公网可访问的回调地址，适合内网部署。

十、扩展方向

  • 接入更多渠道（Telegram / Discord）
  • 终端后端切换为 Docker 模式以获得沙箱隔离
  • 配置 Cron 定时任务实现主动推送
  • 启用 TL 训练（Tinker + Atropos）进行模型微调
  • 添加代码执行超时与资源限制（container_cpu / container_memory）

📅 笔记时间：2026-06-14

🖥️ 部署主机：Linux 6.6.0 x86_64

🐳 镜像：hermes-agnet:260416

🧠 模型：MiniMax-M3 @ api.minimaxi.com/v1

相关推荐
必胜刻6 小时前
从零搭建全栈博客系统：Go + Vue 3 + Docker 全流程实战
vue.js·docker·golang
我叫张小白。6 小时前
Docker镜像构建原理与Dockerfile工程化实践深度剖析
运维·docker·容器
菜鸟是大神7 小时前
【Hermes入门11讲】第七讲：定时自动化——让Hermes成为你的24小时助手
人工智能·github·hermes
菜鸟是大神9 小时前
【Hermes入门11讲】第五讲：Hermes的记忆力——持久记忆系统详解
hermes
梦想的颜色16 小时前
硬核实践：使用 Docker 部署生产级 Redis（持久化 + 安全配置 + 高可用）
redis·docker·redis持久化·docker compose·redis哨兵·rdb aof
weixin_4713830316 小时前
Docker - 05 - 构建流程
运维·docker·容器
段智华17 小时前
Hermes轨迹自进化：用失败Trace炼成更强Skill
ai-native·hermes·自进化智能体
ejinxian19 小时前
微虚拟机 smolvm 与Docker 容器比较
运维·docker·容器·smolvm
爱码少年20 小时前
Docker如何一次查看多个容器日志
运维·docker·容器
Sean‘21 小时前
GitLab 升级后 502：Puma 反复重启问题处理记录
docker·gateway·gitlab
热门推荐
01GitHub 镜像站点022026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf03AI科技热点日报 | 2026年07月01日04【AI】2026 年具身智能模型和世界模型总结052026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？062026 年 AI 大模型 & AI 编程工具实战全总结072026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？08Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析09Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费102026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？