Deploy soothing-eagerness

Deploy and Host Hermes Agent with Railway

把 Hermes Agent 部署到 Railway 的一键模板。当前模板默认使用 Hermes Agent v0.21.3 / v2026.9.14，适合把 Hermes 作为长期在线的聊天机器人、Web Dashboard 或轻量工作台运行。

About Hosting Hermes Agent

这个模板使用 Dockerfile 从指定 Hermes Agent tag 构建镜像，在 Railway 上运行 gateway、Dashboard 代理和状态页。模板会把 /data/.hermes 作为 Hermes home，建议挂载 Railway Volume 到 /data，这样配置、会话、技能和工作区不会在重启后丢失。模型配置通过 Railway Variables 注入，支持自定义 OpenAI 兼容接口、OpenRouter、Anthropic 和 MiniMax。

核心能力：

• Railway 一键部署，使用 Dockerfile 构建 Hermes Agent。
• 持久化 /data/.hermes，重启后保留 Hermes 配置、会话和运行时数据。
• 内置 Web Dashboard 代理、登录页和状态页。
• 预构建 Hermes Web UI、TUI 和浏览器终端依赖，减少冷启动时的构建工作。
• 支持 QQ Bot、企业微信 WeCom、个人微信 WeChat/Weixin、Telegram、Discord、Slack 等 Hermes gateway 平台。

Why Deploy Hermes Agent on Railway?

Railway 适合托管这类需要长期在线、需要公网入口、又需要少量持久化数据的 agent 服务。使用本模板后，你不需要手动维护服务器、systemd、反向代理和 TLS。Railway 负责构建、部署、日志、域名、环境变量和 Volume，Hermes 负责模型调用、消息平台接入和 Dashboard 交互。

Common Use Cases

• 部署 QQ、微信、Telegram、Discord 或 Slack 上的长期在线 AI 助手。
• 给团队内部使用一个带登录保护的 Hermes Web Dashboard。
• 在 Railway 上测试自定义 OpenAI 兼容模型接口。
• 为个人自动化、消息转发、工具调用和轻量任务执行提供远程运行环境。
• 使用持久化 Volume 保留 Hermes 会话、技能和工作区。

Dependencies for Hermes Agent Hosting

模板会在镜像内安装 Hermes Agent、Python 运行环境、Node.js 构建依赖、Hermes Web UI、TUI 和浏览器终端静态资源。运行时主要依赖 Railway 的 Variables、公网域名和 Volume。

Deployment Dependencies

• Railway workspace 和一个 Railway service。
• GitHub 仓库访问权限，用于从 wsbjj/hermes-railway-template 构建。
• 一个模型 provider key，例如 OpenAI 兼容接口、OpenRouter、Anthropic 或 MiniMax。
• 至少一个消息平台凭据，或者开启 Dashboard-only 模式。
• 推荐挂载 Railway Volume 到 /data。

快速部署

1. 点击上方 Deploy on Railway。
2. 选择 workspace，创建项目。
3. 在 Railway Variables 里填入模型和消息平台变量。
4. 绑定持久化 Volume 到 /data。
5. 部署完成后打开 Railway 提供的公网域名。

Railway Variables 里不要给值加引号。直接填：

OPENAI_API_KEY=sk-xxx

不要填：

OPENAI_API_KEY="sk-xxx"

最小可用配置

下面是 QQ Bot + 自定义 OpenAI 兼容接口的最小配置。把 OPENAI_BASE_URL 换成你的接口地址，HERMES_MODEL 换成真实模型 ID。

HERMES_GIT_REF=v2026.9.14
HERMES_HOME=/data/.hermes
HOME=/data

HERMES_INFERENCE_PROVIDER=custom
HERMES_MODEL=your-model-id
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_API_KEY=your-api-key

QQ_APP_ID=your-qq-app-id
QQ_CLIENT_SECRET=your-qq-client-secret
QQ_ALLOWED_USERS=openid_a,openid_b

HERMES_DASHBOARD=1
HERMES_DASHBOARD_PROXY_PASSWORD=change-this-password

自定义接口如果只填裸域名，例如 https://cmdme.cn，入口脚本会自动归一化为 https://cmdme.cn/v1。

