注服务器部署Hermes超详细指南由于过于详细所以分为三部分结尾有踩坑点说明。Hermes Agent 云服务器部署一基础环境、Docker 镜像、目录挂载与模型配置Hermes Agent 云服务器部署二微信 Weixin Gateway 与 Docker Compose 常驻运行Hermes Agent 云服务器部署三面试题库、Cron 定时任务与故障排查本笔记记录 Hermes Agent 从“终端聊天可用”到“微信私聊可用”的配置过程。重点包括Weixin Gateway、微信配对授权、Docker Compose 后台常驻、两个 SSH 窗口如何操作、常见错误排查。前提第 1 部分已经完成Docker 镜像nousresearch/hermes-agent:latest已成功拉取/root/.hermes数据目录已存在模型 API 已配置成功终端聊天界面已经可以正常回复1. 终端聊天能回复不代表微信能回复在 setup 完成后Hermes 可能进入终端聊天界面Welcome to Hermes Agent! Type your message or /help for commands.在这个界面输入你好如果 Hermes 能回复说明模型 provider 配置成功 API Key 可用 模型名称可用 Hermes Agent 本体可以调用模型但是这只能说明“本地终端聊天”没问题。微信聊天还需要另一个组件Hermes GatewayGateway 负责连接微信 / Telegram / Discord 等消息平台接收微信消息把消息转交给 Hermes Agent把 Agent 回复发回微信执行 cron 定时任务调度所以终端聊天可用 ≠ 微信聊天可用微信要正常回复必须启动gateway run2. 退出终端聊天界面如果当前还在终端聊天界面Welcome to Hermes Agent! Type your message or /help for commands.可以输入/exit或者按Ctrl C命令解释/exit是 Hermes 终端聊天界面的退出命令。Ctrl C是 Linux 终端中断当前前台程序的快捷键。注意如果当前运行的是chat按Ctrl C只是退出聊天如果当前运行的是gateway run按Ctrl C会停止微信网关3. 临时启动微信 Gateway最初可以用临时方式启动 gatewaydockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent gateway run命令解释dockerrun创建并运行一个新的容器。-it交互式运行适合在终端里实时查看输出。--rm容器退出后自动删除容器。-v/root/.hermes:/opt/data把宿主机/root/.hermes映射到容器内/opt/data。这保证临时容器也能读取同一套配置、API Key、微信登录状态和 cron 数据。-eTZAsia/Shanghai设置容器时区为北京时间。nousresearch/hermes-agent使用 Hermes Agent 镜像。gateway run启动 Hermes Gateway。临时启动方式的问题这种方式适合测试但不适合长期运行。原因SSH 断开gateway 可能停止 按 CtrlCgateway 会停止 容器是临时的没有固定名字 不方便 docker exec / logs / restart 管理当 gateway 停止时微信会收到类似消息⚠️ Gateway shutting down — Your current task will be interrupted.这不是 Hermes 崩溃而是你正在运行的 gateway 被停止了。4. 配置微信平台在 setup 或 gateway setup 中出现平台列表Select platforms to configure: [ ] 1. Telegram [ ] 2. Discord ... [ ] 12. WeCom (Enterprise WeChat) [ ] 13. WeCom Callback (Self-Built App) [ ] 14. Weixin / WeChat应选择14. Weixin / WeChat不要选12. WeCom 13. WeCom Callback区别说明选项含义Weixin / WeChat个人微信WeCom企业微信WeCom Callback企业微信自建应用回调当前目标是在个人微信里和 Hermes 聊天所以选择Weixin / WeChat5. 配置 direct messages 授权方式配置微信时出现How should direct messages be authorized? → Use DM pairing approval (recommended) Allow all direct messages Only allow listed user IDs Disable direct messages选择Use DM pairing approval (recommended)选项解释选项含义是否推荐Use DM pairing approval第一次私聊需要配对码批准推荐Allow all direct messages所有人都可以私聊调用 Agent不推荐Only allow listed user IDs只允许白名单用户推荐但需要手动配置Disable direct messages禁用私聊不适合当前场景当前选择 pairing approval 的原因既安全又方便第一次从微信发消息时Hermes 会给一个 pairing code。服务器端批准后该微信用户就能正常聊天。6. 微信收到 pairing code启动 gateway 后在微信里发送/status或你好如果用户未授权微信会收到类似Hi~ I dont recognize you yet! Heres your pairing code: NENVYLJQ Ask the bot owner to run: hermes pairing approve weixin NENVYLJQ这说明微信消息已经成功到达 Hermes Gateway 但当前微信用户还没有授权此时不是故障而是需要批准配对。7. 为什么 docker exec hermes hermes 会失败曾经尝试执行dockerexec-ithermes hermes pairing list结果报错OCI runtime exec failed: exec: hermes: executable file not found in $PATH原因docker run nousresearch/hermes-agent setup能正常运行是因为镜像内部有 entrypoint。当你执行dockerrun... nousresearch/hermes-agent setup实际上 Docker 会先运行镜像的 entrypoint再把setup交给 entrypoint 处理。但是dockerexec-ithermes hermes pairing list是在已经运行的容器里直接找一个叫hermes的可执行文件。这个可执行文件在容器内不一定存在于$PATH所以会失败。正确做法用新的临时容器执行 Hermes CLI 命令并挂载同一个数据目录dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin NENVYLJQ8. 批准微信配对当微信收到配对码NENVYLJQ在服务器执行dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin NENVYLJQ命令解释dockerrun-it--rm启动一个临时 Hermes CLI 容器执行完自动删除。-v/root/.hermes:/opt/data使用和 gateway 一样的数据目录。这很重要因为 pairing 信息保存在/root/.hermes中。nousresearch/hermes-agent pairing approve weixin NENVYLJQ执行 Hermes pairing approve 命令。参数解释参数含义pairing配对管理approve批准配对weixin平台是微信NENVYLJQ微信收到的配对码批准成功后在微信里重新发送/status如果有回复就说明授权成功。9. 查看 pairing 列表如果不确定配对码可以执行dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing list作用列出当前等待批准的配对请求。如果微信里显示的配对码和命令里显示的配对码有差异以服务器上pairing list显示的为准。10. /status 的作用微信私聊发送/status正常会返回 Hermes Gateway 状态。例如可能看到Agent Running: No Connected Platforms: weixin解释Agent Running: No不代表 Hermes 没启动。它通常表示当前没有正在执行中的 agent 任务如果你随后发送你好Hermes 能回复就说明服务正常。Connected Platforms: weixin说明微信平台已连接。11. /sethome 的作用微信授权成功后发送/sethome作用把当前微信会话设置为 Hermes 的 home channel。后续 cron 定时任务、主动推送、默认投递目标等可能会使用这个 home channel。执行成功后Hermes 可能会提示当前 home 设置为某个微信 chat_id例如o9cq80y9HMRyFHDRQ5NMyWk8cYccim.wechat这个 ID 后续创建 cron 任务时非常重要。比如 cron 投递到微信时可能需要weixin:o9cq80y9HMRyFHDRQ5NMyWk8cYccim.wechat12. 为什么需要 Docker Compose 常驻运行临时运行 gateway 的方式是dockerrun-it--rm... gateway run缺点终端关闭服务就停 CtrlC 服务就停 容器无固定名字 服务器重启后不会自动恢复 管理不方便因此需要 Docker Compose 后台常驻运行。目标是让 Hermes Gateway 作为后台服务运行容器名固定为 hermes 服务器重启后自动启动 可以 docker compose restart 可以 docker compose logs 查看日志13. 创建 Docker Compose 文件在服务器执行cd/rootcatcompose.hermes.ymlEOF services: hermes: image: nousresearch/hermes-agent:latest container_name: hermes restart: unless-stopped command: gateway run volumes: - /root/.hermes:/opt/data environment: - TZAsia/Shanghai mem_limit: 3500m cpus: 2.5 EOF命令解释cd/root切换到 root 用户主目录。将 compose 文件放在/root下方便管理。catcompose.hermes.ymlEOF ... EOF创建文件/root/compose.hermes.yml。这是 shell heredoc 写法用于把多行内容写入文件。compose 文件逐行解释services:定义 Docker Compose 管理的服务列表。hermes:定义一个服务名字叫hermes。image:nousresearch/hermes-agent:latest使用镜像nousresearch/hermes-agent:latestcontainer_name:hermes指定容器名称为hermes这样后续可以稳定使用dockerpsdockerlogs hermesdockercompose restart hermesrestart:unless-stopped设置重启策略。含义除非手动停止否则容器异常退出或服务器重启后会自动启动这是服务器长期运行服务常用配置。command:gateway run容器启动后执行gateway run即启动 Hermes Gateway。volumes:-/root/.hermes:/opt/data挂载数据目录。含义宿主机 /root/.hermes 映射到容器内 /opt/data这样配置、微信登录状态、cron、题库等数据不会因为容器删除而丢失。environment:-TZAsia/Shanghai设置时区为北京时间。mem_limit:3500m限制容器最多使用约 3.5GB 内存。服务器本身是 4G 内存加了 4G swap。限制 Hermes 容器内存是为了避免容器把整台机器内存吃满。cpus:2.5限制容器最多使用约 2.5 个 CPU 核心。服务器是 4 核给 Hermes 留 2.5 核避免它占满全部 CPU。14. 启动 Hermes Gateway 常驻容器执行dockercompose-f/root/compose.hermes.yml up-d命令解释dockercompose使用 Docker Compose v2。-f/root/compose.hermes.yml指定 compose 文件路径。up创建并启动服务。-d后台运行也叫 detached mode。如果成功会看到类似[] Running 2/2 ✔ Network root_default Created ✔ Container hermes Started这说明容器已经在后台启动。15. 查看容器是否运行执行dockerps--formattable {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}命令解释dockerps列出正在运行的容器。--formattable {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}按指定格式输出表格只显示关键信息。正常应该看到CONTAINER ID IMAGE STATUS NAMES 7bb1315ac9f6 nousresearch/hermes-agent:latest Up 12 seconds hermes其中NAMES hermes STATUS Up ...说明 Hermes Gateway 正在运行。16. 查看 Gateway 日志执行dockercompose-f/root/compose.hermes.yml logs-fhermes命令解释dockercompose-f/root/compose.hermes.yml logs查看 compose 服务日志。-ffollow持续跟踪日志输出。hermes只查看hermes这个服务的日志。正常启动时会看到类似Dropping root privileges Syncing bundled skills into ~/.hermes/skills/ ... Done: 0 new, 0 updated, 89 unchanged. 89 total bundled. ┌─────────────────────────────────────────────────────────┐ │ ⚕ Hermes Gateway Starting... │ ├─────────────────────────────────────────────────────────┤ │ Messaging platforms cron scheduler │ │ Press CtrlC to stop │ └─────────────────────────────────────────────────────────┘注意这个命令只是看日志。按Ctrl C只会退出日志查看不会停止后台容器。这是非常重要的一点。17. 两个 SSH 窗口如何使用当时使用了两个 SSH 窗口。第一个窗口用于看日志dockercompose-f/root/compose.hermes.yml logs-fhermes这个窗口可以观察微信是否收到消息用户是否 unauthorizedgateway 是否重启cron 是否执行agent 是否报错如果不想继续看日志可以按Ctrl C退出日志查看。这不会停止 Hermes 服务。第二个窗口用于执行管理命令例如dockerpsdockercompose-f/root/compose.hermes.yml restart hermesdockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin 配对码总结窗口用途第一个窗口看实时日志第二个窗口执行管理命令18.Gateway shutting down是什么微信曾收到⚠️ Gateway shutting down — Your current task will be interrupted.原因通常是因为执行了dockercompose-f/root/compose.hermes.yml restart hermes或者停止了临时 gatewayCtrl C解释这条消息表示当前 Gateway 正在关闭 正在执行的任务会被中断它不一定是错误。如果是你主动重启容器导致的这是正常现象。19. 常用 Compose 管理命令启动服务dockercompose-f/root/compose.hermes.yml up-d后台启动 Hermes Gateway。查看运行状态dockerps查看正在运行的容器。查看实时日志dockercompose-f/root/compose.hermes.yml logs-fhermes持续查看日志。查看最近 100 行日志dockercompose-f/root/compose.hermes.yml logs--tail100hermes适合排查问题不会一直阻塞终端。重启服务dockercompose-f/root/compose.hermes.yml restart hermes用于修改.env或配置后让服务重新加载。停止服务dockercompose-f/root/compose.hermes.yml down停止并删除 compose 创建的容器和网络。注意不会删除 /root/.hermes 数据目录再次启动服务dockercompose-f/root/compose.hermes.yml up-d20. 检查微信相关日志如果微信没有回复可以查看日志dockercompose-f/root/compose.hermes.yml logs--tail200hermes|grep-Eiweixin|wechat|pair|auth|error|account|login|poll|message命令解释dockercompose-f/root/compose.hermes.yml logs--tail200hermes查看最近 200 行 Hermes 日志。grep-Eiweixin|wechat|pair|auth|error|account|login|poll|message筛选包含关键字的日志。参数参数含义-E使用扩展正则-i忽略大小写关键字含义关键字说明weixin/wechat微信相关日志pair配对相关auth授权相关error错误account微信账号login登录poll轮询message消息21. Unauthorized user 日志日志中曾出现WARNING gateway.run: Unauthorized user: o9cq80y9HMRyFHDRQ5NMyWk8cYccim.wechat这说明微信消息已经到达 Gateway 但该微信用户没有被授权常见原因pairing code 没批准pairing 批准了但 gateway 没重启/没加载allowlist 没配置当前微信 chat_id 和批准的不是同一个处理思路优先处理 pairingdockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing list然后批准dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin 配对码如果仍然 unauthorized可以考虑配置 allowlist。22. allowlist 的作用日志里还出现过WARNING gateway.run: No user allowlists configured. All unauthorized users will be denied.意思是当前没有配置用户白名单 未授权用户会被拒绝如果 pairing 机制没有正确生效可以手动把自己的微信 ID 加入 Weixin allowlist。例如微信 ID 是o9cq80y9HMRyFHDRQ5NMyWk8cYccim.wechat可以编辑nano/root/.hermes/.env追加类似配置WEIXIN_ALLOWED_USERSo9cq80y9HMRyFHDRQ5NMyWk8cYccim.wechat然后重启 gatewaydockercompose-f/root/compose.hermes.yml restart hermes注意不同 Hermes 版本的 allowlist 环境变量名可能略有差异。如果设置后无效应查看官方文档或当前.env中已有的 Weixin 配置项。23. 微信普通聊天测试顺序授权成功后建议按这个顺序测试微信第一步测试状态命令/status如果有回复说明微信 Gateway 通了。第二步设置 home channel/sethome如果成功会将当前私聊会话设置为默认投递目标。第三步测试普通模型回复你好用一句中文回复我如果 Hermes 回复中文说明微信 Gateway 正常 用户授权正常 模型调用正常 消息回传正常24. 为什么优先用私聊测试当前部署目标是微信个人聊天。普通微信群可能存在限制iLink bot 身份可能无法收到普通微信群消息Hermes 可能默认禁用 group messages群聊用户授权更复杂群聊容易误触发 API 调用所以先用微信私聊测试最稳。建议配置WEIXIN_DM_POLICYpairing WEIXIN_GROUP_POLICYdisabled含义配置含义WEIXIN_DM_POLICYpairing私聊使用配对授权WEIXIN_GROUP_POLICYdisabled禁用群聊25. 重新运行 gateway setup如果微信配置缺失可以重新运行dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent gateway setup命令解释gateway setup进入消息平台配置向导。可以重新选择Weixin / WeChat并完成扫码登录、授权策略设置。26. 查看 Hermes 数据目录中的微信配置可以执行grep-RWEIXIN\|weixin\|wechat-n/root/.hermes|head-80命令解释grep-R递归搜索目录。WEIXIN\|weixin\|wechat搜索微信相关关键字。-n显示行号。/root/.hermes搜索 Hermes 数据目录。head-80只显示前 80 行避免输出太多。用途检查是否存在Weixin 配置account_idallowed usersdm policygroup policytoken / login state27. 当前阶段最终状态完成第 2 阶段后应该达到容器后台运行dockerps能看到hermes Up ...Gateway 日志正常dockercompose-f/root/compose.hermes.yml logs--tail100hermes能看到 Gateway started没有持续报错。微信 /status 有回复微信发送/status能收到回复。微信 /sethome 成功微信发送/sethome能成功设置 home channel。微信普通聊天可用微信发送你好Hermes 能调用模型并回复。28. 第 2 部分常用命令汇总启动 Hermes Gatewaydockercompose-f/root/compose.hermes.yml up-d查看容器dockerps--formattable {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}查看实时日志dockercompose-f/root/compose.hermes.yml logs-fhermes查看最近日志dockercompose-f/root/compose.hermes.yml logs--tail100hermes重启 Gatewaydockercompose-f/root/compose.hermes.yml restart hermes停止 Gatewaydockercompose-f/root/compose.hermes.yml down重新配置 Gatewaydockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent gateway setup查看 pairing 列表dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing list批准微信 pairingdockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin 配对码查看微信相关日志dockercompose-f/root/compose.hermes.yml logs--tail200hermes|grep-Eiweixin|wechat|pair|auth|error|account|login|poll|message29. 本阶段易踩坑汇总坑 1以为终端聊天能回复微信就一定能回复实际终端聊天只验证模型调用 微信聊天必须启动 gateway坑 2用临时 docker run 跑 gateway表现SSH 断开或 CtrlC 后微信收到 Gateway shutting down解决使用 Docker Compose 后台常驻dockercompose-f/root/compose.hermes.yml up-d坑 3配对码没批准表现Hi~ I dont recognize you yet! Heres your pairing code: ...解决dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin 配对码坑 4docker exec hermes hermes ...报错表现exec: hermes: executable file not found in $PATH原因容器内没有直接叫hermes的可执行命令。解决用新的临时容器执行 CLIdockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing list坑 5看日志时按 CtrlC 以为会停止服务如果运行的是dockercompose-f/root/compose.hermes.yml logs-fhermes按CtrlC只会退出日志查看不会停止后台服务。如果运行的是dockerrun-it--rm... gateway run按CtrlC会停止 gateway。坑 6微信 Unauthorized user表现Unauthorized user: xxxim.wechat说明微信消息到了但用户没授权。解决顺序pairing listpairing approve微信重新发/status必要时配置 allowlist重启 gateway第 3 部分将记录Hermes Agent 云服务器部署三面试题库、Cron 定时任务与故障排查会详细解释/root/.hermes/interview和/opt/data/interview的关系如何放入 txt / md 面试题文件为什么 Hermes 能读 txt但可能被安全审批拦截/approve、/deny、/stop怎么用为什么自然语言创建任务可能生成不存在的脚本Script not found: /opt/data/scripts/check_and_send.sh的原因/cron在微信里 Unknown command 的原因用 SSH 创建 cron 任务Deliver: local和Deliver: weixin:chat_id的区别cron 任务为什么创建成功但微信没收到Gateway is not running提示如何理解
服务器部署Hermes【超详细版本】（二）：微信 Weixin Gateway 与 Docker Compose 常驻运行
注服务器部署Hermes超详细指南由于过于详细所以分为三部分结尾有踩坑点说明。Hermes Agent 云服务器部署一基础环境、Docker 镜像、目录挂载与模型配置Hermes Agent 云服务器部署二微信 Weixin Gateway 与 Docker Compose 常驻运行Hermes Agent 云服务器部署三面试题库、Cron 定时任务与故障排查本笔记记录 Hermes Agent 从“终端聊天可用”到“微信私聊可用”的配置过程。重点包括Weixin Gateway、微信配对授权、Docker Compose 后台常驻、两个 SSH 窗口如何操作、常见错误排查。前提第 1 部分已经完成Docker 镜像nousresearch/hermes-agent:latest已成功拉取/root/.hermes数据目录已存在模型 API 已配置成功终端聊天界面已经可以正常回复1. 终端聊天能回复不代表微信能回复在 setup 完成后Hermes 可能进入终端聊天界面Welcome to Hermes Agent! Type your message or /help for commands.在这个界面输入你好如果 Hermes 能回复说明模型 provider 配置成功 API Key 可用 模型名称可用 Hermes Agent 本体可以调用模型但是这只能说明“本地终端聊天”没问题。微信聊天还需要另一个组件Hermes GatewayGateway 负责连接微信 / Telegram / Discord 等消息平台接收微信消息把消息转交给 Hermes Agent把 Agent 回复发回微信执行 cron 定时任务调度所以终端聊天可用 ≠ 微信聊天可用微信要正常回复必须启动gateway run2. 退出终端聊天界面如果当前还在终端聊天界面Welcome to Hermes Agent! Type your message or /help for commands.可以输入/exit或者按Ctrl C命令解释/exit是 Hermes 终端聊天界面的退出命令。Ctrl C是 Linux 终端中断当前前台程序的快捷键。注意如果当前运行的是chat按Ctrl C只是退出聊天如果当前运行的是gateway run按Ctrl C会停止微信网关3. 临时启动微信 Gateway最初可以用临时方式启动 gatewaydockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent gateway run命令解释dockerrun创建并运行一个新的容器。-it交互式运行适合在终端里实时查看输出。--rm容器退出后自动删除容器。-v/root/.hermes:/opt/data把宿主机/root/.hermes映射到容器内/opt/data。这保证临时容器也能读取同一套配置、API Key、微信登录状态和 cron 数据。-eTZAsia/Shanghai设置容器时区为北京时间。nousresearch/hermes-agent使用 Hermes Agent 镜像。gateway run启动 Hermes Gateway。临时启动方式的问题这种方式适合测试但不适合长期运行。原因SSH 断开gateway 可能停止 按 CtrlCgateway 会停止 容器是临时的没有固定名字 不方便 docker exec / logs / restart 管理当 gateway 停止时微信会收到类似消息⚠️ Gateway shutting down — Your current task will be interrupted.这不是 Hermes 崩溃而是你正在运行的 gateway 被停止了。4. 配置微信平台在 setup 或 gateway setup 中出现平台列表Select platforms to configure: [ ] 1. Telegram [ ] 2. Discord ... [ ] 12. WeCom (Enterprise WeChat) [ ] 13. WeCom Callback (Self-Built App) [ ] 14. Weixin / WeChat应选择14. Weixin / WeChat不要选12. WeCom 13. WeCom Callback区别说明选项含义Weixin / WeChat个人微信WeCom企业微信WeCom Callback企业微信自建应用回调当前目标是在个人微信里和 Hermes 聊天所以选择Weixin / WeChat5. 配置 direct messages 授权方式配置微信时出现How should direct messages be authorized? → Use DM pairing approval (recommended) Allow all direct messages Only allow listed user IDs Disable direct messages选择Use DM pairing approval (recommended)选项解释选项含义是否推荐Use DM pairing approval第一次私聊需要配对码批准推荐Allow all direct messages所有人都可以私聊调用 Agent不推荐Only allow listed user IDs只允许白名单用户推荐但需要手动配置Disable direct messages禁用私聊不适合当前场景当前选择 pairing approval 的原因既安全又方便第一次从微信发消息时Hermes 会给一个 pairing code。服务器端批准后该微信用户就能正常聊天。6. 微信收到 pairing code启动 gateway 后在微信里发送/status或你好如果用户未授权微信会收到类似Hi~ I dont recognize you yet! Heres your pairing code: NENVYLJQ Ask the bot owner to run: hermes pairing approve weixin NENVYLJQ这说明微信消息已经成功到达 Hermes Gateway 但当前微信用户还没有授权此时不是故障而是需要批准配对。7. 为什么 docker exec hermes hermes 会失败曾经尝试执行dockerexec-ithermes hermes pairing list结果报错OCI runtime exec failed: exec: hermes: executable file not found in $PATH原因docker run nousresearch/hermes-agent setup能正常运行是因为镜像内部有 entrypoint。当你执行dockerrun... nousresearch/hermes-agent setup实际上 Docker 会先运行镜像的 entrypoint再把setup交给 entrypoint 处理。但是dockerexec-ithermes hermes pairing list是在已经运行的容器里直接找一个叫hermes的可执行文件。这个可执行文件在容器内不一定存在于$PATH所以会失败。正确做法用新的临时容器执行 Hermes CLI 命令并挂载同一个数据目录dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin NENVYLJQ8. 批准微信配对当微信收到配对码NENVYLJQ在服务器执行dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin NENVYLJQ命令解释dockerrun-it--rm启动一个临时 Hermes CLI 容器执行完自动删除。-v/root/.hermes:/opt/data使用和 gateway 一样的数据目录。这很重要因为 pairing 信息保存在/root/.hermes中。nousresearch/hermes-agent pairing approve weixin NENVYLJQ执行 Hermes pairing approve 命令。参数解释参数含义pairing配对管理approve批准配对weixin平台是微信NENVYLJQ微信收到的配对码批准成功后在微信里重新发送/status如果有回复就说明授权成功。9. 查看 pairing 列表如果不确定配对码可以执行dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing list作用列出当前等待批准的配对请求。如果微信里显示的配对码和命令里显示的配对码有差异以服务器上pairing list显示的为准。10. /status 的作用微信私聊发送/status正常会返回 Hermes Gateway 状态。例如可能看到Agent Running: No Connected Platforms: weixin解释Agent Running: No不代表 Hermes 没启动。它通常表示当前没有正在执行中的 agent 任务如果你随后发送你好Hermes 能回复就说明服务正常。Connected Platforms: weixin说明微信平台已连接。11. /sethome 的作用微信授权成功后发送/sethome作用把当前微信会话设置为 Hermes 的 home channel。后续 cron 定时任务、主动推送、默认投递目标等可能会使用这个 home channel。执行成功后Hermes 可能会提示当前 home 设置为某个微信 chat_id例如o9cq80y9HMRyFHDRQ5NMyWk8cYccim.wechat这个 ID 后续创建 cron 任务时非常重要。比如 cron 投递到微信时可能需要weixin:o9cq80y9HMRyFHDRQ5NMyWk8cYccim.wechat12. 为什么需要 Docker Compose 常驻运行临时运行 gateway 的方式是dockerrun-it--rm... gateway run缺点终端关闭服务就停 CtrlC 服务就停 容器无固定名字 服务器重启后不会自动恢复 管理不方便因此需要 Docker Compose 后台常驻运行。目标是让 Hermes Gateway 作为后台服务运行容器名固定为 hermes 服务器重启后自动启动 可以 docker compose restart 可以 docker compose logs 查看日志13. 创建 Docker Compose 文件在服务器执行cd/rootcatcompose.hermes.ymlEOF services: hermes: image: nousresearch/hermes-agent:latest container_name: hermes restart: unless-stopped command: gateway run volumes: - /root/.hermes:/opt/data environment: - TZAsia/Shanghai mem_limit: 3500m cpus: 2.5 EOF命令解释cd/root切换到 root 用户主目录。将 compose 文件放在/root下方便管理。catcompose.hermes.ymlEOF ... EOF创建文件/root/compose.hermes.yml。这是 shell heredoc 写法用于把多行内容写入文件。compose 文件逐行解释services:定义 Docker Compose 管理的服务列表。hermes:定义一个服务名字叫hermes。image:nousresearch/hermes-agent:latest使用镜像nousresearch/hermes-agent:latestcontainer_name:hermes指定容器名称为hermes这样后续可以稳定使用dockerpsdockerlogs hermesdockercompose restart hermesrestart:unless-stopped设置重启策略。含义除非手动停止否则容器异常退出或服务器重启后会自动启动这是服务器长期运行服务常用配置。command:gateway run容器启动后执行gateway run即启动 Hermes Gateway。volumes:-/root/.hermes:/opt/data挂载数据目录。含义宿主机 /root/.hermes 映射到容器内 /opt/data这样配置、微信登录状态、cron、题库等数据不会因为容器删除而丢失。environment:-TZAsia/Shanghai设置时区为北京时间。mem_limit:3500m限制容器最多使用约 3.5GB 内存。服务器本身是 4G 内存加了 4G swap。限制 Hermes 容器内存是为了避免容器把整台机器内存吃满。cpus:2.5限制容器最多使用约 2.5 个 CPU 核心。服务器是 4 核给 Hermes 留 2.5 核避免它占满全部 CPU。14. 启动 Hermes Gateway 常驻容器执行dockercompose-f/root/compose.hermes.yml up-d命令解释dockercompose使用 Docker Compose v2。-f/root/compose.hermes.yml指定 compose 文件路径。up创建并启动服务。-d后台运行也叫 detached mode。如果成功会看到类似[] Running 2/2 ✔ Network root_default Created ✔ Container hermes Started这说明容器已经在后台启动。15. 查看容器是否运行执行dockerps--formattable {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}命令解释dockerps列出正在运行的容器。--formattable {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}按指定格式输出表格只显示关键信息。正常应该看到CONTAINER ID IMAGE STATUS NAMES 7bb1315ac9f6 nousresearch/hermes-agent:latest Up 12 seconds hermes其中NAMES hermes STATUS Up ...说明 Hermes Gateway 正在运行。16. 查看 Gateway 日志执行dockercompose-f/root/compose.hermes.yml logs-fhermes命令解释dockercompose-f/root/compose.hermes.yml logs查看 compose 服务日志。-ffollow持续跟踪日志输出。hermes只查看hermes这个服务的日志。正常启动时会看到类似Dropping root privileges Syncing bundled skills into ~/.hermes/skills/ ... Done: 0 new, 0 updated, 89 unchanged. 89 total bundled. ┌─────────────────────────────────────────────────────────┐ │ ⚕ Hermes Gateway Starting... │ ├─────────────────────────────────────────────────────────┤ │ Messaging platforms cron scheduler │ │ Press CtrlC to stop │ └─────────────────────────────────────────────────────────┘注意这个命令只是看日志。按Ctrl C只会退出日志查看不会停止后台容器。这是非常重要的一点。17. 两个 SSH 窗口如何使用当时使用了两个 SSH 窗口。第一个窗口用于看日志dockercompose-f/root/compose.hermes.yml logs-fhermes这个窗口可以观察微信是否收到消息用户是否 unauthorizedgateway 是否重启cron 是否执行agent 是否报错如果不想继续看日志可以按Ctrl C退出日志查看。这不会停止 Hermes 服务。第二个窗口用于执行管理命令例如dockerpsdockercompose-f/root/compose.hermes.yml restart hermesdockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin 配对码总结窗口用途第一个窗口看实时日志第二个窗口执行管理命令18.Gateway shutting down是什么微信曾收到⚠️ Gateway shutting down — Your current task will be interrupted.原因通常是因为执行了dockercompose-f/root/compose.hermes.yml restart hermes或者停止了临时 gatewayCtrl C解释这条消息表示当前 Gateway 正在关闭 正在执行的任务会被中断它不一定是错误。如果是你主动重启容器导致的这是正常现象。19. 常用 Compose 管理命令启动服务dockercompose-f/root/compose.hermes.yml up-d后台启动 Hermes Gateway。查看运行状态dockerps查看正在运行的容器。查看实时日志dockercompose-f/root/compose.hermes.yml logs-fhermes持续查看日志。查看最近 100 行日志dockercompose-f/root/compose.hermes.yml logs--tail100hermes适合排查问题不会一直阻塞终端。重启服务dockercompose-f/root/compose.hermes.yml restart hermes用于修改.env或配置后让服务重新加载。停止服务dockercompose-f/root/compose.hermes.yml down停止并删除 compose 创建的容器和网络。注意不会删除 /root/.hermes 数据目录再次启动服务dockercompose-f/root/compose.hermes.yml up-d20. 检查微信相关日志如果微信没有回复可以查看日志dockercompose-f/root/compose.hermes.yml logs--tail200hermes|grep-Eiweixin|wechat|pair|auth|error|account|login|poll|message命令解释dockercompose-f/root/compose.hermes.yml logs--tail200hermes查看最近 200 行 Hermes 日志。grep-Eiweixin|wechat|pair|auth|error|account|login|poll|message筛选包含关键字的日志。参数参数含义-E使用扩展正则-i忽略大小写关键字含义关键字说明weixin/wechat微信相关日志pair配对相关auth授权相关error错误account微信账号login登录poll轮询message消息21. Unauthorized user 日志日志中曾出现WARNING gateway.run: Unauthorized user: o9cq80y9HMRyFHDRQ5NMyWk8cYccim.wechat这说明微信消息已经到达 Gateway 但该微信用户没有被授权常见原因pairing code 没批准pairing 批准了但 gateway 没重启/没加载allowlist 没配置当前微信 chat_id 和批准的不是同一个处理思路优先处理 pairingdockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing list然后批准dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin 配对码如果仍然 unauthorized可以考虑配置 allowlist。22. allowlist 的作用日志里还出现过WARNING gateway.run: No user allowlists configured. All unauthorized users will be denied.意思是当前没有配置用户白名单 未授权用户会被拒绝如果 pairing 机制没有正确生效可以手动把自己的微信 ID 加入 Weixin allowlist。例如微信 ID 是o9cq80y9HMRyFHDRQ5NMyWk8cYccim.wechat可以编辑nano/root/.hermes/.env追加类似配置WEIXIN_ALLOWED_USERSo9cq80y9HMRyFHDRQ5NMyWk8cYccim.wechat然后重启 gatewaydockercompose-f/root/compose.hermes.yml restart hermes注意不同 Hermes 版本的 allowlist 环境变量名可能略有差异。如果设置后无效应查看官方文档或当前.env中已有的 Weixin 配置项。23. 微信普通聊天测试顺序授权成功后建议按这个顺序测试微信第一步测试状态命令/status如果有回复说明微信 Gateway 通了。第二步设置 home channel/sethome如果成功会将当前私聊会话设置为默认投递目标。第三步测试普通模型回复你好用一句中文回复我如果 Hermes 回复中文说明微信 Gateway 正常 用户授权正常 模型调用正常 消息回传正常24. 为什么优先用私聊测试当前部署目标是微信个人聊天。普通微信群可能存在限制iLink bot 身份可能无法收到普通微信群消息Hermes 可能默认禁用 group messages群聊用户授权更复杂群聊容易误触发 API 调用所以先用微信私聊测试最稳。建议配置WEIXIN_DM_POLICYpairing WEIXIN_GROUP_POLICYdisabled含义配置含义WEIXIN_DM_POLICYpairing私聊使用配对授权WEIXIN_GROUP_POLICYdisabled禁用群聊25. 重新运行 gateway setup如果微信配置缺失可以重新运行dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent gateway setup命令解释gateway setup进入消息平台配置向导。可以重新选择Weixin / WeChat并完成扫码登录、授权策略设置。26. 查看 Hermes 数据目录中的微信配置可以执行grep-RWEIXIN\|weixin\|wechat-n/root/.hermes|head-80命令解释grep-R递归搜索目录。WEIXIN\|weixin\|wechat搜索微信相关关键字。-n显示行号。/root/.hermes搜索 Hermes 数据目录。head-80只显示前 80 行避免输出太多。用途检查是否存在Weixin 配置account_idallowed usersdm policygroup policytoken / login state27. 当前阶段最终状态完成第 2 阶段后应该达到容器后台运行dockerps能看到hermes Up ...Gateway 日志正常dockercompose-f/root/compose.hermes.yml logs--tail100hermes能看到 Gateway started没有持续报错。微信 /status 有回复微信发送/status能收到回复。微信 /sethome 成功微信发送/sethome能成功设置 home channel。微信普通聊天可用微信发送你好Hermes 能调用模型并回复。28. 第 2 部分常用命令汇总启动 Hermes Gatewaydockercompose-f/root/compose.hermes.yml up-d查看容器dockerps--formattable {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}查看实时日志dockercompose-f/root/compose.hermes.yml logs-fhermes查看最近日志dockercompose-f/root/compose.hermes.yml logs--tail100hermes重启 Gatewaydockercompose-f/root/compose.hermes.yml restart hermes停止 Gatewaydockercompose-f/root/compose.hermes.yml down重新配置 Gatewaydockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent gateway setup查看 pairing 列表dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing list批准微信 pairingdockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin 配对码查看微信相关日志dockercompose-f/root/compose.hermes.yml logs--tail200hermes|grep-Eiweixin|wechat|pair|auth|error|account|login|poll|message29. 本阶段易踩坑汇总坑 1以为终端聊天能回复微信就一定能回复实际终端聊天只验证模型调用 微信聊天必须启动 gateway坑 2用临时 docker run 跑 gateway表现SSH 断开或 CtrlC 后微信收到 Gateway shutting down解决使用 Docker Compose 后台常驻dockercompose-f/root/compose.hermes.yml up-d坑 3配对码没批准表现Hi~ I dont recognize you yet! Heres your pairing code: ...解决dockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing approve weixin 配对码坑 4docker exec hermes hermes ...报错表现exec: hermes: executable file not found in $PATH原因容器内没有直接叫hermes的可执行命令。解决用新的临时容器执行 CLIdockerrun-it--rm\-v/root/.hermes:/opt/data\-eTZAsia/Shanghai\nousresearch/hermes-agent pairing list坑 5看日志时按 CtrlC 以为会停止服务如果运行的是dockercompose-f/root/compose.hermes.yml logs-fhermes按CtrlC只会退出日志查看不会停止后台服务。如果运行的是dockerrun-it--rm... gateway run按CtrlC会停止 gateway。坑 6微信 Unauthorized user表现Unauthorized user: xxxim.wechat说明微信消息到了但用户没授权。解决顺序pairing listpairing approve微信重新发/status必要时配置 allowlist重启 gateway第 3 部分将记录Hermes Agent 云服务器部署三面试题库、Cron 定时任务与故障排查会详细解释/root/.hermes/interview和/opt/data/interview的关系如何放入 txt / md 面试题文件为什么 Hermes 能读 txt但可能被安全审批拦截/approve、/deny、/stop怎么用为什么自然语言创建任务可能生成不存在的脚本Script not found: /opt/data/scripts/check_and_send.sh的原因/cron在微信里 Unknown command 的原因用 SSH 创建 cron 任务Deliver: local和Deliver: weixin:chat_id的区别cron 任务为什么创建成功但微信没收到Gateway is not running提示如何理解
