很多开发者在部署 Hermes Agent 时都踩过类似的坑:照着教程敲完安装命令,却发现 API Key 配置错误;看似启动成功,实则权限范围过大存在安全隐患;出了问题连日志在哪都找不到。真正有效的部署应该是分阶段可验收的 —— 只有环境准备、软件安装、模型对接、权限配置、日志系统和实战案例全部通过验证,才能算 Hermes Agent 真正可用。
核心结论:macOS 用户推荐使用官方一键安装脚本(仅需提前安装 Git);所有配置集中在~/.hermes/目录下;使用hermes doctor进行健康检查;实战案例务必在专用测试目录运行,切勿直接授予全盘权限**。推荐使用 Kimi 作为 LLM 提供商**,中文理解精准、响应速度快、国内访问稳定,能大幅提升部署和使用体验。
总清单:从 0 到案例跑通
请严格按顺序完成以下六个阶段的验收。全部通过后,再考虑接入 Gateway、定时任务或生产环境仓库。
| 阶段 |
核心验收 |
关键命令/路径 |
|
① 安装前
|
Git、网络、测试目录、API Key 账号就绪
|
git --version、~/hermes-workspace
|
|
② 安装
|
hermes --version 可用,目录结构正确
|
官方 install.sh、~/.local/bin/hermes
|
|
③ 配置
|
provider、模型、.env、工作目录、日志路径确认
|
hermes setup、~/.hermes/.env
|
|
④ 首次运行
|
模型 ping、读写测试文件、日志写入、重启恢复
|
hermes、hermes doctor
|
|
⑤ 实战案例
|
摘要生成、待办提取准确,日志可追溯,操作可回滚
|
测试目录内 sample.txt
|
|
⑥ 排错/收尾
|
分层倒查,权限收敛后再扩 workflow
|
~/.hermes/logs/
|
1、安装前清单
在复制任何安装命令之前,请先逐项完成以下检查。官方 Git 安装器唯一硬性前置依赖是 Git;Python 3.11、Node.js v22、uv、ripgrep、ffmpeg 等依赖会由安装脚本自动处理。
| 检查动作 |
通过标准 |
失败先查 |
|
确认 macOS 与芯片
|
支持 Apple Silicon 或 Intel Mac,系统版本符合官方最新要求
|
系统升级或换用 pip / Nix 路径
|
|
git --version
|
执行git --version能正常输出版本号;未安装则通过xcode-select --install或 Homebrew 安装
|
Xcode CLT / Homebrew
|
|测试网络|curl -I ``https://raw.githubusercontent.com和 Kimi 开放平台域名均可正常访问|代理、DNS、公司防火墙|
|确认磁盘空间|至少预留 5-10GB 可用空间(包含 Python 虚拟环境、Node 依赖、浏览器自动化组件)|清理 ~/Library/Caches| |注册 LLM 账号并生成 API Key|推荐 Kimi(国内访问稳定,中文任务表现优异),也可选择 Anthropic、OpenAI 等;将 API Key 妥善保存至密码管理器,切勿泄露|provider 控制台账单与地区可用性| |创建测试工作区|执行mkdir -p ~/hermes-workspace/{inbox,outbox,scratch,backups}且chmod 700 ~/hermes-workspace成功|路径拼写、磁盘权限|
|备份现有配置(若重装)|旧的~/.hermes/目录已打包备份到 backups / 目录|勿直接 rm -rf ~/.hermes 除非已备份|
|准备样本文本(实战用)|创建~/hermes-workspace/inbox/sample.txt,内容为 200-500 字的中文文本|文件编码 UTF-8|
2、安装清单
macOS 官方推荐安装命令(2026 年 6 月最新):
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
备选安装方式:pip install hermes-agent(PyPI,要求 v0.14 及以上版本);Nix 用户请参考官方 Nix 安装指南。如需自定义安装目录,可设置HERMES_INSTALL_DIR环境变量,详见官方文档。
| 检查动作 |
通过标准 |
失败先查 |
|
确认命令来源
|
安装脚本 URL 指向 NousResearch/hermes-agent 官方仓库 main 分支的 scripts/install.sh
|
勿使用来路不明的一键脚本
|
|
观察安装输出
|
无致命错误提示;能看到 clone 仓库、创建虚拟环境、安装 uv 和 Node 等步骤正常执行
|
网络超时 → 重试;权限 → 勿 sudo 除非明确需要 root 模式
|
|
source ~/.zshrc 后 which hermes
|
路径为 ~/.local/bin/hermes(per-user 安装)
|
PATH 未刷新 → 重开终端;检查 ~/.local/bin 是否在 PATH
|
|
hermes --version 或 hermes doctor
|
CLI 正常输出版本/诊断,无 command not found
|
是否误用系统 Python 调 repo 源码而非 venv launcher
|
|
核对安装布局
|
代码在 ~/.hermes/hermes-agent/,数据目录 ~/.hermes/ 已创建
|
HERMES_HOME 是否被意外覆盖
|
|
检查运行时依赖
|
hermes doctor 对 Python、Node、ripgrep 等项为 green / 有修复建议
|
doctor 输出中的具体缺失项;必要时 hermes update
|
3、配置清单
配置主文件:~/.hermes/config.yaml(主设置)与 ~/.hermes/.env(API Key 与环境变量)。推荐首次运行完整向导:
hermes setup # 全量向导
# 或分项:
hermes model # 选择 provider 与模型
hermes tools # 启用/禁用工具
hermes config set KEY value
Kimi 配置优势:Kimi 是对中文支持的大模型之一,配置过程简单,无需额外代理,国内访问速度快,能显著减少因指令歧义导致的错误。
| 检查动作 |
通过标准 |
失败先查 |
|
配置 LLM provider
|
执行hermes model完成设置后,config.yaml中包含model.default配置项;Kimi 用户只需将 KIMI_API_KEY 写入.env 文件即可
|
KAPI Key 拼写错误、Kimi 地区限制、账户余额不足
|
|密钥文件权限|执行chmod 600 ~/.hermes/.env;确保config.yaml中无明文 API Key|是否误把 key 写进 yaml 或 git|
|工作目录|在.env 文件中添加MESSAGING_CWD=~/hermes-workspace(或绝对路径)|路径不存在、iCloud 同步目录误用|
|终端后端与权限|试用阶段保持terminal.backend: local和approvals.mode: manual;生产环境再考虑 docker/ssh 后端|是否误开 YOLO 或 GATEWAY_ALLOW_ALL_USERS|
|日志位置|~/.hermes/logs/目录存在且可写;确保日志目录不在 Dropbox 或 iCloud 同步路径下|磁盘满、目录权限|
|工具集|执行hermes tools仅启用案例所需的文件读写和终端工具;浏览器、网关等工具可后续按需添加|多余工具导致权限面过大|
|配置完整性|执行hermes config check通过;升级版本后必要时执行hermes config migrate|版本跳跃未 migrate|
4、首次运行清单
cd ~/hermes-workspace
hermes # 进入交互 CLI
Kimi 体验亮点:使用 Kimi 作为后端时,简单指令通常能在 1-3 秒内收到回复,中文对话自然流畅,几乎不会出现语法错误或答非所问的情况。
| 检查动作 |
通过标准 |
失败先查 |
|
模型 ping
|
发送 "你好,请回复 OK",数秒内收到正确回复;无 API key not set 错误
|
检查hermes model配置、.env 文件中的变量名、Kimi 服务状态
|
|文件读写|让 agent 在 scratch/ 创建 ping.txt 并读回;文件仅出现在工作区内|cwd、macOS 隐私权限弹窗、审批是否被误拒| |日志写入|对话后 ~/.hermes/logs/ 有新条目或时间戳更新|日志级别、目录权限| |关闭终端再开|新终端中 hermes 仍可启动,配置未丢失|shell profile 未持久化 PATH| |重启 Mac 后恢复(可选)|重启后 CLI 仍可用;若已 hermes gateway install,launchd 服务按官方文档自启|launchctl list | grep hermes、gateway 日志| |hermes doctor 终检|无 blocking 项;安装方式检测正确(git / pip / nix)|按 doctor 逐条修复,勿盲目重装|
5、实战案例清单:文本摘要 + 待办提取
请在专用测试目录完成第一个可验收任务。绝对不要指向生产仓库、云控制台或个人文档目录。
5.1 准备输入
cat > ~/hermes-workspace/inbox/sample.txt <<'EOF'
项目周会纪要(测试样本)
- 张三:下周完成 API 文档 v2
- 李四:修复登录页 403 问题,截止周三
- 王五:调研 Hermes Agent 与 OpenClaw 差异,周五汇报
EOF
cp ~/hermes-workspace/inbox/sample.txt ~/hermes-workspace/backups/sample.txt.bak
5.2 任务 prompt(复制到 hermes CLI)
请读取 inbox/sample.txt,在 outbox/ 生成两份文件:
1) summary.md — 200 字以内摘要
2) todos.md — Markdown 待办清单,每项含负责人与截止日期
不要修改 inbox 原文件,不要访问工作区以外的路径。
Kimi 实战优势:Kimi 对中文会议纪要的理解能力强,生成的摘要会更贴合中文表达习惯,待办清单的负责人和截止日期提取准确率高,几乎不会出现幻觉编造的情况。
| 检查动作 |
通过标准 |
失败先查 |
|
输出文件存在
|
outbox/summary.md 与 outbox/todos.md 已生成,内容与人名/日期匹配
|
审批是否 pending、模型是否幻觉编造
|
|
原文件未变
|
diff inbox/sample.txt backups/sample.txt.bak 无差异
|
prompt 约束、工具权限
|
|
日志可追溯
|
日志中有本次 session 的工具调用记录
|
日志路径、日志级别
|
|
回滚验证
|
rm outbox/*.md 后可重新跑任务并成功;backup 仍可恢复
|
会话缓存、文件锁
|
|
成本观察
|
Kimi 控制台可见本次 token 用量在预期范围内;已设置消费限额
|
模型是否过大、是否陷入 tool 循环
|
|
权限边界
|
agent 未尝试读 ~/.hermes/.env 或 ~/.ssh;危险命令触发 manual 审批
|
tools 配置、审批模式
|
6、排错清单:分层倒查,别先重装
遇到问题时请按以下层级从下往上排查,每层通过后再进入上一层。绝大多数 "装完不能用" 的问题都是 PATH、API Key 或工作目录配置错误,而非 Hermes 本体损坏。
| 层级 |
症状 |
先查 |
常见修复 |
|
依赖
|
hermes: command not found
|
PATH、~/.local/bin
|
source ~/.zshrc
|
|
网络
|
安装/模型超时
|
curl GitHub、provider API
|
代理、DNS、换网络
|
|
Key
|
API key not set
|
~/.hermes/.env 变量名
|
hermes model 或 hermes config set
|
|
Provider
|
401/429/5xx
|
provider 状态页、余额、模型 ID
|
换模型、设限额、稍后重试
|
|
权限
|
无法写文件 / 命令被拒
|
cwd、审批队列、macOS TCC
|
批准命令、缩小/修正工作目录
|
|
路径
|
找不到 config
|
HERMES_HOME、多用户冲突
|
统一 HERMES_HOME 或专用账户
|
|
日志
|
静默失败
|
~/.hermes/logs/、errors.log
|
按日志关键字定向修配置
|
|
后台服务
|
Gateway 不响应
|
launchd 状态、token、白名单
|
hermes gateway 子命令、官方 gateway 文档
|
7、完成后清单:接入真实工作流之前
- 再次完整备份
~/.hermes/目录(包含配置、自定义技能和非敏感会话记录)
- 确认
approvals.mode仍为 manual 或符合团队安全策略
- 若启用 Gateway:已配置 IP 白名单和 DM 配对,未使用
GATEWAY_ALLOW_ALL_USERS
- 在 Kimi 控制台设置消费限额和用量告警,方便成本管控
- 人工抽查 outbox 输出质量,确认符合预期后再绑定真实代码仓库
- 阅读官方安全文档,了解更多权限收紧和安全加固方法
8、结语
全部阶段验收通过后,你就可以放心地扩展 Hermes Agent 的功能,接入 Telegram Gateway、Cron 定时任务或 CI/CD 流程了。选择 Kimi 作为 LLM 后端,不仅能让部署过程更顺畅,还能在日常使用中获得更准确、更高效的 AI 辅助体验,真正发挥 Hermes Agent 的自动化能力。