当前位置：首页>Linux>从0开始配置 Hermes(Linux 版)

从0开始配置 Hermes(Linux 版)

2026-10-11 07:49:36

系列：第一季 · 第 2 篇

这篇解决什么

在 Linux 上从零安装 Hermes Agent，接上 DeepSeek，让它能真正帮你干活
不止 CLI —— 顺手把 Web 管理界面、tg bot 和飞书 bot 一起配通
所有步骤都在 Ubuntu 24.04 干净环境里真实跑过，命令和结果都贴出来了，你照着敲就行

最小前提

系统：Ubuntu 24.04（其他 Linux 主线命令不变，包管理器命令可能不同）
Shell：bash
网络：能访问 GitHub、pypi.org、api.deepseek.com
你需要准备：一个 DeepSeek API Key
本文主例子：DeepSeek（ deepseek-v4-pro，推理强度 xhigh）
本文扩展范围：Qwen / GLM / Kimi / MiniMax 等只做补充说明，不抢主线

只承诺在以上前提下可复现。文中所有命令都在 Docker Ubuntu 24.04 干净容器里从头跑过。

最终你会得到什么

hermes 命令可用， config.yaml 和 .env 就位
默认模型切到 DeepSeek，CLI 里能正常对话
本地 http://127.0.0.1:9119 打开 Web Dashboard
tg bot 在线，私聊能收到回复
飞书 bot 在线，WebSocket 直连无需公网 IP

1. 安装前检查

做什么

确认你的终端环境满足最小条件。

命令

whoami
cat /etc/os-release | head -4
curl --version | head -1
git --version

执行结果

neolabai@lab:~$ whoami
neolabai
neolabai@lab:~$ cat /etc/os-release | head -4
PRETTY_NAME="Ubuntu 24.04.4 LTS"
NAME="Ubuntu"
VERSION_ID="24.04"
VERSION="24.04.4 LTS (Noble Numbat)"
neolabai@lab:~$ curl --version | head -1
curl 8.5.0(x86_64-pc-linux-gnu)
neolabai@lab:~$ git --version
git version 2.43.0

成功标志 / 失败点

whoami 输出你的用户名
curl 和 git 都能输出版本号
如果 commandnotfound： sudo apt install-y curl git
Docker 最小镜像还需要 xz-utils（安装脚本解压 Node.js 用）： sudo apt install-y xz-utils
这一步没通过不要往下走

2. 安装 Hermes

做什么

用官方安装脚本安装 Hermes。加了 --skip-setup 把"安装"和"配置"拆开 —— 先保证装上了，再单独配 DeepSeek，排障路径更清晰。

命令

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s ----skip-setup

执行结果

关键输出行：

✓InstallationComplete!
📁Your files:
Config:/home/neolabai/.hermes/config.yaml
   API Keys:/home/neolabai/.hermes/.env
Code:/home/neolabai/.hermes/hermes-agent
⚡Reload your shell to use'hermes' command:
   source ~/.bashrc

成功标志 / 失败点

看到 InstallationComplete!
安装脚本内部会装 uv、Python 3.11、Node.js、pip 依赖，第一次可能几分钟
如果卡在网络下载，先确认能访问 GitHub raw 和 pypi
没成功不要重试超过 3 次，先看最后 30 行报错

3. 刷新 shell，验证 hermes 命令

做什么

重新加载 shell 配置，确认 hermes 命令真的可用。

命令

source ~/.bashrc
command -v hermes
hermes --version
hermes config path
hermes config env-path

执行结果

neolabai@lab:~$ source ~/.bashrc
neolabai@lab:~$ command -v hermes
/home/neolabai/.local/bin/hermes
neolabai@lab:~$ hermes --version
HermesAgent v0.13.0(2026.5.7)
Project:/home/neolabai/.hermes/hermes-agent
Python:3.11.15
OpenAI SDK:2.24.0
Up to date
neolabai@lab:~$ hermes config path
/home/neolabai/.hermes/config.yaml
neolabai@lab:~$ hermes config env-path
/home/neolabai/.hermes/.env