模型配置

自定义 OpenAI 兼容接口

推荐用于 GLM、自建转发服务、聚合 API 或其他 OpenAI-compatible endpoint。

HERMES_INFERENCE_PROVIDER=custom
HERMES_MODEL=glm-5.2
OPENAI_BASE_URL=https://cmdme.cn/v1
OPENAI_API_KEY=your-api-key

也可以使用 CUSTOM_BASE_URL 和 CUSTOM_API_KEY：

HERMES_INFERENCE_PROVIDER=custom
HERMES_MODEL=your-model-id
CUSTOM_BASE_URL=https://your-openai-compatible-endpoint/v1
CUSTOM_API_KEY=your-api-key

入口脚本会把自定义接口写入 /data/.hermes/config.yaml：

model:
  default: your-model-id
  provider: custom
  base_url: https://your-openai-compatible-endpoint/v1
  api_key: ${OPENAI_API_KEY}

密钥不会明文写入 config.yaml。

OpenRouter

HERMES_INFERENCE_PROVIDER=openrouter
HERMES_MODEL=openai/gpt-4.1-mini
OPENROUTER_API_KEY=your-openrouter-key

Anthropic

HERMES_INFERENCE_PROVIDER=anthropic
HERMES_MODEL=claude-sonnet-4-5
ANTHROPIC_API_KEY=your-anthropic-key

MiniMax 国际版

HERMES_INFERENCE_PROVIDER=minimax
HERMES_MODEL=MiniMax-M2.7
MINIMAX_API_KEY=your-minimax-key

MiniMax 中国区

HERMES_INFERENCE_PROVIDER=minimax-cn
HERMES_MODEL=MiniMax-M2.7
MINIMAX_CN_API_KEY=your-minimax-cn-key

消息平台配置

至少配置一个消息平台，或者开启 Dashboard-only 模式。

QQ Bot

QQ_APP_ID=your-qq-app-id
QQ_CLIENT_SECRET=your-qq-client-secret
QQ_ALLOWED_USERS=openid_a,openid_b

企业微信 WeCom

WECOM_BOT_ID=your-wecom-bot-id
WECOM_SECRET=your-wecom-secret
WECOM_ALLOWED_USERS=user_a,user_b

个人微信 WeChat / Weixin

Hermes 官方支持个人微信机器人。适配器名称是 Weixin，走腾讯 iLink Bot API，文档标题为 Weixin (WeChat)。这和公众号、企业微信不是同一套接口。

• 支持：个人微信 iLink 机器人私聊（扫码登录后给该 bot 发 DM）。
• 不支持：微信公众号、把普通微信号当 bot 进普通微信群。QR 登录连上的是 ...@im.bot 身份，通常不能像普通好友一样拉进群。
• 企业微信请用上面的 WeCom 配置。

Railway 上建议先在本地或 Dashboard 终端完成一次 hermes gateway setup，把得到的 account_id 和 token 写进 Variables。Volume 挂到 /data 后，登录态会保存在 /data/.hermes/weixin/accounts/。

WEIXIN_ACCOUNT_ID=your-weixin-account-id
WEIXIN_TOKEN=your-weixin-bot-token
WEIXIN_ALLOWED_USERS=user_id_a,user_id_b
WEIXIN_DM_POLICY=allowlist

也接受 WECHAT_* 别名，入口脚本会映射到 Hermes 的 WEIXIN_* 变量：

WECHAT_ACCOUNT_ID=your-weixin-account-id
WECHAT_TOKEN=your-weixin-bot-token
WECHAT_ALLOWED_USERS=user_id_a,user_id_b

Telegram

TELEGRAM_BOT_TOKEN=your-telegram-bot-token
TELEGRAM_ALLOWED_USERS=123456789,987654321

Discord

DISCORD_BOT_TOKEN=your-discord-bot-token
DISCORD_ALLOWED_USERS=123456789012345678

Slack

SLACK_BOT_TOKEN=xoxb-xxx
SLACK_APP_TOKEN=xapp-xxx
SLACK_ALLOWED_USERS=U12345678

Dashboard

默认建议开启 Dashboard，并设置登录密码：

HERMES_DASHBOARD=1
HERMES_DASHBOARD_PROXY_PASSWORD=change-this-password

