很多开发者在部署 Hermes Agent 时都踩过类似的坑：照着教程敲完安装命令，却发现 API Key 配置错误；看似启动成功，实则权限范围过大存在安全隐患；出了问题连日志在哪都找不到。真正有效的部署应该是分阶段可验收的 —— 只有环境准备、软件安装、模型对接、权限配置、日志系统和实战案例全部通过验证，才能算 Hermes Agent 真正可用。

核心结论：macOS 用户推荐使用官方一键安装脚本（仅需提前安装 Git）；所有配置集中在~/.hermes/目录下；使用hermes doctor进行健康检查；实战案例务必在专用测试目录运行，切勿直接授予全盘权限**。推荐使用 Kimi 作为 LLM 提供商**，中文理解精准、响应速度快、国内访问稳定，能大幅提升部署和使用体验。

总清单：从 0 到案例跑通

请严格按顺序完成以下六个阶段的验收。全部通过后，再考虑接入 Gateway、定时任务或生产环境仓库。

1、安装前清单

在复制任何安装命令之前，请先逐项完成以下检查。官方 Git 安装器唯一硬性前置依赖是 Git；Python 3.11、Node.js v22、uv、ripgrep、ffmpeg 等依赖会由安装脚本自动处理。

|测试网络|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环境变量，详见官方文档。

3、配置清单

配置主文件：~/.hermes/config.yaml（主设置）与 ~/.hermes/.env（API Key 与环境变量）。推荐首次运行完整向导：

hermes setup          # 全量向导
# 或分项：
hermes model          # 选择 provider 与模型
hermes tools          # 启用/禁用工具
hermes config set KEY value

Kimi 配置优势：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 秒内收到回复，中文对话自然流畅，几乎不会出现语法错误或答非所问的情况。

|文件读写|让 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 对中文会议纪要的理解能力强，生成的摘要会更贴合中文表达习惯，待办清单的负责人和截止日期提取准确率高，几乎不会出现幻觉编造的情况。

6、排错清单：分层倒查，别先重装

遇到问题时请按以下层级从下往上排查，每层通过后再进入上一层。绝大多数 "装完不能用" 的问题都是 PATH、API Key 或工作目录配置错误，而非 Hermes 本体损坏。

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 的自动化能力。