成功标志 / 失败点

command-v hermes 输出真实路径
hermes config path 和 hermes config env-path 都有输出
如果 commandnotfound，关掉终端重新打开再试
这一步没通过说明第 2 步安装没成功

4. 配置 DeepSeek

4.1 写入凭据

做什么

把 DeepSeek 的 Key 和 Base URL 写入 Hermes 的 .env。

命令

echo "DEEPSEEK_API_KEY=sk-你的真实key">>~/.hermes/.env
echo "DEEPSEEK_BASE_URL=https://api.deepseek.com/v1">>~/.hermes/.env
tail -2~/.hermes/.env

执行结果

neolabai@lab:~$ tail -2~/.hermes/.env
DEEPSEEK_API_KEY=sk-你的真实key
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1

4.2 切 provider 与模型

命令

hermes config set model.provider deepseek
hermes config set model.default deepseek-v4-pro

执行结果

neolabai@lab:~$ hermes config set model.provider deepseek
✓Set model.provider = deepseek
neolabai@lab:~$ hermes config set model.default deepseek-v4-pro
✓Set model.default= deepseek-v4-pro

4.3 ⚠️ 关键坑：清空全局 base_url

默认 config.yaml 里 model.base_url 写的是 https://openrouter.ai/api/v1，会覆盖.env 里的 DEEPSEEK_BASE_URL。不处理这一步，你的请求会被路由到 OpenRouter 而不是直达 DeepSeek，拿 DeepSeek 的 key 去 OpenRouter 当然鉴权失败。

命令

hermes config set model.base_url ''

执行结果

neolabai@lab:~$ hermes config set model.base_url ''
✓Set model.base_url =

成功标志 / 失败点

hermes doctor 不报 DeepSeek key 缺失
别忘了 model.base_url'' 这一步
sk-你的真实key 必须换成你自己的真 key

5. CLI 验收

做什么

进入 CLI 发一句测试话，确认不是"看起来装好了"，而是真的能聊。

命令

hermes chat -q "请用一句话介绍你自己"

执行结果

neolabai@lab:~$ hermes chat -q "请用一句话介绍你自己"
Query:请用一句话介绍你自己
╭─⚕Hermes───────────────────────────────────────────────────────╮
你好！我是HermesAgent，一个运行在Linux环境中的 CLI AI 助手，
拥有丰富的工具和技能生态，能帮你完成代码开发、系统运维、数据科学、
创意设计、智能体编排等各类任务。
╰──────────────────────────────────────────────────────────────────╯
Session:20260514_041801_29d686
Duration:3s

成功标志 / 失败点

不报 provider / key 缺失错误
模型返回完整的中文回答
如果鉴权失败，先检查 .env 里的 key 是否正确，再确认第 4.3 步 base_url'' 做了没有

6. 启动 Web Dashboard

做什么

Hermes 自带一个本地 Web 管理界面，默认 127.0.0.1:9119。在浏览器里可以管理配置、API Key、会话、日志。

命令

hermes dashboard --no-open &
sleep 3
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:9119

执行结果

neolabai@lab:~$ hermes dashboard --no-open &
neolabai@lab:~$ curl -s -o /dev/null-w "%{http_code}" http://127.0.0.1:9119
200

200 表示页面正常。在浏览器打开 http://127.0.0.1:9119 就能看到管理界面。

成功标志 / 失败点

curl 返回 200
默认只绑 127.0.0.1，仅本机可访问（这是安全设计，不是 bug）
如果端口被占用： hermes dashboard--port8080

7. 接入 tg bot

7.1 装依赖

Hermes 装好后 python-telegram-bot 默认不装，需要手动补：

uv pip install python-telegram-bot

7.2 写 tg bot 凭据

做什么

把 tg bot 的 token 和你的用户 ID 写入 .env。