部署后访问 Railway 域名会先进入模板自带登录页。登录后可以访问 Hermes Dashboard、状态页和内置终端。

如果只想运行 Dashboard，不接消息平台：

HERMES_DASHBOARD=1
HERMES_GATEWAY_ENABLED=false
HERMES_DASHBOARD_PROXY_PASSWORD=change-this-password

示例变量文件

• examples/railway.qq-custom.env: QQ Bot + 自定义 OpenAI 兼容接口。
• examples/railway.wecom-custom.env: 企业微信 WeCom + 自定义 OpenAI 兼容接口。
• examples/railway.wechat-custom.env: 个人微信 WeChat/Weixin + 自定义 OpenAI 兼容接口。
• examples/railway.weixin-custom.env: 与 WeChat 示例相同，使用 Hermes 官方 WEIXIN_* 变量名。
• examples/railway.qq-minimax.env: QQ Bot + MiniMax 国际版。
• examples/railway.qq-minimax-cn.env: QQ Bot + MiniMax 中国区。
• examples/railway.dev-dashboard.env: Dashboard 调试配置。

关键变量

Railway Volume

建议给服务挂载一个 Volume：

Mount Path: /data

这样 Hermes 的配置、会话、技能、缓存和工作区会持久化。没有 Volume 时服务仍能启动，但每次重新部署都会丢失运行态数据。

手动从 GitHub 部署

如果不使用模板按钮，也可以手动创建 Railway 服务：

Railway Dashboard -> New Project -> Deploy from GitHub repo -> wsbjj/hermes-railway-template

然后在 Variables 中填入上面的模型和平台配置。

常见问题

自定义接口返回 INVALID_API_KEY

先确认 Railway Variables 中的 key 没有引号。然后确认 OPENAI_BASE_URL 是 API base URL，例如：

OPENAI_BASE_URL=https://cmdme.cn/v1

最新入口脚本会把 model.api_key 写成 ${OPENAI_API_KEY}，用于避免 Hermes 对非官方自定义域名时找不到 key。

日志提示 run hermes model to configure (api_key)

重新部署最新模板。入口脚本会从 Railway Variables 同步 /data/.hermes/config.yaml 的 model 配置，并写入 env 引用形式的 api_key。

裸域名接口返回 HTML

如果模型日志里出现 HTML doctype，通常是 base URL 指向了网页入口。请使用 /v1 API 地址。裸域名会自动补 /v1，但带路径的地址需要你自己确认是 API endpoint。

Dashboard 打不开或跳登录

确认已设置：

HERMES_DASHBOARD=1
HERMES_DASHBOARD_PROXY_PASSWORD=change-this-password

未登录访问 /readyz、/terminal、Dashboard API 时会被重定向到登录页，这是预期行为。

没有配置消息平台

如果不想接 QQ/微信/Telegram 等平台，需要开启 Dashboard-only：

HERMES_DASHBOARD=1
HERMES_GATEWAY_ENABLED=false
HERMES_DASHBOARD_PROXY_PASSWORD=change-this-password

否则入口脚本会要求至少配置一个消息平台。

个人微信扫码登录

Hermes 的微信适配器需要 iLink 的 account_id 和 token。推荐两种方式：

1. 在本地运行 hermes gateway setup，选择 Weixin，用手机微信扫码，再把得到的 WEIXIN_ACCOUNT_ID 和 WEIXIN_TOKEN 填进 Railway Variables。
2. 先用 Dashboard-only 模式部署，打开状态页终端运行 hermes gateway setup，登录态会写到 /data/.hermes/weixin/accounts/。之后补上 WEIXIN_ACCOUNT_ID 并打开 gateway。

必须挂载 Volume 到 /data，否则扫码结果会在重新部署后丢失。同一个 WEIXIN_TOKEN 同时只能有一个 gateway 在线。

相关链接

• Hermes Agent: https://github.com/NousResearch/hermes-agent
• Hermes 文档: https://github.com/NousResearch/hermes-agent/tree/main/website/docs
• Railway 模板: https://railway.com/deploy/soothing-eagerness?utm_medium=integration&utm_source=template&utm_campaign=generic