树莓派 Hermes Agent 部署文档：Docker 环境下的完整落地指南与 TaoToken 接入

1. 树莓派跑 Hermes Agent 到底卡在哪Docker 部署的真实场景Hermes Agent 是一个可以常驻在本地设备上的智能体网关它能接微信、接命令行、接 Dashboard把大模型的对话能力落到你自己的硬件上。树莓派 8GB 版本是很多人手里的第一台“永远在线”的小主机功耗低、噪音小、24 小时开着也不心疼所以拿它来跑 Hermes Agent 是很自然的选择。但真到动手的时候问题会一个接一个冒出来镜像 3.8GB 拉不动、aarch64 架构下容器起不来、Dashboard 绑了 0.0.0.0 却打不开、容器里写的文件宿主机没权限、模型 API 端点默认指向海外服务导致请求超时。这篇内容就是把这些坑按顺序填平。我会从系统源配置讲到 Docker 安装再给出可以直接复制的 docker-compose 配置最后把 API 端点切到 TaoToken 完成统一 Key 接入并用日志和接口调用验证部署成功。适合手里有树莓派 4B/5、想跑一个本地 Agent 网关、又不想被网络和权限问题反复折腾的人。整个过程不需要你懂容器编排命令和配置文件我都会给全你照着改路径和 Key 就行。需要提前说明的是树莓派的内存和磁盘是硬约束。Hermes Agent 镜像约 3.8GB运行数据约 300MB建议至少留 10GB 可用空间。8GB 内存版本跑 gateway dashboard 两个容器是够的4GB 版本建议只跑 gatewayDashboard 用的时候再临时起。下面所有操作默认你在树莓派本机终端执行用户有 sudo 权限系统是 Raspberry Pi OS 或 Debian 13 (trixie) aarch64。2. 前置准备Docker 安装、镜像加速与 TaoToken Key 获取2.1 系统源换成国内镜像树莓派默认的 Debian 源在国内访问很慢先把/etc/apt/sources.list.d/debian.sources里的http://deb.debian.org换成清华镜像。一条命令搞定sudo sed -i s|http://deb.debian.org|https://mirrors.tuna.tsinghua.edu.cn|g /etc/apt/sources.list.d/debian.sources sudo apt update注意树莓派专属源archive.raspberrypi.com没有对应的国内镜像保留原地址即可不要一起替换否则apt update会报 404。2.2 安装 Docker 与 compose 插件用阿里云的 Docker CE 源手动安装比一键脚本更可控也不会因为网络问题中途断掉curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-ce.gpg echo deb [archarm64 signed-by/usr/share/keyrings/docker-ce.gpg] https://mirrors.aliyun.com/docker-ce/linux/debian trixie stable | sudo tee /etc/apt/sources.list.d/docker.list sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin装完后把当前用户加进 docker 组这样后面不用每条命令都加 sudosudo usermod -aG docker $USER newgrp docker sudo systemctl enable docker --nownewgrp docker让当前终端立即生效不然要重新登录一次。2.3 配置镜像加速创建/etc/docker/daemon.json加上国内可用的 registry mirror同时限制并发下载数避免树莓派网络被打满{ registry-mirrors: [ https://docker.1ms.run, https://docker.xuanyuan.me ], max-concurrent-downloads: 3 }重启生效sudo systemctl restart docker docker info | grep -A 3 Registry Mirrors如果docker info里能看到你配置的 mirror 地址说明加速生效了。2.4 获取 TaoToken API KeyHermes Agent 默认的模型端点指向海外服务在树莓派这种网络环境下请求经常超时。把端点改成 TaoToken 之后所有模型调用走同一个 Key、同一个 Base URL省去每个模型单独配 Key 的麻烦。打开https://taotoken.net/api-keys登录后创建一个 Key复制出来形如sk-xxxxxxxx。这个 Key 后面会写进环境变量不要直接提交到 git 仓库。TaoToken 的 API Base URL 是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions接口格式Hermes Agent 里配置OPENAI_BASE_URL指向它即可。提示Key 只在创建时完整显示一次建议先存到密码管理器里。如果怀疑泄露在控制台直接删除重建旧 Key 立即失效。3. 可复制配置docker-compose.yml 与环境变量3.1 目录结构先在用户目录下建好工作目录和数据目录mkdir -p ~/hermes-docker mkdir -p ~/.hermes~/.hermes是持久化目录容器里的/opt/data挂载到这里配置、会话、微信 Token 都存这儿容器重建数据不丢。3.2 docker-compose.yml 完整内容文件路径~/hermes-docker/docker-compose.ymlservices: gateway: image: nousresearch/hermes-agent:latest container_name: hermes restart: unless-stopped network_mode: host volumes: - ~/.hermes:/opt/data environment: - HERMES_UID${HERMES_UID:-1000} - HERMES_GID${HERMES_GID:-1000} - OPENAI_API_KEY${OPENAI_API_KEY} - OPENAI_BASE_URL${OPENAI_BASE_URL} - OPENAI_MODEL${OPENAI_MODEL} command: [gateway, run] dashboard: image: nousresearch/hermes-agent:latest container_name: hermes-dashboard restart: unless-stopped network_mode: host depends_on: - gateway volumes: - ~/.hermes:/opt/data environment: - HERMES_UID${HERMES_UID:-1000} - HERMES_GID${HERMES_GID:-1000} command: [dashboard, --host, 127.0.0.1, --no-open]这里有几个关键点。network_mode: host让容器直接用宿主机网络Dashboard 的 9119 端口和 gateway 的端口都不需要额外映射。Dashboard 的--host我写的是127.0.0.1只监听本机避免把管理界面暴露到局域网需要访问时用 SSH 隧道转发。3.3 .env 文件同目录下创建~/hermes-docker/.env把 Key 和端点写进去HERMES_UID1000 HERMES_GID1000 OPENAI_API_KEYsk-你的TaoToken密钥 OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_MODELclaude-sonnet-4-5HERMES_UID和HERMES_GID用id -u和id -g查一下当前用户的值填进去默认 1000 对大多数树莓派用户是对的。模型 ID 按你在 TaoToken 控制台看到的可用模型填这里以claude-sonnet-4-5为例。注意.env文件权限设成 600chmod 600 ~/hermes-docker/.env避免同机其他用户读到 Key。3.4 拉取镜像镜像约 3.8GB树莓派上拉取要几分钟到十几分钟取决于网络。用后台方式拉避免 SSH 断线中断docker pull nousresearch/hermes-agent:latest如果拉取过程中卡在某一层不动先确认daemon.json里的 mirror 生效再重试。拉完后docker images能看到镜像大小。3.5 启动容器cd ~/hermes-docker docker compose up -d docker compose psdocker compose ps里两个容器状态都是Up就说明起来了。如果 gateway 反复重启先看日志下一节会讲怎么排查。4. 验证请求日志检查与接口调用确认部署成功4.1 查看启动日志容器起来不等于服务正常先看 gateway 日志docker logs hermes --tail 50正常启动会看到类似gateway listening on ...和模型端点初始化的输出。如果看到401 Unauthorized说明 Key 不对或没读到如果看到connection refused或超时说明 Base URL 或网络有问题。Dashboard 日志docker logs hermes-dashboard --tail 50确认 9119 端口在监听ss -tlnp | grep 91194.2 直接调用模型接口验证 Key在树莓派上直接用 curl 打 TaoToken 的接口确认 Key 和端点本身是通的把问题范围缩小到 Hermes 配置之前curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复两个字正常}], max_tokens: 20 }返回 JSON 里choices[0].message.content有内容说明 Key 和端点没问题。如果这里就报 401先解决 Key 问题别急着调 Hermes。4.3 通过 Hermes 发一条测试消息gateway 起来后用内置的 CLI 发一条消息走完整链路docker exec -it hermes hermes gateway send --text 你好测试一下如果配置正确会返回模型生成的回复。这一步能通说明 Hermes 已经成功把请求转发到 TaoToken 并拿到结果。4.4 健康检查脚本写一个简单的健康检查脚本放到~/hermes-docker/healthcheck.sh#!/bin/bash set -e echo 容器状态 docker compose -f ~/hermes-docker/docker-compose.yml ps echo gateway 最近日志 docker logs hermes --tail 10 echo 端口监听 ss -tlnp | grep 9119 || echo 9119 未监听 echo API 连通性 curl -s -o /dev/null -w HTTP %{http_code}\n \ https://taotoken.net/api/v1/models \ -H Authorization: Bearer $(grep OPENAI_API_KEY ~/hermes-docker/.env | cut -d -f2)加执行权限后运行chmod x ~/hermes-docker/healthcheck.sh ~/hermes-docker/healthcheck.shHTTP 200表示 API 端点可达容器状态和端口都正常部署就算完成了。4.5 访问 DashboardDashboard 只监听 127.0.0.1从你的电脑通过 SSH 隧道转发ssh -L 9119:127.0.0.1:9119 你的用户名树莓派IP然后在本地浏览器打开http://127.0.0.1:9119。如果 Dashboard 绑定了 0.0.0.0需要在~/.hermes/config.yaml里配 basic_auth生成密码哈希docker exec hermes-dashboard python3 -c from plugins.dashboard_auth.basic import hash_password; print(hash_password(你的密码))把输出的哈希填进 config.yaml 的dashboard.basic_auth.password_hash。不过更推荐保持 127.0.0.1 SSH 隧道的方式少一层认证配置也更安全。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常见的报错。日志里出现401或invalid api key按顺序查三处.env里的OPENAI_API_KEY有没有多余空格或引号docker compose config看环境变量有没有正确注入容器里docker exec hermes env | grep OPENAI确认读到的值和你写的一致。如果 Key 是从控制台复制的注意别把前后空白带进去。5.2 local proxy failed这个报错通常出现在容器内请求外部 API 时。network_mode: host下容器直接用宿主机网络如果宿主机配了 HTTP_PROXY 之类的环境变量容器会继承导致请求被转发到不存在的代理。检查宿主机env | grep -i proxy如果有残留的代理变量在.env里显式清空HTTP_PROXY HTTPS_PROXY NO_PROXYlocalhost,127.0.0.1然后docker compose up -d重建容器。5.3 reading choices 相关报错日志里出现reading choices或cannot read property choices of undefined说明 Hermes 拿到了响应但结构不对。多半是 Base URL 写错了比如漏了/v1或者多写了路径。TaoToken 的 Base URL 是https://taotoken.net/apiHermes 内部会拼/v1/chat/completions你不需要在 Base URL 里再加/v1。用第 4.2 节的 curl 命令确认返回结构再对照.env里的OPENAI_BASE_URL。5.4 OAuth 相关报错如果日志里出现 OAuth 或 token refresh 失败说明 Hermes 在尝试用 OAuth 方式认证某个模型提供商。用 TaoToken 统一 Key 接入时不需要 OAuth检查~/.hermes/config.yaml里有没有残留的 OAuth provider 配置把对应的 provider 段删掉只保留走OPENAI_BASE_URL的配置。改完重启 gatewaydocker compose restart gateway5.5 权限错误容器里写文件报Permission denied是 UID/GID 不匹配。修复宿主机数据目录所有权sudo chown -R $USER:$USER ~/.hermes确认.env里HERMES_UID和HERMES_GID等于id -u和id -g的输出然后重建容器。5.6 镜像拉取卡住docker pull长时间停在某一层先docker info确认 mirror 生效再检查磁盘空间df -h。树莓派磁盘满了也会导致拉取失败。清理无用镜像docker image prune -a后再试。6. 把 Key 统一到 TaoToken长期编码与 Agent 场景的接入建议部署跑通之后日常使用中你可能会遇到模型切换的需求今天用这个模型写代码明天用那个模型处理长文本。如果每个模型都单独配 Key、单独改端点维护成本很高。TaoToken 的价值就在于把多个模型的调用统一到一个 Base URL 和一个 Key 上Hermes Agent 只需要改.env里的OPENAI_MODEL就能切换模型不用动其他配置。对于长期跑在树莓派上的 Agent 场景建议把 gateway 设成restart: unless-stopped这样树莓派重启后容器自动拉起。Dashboard 按需启动平时用 SSH 隧道访问。如果你打算把 Hermes 接到微信上做个人助手扫码获取 Token 的命令是docker exec -it hermes hermes gateway setup选择微信后终端会显示二维码扫码后 Token 自动写入~/.hermes下的配置gateway 自动生效不用重启。相关环境变量WEIXIN_ALLOWED_USERS控制允许交互的用户WEIXIN_DM_POLICY默认pairingWEIXIN_GROUP_POLICY默认disabled按需调整。如果你后面要接 Claude Code 或者做更复杂的 Agent 编排TaoToken 的 Coding Plan 提供了适合长期编码场景的额度方案可以在https://taotoken.net/coding-plan了解。模型对话调试用https://taotoken.net/models接入文档在https://taotoken.net/docKey 管理在https://taotoken.net/api-keys。把这几处收藏好后面换模型、加额度、查文档都不用再翻聊天记录。最后提醒一句树莓派上的.env和~/.hermes目录里存着 Key 和微信 Token定期备份~/.hermes到安全位置但别把.env一起提交到公开仓库。容器重建时数据不丢靠的就是这个持久化目录。