获取 token：在 tg 里找 @BotFather， /newbot 创建 bot。获取你的数字 ID：在 tg 里找 @userinfobot。

命令

echo "TELEGRAM_BOT_TOKEN=123456789:AAF...">>~/.hermes/.env
echo "TELEGRAM_ALLOWED_USERS=你的数字ID">>~/.hermes/.env

7.3 启动 gateway

命令

hermes gateway

执行结果

关键输出：

StartingHermesGateway...
[Telegram]Connected to Telegram(polling mode)
✓ telegram connected
Gateway running with1 platform(s)

看到 ✓telegram connected 就说明 bot 上线了。现在在 tg 里给你的 bot 发一条私聊：

请用一句话介绍你自己

网关侧的日志确认收发了：

inbound message: platform=telegram user=Neo msg='请用一句话介绍你自己'
response ready: time=3.8s api_calls=1 response=77 chars
Sending response (77 chars) to 2052048288

成功标志 / 失败点

gateway 日志出现 ✓telegram connected
tg 私聊 bot 能收到回复
如果连接失败，先确认宿主机网络能访问 api.telegram.org（本文环境不需要代理）
一个 bot token 同时只能有一个活跃 gateway，不要多开

8. 模型平台扩展

Hermes 不只支持 DeepSeek，以下国内平台官方 provider 都已内置，换个 key 就能接：

Qwen（通义千问）： qwen-oauth 或阿里云 DashScope 两条路线
GLM（智谱）：provider zai，env 变量 GLM_API_KEY
Kimi（月之暗面）：provider kimi-coding
MiniMax：内置 provider
StepFun（阶跃星辰）：内置 provider
Xiaomi MiMo：内置 provider

本篇只深打 DeepSeek 一条主线。其他平台的接入步骤类似：拿到 key → 写 .env → hermes configsetmodel.provider xxx。

8.1 自定义 API 网关

如果你有自建的 OpenAI 兼容接口（本地 API 网关、Ollama、vLLM 等），Hermes 通过 custom provider 直接支持：

# .env 写入
echo "OPENAI_API_KEY=sk-xxx">>~/.hermes/.env
echo "OPENAI_BASE_URL=http://你的地址:端口/v1">>~/.hermes/.env
# 切 provider
hermes config set model.provider custom
hermes config set model.default 模型名

验证可用模型：

curl -s http://你的地址:端口/v1/models -H "Authorization: Bearer sk-xxx"

示例返回（本地 API 网关实测）：

gpt-5.5
gpt-5.4
gpt-5.4-mini
gpt-5.3-codex
gpt-image-1
gpt-image-2
...共9个模型

选好模型后：

hermes config set model.default gpt-5.4# 性价比之选
hermes config set agent.reasoning_effort xhigh # 推理强度

此模式适用于任何 OpenAI 兼容接口，无需依赖特定 provider 插件。

9. 微信与 QQ 接入指南

Hermes 支持接入微信和 QQ，都是国内用户最关心的平台。下面说清每条路的前置条件和操作步骤。

9.1 微信

微信接入走腾讯 iLink Bot API，通过扫码登录完成配对：

操作步骤：

hermes gateway setup

选择 Weixin → 终端显示二维码 → 手机微信扫码 → 确认登录

扫码成功后， account_id 和 token 自动存入 ~/.hermes/weixin/accounts/，之后启动 gateway 即可在线。

使用说明：

接入身份是 iLink bot 身份（如 xxx@im.bot），这意味着它是一个独立 bot 账号，不是把你的个人微信号变成机器人
DM 私聊是最稳定的使用路径
普通微信群的支持取决于 iLink 侧的事件投递能力，当前大部分部署以 DM 为主

9.2 QQ

QQ 接入走 官方 QQ Bot API (v2)：

操作步骤：

去 q.qq.com 注册应用，获取 App ID 和 App Secret
开启消息 Intent（C2C 私聊、群 @消息）
在 .env 写入： QQ_APP_ID=你的AppIDQQ_CLIENT_SECRET=你的AppSecretQQ_ALLOWED_USERS=你的用户OpenID
启动 gateway： hermes gateway

