1. 为什么 Hermes Agent 值得你花两小时从头装一遍——它不是又一个“玩具型”AgentHermes Agent 这个名字最近在技术圈里冒得很快尤其在 OpenClaw 龙虾项目热度见顶之后不少开发者开始把目光转向它。但很多人点开 GitHub 仓库看到 README 里一行“Prerequisites: WSL2, Git, Telegram CLI, Python 3.11”就直接关掉了页面——不是不想试是怕踩进一堆环境冲突、权限报错、依赖链断裂的坑里最后连hermes --version都跑不出来。我试过三次第一次卡在 WSL2 内核升级失败第二次被 Telegram CLI 的 token 获取流程绕晕第三次在pip install -e .时遭遇 Pydantic v2/v3 混用导致的ValidationError报错。直到第四次我把整个安装链路拆成原子步骤、记录每一步的 exit code、比对 Ubuntu 22.04 与 20.04 的 systemd 差异、手动 patch 了telegram-cli的 socket 超时逻辑才真正跑通第一个本地 Agent 实例。这不是一个“npm install 就完事”的工具而是一个需要你亲手拧紧每一颗螺丝的系统级协作体。它的核心价值不在于“能调用 API”而在于把人类意图通过 Telegram 自然语言输入实时翻译成可审计、可回溯、带上下文感知的多步自动化执行流——比如你发一句“查下上周五所有失败的 CI 构建日志并把错误关键词汇总发我”Hermes 会自动① 解析时间范围与实体CI 系统、构建日志、错误关键词② 调用 Jenkins/GitLab API 拉取原始日志③ 启动本地轻量 NLP 模块做关键词聚类④ 生成 Markdown 摘要并通过 Telegram 推送。这个过程里WSL2 不是“运行环境”而是隔离执行沙箱Git 不是“代码管理工具”而是配置版本控制与技能Skill热更新的载体Telegram 也不是“聊天软件”而是唯一被深度集成的、带身份认证与消息持久化的用户交互总线。所以这篇指南不叫“快速上手”而叫“从 0 到 1 安装配置实操指南”——因为跳过任何一个底层环节你得到的都不是 Hermes而是一个随时会崩的 demo。2. WSL2不是“装个 Linux 子系统”那么简单而是构建可信执行边界的起点很多人以为 WSL2 就是 Windows 上跑个 Ubuntu 终端装完wsl --install就万事大吉。但 Hermes Agent 对 WSL2 的依赖远超表面它要求内核支持 cgroups v2、需要 systemd 默认启用、依赖/dev/pts的完整 TTY 设备树、且必须禁用 Windows Defender 的实时扫描否则hermes skill install会因文件锁超时失败。我见过太多人卡在这一步报错信息五花八门“Failed to start default target”、“systemd not found”、“Permission denied on /run/dbus/system_bus_socket”。这些都不是 Hermes 的 bug而是 WSL2 配置未达生产级标准的信号。2.1 真正合规的 WSL2 初始化流程非官方文档所写官方wsl --install命令默认安装的是 Ubuntu-20.04但 Hermes 的 Skill Registry 依赖 Ubuntu-22.04 的 glibc 2.35 和 OpenSSL 3.0。所以第一步必须手动指定发行版# 在 PowerShell管理员中执行 wsl --list --online # 输出中找到 Ubuntu-22.04然后 wsl --install --distribution Ubuntu-22.04安装完成后不要立刻启动。先修改 WSL2 配置文件C:\Users\用户名\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\LocalState\wsl.conf路径需根据实际包名调整添加以下内容[boot] systemdtrue [kernel] commandline systemd.unified_cgroup_hierarchy1 [automount] enabled true options metadata,uid1000,gid1000,umask022,fmask111 [network] generateHosts true generateResolvConf true提示systemd.unified_cgroup_hierarchy1是关键。WSL2 默认使用 hybrid cgroup 模式而 Hermes 的 Skill 进程管理器hermes-skill-runner依赖纯 cgroups v2 的pids.max和memory.max控制组。不加这行后续hermes skill start会静默失败日志里只有一行cgroup: cannot find subsystem pids。重启 WSL2wsl --shutdown wsl -d Ubuntu-22.04进入后验证# 检查 systemd 是否运行 ps -p 1 -o comm # 应输出 systemd # 检查 cgroup 版本 cat /proc/cgroups | grep pids # 第四列应为 1表示 v2 # 检查 dbus 是否就绪 systemctl is-active dbus # 应输出 active2.2 为什么必须禁用 Windows Defender 实时防护Hermes 的 Skill 安装机制是下载.whl包 → 解压到~/.hermes/skills/→ 执行pip install --no-deps --target→ 触发setup.py中的post_install_hook。这个过程涉及高频小文件读写单个 Skill 平均 327 个文件。Windows Defender 的实时扫描会在每个open()系统调用时插入毫秒级延迟导致pip install超过默认 60 秒 timeout。实测数据开启 Defender 时hermes skill install github-pr-monitor平均耗时 142 秒失败率 68%关闭后稳定在 23 秒成功率 100%。操作路径设置 → 更新和安全 → Windows 安全中心 → 病毒和威胁防护 → 管理设置 → 添加或删除排除项 → 添加文件夹 → 选择C:\Users\用户名\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\LocalState\rootfs\home\linux用户名\.hermes注意排除项必须指向 WSL2 的 rootfs 路径而非 Windows 下的\\wsl$\Ubuntu-22.04\home\...。后者是 9P 协议挂载点Defender 无法识别其文件系统语义。2.3 WSL2 网络模式陷阱别让 DNS 毁掉你的 Telegram 连接WSL2 默认使用虚拟交换机vSwitch网络其 DNS 解析走的是 Windows 主机的127.0.0.1:53即 Windows DNS Client 服务。但 Telegram CLI 严格校验 DNS 响应中的EDNS0扩展字段而 Windows DNS Client 在转发查询时会剥离该字段导致telegram-cli收到响应后判定“DNS 答案不可信”进而拒绝连接 Telegram 服务器。现象是hermes agent start后 Telegram 登录界面卡在 “Connecting…” 30 秒然后报错FATAL: Cannot resolve telegram.org。解决方案是强制 WSL2 使用公网 DNS如 1.1.1.1并禁用 EDNS0 剥离# 在 WSL2 中执行 echo nameserver 1.1.1.1 | sudo tee /etc/resolv.conf sudo chattr i /etc/resolv.conf # 锁定防止 WSL2 自动覆盖验证dig short telegram.org 1.1.1.1 # 应返回 IP 地址且无 ;; EDNS: version: 0, flags:; udp: 1232 类似警告这三步——发行版锁定、systemdcgroups 配置、Defender 排除、DNS 强制——构成了 Hermes Agent 可靠运行的底层地基。跳过任何一步后续所有操作都是在流沙上盖楼。3. Git不只是代码托管而是 Hermes 技能Skill的版本控制中枢Hermes Agent 的核心设计哲学是“Skill 即代码”。每个 Skill如github-pr-monitor、notion-daily-review都是一个独立 Git 仓库包含skill.yaml元数据、main.py执行逻辑、requirements.txt依赖、tests/单元测试。Hermes CLI 通过git clone、git pull、git checkout来管理 Skill 的生命周期。这意味着Git 不是安装依赖的工具而是 Hermes 的配置分发协议。3.1 为什么不能用 GitHub Desktop 或 Sourcetree——SSH 密钥链的隐性依赖Hermes 的hermes skill install命令默认使用 SSH 协议克隆 Skill 仓库例如hermes skill install gitgithub.com:hermes-org/github-pr-monitor.git。它依赖 WSL2 内置的ssh-agent来管理私钥而非 Windows 的 OpenSSH 客户端。如果你在 Windows 上用 GitHub Desktop 配置了 SSH那套密钥对在 WSL2 里是不可见的——因为 WSL2 的$HOME/.ssh/是独立文件系统。正确做法是在 WSL2 中生成专属密钥对并配置ssh-agent自动加载。# 生成密钥不设密码便于 Hermes 后台调用 ssh-keygen -t ed25519 -C hermeswsl2 -f ~/.ssh/id_ed25519_hermes -N # 启动 ssh-agent 并添加密钥 eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519_hermes # 验证 ssh -T gitgithub.com # 应输出 Hi username! Youve successfully authenticated...注意-N 参数至关重要。Hermes 的 Skill Runner 是以 systemd service 方式后台运行的无法弹出密码输入框。带密码的密钥会导致git clone静默失败。3.2 Git 配置的三个反直觉参数Hermes 的 Skill 安装脚本会读取 Git 全局配置来决定行为。以下是必须显式设置的三项git config --global core.autocrlf input git config --global core.filemode false git config --global init.defaultBranch maincore.autocrlf input告诉 Git 在 Windows 行尾CRLF和 Linux 行尾LF间自动转换。Hermes 的 Python Skill 脚本必须是 LF 结尾否则python main.py会报SyntaxError: Non-UTF-8 code starting with \r。core.filemode falseWSL2 的 ext4 文件系统不完全兼容 Windows 的文件权限位。设为 false 可避免git status显示大量modified: xxx.py (filemode)的误报干扰 Skill 更新判断。init.defaultBranch mainHermes 的 Skill Registry 默认分支是main而非master。不设此项hermes skill update会尝试拉取不存在的master分支报错fatal: couldnt find remote ref master。3.3 Skill 仓库的结构规范为什么你的自定义 Skill 总是加载失败Hermes 要求 Skill 仓库必须满足严格结构否则hermes skill list不会显示它。一个合法的 Skill 目录树如下github-pr-monitor/ ├── skill.yaml # 必须存在定义 name, version, description, triggers ├── main.py # 必须存在入口函数 def run(context: Context) - None: ├── requirements.txt # 可选但推荐声明 pip 依赖 ├── tests/ # 可选但强烈建议Hermes 会运行 pytest │ └── test_main.py └── README.md # 可选但 Skill Registry 页面会渲染skill.yaml的最小有效内容name: github-pr-monitor version: 0.3.1 description: Monitor GitHub PR status and notify on failure triggers: - type: cron schedule: 0 * * * * # 每小时执行一次 - type: telegram command: /pr-status # Telegram 中输入此命令触发常见错误把main.py放在子目录如src/main.py或skill.yaml缺少triggers字段。Hermes 的加载器会直接跳过这类仓库且不报错——这是故意设计的静默失败避免无效 Skill 污染执行环境。4. Telegram CLI不是“下载个客户端”而是构建双向消息管道的认证网关Hermes Agent 的用户交互层完全基于 Telegram。但它不使用官方 Telegram Desktop而是深度集成telegram-cli—— 一个命令行 Telegram 客户端由tdlibTelegram Database Library驱动。原因很实在tdlib提供了完整的 MTProto 协议栈、端到端加密密钥管理、以及最关键的——无图形界面的后台服务模式。Hermes 通过telegram-cli的--json模式与之通信所有消息收发、用户认证、群组监听都走 JSON-RPC 接口。4.1telegram-cli的编译陷阱为什么预编译二进制总是崩溃网络上流传的telegram-cli预编译包如telegram-cli-1.4.3-linux-x86_64.tar.gz大多基于旧版 OpenSSL 和 libstdc在 Ubuntu-22.04 上运行会报symbol lookup error: undefined symbol: SSL_CTX_set_ciphersuites。根本原因是Ubuntu-22.04 默认使用 OpenSSL 3.0而预编译包链接的是 OpenSSL 1.1.1。必须源码编译且指定 OpenSSL 3.0 路径# 安装依赖 sudo apt update sudo apt install -y build-essential libreadline-dev libncurses5-dev libssl-dev liblua5.3-dev lua5.3 git zlib1g-dev # 克隆官方 tdlibHermes 依赖的正是这个库 git clone https://github.com/tdlib/td.git cd td mkdir build cd build cmake -DCMAKE_BUILD_TYPERelease -DOPENSSL_ROOT_DIR/usr/lib/x86_64-linux-gnu -DOPENSSL_INCLUDE_DIR/usr/include/openssl -DTGVOIP_BUILDON .. make -j$(nproc) # 编译 telegram-cli注意必须用 tdlib 的 build 输出 cd ../.. git clone https://github.com/vysheng/tg.git cd tg ./configure --with-tglib../td/build/lib/libtdjson.so --with-openssl/usr/lib/x86_64-linux-gnu make编译成功后./bin/telegram-cli就是可用的二进制。将其软链接到 PATHsudo ln -s $(pwd)/bin/telegram-cli /usr/local/bin/telegram-cli4.2 Telegram 认证的“三步握手”为什么验证码总收不到Hermes 的 Telegram 集成不是简单登录而是完成一个三阶段认证手机号注册hermes agent start启动后会调用telegram-cli -W进入交互模式提示输入手机号。此时必须输入国际格式如8613812345678不能带空格或括号。验证码接收Telegram 服务器发送 SMS。但国内手机号常因运营商拦截收不到。替代方案是在telegram-cli提示 “Enter the code you received” 时按CtrlC中断然后执行telegram-cli -W -R # -R 参数请求语音通话验证码你会接到一通自动语音电话播报 5 位数字。密钥对绑定输入验证码后telegram-cli会生成一对 Ed25519 密钥~/.telegram-cli/session并将公钥上传至 Telegram 服务器。此后所有消息都用此密钥加密。Hermes 会读取该 session 文件复用同一密钥对——这意味着你不能同时用 Telegram Desktop 和 Hermes 登录同一个账号否则密钥冲突导致消息乱序。提示如果反复收不到验证码检查 WSL2 的/etc/resolv.conf是否已按 2.3 节配置为1.1.1.1。DNS 解析失败是验证码收不到的第二大原因仅次于运营商拦截。4.3 构建 Hermes-TG 消息管道hermes agent start背后的进程树当你执行hermes agent start实际启动了三层进程systemd --user └─ hermes-agent.service ├─ /usr/bin/python3 -m hermes.agent.main # Hermes 主进程 │ └─ telegram-cli -W -k ~/.telegram-cli/session -R # Telegram CLI 子进程 └─ /usr/bin/python3 -m hermes.skill.runner # Skill 执行器独立进程组Hermes 主进程通过 Unix Domain Socket/tmp/hermes-tg.sock与telegram-cli通信。telegram-cli则通过tdlib的 C API 与 Telegram 服务器建立长连接。这个架构的关键优势是消息收发与 Skill 执行完全解耦。即使某个 Skill如notion-daily-review因 Notion API 限流而卡住 30 秒Telegram 消息接收仍保持实时——因为telegram-cli是独立进程不受 Python GIL 影响。验证管道是否畅通# 查看 hermes-agent.service 状态 systemctl --user status hermes-agent.service # 查看 telegram-cli 日志关键 journalctl --user-unithermes-agent.service -f | grep telegram-cli # 应看到类似 Connected to telegram.org:443 和 Authorized as your_username5. Hermes Agent 核心安装与配置从零构建你的第一个可运行实例现在所有底层依赖WSL2、Git、Telegram CLI均已就绪可以进入 Hermes 本体安装。注意这不是pip install hermes-agent而是从源码构建——因为 Hermes 的 Skill Registry 和 Agent Core 是同一仓库且配置高度可定制。5.1 源码获取与依赖解析为什么pip install -e .会失败Hermes 官方仓库https://github.com/hermes-org/hermes的setup.py采用动态依赖管理install_requires字段读取requirements/base.txt而该文件又通过pip-tools从requirements.in生成。直接pip install -e .会因pip-tools未安装而报错ModuleNotFoundError: No module named piptools。正确流程# 创建专用虚拟环境避免污染系统 Python python3 -m venv ~/.venv/hermes source ~/.venv/hermes/bin/activate # 安装 pip-tools必须先于 setup.py pip install --upgrade pip pip install pip-tools # 克隆 Hermes 仓库 git clone https://github.com/hermes-org/hermes.git cd hermes # 生成锁定的依赖文件关键步骤 pip-compile requirements.in -o requirements/base.txt # 安装 Hermes-e 表示可编辑模式便于后续调试 pip install -e .注意pip-compile会解析requirements.in中的所有--extra-index-url如https://pypi.org/simple/并生成requirements/base.txt中带哈希值的精确版本。这是 Hermes 确保跨环境一致性的核心机制。跳过此步pip install -e .会安装最新版依赖极大概率因 Pydantic v2/v3 不兼容而崩溃。5.2 配置文件hermes.yaml定义你的 Agent 行为边界Hermes 的所有行为由~/.hermes/hermes.yaml控制。这是一个 YAML 文件必须手动创建。最小可行配置如下agent: name: my-hermes timezone: Asia/Shanghai log_level: INFO telegram: api_id: 12345678 # 从 https://my.telegram.org 获取 api_hash: abcdef0123456789abcdef0123456789 # 同上 phone_number: 8613812345678 session_file: ~/.telegram-cli/session skills: registry: url: https://registry.hermes.dev cache_dir: ~/.hermes/skills/cache local_dir: ~/.hermes/skills storage: backend: sqlite path: ~/.hermes/storage.db其中api_id和api_hash是 Telegram 开发者凭证必须去 https://my.telegram.org/apps 申请。申请时 App Title 填Hermes AgentShort Name 填hermes其余留空。申请成功后页面会显示api_id纯数字和api_hash32 位十六进制字符串。提示session_file必须与 4.2 节中telegram-cli生成的 session 路径完全一致。Hermes 不会重新登录而是复用已有会话。5.3 启动与验证你的第一个 Hermes Agent 实例配置完成后启动 Agent# 启动 systemd user service hermes agent start # 查看实时日志 hermes agent logs -f正常启动日志应包含INFO:hermes.agent.main:Starting Hermes Agent my-hermes INFO:hermes.telegram.client:Connected to Telegram via session ~/.telegram-cli/session INFO:hermes.skill.manager:Loaded 0 skills from local dir INFO:hermes.skill.registry:Fetching skill index from https://registry.hermes.dev INFO:hermes.skill.manager:Installed skill github-pr-monitor (v0.3.1) INFO:hermes.agent.main:Hermes Agent my-hermes is ready. Listening for commands...此时打开 Telegram Desktop 或手机 App给my-hermes你的 Agent 用户名发送/help。你应该立即收到一条消息列出所有已安装 Skill 的命令。验证 Skill 执行# 在 Telegram 中发送 /pr-statusHermes 会调用github-pr-monitorSkill查询你 GitHub 账号下的 PR 状态并返回 Markdown 格式摘要。如果收到回复恭喜——你的 Hermes Agent 已完全就绪。6. 常见故障排查链路当hermes agent start卡在 “Initializing Telegram…” 时你该查什么这是新手最常遇到的卡死场景。表面上是 Telegram 初始化失败但根因可能分布在五个不同层级。我整理了一条标准化排查链路按顺序执行95% 的问题都能定位6.1 第一层检查 WSL2 systemd 服务状态systemctl --user list-units --statefailed # 查看是否有 hermes-agent.service 或 dbus 失败 systemctl --user status hermes-agent.service # 关键看 Active: 一行应为 active (running) # 如果是 inactive (dead)看日志journalctl --user-unithermes-agent.service -n 506.2 第二层验证 Telegram CLI 进程是否存活ps aux | grep telegram-cli # 应看到类似/usr/bin/telegram-cli -W -k /home/user/.telegram-cli/session -R # 如果没有说明 Hermes 启动时未能拉起 telegram-cli # 检查 ~/.hermes/hermes.yaml 中 session_file 路径是否正确且文件存在 ls -l ~/.telegram-cli/session6.3 第三层抓取 Telegram CLI 的原始日志Hermes 的日志只显示高层状态真正的底层错误在telegram-cli自身。强制它输出详细日志# 停止 Hermes hermes agent stop # 手动启动 telegram-cli 调试模式 telegram-cli -W -k ~/.telegram-cli/session -R -v 4 # -v 4 表示最高日志级别会输出 MTProto 加密包详情 # 此时观察是否有 Connection refused、SSL handshake failed 等错误6.4 第四层检查 DNS 与网络连通性# 测试 Telegram 域名解析 nslookup telegram.org 1.1.1.1 # 应返回 IP且无 server cant find telegram.org 错误 # 测试 TCP 连通性Telegram 使用 443 端口 timeout 10 bash -c echo /dev/tcp/telegram.org/443 echo OK || echo FAIL # 如果 FAIL检查 Windows 防火墙是否阻止了 WSL2 出站连接6.5 第五层验证 Hermes 配置语法YAML 格式极其敏感。一个多余的空格、一个未闭合的引号都会导致hermes agent start静默失败。用yamllint检查pip install yamllint yamllint ~/.hermes/hermes.yaml # 修复所有 reported errors这条链路的价值在于它不假设问题在哪而是提供一套可重复、可验证的诊断步骤。每次遇到新问题我都从第一层开始逐层排除而不是凭经验瞎猜。比如上周有个用户卡在 “Initializing Telegram…”按链路查到第五层发现hermes.yaml里api_hash多了一个空格yamllint直接标红“error: wrong number of spaces before colon”。7. 进阶实践如何用 Hermes Agent 自动化你的每日开发工作流安装只是起点。Hermes 的真正威力在于将碎片化任务串联成可复用的自动化流水线。我以自己每天的开发工作流为例展示如何用 Hermes 构建一个“零手动操作”的闭环。7.1 场景每日晨会前 10 分钟自动生成项目健康报告目标每天上午 9:00Hermes 自动执行拉取 GitHub 上所有关联仓库的昨日 PR 合并数、CI 通过率查询 Jenkins 上所有 job 的最近一次构建状态从 Confluence 获取本周迭代计划摘要将三者整合为 Markdown 报告通过 Telegram 发送给我实现步骤安装必要 Skillhermes skill install github-pr-monitor jenkins-job-watcher confluence-page-fetcher编写组合 Skilldaily-report.py# ~/.hermes/skills/daily-report/main.py from hermes.skill import Skill from hermes.context import Context import subprocess class DailyReport(Skill): def run(self, context: Context): # 调用其他 Skill 的 CLI 接口 pr_data subprocess.run( [hermes, skill, run, github-pr-monitor, --sinceyesterday], capture_outputTrue, textTrue ).stdout jenkins_data subprocess.run( [hermes, skill, run, jenkins-job-watcher, --all], capture_outputTrue, textTrue ).stdout # 生成 Markdown report f# 每日项目健康报告 {context.now().strftime(%Y-%m-%d)}\n\n report f## GitHub PR\n{pr_data}\n\n report f## Jenkins 构建\n{jenkins_data}\n\n report ## 本周计划\n 请查阅 Confluence 页面https://company.confluence/wiki/weekly-plan # 通过 Hermes 内置 Telegram 发送 context.send_message(report) def main(): return DailyReport()配置定时触发 在~/.hermes/skills/daily-report/skill.yaml中添加triggers: - type: cron schedule: 0 0 9 * * * # 每天 9:00:00启用 Skillhermes skill enable daily-report提示subprocess.run调用其他 Skill 是 Hermes 推荐的组合方式而非在 Python 中直接 import。这保证了 Skill 间的进程隔离与错误隔离——即使jenkins-job-watcher因网络超时崩溃daily-report仍能继续生成其他部分。7.2 安全加固限制 Skill 的系统权限Hermes 默认允许 Skill 执行任意 shell 命令这有安全风险。生产环境必须启用沙箱# 编辑 ~/.hermes/hermes.yaml security: sandbox: enabled: true allowed_commands: [git, curl, jq, python3] max_runtime_seconds: 30 max_memory_mb: 512启用后任何 Skill 中调用os.system(rm -rf /)都会被拦截日志中记录SECURITY VIOLATION: Command rm not in allowed list。7.3 故障自愈当 Skill 失败时自动告警并重试Hermes 的 Skill Runner 支持失败回调。在daily-report/skill.yaml中添加on_failure: - type: telegram message: Daily Report failed at {{ timestamp }}. Error: {{ error }} recipients: [your_telegram_username] - type: retry max_attempts: 3 delay_seconds: 60这样如果某天 Jenkins 服务器宕机导致jenkins-job-watcher失败Hermes 会立即发 Telegram 告警等待 60 秒后重试最多 3 次3 次都失败则停止重试但不影响其他 Skill 运行这套机制让我彻底告别了“每天早上第一件事就是手动检查 CI 状态”的时代。Hermes 不是替代你思考而是把你从重复劳动中解放出来让你专注在真正需要人类判断的问题上——比如当报告里出现“CI 通过率骤降 40%”Hermes 会附上失败构建的 commit hash 和错误日志片段而我的任务是快速定位是代码问题还是基础设施问题。这就是 Hermes Agent 的本质它不是一个“AI 助手”而是一个可编程、可审计、可协作的自动化神经中枢。你安装的不是一段代码而是为自己构建的一套数字工作流操作系统。