一、项目概况Hermes是一个多平台 AI Agent 框架支持 CLI / Telegram / Discord / Slack / WhatsApp / 飞书等多种交互渠道。它通过 OpenAI 兼容 API 接入各种大语言模型LLM并内置终端沙箱、浏览器自动化、技能系统等能力。当前部署选型项目选择运行环境Dockernikolaik/python-nodejs:python3.11-nodejs20LLM 模型MiniMax-M3LLM 接入点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/bashcnamehermesinamehermes-agnet:260416# 检查容器是否存在若存在则移除ifdockerps-a--format{{.Names}}|grep-q^${cname}$;thenecho[docker] removing existing container${cname}...dockerrm-f${cname}fi# 运行容器dockerrun-itd--restartalways\--name${cname}\-v$(pwd)/data/:/opt/data\${iname}关键参数解读-itd交互式 TTY 后台运行daemon--restartalways容器退出时自动重启确保 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_KEYyour_api_key_here# 飞书可选FEISHU_APP_IDcli_xxxxxxxxxxxxFEISHU_APP_SECRETxxxxxxxxxxxxxxxxxxxx四、MiniMax 接入配置4.1 模型配置 (config.yaml)model:default:MiniMax-M3# 默认模型provider:mimimax# 注意provider 名称为 mimimaxbase_url:https://api.minimaxi.com/v1# 国内线路 API 地址⚠️注意provider字段值为mimimax而非minimax官方拼写这是 Hermes 源码中定义的 provider key需保持一致。4.2 环境变量 (.env)MiniMax 提供两条线路根据网络环境选择# 国内线路当前使用→ base_url: https://api.minimaxi.com/v1MINIMAX_CN_API_KEYyour_api_key_here# 国际线路 → base_url: https://api.minimax.io/v1MINIMAX_API_KEYyour_api_key_hereHermes 的 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.5MiniMax-Text-01五、Agent 核心配置5.1 对话参数agent:max_turns:90# 单次对话最大轮次gateway_timeout:1800# 网关超时 30 分钟reasoning_effort:medium# 推理深度medium可选 low/medium/hightool_use_enforcement:auto# 工具调用由模型自行决定5.2 终端沙箱terminal:backend:local# 本地执行可改为 docker/modal/singularitydocker_image:nikolaik/python-nodejs:python3.11-nodejs20timeout:180# 命令执行超时 180spersistent_shell:true# 保持 shell 上下文lifetime_seconds:300# 空闲 300s 后回收当前backend: local表示命令直接在宿主机执行。若需要沙箱隔离可改为docker或modal。5.3 上下文压缩compression:enabled:truethreshold:0.5# 使用 50% 上下文窗口时触发压缩target_ratio:0.2# 压缩至原始大小的 20%protect_last_n:20# 保护最近 20 条消息不被压缩5.4 记忆系统memory:memory_enabled:trueuser_profile_enabled:truememory_char_limit:2200# 每条记忆最大字符数user_char_limit:1375# 用户档案最大字符数nudge_interval:10# 每 10 轮触发记忆更新数据持久化在data/memories/目录下容器重启不丢失。5.5 检查点Checkpointscheckpoints:enabled:truemax_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中的飞书凭据。七、个性系统PersonalitiesHermes 内置了 13 种人设在config.yaml中已预设可通过display.personality切换display:personality:kawaii# 当前使用 kawaii 风格内置人设一览key风格helpful友好助手concise简洁高效technical技术专家creative创意脑洞teacher耐心老师kawaii✨萌萌二次元catgirl猫娘 nya~pirate海盗船长shakespeare莎翁腔调surfer加州冲浪手noir黑色电影uwu软萌 uwuphilosopher哲学沉思hype全开狂热SOUL.md中定义的自定义人格幽默码农会覆盖预设人格。八、常用运维操作启动cd/home/wucf/docker/hermesbashstart.sh查看日志dockerlogs-fhermes进入容器dockerexec-ithermesbash重启dockerrestart hermes停止并清理dockerstop hermesdockerrmhermes查看状态dockerps-a--filternamehermes九、踩坑备忘录Provider 拼写config.yaml中 provider 是mimimax少一个n这是 Hermes 源码中的内置 key不要自行修正。API Key 前缀匹配MiniMax 的 API Key 不遵循sk-minimax-前缀Hermes 通过base_url来路由到对应 provider。确保base_url和MINIMAX_CN_API_KEY环境变量线路一致都用国内api.minimaxi.com或都用国际api.minimax.io否则认证会失败。国内线路域名的i国内线路是api.minimaxi.com多一个i国际线路是api.minimax.io——不要搞混。Docker 镜像名称start.sh中镜像名为hermes-agnet:260416agnet是agent的拼写错误实际镜像名需要与此一致或修改脚本中的iname变量。数据持久化data/目录包含 SQLite 数据库、记忆文件、会话记录、技能模块等务必确保挂载正确否则容器重建后数据全部丢失。飞书 WebSocket 模式.env中FEISHU_CONNECTION_MODEwebsocket无需公网可访问的回调地址适合内网部署。十、扩展方向接入更多渠道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