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 还是 VPS，hermas 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_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://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_URL=https://taotoken.net/api - HERMAS_BACKEND=docker 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_KEY=sk-你的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 a+r /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_KEY=sk-你的key TAOTOKEN_BASE_URL=https://taotoken.net/api HERMAS_MODEL=你的模型ID EOF chmod 600 .env # 4. 防火墙：只放 SSH，agent 端口不对外 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 --tail=50 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/api，Key 填 TaoToken 的 Key，Model 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 Key：https://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一看就知道哪里变了，比翻日志快得多。