使用说明：

这是官方 Bot 路线，支持私聊、群聊 @、频道消息
需要 sandbox 测试或正式发布后才能对外使用
配置流程正规，比 tg 多一步应用注册

9.3 飞书

有官方 bot 路线，WebSocket 模式无需公网 IP。本文已完整验证 DM 收发：

[Feishu]Connectedin websocket mode (feishu)
✓ feishu connected

接入步骤：

去 open.feishu.cn 创建企业自建应用
在「添加应用能力」中开启 机器人
.env 写入凭据： FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx FEISHU_CONNECTION_MODE=websocket
启动 gateway，首次 DM 会返回配对码， hermes pairing approve feishu<code> 授权

应用权限配置（重要）：

在飞书开发者后台「权限管理」中，至少需要开通以下 scope：

{
"scopes":{
"tenant":[
"im:chat.access_event.bot_p2p_chat:read",
"im:chat.members:bot_access",
"im:message",
"im:message.group_at_msg:readonly",
"im:message.p2p_msg:readonly",
"im:message:readonly",
"im:message:send_as_bot",
"im:resource",
"im:chat:readonly",
"contact:contact.base:readonly",
"contact:user.employee_id:readonly",
"application:bot.menu:write"
],
"user":[
"im:chat.access_event.bot_p2p_chat:read",
"contact:contact.base:readonly"
]
}
}

这是本文验证通过的权限集，覆盖 DM 收发、群 @消息、资源上传。开通后需要提交审核并发布才能生效。

常见坑：

缺 im:chat:readonly 会导致 [99991672]Accessdenied，不影响 DM 但影响会话信息获取
权限变更后需重新「发布」应用
首次 DM 会触发配对流程， hermes pairing approve 后即可正常使用

9.4 分层推荐

面对国内读者，不同场景的推荐如下：

日常使用首选：

CLI（终端）：最快、最稳、零外部依赖。配好 DeepSeek 直接在终端里用，不需要任何消息平台。本文第 1-5 步走完就能干活
飞书 bot：有官方 bot 路线，接入正规，适合团队共享

也想有手机入口：

tg bot：功能最完整的主流消息入口，本文第 7 步已验证 DM 收发
微信 / QQ：国内覆盖面最广，接入步骤见上文 9.1 和 9.2

模型选择：

本文验证的是 deepseek-v4-pro，日常够用
DeepSeek 也提供 deepseek-reasoner（推理增强），可通过 hermes configsetmodel.default 切换
搭配 GPT 系列模型可获得最佳推理效果

一句话：国内用户优先 CLI + DeepSeek，零门槛先跑起来。需要手机端就上飞书或 tg。

10. 配置系统常驻服务

前面所有步骤都在终端前台跑的 —— 关掉终端 gateway 和 dashboard 就停了。生产环境需要配成 systemd 服务，开机自启、后台常驻。

⚠️ 本节需要真实 Linux 系统（非 Docker）。systemd 依赖宿主机 init 系统，Docker 容器无法验证。

10.1 Gateway 常驻服务

Hermes 自带一键安装：

sudo hermes gateway install --system --run-as-user $USER

这条命令会：

生成 systemd unit 文件
配置为系统级服务（开机自启）
以当前用户身份运行

装完后的日常操作：

sudo systemctl status hermes-gateway   # 查看状态
sudo systemctl restart hermes-gateway  # 重启
journalctl -u hermes-gateway -f        # 实时日志

10.2 Dashboard 常驻服务

Dashboard 没有自带 systemd 安装命令，手动创建一个 unit 文件：

sudo tee /etc/systemd/system/hermes-dashboard.service <<'EOF'
[Unit]
Description=HermesWebDashboard
After=network.target
[Service]
Type=simple
ExecStart=/home/YOUR_USER/.local/bin/hermes dashboard --no-open
Restart=on-failure
RestartSec=10
[Install]
WantedBy=default.target
EOF

