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

一、项目概况

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)

#!/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：

# MiniMax（国内线路）
MINIMAX_CN_API_KEY=your_api_key_here

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

---

四、MiniMax 接入配置

4.1 模型配置 (config.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 提供两条线路，根据网络环境选择：

# 国内线路（当前使用）→ 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 对话参数

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

5.2 终端沙箱

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 上下文压缩

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

5.4 记忆系统

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）

checkpoints:
  enabled: true
  max_snapshots: 50            # 最多保留 50 个快照

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

---

六、多平台接入

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 切换：

display:
  personality: kawaii   # 当前使用 kawaii 风格

内置人设一览：

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

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

---

八、常用运维操作

启动

cd /home/wucf/docker/hermes
bash start.sh

查看日志

docker logs -f hermes

进入容器

docker exec -it hermes bash

重启

docker restart hermes

停止并清理

docker stop hermes && docker rm hermes

查看状态

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