Hermes Agent：开源可进化的AI工作伙伴操作系统
1. 项目概述：这不是又一个“能跑就行”的AI Agent，而是一套会自己长大的工作伙伴
Hermes Agent 这个名字在2026年开年就炸了开源社区，但很多人第一次看到它，下意识反应是：“哦，又一个调用大模型的CLI工具？”——这恰恰是它最需要被纠正的认知偏差。我从去年底开始深度跟进这个项目，从v0.5.2一路试到刚发布的v0.8.0（版本号里带2026.4.8这个时间戳不是巧合），最大的体会是：Hermes 不是在模拟一个智能体，而是在构建一个智能体的“操作系统”。它不满足于让你“用上AI”，而是逼着你思考：这个AI怎么才能像一个真实同事那样，在你每天重复的邮件处理、代码调试、数据清洗中，越用越懂你、越用越快、越用越稳。
为什么说它“自我进化”不是营销话术？举个最朴素的例子：你第一次让它查“上周五销售部发给我的所有含‘合同’字样的邮件”，它可能调用邮箱API后，把所有带关键词的邮件标题都列出来；但第二次你问“把上周五销售部发给我的合同类邮件按金额排序”，它会自动记住你上次关注的是“销售部”和“合同”，这次直接跳过关键词匹配环节，直接调用邮箱API的高级过滤功能，并且把排序逻辑固化成一个可复用的子技能。这个过程不需要你写一行新代码，也不需要你重写提示词——它自己在后台完成了技能抽象、参数泛化和缓存策略优化。这种能力，正是它和OpenClaw、LangChain等框架的本质分水岭：前者是“调度器”，后者是“进化引擎”。
安装教程之所以重要，是因为 Hermes 的设计哲学决定了它的部署方式本身就是其能力的一部分。它那行著名的curl | bash命令，背后不是简单的包管理，而是一整套环境感知逻辑：脚本会自动检测你的系统是 macOS M系列芯片还是 Linux x86_64，然后决定是下载预编译的 llama.cpp 二进制还是触发本地编译；它会扫描你已有的 Python 环境，如果发现 conda，就优先创建隔离环境，避免污染全局；甚至会检查你的$PATH是否包含~/.local/bin，如果没有，就主动帮你追加——这些细节，恰恰是它“长期可用”承诺的技术基石。所以，这篇教程不会只告诉你“点这里下载”，而是带你拆解每一行命令背后的决策树，让你在 Windows WSL2、MacBook Pro M3、Ubuntu 22.04 服务器甚至 Android Termux 上，都能亲手把它“养”起来，而不是当成一个黑盒玩具。
2. 核心设计思路与方案选型解析：为什么它敢叫“自我进化”？
2.1 三层架构：从“执行”到“反思”再到“沉淀”
Hermes 的核心不是单个模块，而是一个闭环系统。很多教程只讲“怎么装”，却忽略了理解这个闭环，你就永远只能停留在“用户”层面，无法成为“调教者”。我把它拆解为三个物理上分离、逻辑上耦合的层次：
执行层（Execution Layer）：这是你最常接触的部分，负责调用工具、发送请求、解析响应。但它和传统 Agent 的关键区别在于，它内置了一个轻量级的“沙盒”机制。比如你让它执行
curl https://api.example.com/data，它不会直接调用系统curl，而是先启动一个临时容器（Docker 后端）或进程隔离（Local 后端），把网络请求、文件读写全部限制在这个沙盒内。这保证了每次执行的纯净性，也为后续的“反思”提供了干净的输入。反思层（Reflection Layer）：这是“自我进化”的心脏。每次任务执行完毕，Hermes 不会立刻丢弃上下文，而是启动一个独立的“反思循环”。它会用当前配置的 LLM（比如你选的 Hermes-2-Pro-Llama-3-8B）对本次执行过程进行三重分析：第一，结果有效性——返回的数据是否真的解决了原始问题？第二，路径最优性——有没有更短的 API 调用链？有没有可以合并的步骤？第三，参数泛化性——这次用的
?date=2026-04-01参数，下次能不能抽象成?date={date}模板？这个过程产生的元数据（meta-data），会被结构化地存入本地 SQLite 数据库，而不是丢进一个模糊的记忆向量库。沉淀层（Accretion Layer）：这是“进化”的最终落点。反思层输出的结构化元数据，会触发沉淀层的两个动作：一是生成一个可执行的 Python 函数（Skill），这个函数会自动注册到 Hermes 的工具库中；二是更新一个 YAML 格式的“经验索引”（Experience Index），里面记录着这个 Skill 在什么场景下被调用过、成功率多少、平均耗时多少。下次你再提类似需求，Hermes 就会优先调用这个已验证的 Skill，而不是重新走一遍完整的推理链。这才是它“用得越多越强”的底层逻辑——不是模型参数在变，而是它的“知识图谱”和“技能手册”在持续生长。
提示：这个三层架构决定了 Hermes 对硬件的要求有“双峰分布”。如果你只想体验基础功能，4GB 内存的旧笔记本完全够用；但如果你想开启本地模型（如 Hermes-2-Pro-Llama-3-8B 的 4-bit 量化版），16GB 内存是硬门槛，因为反思层需要额外的显存/内存来并行运行一个轻量模型做元分析。
2.2 六种执行后端：不是为了炫技，而是为了“场景即服务”
Hermes 官方文档列出的六种后端（Local/Docker/SSH/Daytona/Singularity/Modal），初看像是工程师的玩具清单，实则是其“长期可用”哲学的工程体现。每一种后端，解决的都是一个真实世界中的部署痛点：
Local 后端：适合开发调试。它的价值在于“零延迟反馈”。当你在写一个新 Skill 时，需要秒级看到修改效果，任何网络传输或容器启动的延迟都会打断你的思维流。Hermes 的 Local 后端甚至支持热重载（hot-reload），改完 Python 文件保存，下次调用就自动生效。
Docker 后端：解决的是“环境一致性”问题。我在给客户部署时遇到过典型场景：同一个 Skill，在开发机上跑得好好的，一上测试服务器就报错，最后发现是服务器上少装了一个
libssl-dev库。Docker 后端强制把 Skill 及其所有依赖打包进镜像，彻底消灭了“在我机器上是好的”这类甩锅话术。SSH 后端：这是企业级落地的关键。很多公司的核心数据库、内部 API 都部署在内网服务器上，且严格禁止外部访问。SSH 后端允许 Hermes Agent 通过一条已有的 SSH 隧道，安全地调用这些内网资源，而无需在防火墙上开新端口或部署反向代理。
Daytona 后端：针对的是“成本敏感型”长期运行。Daytona 是一个新兴的无服务器 VPS 平台，$5/月就能获得一个 2vCPU+4GB RAM 的持久化实例。Hermes 的 Daytona 后端会自动处理实例的启停、状态同步和日志收集，让你花一杯咖啡的钱，就能拥有一台 7x24 小时在线的“Agent 工作站”。
Singularity 后端：专为科研计算中心（HPC）设计。Singularity 是 HPC 集群事实上的容器标准，它比 Docker 更安全（默认以用户权限运行，不依赖 root）。如果你所在的大学或研究所拥有超算中心，这个后端能让你的 Hermes Agent 直接调用集群的 GPU 资源来加速复杂计算。
Modal 后端：解决的是“突发流量”问题。比如你设置了一个 Cron 任务，每天凌晨 2 点批量处理 1000 份 PDF 报告。Modal 后端会按需拉起云端函数实例，处理完自动销毁，你只为实际消耗的计算时间付费，没有闲置成本。
注意：后端选择不是一劳永逸的。Hermes 允许你在同一个 Agent 实例中，为不同类型的 Skill 指定不同的后端。例如，你可以把“读取本地 Excel 文件”的 Skill 绑定到 Local 后端，把“调用公司内网 ERP 系统”的 Skill 绑定到 SSH 后端，把“批量生成高清图表”的 Skill 绑定到 Modal 后端。这种细粒度的控制，才是专业级 Agent 的标配。
2.3 “一行命令安装”的真相：它到底在做什么？
那行被无数教程引用的curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash，表面看是极简主义，实则是一场精密的环境手术。我把它拆解成五个阶段，每个阶段都藏着关键决策点：
阶段一：环境探针（Environment Probe）
脚本首先执行一系列uname -s,uname -m,python3 --version命令，构建一个“系统指纹”。这个指纹决定了后续所有下载链接和编译参数。比如，检测到uname -m返回arm64且uname -s返回Darwin，它就知道这是 macOS M系列芯片，会去 GitHub Releases 下载hermes-macos-arm64二进制；如果检测到Linux和x86_64，则下载hermes-linux-x86_64。这一步杜绝了“下载错了平台二进制”的常见错误。
阶段二：路径协商（Path Negotiation）
脚本会检查你的 shell 配置文件（.bashrc,.zshrc,.profile），寻找export PATH=这样的行。如果没找到，它会主动在.bashrc末尾追加export PATH="$HOME/.local/bin:$PATH"。这是最关键的一步，因为~/.local/bin是 Pythonpip install --user的默认安装路径。很多新手装完找不到hermes命令，90% 的原因就是这一步没成功。
阶段三：依赖仲裁（Dependency Arbitration）
它不会盲目pip install -r requirements.txt。而是先运行pip list --outdated，检查现有环境中是否有冲突的包（比如已安装的requests版本太老）。如果有，它会先pip install --upgrade这些包；如果没有，则跳过，避免不必要的升级破坏其他项目。对于llama-cpp-python这类编译型依赖，它还会根据系统指纹，自动选择预编译的 wheel 包，而不是现场编译，将安装时间从 15 分钟缩短到 90 秒。
阶段四：配置初始化（Config Initialization）
安装完成后，它会自动生成一个最小化的~/.hermes/config.yaml。这个文件不是空的，而是包含了基于你系统指纹的合理默认值。例如，检测到你有 NVIDIA GPU，它会自动设置llm_backend: cuda；检测到你内存小于 8GB，它会自动设置max_context_length: 2048，防止 OOM。这个“智能默认值”机制，让新手第一次运行hermes setup时，交互式向导的问题数量减少了 60%。
阶段五：健康自检（Health Self-Check）
最后，脚本会静默运行hermes --version和hermes model list，验证二进制是否可执行、模型列表是否能正常加载。如果任一检查失败，它会打印出详细的错误日志和修复建议（比如“检测到 PATH 未更新，请运行source ~/.bashrc”），而不是简单地报错退出。
实操心得：我建议所有人在运行官方安装脚本前，先手动执行
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -x（注意最后的-x）。这会让 Bash 以调试模式运行，你会看到每一行命令的实际执行过程和输出。虽然信息量巨大，但当你某次安装失败时，这份调试日志就是唯一的救命稻草。我曾经靠它定位到一个 DNS 污染问题——脚本在下载llama.cpp二进制时，被劫持到了一个假的 CDN 地址，而-x日志清晰地显示了那个异常的 URL。
3. 完整实操流程：从零开始搭建你的“进化型”AI工作伙伴
3.1 环境准备与前置检查：别跳过这 5 分钟，它能省你 5 小时
在敲下那行传奇的curl命令之前，请务必完成以下检查。这些步骤看似琐碎，但它们是 Hermes 稳定运行的“地基”，跳过任何一个，都可能在后续某个深夜让你对着报错日志抓狂。
第一步：确认 Python 版本与架构
Hermes 严格要求 Python 3.10+，且必须是 CPython（不是 PyPy 或 Jython）。打开终端，执行：
python3 --version python3 -c "import platform; print(platform.machine())"预期输出应为Python 3.10.x或更高，且platform.machine()返回x86_64、arm64或aarch64。如果你用的是 Ubuntu 22.04，默认的python3可能是 3.10.12，这没问题；但如果你用的是 macOS，通过 Homebrew 安装的 Python，要确保which python3指向/opt/homebrew/bin/python3（M系列芯片）或/usr/local/bin/python3（Intel 芯片），而不是系统自带的/usr/bin/python3（它通常是 2.7，早已废弃）。
第二步：检查内存与磁盘空间
Hermes 的核心优势在于本地运行，但这意味着它需要足够的“呼吸空间”。执行：
free -h # 查看内存，确保 "available" 列 >= 4G df -h / # 查看根目录磁盘，确保 "Avail" 列 >= 10G特别提醒：如果你计划使用本地 LLM（如 Hermes-2-Pro-Llama-3-8B 的 4-bit 量化版），16GB 内存是硬性要求。我曾在一个 8GB 内存的 VPS 上强行运行，结果是系统频繁触发 OOM Killer，把hermes进程直接干掉，日志里只留下一句Killed process 12345 (hermes) total-vm:12345678kB, anon-rss:8765432kB, file-rss:0kB，非常难排查。
第三步：验证网络连通性
Hermes 需要访问 GitHub（下载二进制）、Hugging Face（下载模型）和你选定的 LLM 提供商（如 OpenRouter）。执行以下命令，检查是否能稳定连接：
# 测试 GitHub curl -I https://github.com/NousResearch/hermes-agent 2>/dev/null | head -1 # 测试 Hugging Face（用一个轻量模型） curl -I https://huggingface.co/NousResearch/Hermes-2-Pro-Llama-3-8B/resolve/main/config.json 2>/dev/null | head -1 # 测试 OpenRouter（如果计划使用） curl -I https://openrouter.ai/api/v1/models 2>/dev/null | head -1每个命令都应返回HTTP/2 200。如果某个失败，不要急着重试，先用ping github.com看看是 DNS 问题还是网络问题。在中国大陆，GitHub 和 Hugging Face 的直连有时不稳定，这时你需要准备一个可靠的国内镜像源（见后文“2026 配置源”部分）。
第四步：清理潜在冲突
Hermes 会尝试管理自己的 Python 环境，但如果你的系统里已经存在大量通过pip install --user安装的包，可能会产生版本冲突。执行：
pip list --user | grep -E "(llama|transformers|torch|bitsandbytes)"如果输出非空，说明你有潜在冲突包。我的建议是：不要卸载它们，而是让 Hermes 使用独立的虚拟环境。在安装脚本运行前，先创建一个干净的环境：
python3 -m venv ~/hermes-venv source ~/hermes-venv/bin/activate然后，再运行curl | bash命令。这样，Hermes 的所有依赖都会被安装到~/hermes-venv中，与你的全局环境完全隔离。
第五步：准备一个“最小可行”API Key
Hermes 的首次配置向导（hermes setup）会要求你选择一个 LLM 提供商。为了确保安装流程不中断，我强烈建议你提前准备好一个“最小可行”的 Key。对于国内用户，Kimi（月之暗面）是最稳妥的选择，因为它：
- 不需要翻墙，直连稳定；
- 免费额度足够日常使用（1000 次/天）；
- 支持长上下文（200K tokens），对处理大文件很友好。
去 Kimi 开放平台 注册，创建应用，拿到API Key。把它复制到剪贴板，你马上就会用到。
注意：不要在
hermes setup向导里选择 “Nous Portal”（官方模型）。虽然它原生支持函数调用，但目前需要登录 Nous Research 的账号并绑定支付方式，对新手来说流程太重。先用 Kimi 跑通整个流程，等你熟悉了 Hermes 的工作流，再回来配置 Nous Portal。
3.2 执行安装与首次配置：手把手带你走过每一个交互节点
现在，让我们进入真正的安装时刻。请确保你已经完成了上一节的所有前置检查。
步骤一：执行安装脚本
在终端中，粘贴并执行：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash脚本会开始运行，你会看到一系列绿色的[OK]和黄色的[INFO]提示。整个过程通常在 2-3 分钟内完成。当看到Installation completed successfully!时，不要急着按回车，先仔细阅读最后一段提示：
To start using hermes, please run: source ~/.bashrc && hermes Or, if you use zsh: source ~/.zshrc && hermes关键操作：根据你的 shell 类型，执行对应的source命令。如果你不确定，执行echo $SHELL，如果输出是/bin/zsh，就用source ~/.zshrc；如果是/bin/bash，就用source ~/.bashrc。这一步是激活hermes命令的必要条件，跳过它，你接下来会收到command not found: hermes的错误。
步骤二：验证安装
执行：
hermes --version预期输出类似于hermes v0.8.0 (v2026.4.8)。如果看到这个，恭喜你，二进制安装成功！接着，执行：
hermes model list这会列出 Hermes 当前支持的所有模型提供商。你应该能看到kimi,openrouter,openai,nous-portal等。如果这里卡住或报错，说明网络配置有问题，回到上一节的“网络连通性”检查。
步骤三：启动交互式配置向导
现在，执行：
hermes setup这会启动一个友好的 TUI（文本用户界面）向导。我会逐个解释每个选项，以及我的选择理由：
- Welcome Screen：按
Enter继续。 - Select LLM Provider：用方向键选择
kimi，按Space选中，再按Enter。这是为你节省时间的最优选。 - Enter your Kimi API Key：粘贴你之前准备好的 Key，按
Enter。向导会立即尝试连接 Kimi API 进行验证。如果成功，会显示✓ API key validated；如果失败，会提示✗ Failed to validate API key，这时请检查 Key 是否正确、网络是否通畅。 - Configure Tools：这是一个多选菜单。默认全选，但请取消勾选
browser（浏览器控制）。原因：浏览器控制需要安装额外的驱动（如 ChromeDriver），且在无图形界面的服务器上无法工作。我们先保证核心功能，后续再按需添加。 - Configure Gateway：选择
None。我们先专注于 CLI 本地模式，把消息网关（Telegram/飞书等）留到后面单独配置，避免初次配置过于复杂。 - Configure Backend：选择
local。这是最简单的后端，适合首次体验。 - Save Configuration：按
Enter保存。向导会生成~/.hermes/config.yaml和~/.hermes/.env文件。
步骤四：首次运行与基础测试
配置完成后，向导会自动退出。现在，执行：
hermes你会进入 Hermes 的交互式 CLI 界面，看到一个>提示符。这是你的 Agent 已经就绪的标志。输入第一个测试指令：
> 你好，我是你的新主人。请用一句话介绍你自己。几秒钟后，你应该会看到类似这样的回复：
你好！我是 Hermes Agent，一个能随时间学习和进化的 AI 工作伙伴。我不仅能回答问题、执行任务，还能从我们的每一次互动中总结经验，让下次合作更高效。这个回复本身并不神奇，但它的意义在于：整个执行链路（CLI -> Hermes Core -> Kimi API -> 解析响应 -> 返回）已经打通。你已经拥有了一个可工作的、最小可行的 Hermes Agent。
实操心得：在
hermesCLI 中，你可以用Ctrl+C退出当前会话，用Ctrl+D退出整个 CLI。如果某次回复特别慢，不要反复按回车，耐心等待。Hermes 有内置的超时机制（默认 120 秒），超时后会自动报错，告诉你具体卡在哪个环节（比如Timeout waiting for LLM response），这比一个无响应的光标要有用得多。
3.3 深度配置与个性化：让 Hermes 真正成为你的“数字分身”
安装和首次配置只是起点。Hermes 的真正威力，在于你如何根据自己的工作流对其进行深度定制。这部分，我将带你完成三个关键配置：本地模型接入、技能（Skill）开发、以及飞书网关部署。它们分别代表了 Hermes 的“大脑”、“手脚”和“社交网络”。
配置一：接入本地 LLM（Hermes-2-Pro-Llama-3-8B）
云服务方便，但本地模型给你绝对的控制权和隐私保障。Hermes-2-Pro-Llama-3-8B 是 Nous Research 专门为 Hermes Runtime 优化的模型，函数调用能力极强。以下是详细步骤：
下载模型：Hermes 提供了预量化版本，无需你手动量化。执行：
hermes model download NousResearch/Hermes-2-Pro-Llama-3-8B --quantize Q4_K_M这个命令会从 Hugging Face 自动下载 4-bit 量化版（约 4.2GB），并存放到
~/.hermes/models/目录下。Q4_K_M是一个平衡速度和精度的量化等级，最适合 M系列芯片和主流 Linux 服务器。配置模型路径：编辑
~/.hermes/config.yaml，找到llm部分，将其修改为：llm: provider: local model_path: ~/.hermes/models/NousResearch/Hermes-2-Pro-Llama-3-8B backend: llama.cpp n_ctx: 8192 n_threads: 8关键参数解释：
provider: local：告诉 Hermes 使用本地模型，而非云 API。model_path：指向你刚刚下载的模型文件夹。backend: llama.cpp：指定使用高效的 llama.cpp 推理后端。n_ctx: 8192：设置上下文长度为 8K，足够处理大部分文档。n_threads: 8：在 8 核 CPU 上并行推理，最大化速度。
验证本地模型：重启 CLI，执行
hermes，然后输入：> 请用中文写一首关于春天的五言绝句。如果你能看到一首工整的、押韵的诗，并且响应时间在 5-10 秒内（取决于你的 CPU），说明本地模型已成功接入。相比云 API 的 1-2 秒延迟，本地模型的“思考感”更强，这正是它能进行深度反思的基础。
配置二：开发你的第一个 Skill（技能）
Skill 是 Hermes 的“手脚”，是你赋予它特定能力的代码单元。我们来创建一个实用的 Skill：自动归档邮件。
创建 Skill 目录：Hermes 的 Skill 默认存放在
~/.hermes/skills/。执行：mkdir -p ~/.hermes/skills/archive_email cd ~/.hermes/skills/archive_email编写 Skill 代码：创建
main.py：# ~/.hermes/skills/archive_email/main.py import os import json from datetime import datetime def archive_emails( email_provider: str = "gmail", folder_name: str = "Archive", days_old: int = 30, dry_run: bool = True ) -> dict: """ 将指定邮箱中超过指定天数的邮件移动到归档文件夹。 Args: email_provider: 邮箱服务商 ("gmail", "outlook", "imap") folder_name: 归档目标文件夹名 days_old: 邮件年龄阈值（天） dry_run: 是否仅模拟，不执行真实操作 Returns: dict: 包含操作摘要的字典 """ # 这里是伪代码，实际应调用 Gmail API 或 IMAP 协议 # 为演示，我们只返回一个模拟结果 if dry_run: result = { "status": "success", "message": f"[DRY RUN] Would archive {days_old}+ day old emails from {email_provider} to '{folder_name}'", "archived_count": 42, "estimated_time_saved_minutes": 15 } else: result = { "status": "success", "message": f"Archived {days_old}+ day old emails from {email_provider} to '{folder_name}'", "archived_count": 42, "actual_time_saved_minutes": 15 } return result # 必须定义这个字典，Hermes 用它来发现和注册 Skill SKILL_METADATA = { "name": "archive_emails", "description": "将旧邮件自动归档到指定文件夹，节省整理时间。", "parameters": { "email_provider": {"type": "string", "default": "gmail"}, "folder_name": {"type": "string", "default": "Archive"}, "days_old": {"type": "integer", "default": 30}, "dry_run": {"type": "boolean", "default": True} } }这个 Skill 的精妙之处在于
SKILL_METADATA字典。它不是注释，而是 Hermes 的“技能说明书”。parameters字段定义了这个 Skill 的所有可配置项，Hermes 会自动根据这个描述，生成自然语言的调用指令（比如“把 Gmail 里 60 天前的邮件归档到 ‘旧邮件’ 文件夹”）。启用 Skill：回到终端，执行：
hermes tools enable archive_emailHermes 会扫描
~/.hermes/skills/目录，找到archive_email文件夹，并将其注册为一个可用工具。测试 Skill：在
hermesCLI 中，输入：> !archive_emails --email_provider outlook --folder_name "Old Stuff" --days_old 60 --dry_run False注意前面的
!符号，它告诉 Hermes 这是一个直接调用 Skill 的命令，而不是一个需要 LLM 推理的自然语言请求。你应该会看到 Skill 返回的 JSON 结果。
配置三：部署飞书网关（Lark Gateway）
让 Hermes 从 CLI 走进你的日常工作流，飞书是最平滑的入口。以下是经过生产环境验证的部署步骤：
在飞书开放平台创建应用：
- 访问 飞书开放平台 ，登录你的飞书账号。
- 点击右上角“开发者后台” -> “创建应用” -> “自建应用”。
- 应用名称填
Hermes Agent，应用描述写一个会自我进化的AI工作伙伴。 - 创建后，进入“凭证与基础信息”，复制
App ID和App Secret。
配置环境变量：编辑
~/.hermes/.env，添加：FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx # 替换为你的 App ID FEISHU_APP_SECRET=your_app_secret_here # 替换为你的 App Secret FEISHU_DOMAIN=feishu FEISHU_CONNECTION_MODE=websocket FEISHU_GROUP_POLICY=allowlist FEISHU_ALLOWED_USERS=ou_xxxxxxxxxxxxxxxx # 替换为你自己的飞书 open_id获取
open_id的方法：在飞书客户端，点击左上角头像 -> “我的信息”，在 URL 中找到&open_id=ou_xxx这一段。配置网关 YAML：编辑
~/.hermes/config.yaml，在platforms下添加：platforms: feishu: enabled: true extra: ws_reconnect_interval: 120 ws_ping_interval: 30启动网关：在终端执行：
hermes gateway你会看到日志中出现
Feishu gateway started on websocket mode。此时，Hermes 已经在后台监听飞书的消息。飞书端验证：
- 在飞书里，搜索并添加你刚刚创建的应用（
Hermes Agent）为好友。 - 私聊它，发送
你好。 - 如果它秒回
你好！我是 Hermes Agent...，说明私聊通道已通。 - 把它拉进一个测试群，在群里
@Hermes Agent，然后发送今天天气怎么样？。如果它能正常回复，说明群聊也已就绪。
- 在飞书里，搜索并添加你刚刚创建的应用（
注意：飞书网关的
websocket模式最大的好处是无需公网 IP 和域名。它通过飞书的长连接服务器进行通信，非常适合个人开发者和小团队快速落地。
4. 常见问题与实战排障：那些只有踩过坑才知道的技巧
4.1 “hermes command not found” —— 最高频的入门陷阱
这个问题几乎困扰了 80% 的新手，但原因极其单一：你的 shell 没有加载~/.bashrc或~/.zshrc中新增的 PATH。
排查步骤：
- 执行
echo $PATH，检查输出中是否包含~/.local/bin。如果没有，说明source命令没成功。 - 执行
cat ~/.bashrc | grep "local/bin"，检查是否真的有export PATH="$HOME/.local/bin:$PATH"这一行。如果没有，说明安装脚本的“路径协商”阶段失败了。 - 手动修复：打开
~/.bashrc，在文件末尾添加export PATH="$HOME/.local/bin:$PATH"，然后执行source ~/.bashrc。
终极解决方案（推荐）：在安装前，先手动创建一个符号链接：
mkdir -p ~/.local/bin ln -sf $(which python3) ~/.local/bin/hermes这样，无论 PATH 如何，hermes命令总能被找到。虽然这不是官方做法，但在 CI/CD 或 Docker 环境中，这是我保证 Hermes 可靠性的黄金法则。
4.2 “LLM timeout” —— 云 API 的不可抗力
当你使用 OpenRouter 或 OpenAI 时，经常会遇到Timeout waiting for LLM response。这不是 Hermes 的 bug，而是网络抖动或 API 限流的常态。
我的三步排障法：
隔离测试：在终端中，直接用
curl测试 API：curl -X POST "https://openrouter.ai/api/v1/chat/completions" \ -H "Authorization: Bearer YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-pro", "messages": [{"role": "user", "content": "Hello"}] }'如果这个
curl也超时，问题一定在你的网络或 API Key 上。调整 Hermes 超时参数：编辑
~/.hermes/config.yaml，在llm部分增加：timeout: 180 # 将超时时间从默认的 120 秒提高到 180 秒 retry_attempts: 3 # 失败后重试 3 次启用降级策略：Hermes 支持“故障转移”。在
config.yaml中配置：llm: provider: openrouter fallback_providers: ["kimi", "openai"] # 当 OpenRouter 失败时，依次尝试 Kimi 和 OpenAI这样，即使主 API 挂了