1. 先想清楚hermas agent 部署选型到底在选什么hermas agent 是一个可以长期驻留、能执行命令、调用工具、接触文件系统的智能体运行时。它和那种跑完就退出的脚本工具最大的区别在于它需要持续在线、需要稳定的运行边界、需要能远程唤醒。所以当你搜索「hermas agent 部署选型」的时候真正要回答的不是「怎么装」而是「装在哪里后面最省事」。我见过太多人一上来就在自己笔记本上pip install跑通用了两周发现电脑一合盖 agent 就断了Telegram 消息收不到定时任务不执行最后还是要迁移到服务器。迁移本身不复杂但之前配的路径、挂载、环境变量、密钥全都要重来一遍。所以部署选型这件事越早想清楚越省钱省时间。hermas agent 官方支持多种 terminal backend包括 local、docker、ssh、daytona、modal、singularity。这个 backend 决定了 agent 的命令和工具调用到底在哪个环境里执行。换句话说backend 就是「agent 的手脚伸到哪里」的开关。你选 Docker它的手脚就在容器里你选 SSH它的手脚就在远程主机上你选 local它就直接在你当前系统里操作。围绕这个核心部署选型实际要权衡四件事是否需要长期在线、是否需要清晰的隔离边界、后续维护成本高不高、以及你是想短期试试还是准备长期用。这四个问题的答案不同最优方案就完全不同。本文聚焦 Docker 与 VPS 两种最主流的形态把 SSH 远程配置、资源占用、扩展性对比讲透并给出可复制的 Docker Compose 与 VPS 初始化脚本最后演示通过 TaoToken 统一 Key 接入 API 的完整验证步骤。适合读这篇的人已经决定要认真用 hermas agent但在「容器化」和「上服务器」之间犹豫或者已经跑起来但不确定当前方案能不能撑住长期使用。如果你只是想花十分钟看看它长什么样那本地跑一下就够了不用往下看。2. TaoToken 前置准备统一 Key 与 Base URL 怎么配不管最后选 Docker 还是 VPShermas agent 都需要调用大模型 API。这里我建议一开始就用 TaoToken 做统一接入层原因是它把多家模型的调用收敛成一个 Base URL 和一个 Key后面你换模型、加模型、做多 agent 分流都不用改 agent 本身的配置只改环境变量就行。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容的 base_url 使用。你需要先去控制台创建一个 API Key然后把它写进 hermas agent 的环境变量里。控制台地址是https://taotoken.net/console创建 Key 的页面在https://taotoken.net/api-keys。这里有个容易踩的坑很多人把 base_url 写成https://taotoken.net/api/v1结果请求 404。正确的做法是 base_url 只写到/api具体的/v1/chat/completions由 SDK 自己拼。如果你用的是 OpenAI 官方 SDK它会自动补/chat/completions所以 base_url 给https://taotoken.net/api就对了。模型 ID 方面TaoToken 支持多家主流模型你在控制台能看到当前可用的模型列表。hermas agent 的配置里一般有一个model字段填你想要的模型 ID 即可。如果你不确定填什么先用一个通用的对话模型验证链路跑通之后再换成更适合 agent 场景的模型。环境变量建议这样组织Docker 和 VPS 两种方案都能复用同一套export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export HERMAS_MODEL你的模型ID把这三个变量写进.env文件Docker Compose 可以直接env_file引用VPS 上可以用 systemd 的EnvironmentFile加载。这样你的密钥不会硬编码在代码或 compose 文件里后面换 Key 也只改一个地方。如果你还没决定用哪个模型可以先到模型对话页面手动发一条消息确认 Key 有效、余额正常、模型能返回内容。这一步花两分钟能省掉后面在 agent 里排查 401 的半小时。模型对话入口是https://taotoken.net/model-chat。对于准备长期跑 agent 的场景建议直接上 Coding Plan因为 agent 的调用频率通常比手动对话高得多按量计费在长期使用下不一定划算。Coding Plan 的入口在https://taotoken.net/coding-plan具体额度以页面展示为准。3. 可复制配置Docker Compose 与 VPS 初始化脚本这一节给两份可以直接复制粘贴的配置。Docker Compose 适合你有一台常开的机器可以是家里的迷你主机、NAS、或者云服务器VPS 初始化脚本适合你从零开一台云主机、想一次性把环境配好。先说 Docker Compose。核心思路是把 hermas agent 跑在容器里通过挂载卷持久化它的数据目录通过环境变量注入 TaoToken 的 Key 和 Base URL通过restart: unless-stopped保证它挂了能自动起来。version: 3.9 services: hermas-agent: image: hermas/agent:latest container_name: hermas-agent restart: unless-stopped env_file: - .env environment: - TAOTOKEN_BASE_URLhttps://taotoken.net/api - HERMAS_BACKENDdocker volumes: - ./data:/app/data - ./logs:/app/logs ports: - 127.0.0.1:8080:8080 logging: driver: json-file options: max-size: 10m max-file: 3几个关键点解释一下。env_file引用同目录的.env里面放TAOTOKEN_API_KEY和HERMAS_MODEL。volumes把./data挂到容器内/app/data这样容器重建数据不丢。ports只绑定127.0.0.1不暴露到公网需要远程访问就通过 SSH 隧道或者反向代理。logging限制日志大小避免长期运行把磁盘写满。对应的.env文件TAOTOKEN_API_KEYsk-你的key HERMAS_MODEL你的模型ID启动命令docker compose up -d docker compose logs -f hermas-agent再说 VPS 初始化脚本。假设你开了一台 Ubuntu 22.04 的云主机用 root 或 sudo 用户登录后把下面这段存成init-hermas.sh然后执行。脚本做了几件事更新系统、装 Docker、创建专用用户和目录、写.env、拉取镜像并启动。#!/usr/bin/env bash set -euo pipefail # 1. 基础依赖 apt-get update -y apt-get install -y ca-certificates curl gnupg ufw # 2. 安装 Docker install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ | gpg --dearmor -o /etc/apt/keyrings/docker.gpg chmod ar /etc/apt/keyrings/docker.gpg echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] \ https://download.docker.com/linux/ubuntu $(. /etc/os-release echo $VERSION_CODENAME) stable \ /etc/apt/sources.list.d/docker.list apt-get update -y apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 3. 目录与配置 mkdir -p /opt/hermas/{data,logs} cd /opt/hermas cat .env EOF TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api HERMAS_MODEL你的模型ID EOF chmod 600 .env # 4. 防火墙只放 SSHagent 端口不对外 ufw allow 22/tcp ufw --force enable # 5. 启动 docker compose up -d docker compose ps这个脚本跑完hermas agent 就在 VPS 上常驻了。SSH 远程配置方面如果你想让 hermas agent 通过 SSH backend 去操作另一台机器需要在 agent 的配置里指定目标主机的 host、user、key 路径。建议用专用密钥对不要复用你个人的登录密钥并且目标主机的authorized_keys里限制该密钥只能执行必要命令。资源占用上Docker 方案在同样负载下比 VPS 裸跑多一层容器开销但差异通常在几十 MB 内存量级对现代机器可以忽略。真正影响资源的是 agent 同时处理的任务数和模型调用的并发数这两个才是你调优时要盯的指标。4. 验证请求确认 hermas agent 真的连上了 TaoToken配置写完不代表链路通了。这一步用最小成本验证先绕过 agent直接用 curl 打 TaoToken 的接口确认 Key 和 Base URL 没问题再让 agent 发一条真实请求确认它读到了环境变量。第一步curl 验证curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $HERMAS_MODEL, messages: [{role: user, content: ping}], max_tokens: 16 }如果返回里有choices数组且content非空说明 Key、Base URL、模型 ID 三者都对。如果返回 401看下一节的排查。如果返回 404大概率是 base_url 多写了/v1。第二步在容器里验证环境变量是否注入成功docker compose exec hermas-agent env | grep -E TAOTOKEN|HERMAS你应该能看到TAOTOKEN_API_KEY、TAOTOKEN_BASE_URL、HERMAS_MODEL三个变量。如果看不到说明.env没被正确加载检查env_file路径和文件权限。第三步触发 agent 执行一个简单任务观察日志docker compose logs -f --tail50 hermas-agent正常情况你会看到 agent 发起模型调用、收到响应、执行工具调用的完整链路日志。如果日志里出现local proxy failed或者连接超时说明容器网络出不去检查宿主机的 DNS 和出站规则。VPS 方案验证方式一样只是把docker compose exec换成docker exec日志用docker logs。如果你用的是 systemd 直接跑非容器用journalctl -u hermas-agent -f看日志。验证通过的标准很简单agent 能收到你的指令、能调用模型、能把结果返回给你。这三步都通了部署就算落地了。后面再根据实际使用调并发、调超时、加监控。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。你在部署 hermas agent 接 TaoToken 的过程中大概率会遇到下面几类问题我按出现频率排序。401 Unauthorized。最常见的原因是 Key 没传进去或者传错了。先确认.env里TAOTOKEN_API_KEY没有多余空格和引号然后确认容器里env | grep TAOTOKEN能看到。如果 Key 是对的还报 401检查是不是用了过期的 Key去控制台重新生成一个。还有一种情况是 Key 有额度限制余额不足也会返回 401 或 403去控制台看下余额。local proxy failed。这个报错通常出现在容器网络配置有问题的时候。hermas agent 在容器里发起请求如果宿主机的 DNS 解析不了taotoken.net或者容器没配dns就会报这个。解决办法是在 compose 里加dns: - 223.5.5.5或者检查宿主机resolvectl status。另外如果你在容器里配了 HTTP_PROXY 之类的变量但代理不可用也会报这个把代理变量清掉即可。reading choices 相关报错。典型的是error reading choices: unexpected end of JSON input或者choices is empty。这通常意味着接口返回了非预期格式原因可能是 base_url 写错导致打到了别的端点或者模型 ID 不存在导致返回了错误结构。先 curl 验证一遍确认返回体里有choices。如果 curl 正常但 agent 报错检查 agent 配置里的base_url是不是被某处覆盖成了别的值。OAuth 相关报错。如果你用的是需要 OAuth 的模型接入方式报错可能是OAuth token expired或invalid_grant。TaoToken 的 Key 方式是静态 Bearer Token不涉及 OAuth 刷新所以如果你看到 OAuth 报错说明 agent 配置里还残留着旧的认证方式。检查配置文件里有没有auth_type: oauth之类的字段改成api_key并指向 TaoToken 的 Key。Codex auth.json 场景。如果你同时用 Codex 类工具它的auth.json里存的是 OpenAI 的凭证和 hermas agent 的配置是两套。不要混用。hermas agent 只需要TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL两个值不需要auth.json。如果你在 agent 日志里看到它在读auth.json说明配置指向了错误的认证文件检查 agent 的 provider 配置。CC Switch / Cline MCP 场景。如果你用 CC Switch 或 Cline 的 MCP 来管理多个模型接入记得三件套要写全Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填控制台里看到的模型 ID。少任何一个都会导致调用失败。MCP 配置里如果 Base URL 写成了别的中转地址也会报 401 或连接失败。排查的通用思路是先 curl 验证接口层再验证环境变量注入最后看 agent 日志。三层都过一遍问题基本能定位到具体哪一层。6. 长期使用建议与接入入口Docker 和 VPS 不是二选一的对立关系。实际生产里更常见的组合是VPS 提供常驻算力和公网入口Docker 提供隔离边界和可复现环境hermas agent 跑在 VPS 上的容器里。这样你既有 24/7 在线能力又有清晰的运行边界迁移和升级也方便。如果你还在犹豫我的建议是短期体验用本地想清楚要长期用就直接上 VPS Docker。中间那一步「先本地再迁移」往往是最费时间的因为配置要重来一遍。资源占用上一台 2 核 4G 的 VPS 跑单个 hermas agent 容器绰绰有余主要开销在模型调用的网络等待不在本地计算。扩展性方面Docker 方案的优势在于你可以用 compose 快速加第二个 agent 实例、加一个 Redis 做队列、加一个反向代理做入口都是改几行 YAML 的事。VPS 裸跑的话加服务要手动配 systemd 和端口长期维护成本更高。所以如果你预期后面会加功能、加实例Docker 的扩展性更友好。接入入口整理一下方便你按需跳转创建和管理 API Keyhttps://taotoken.net/api-keys接入文档和 Base URL 说明https://taotoken.net/doc验证模型是否可用https://taotoken.net/model-chat长期编码和 Agent 场景的套餐https://taotoken.net/coding-plan控制台总入口https://taotoken.net/console最后说一个我自己的经验hermas agent 这类工具部署选型做对之后后面 90% 的折腾都来自配置漂移——今天改个环境变量明天换个模型 ID后天动一下挂载路径久而久之就忘了当前跑的是什么配置。解决办法是把.env和docker-compose.yml都纳入版本管理Key 用占位符真实值放本地每次改动都提交一次。这样出问题的时候git diff一看就知道哪里变了比翻日志快得多。