把 YOUR_USER 替换成你的实际用户名。 --no-open 是因为服务没有图形界面，不需要弹浏览器。

启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable --now hermes-dashboard

验证：

curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:9119
# 返回 200 即正常

10.3 最终效果

配完后你的机器上会有两个常驻服务：

sudo systemctl status hermes-gateway hermes-dashboard --no-pager

hermes-gateway：tg + 飞书双平台在线
hermes-dashboard：Web 管理界面在 http://127.0.0.1:9119

两者都是开机自启、挂了自动重拉。

最终验收

如果你不想逐条对，只记下面这组：

source ~/.bashrc
command -v hermes
hermes config path
hermes config env-path
hermes doctor
hermes chat -q "你好"

通过标准

command-v hermes 有路径
hermes doctor 不报配置阻断
hermes chat-q 返回完整回答

总结

本文主线：在 Ubuntu 24.04 上从零安装 Hermes，用 DeepSeek v4-pro（推理 xhigh），跑通 CLI + Web Dashboard + tg bot + 飞书 bot 四个入口
关键坑： model.base_url 默认指向 OpenRouter，必须清掉才能直达 DeepSeek
国内用户推荐：优先用 CLI + DeepSeek，零门槛先跑起来；需要手机端就上飞书 bot（WebSocket 直连，无需公网 IP）或 tg bot
tg bot 搭配 GPT 系列模型可获得最佳效果

🧬 生物信息学 · 智能医学工程 · 医学影像学交流群
入群咨询：19.9 元（全系统支持，群内优先答疑）远程安装/配置：168 元/次（一对一远程，包教会）
加微信：neolabai加好友请备注：单位/学校 - 专业/方向 - 姓名/昵称

生物信息学、智能医学工程、医学影像学：你为什么需要一个 AI Agent？

本文来自网友投稿或网络内容，如有侵犯您的权益请联系我们删除，联系邮箱：596563534@qq.com 。

从0开始配置 Hermes(Linux 版)

这篇解决什么

最小前提

最终你会得到什么

1. 安装前检查

2. 安装 Hermes

3. 刷新 shell，验证 hermes 命令

4. 配置 DeepSeek

4.1 写入凭据

4.2 切 provider 与模型

4.3 ⚠️ 关键坑：清空全局 base_url

5. CLI 验收

6. 启动 Web Dashboard

7. 接入 tg bot

7.1 装依赖

7.2 写 tg bot 凭据

7.3 启动 gateway

8. 模型平台扩展

8.1 自定义 API 网关

9. 微信与 QQ 接入指南

9.1 微信

9.2 QQ

9.3 飞书

9.4 分层推荐

10. 配置系统常驻服务

10.1 Gateway 常驻服务

10.2 Dashboard 常驻服务

10.3 最终效果

最终验收

总结

最新文章

热门文章

随机文章

从0开始配置 Hermes(Linux 版)

这篇解决什么

最小前提

最终你会得到什么

1. 安装前检查

2. 安装 Hermes

3. 刷新 shell，验证 hermes 命令

4. 配置 DeepSeek

4.1 写入凭据

4.2 切 provider 与模型

4.3 ⚠️ 关键坑：清空全局 base_url

5. CLI 验收

6. 启动 Web Dashboard

7. 接入 tg bot

7.1 装依赖

7.2 写 tg bot 凭据

7.3 启动 gateway

8. 模型平台扩展

8.1 自定义 API 网关

9. 微信与 QQ 接入指南

9.1 微信

9.2 QQ

9.3 飞书

9.4 分层推荐

10. 配置系统常驻服务

10.1 Gateway 常驻服务

10.2 Dashboard 常驻服务

10.3 最终效果

最终验收

总结

Go程序部署到Linux:systemd守护进程配置

AI编程风向突变!Python不香了?国内技术团队正集体转向Rust和Go,性能飙升十倍

最新文章

热门文章

随机文章