Telegram 私人机器人方便访问 VPS 上的代理，但网关已连接不代表指定的人能得到回复。本指南从全新 Hermes Agent 数据目录开始，只允许一个 Telegram 数字用户 ID，检查真实回答，并为操作者保留经验证的停止控制。它依据 NousResearch 的 v0.22.2 Docker 说明和Telegram 说明，于 2026 年 10 月 19 日核查。BIG CHANGE 没有为本指南运行 VPS、拉取镜像、创建机器人或调用模型。

关键变化

  • 变化是什么： 按摘要固定且核对版本的 Docker 镜像，加上专用的 /opt/data 挂载，可识别这一个网关的软件和状态。
  • 为什么重要： Telegram 数字 ID 白名单及真实私聊回复能确认指定账户是否可用网关。
  • 需要注意： 配对或全局授权可能扩大访问，无害提示不能限制代理工具。请检查授权、日志、重启及停止状态。

你须有权通过 SSH 管理一台 Linux VPS，有可用的 Docker Engine 和主机恢复访问、可通过 BotFather 创建机器人的 Telegram 账户，以及符合 Hermes 模型提供方条件的账户。核对主机架构与资源是否适合官方 amd64 或 arm64 镜像，并在向导前查看提供方当前的访问及计费条件。本指南假设 Docker 已可用，安装和防火墙变更依系统与服务商而定。主机须能出站连接 Telegram 及选定模型提供方。为 Hermes 状态保留私人目录并限制谁可读取：/opt/data 将保存凭据、会话和日志。Docker 手册把该挂载称为持久的权威数据来源。

1. 配置前固定镜像

通过 SSH 连接，以下命令保持在同一个 shell 中运行。stable 标签可能移动。拉取镜像、记录仓库摘要，并确认镜像自身报告的版本为 0.22.2。版本不同、摘要缺失、目录已有状态，或名为 hermes 的容器已存在时停止。继续前按实际版本更新说明，或取得有文档支持的匹配镜像。摘要固定实际运行的镜像，但自身不能证明发行版本。

Terminal
set -eu
docker info >/dev/null
docker container inspect hermes >/dev/null 2>&1 && { echo 'Container hermes already exists; stop here.'; exit 1; }
HERMES_DATA="$HOME/.hermes"
if [ -e "$HERMES_DATA" ]; then echo 'Hermes data path already exists; stop here.'; exit 1; fi
mkdir -m 700 "$HERMES_DATA"
docker pull nousresearch/hermes-agent:stable
docker image inspect nousresearch/hermes-agent:stable --format '{{json .RepoDigests}}'
IMAGE_REF="$(docker image inspect nousresearch/hermes-agent:stable --format '{{index .RepoDigests 0}}')"
if ! printf '%s\n' "$IMAGE_REF" | grep -Eq '^nousresearch/hermes-agent@sha256:[0-9a-f]{64}$'; then
  echo 'No valid repository digest; stop here.'; exit 1
fi
printf 'Pinned image: %s\n' "$IMAGE_REF"
VERSION_OUTPUT="$(docker run --rm "$IMAGE_REF" --version)"
printf 'Image version: %s\n' "$VERSION_OUTPUT"
if ! printf '%s\n' "$VERSION_OUTPUT" | grep -Eq '(^|[^0-9])v?0[.]22[.]2([^0-9]|$)'; then
  echo 'Image version is not 0.22.2; stop here.'; exit 1
fi

set -eu 会在 Docker 不可用、拉取或检查失败、版本命令失败时停止这一串 shell 操作。明确的摘要及版本检查也会拦下空摘要或其他版本。遇到这些结果不要继续配置。保留所记录的 nousresearch/hermes-agent@sha256:… 值。以下配置与网关均使用 IMAGE_REF，后续标签变化就不会悄悄替换这个容器。这些检查要在真实 VPS 上进行；本文没有已验证的镜像摘要。使用主机原生文件系统上的新专用目录，绝不要让两个网关容器同时使用同一数据目录。

2. 配置提供方和一名 Telegram 私聊发送者

使用已挂载目录运行Docker 配置向导。选择账户获准的模型路径，完成认证并检查生成的提供方及模型设置。访问与费用依账户而定；设置已保存并不证明模型请求成功。

Terminal
docker run -it --rm -v "$HERMES_DATA:/opt/data" "$IMAGE_REF" setup

在 Telegram 向 @BotFather 使用 /newbot 请求机器人，并保密其令牌。取得指定发送者的Telegram 数字用户 ID，例如采用Telegram 手册链接的 ID 检查方法；用户名不等于 ID。向导或 hermes gateway setup 可写入机器人令牌与白名单。手动配置时，将 TELEGRAM_BOT_TOKEN=<private token>和TELEGRAM_ALLOWED_USERS=<your numeric ID> 放入 $HERMES_DATA/.env，在容器内它对应 /opt/data/.env。不要把令牌放进命令、shell 历史、共享笔记或本文。

在 $HERMES_DATA/config.yaml (/opt/data/config.yaml，容器内路径）中，设置全局未授权私信行为：

YAML
unauthorized_dm_behavior: ignore

配置容器退出后，官方镜像可能已把 $HERMES_DATA 的所有者改成运行时 UID 10000。引导过程把 .env 限为模式 600，并将已有的 config.yaml 收紧为 640；在该次引导中初次创建的配置也可能需要相同收紧。普通 SSH 登录者因此可能无法打开文件。若向导没有设置所需键，获授权的主机管理员 可用 sudo 检查和编辑这两个准确文件，再恢复运行时所有权及私人权限。以 UID 10000 运行主机编辑器，可能无法穿过登录用户所有的 $HOME，所以命令使用主机管理员权限。在具有 sudo和vi 的主机上，先核对不含秘密的所有者及模式回读，再使用命令。UID 不同或文件缺失时不要继续，先解决主机具体访问问题。

Terminal
sudo stat -c '%u:%g %a %n' "$HERMES_DATA" "$HERMES_DATA/.env" "$HERMES_DATA/config.yaml"
# Expected: directory owner 10000 and mode 700; .env owner 10000 and mode 600.
# config.yaml should have owner 10000; its first-boot mode can vary.
sudo vi "$HERMES_DATA/.env"
sudo vi "$HERMES_DATA/config.yaml"
sudo chown 10000:10000 "$HERMES_DATA/.env" "$HERMES_DATA/config.yaml"
sudo chmod 700 "$HERMES_DATA"
sudo chmod 600 "$HERMES_DATA/.env"
sudo chmod 640 "$HERMES_DATA/config.yaml"
sudo stat -c '%u:%g %a %n' "$HERMES_DATA" "$HERMES_DATA/.env" "$HERMES_DATA/config.yaml"

最终的 stat 输出应显示两文件 UID/GID 均为 10000，目录模式为 700, .env 模式为 600和config.yaml 模式为 640；它显示元数据，不显示凭据。chown 只针对这两个文件，也包括编辑器生成的替换文件。若没有 sudo或vi，使用主机获准的管理流程，完成相同所有者与模式回读。不要把状态目录改成所有人可读，也不要为本步骤重映射容器用户。

编辑时保留向导的模型提供方设置。确保 Telegram 专属的 unauthorized_dm_behavior 覆盖没有设置 pair，全局的 GATEWAY_ALLOWED_USERS或GATEWAY_ALLOW_ALL_USERS 也没有给予更广访问。在 config.yaml 中，还须确保 gateway.allow_all_users 及顶层的 allow_all_users 都不为 true，且全局或 Telegram 白名单没有其他发送者。不要在白名单使用 *，不要加群组白名单，不要批准配对码。全新目录避免继承授权；已有数据时应停止并检查，不能覆盖。保持 BotFather 的群组隐私开启，不把机器人加入群组，也不设为群组管理员。网关访问手册将白名单与持久配对授权列为不同访问路径。安全手册说明 ignore 会静默丢弃未授权私信。

白名单控制谁能开始对话，不限制获授权代理能做什么。Hermes Telegram 会话默认带有终端工具；放行发送者前检查工具权限、Docker 挂载、提供方访问及主机政策。无害测试提示只是提示，不是权限限制。

3. 启动网关并检查首次回复

用已记录摘要启动一个命名容器。已发布的 Docker 命令包含可选的 -p 8642:8642 用于 API 访问；此处省略，因为 Telegram 私信不需要公开 API 或控制面板端口。镜像监督网关进程，Docker 的 unless-stopped 策略则管理 Docker 启动时的容器重启。挂载目录让配置和会话在容器重启后保留。

Terminal
docker run -d --name hermes --restart unless-stopped \
  -v "$HERMES_DATA:/opt/data" "$IMAGE_REF" gateway run
if ! {
  docker inspect hermes --format '{{.Image}} {{.State.Status}}' &&
  [ "$(docker inspect hermes --format '{{.State.Status}}')" = running ] &&
  docker logs --tail 50 hermes &&
  docker exec -u hermes hermes hermes pairing list
}; then
  echo 'State, logs or pairing check failed; stopping before any message.'
  docker stop hermes || true
  docker inspect hermes --format '{{.State.Status}}' || true
  exit 1
fi

确认容器为 running，检查日志中的 Telegram 连接及提供方错误，发送提示前查看配对列表。任何初始读取失败时，代码块会停止网关并打印状态；CLI 或授权结果不明不能算放行。继续调查前确认 exited，状态不明时不要发消息或重启。不应有其他获批发送者；发现后先停止网关并检查停止状态。docker exec 不能对已停止容器运行，而普通镜像入口可能恢复先前运行的网关。对于全新、默认 UID 的安装，下方离线检查只以 UID 10000 运行固定的 Hermes CLI，禁用网络且绕过网关启动。它改编自文档配对命令及入口，BIG CHANGE 未实测。只有已确认运行中网关 UID 和挂载数据所有者都是 10000 时才使用。所有权、UID、CLI 输出或授权状态不明，保持停止，解决后才能重启。

Terminal
if [ "$(docker exec -u hermes hermes id -u)" != 10000 ] || [ "$(stat -c %u "$HERMES_DATA")" != 10000 ]; then
  echo 'Runtime UID or data owner differs; stop for a host-specific repair.'; docker stop hermes; exit 1
fi
docker stop hermes
if [ "$(docker inspect hermes --format '{{.State.Status}}')" != exited ]; then
  echo 'Container is not exited; do not mount state in another container.'; exit 1
fi
docker run --rm --network none --user 10000:10000 \
  --entrypoint /opt/hermes/.venv/bin/hermes \
  -v "$HERMES_DATA:/opt/data" "$IMAGE_REF" pairing list
# For a listed unwanted Telegram user, read the exact numeric ID first:
printf 'Unwanted numeric Telegram user ID: '; IFS= read -r UNWANTED_ID
if ! printf '%s\n' "$UNWANTED_ID" | grep -Eq '^[0-9]+$'; then echo 'Invalid ID; leave gateway stopped.'; exit 1; fi
docker run --rm --network none --user 10000:10000 \
  --entrypoint /opt/hermes/.venv/bin/hermes \
  -v "$HERMES_DATA:/opt/data" "$IMAGE_REF" pairing revoke telegram "$UNWANTED_ID"
docker run --rm --network none --user 10000:10000 \
  --entrypoint /opt/hermes/.venv/bin/hermes \
  -v "$HERMES_DATA:/opt/data" "$IMAGE_REF" pairing list

确认最终列表不再有不需要的 ID。私下检查 $HERMES_DATA/.env和config.yaml 中其他平台及全局白名单、* 或全部允许设置，按文档配置路径撤除不需要的授权。所有访问路径检查前保持网关停止。移除白名单一项不会撤销独立配对或全局授权。完成回读后，docker start hermes 会有意恢复原容器；发消息前再检查日志及配对。

从获准账户打开与机器人的私人对话，发一个无害请求，例如“用简短问候回复”。确认聊天里有真实回答，并检查对应网关日志或会话记录。消息已发送、正在输入、状态显示或配置完成界面都不是回答。Telegram 的 /whoami 可显示当前消息范围，但不能证明主机授权。只保留不敏感的检查证据。

若机器人不答，先读取容器状态及 docker logs --tail 50 hermes。检查令牌、准确的数字 TELEGRAM_ALLOWED_USERS 值、模型提供方认证及用量资格、出站连接。轮次不明确时先看私聊及日志，再决定发下一条。文档所述冷启动可能丢掉待处理更新，去重也仅在有限内存范围内生效；此路径不保证恰好一次送达。

4. 检查重启、停止与恢复

首次轮次结束后重启同一容器，检查新日志及保留的 /opt/data 状态，然后发送一个新的无害私聊提示并确认回复。停止容器，读取 Docker 状态。exited 才是停止信号，聊天安静并不算。docker start hermes 是稍后有意恢复的方法。

Terminal
docker restart hermes
docker logs --tail 50 hermes
docker inspect hermes --format '{{.State.Status}}'
# After the restarted gateway is ready, send a new private test message.
docker stop hermes
docker inspect hermes --format '{{.State.Status}}'
# Expected after stop: exited
# When intentionally resuming later: docker start hermes

重启失败时检查 Docker 状态及日志，再查看 $HERMES_DATA/logs/gateways/default/current和$HERMES_DATA/logs/container-boot.log、目录挂载、所有权及固定镜像与版本。v0.22.2 发行说明记载网关启动存活修复，不能证明你主机发生什么。不要删数据目录来修复。令牌泄漏时，停止网关、在 BotFather 撤销、私下替换挂载的 .env 中令牌，重启前再查访问。也要撤销不需要的配对授权，检查实际白名单。

VPS 托管与模型用量可能分别收费。核对实际套餐、限制及费用；没有承诺运行时间、免费模型额度或可用性目标。Telegram 及模型提供方会处理经过它们的消息，主机挂载目录保存本地秘密及会话状态。本检查只针对一台主机、一个机器人和首次回复。其他 BIG CHANGE 指南介绍Hermes 备份与恢复和Hermes 定期任务.

来源与延伸阅读

以下Docker 配置, Telegram 配置, 网关访问指南, 安全指南和v0.22.2 发行版均为 NousResearch 的第一方来源。快速入门解释模型提供方配置。这些链接说明操作方法，不是 BIG CHANGE 运行 VPS 或 Telegram 机器人的记录。