MacBook 安装 Hermes 桌面版操作指南

一、环境要求

二、安装步骤

2.1 安装 Hermes CLI（终端版）

打开 终端（Terminal），执行一键安装命令：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装脚本会自动完成以下操作：

1. 检测 macOS 版本和芯片架构（Apple Silicon / Intel）
2. 安装 Python 和 uv（如果未安装）
3. 创建虚拟环境
4. 安装 hermes-agent 包
5. 配置 shell 启动脚本（.zshrc 或 .bash_profile）
6. 生成启动器脚本

安装完成后，关闭并重新打开终端，或执行：

source ~/.zshrc

2.2 验证安装

终端中执行：

hermes --version

如果能输出版本号（如 Hermes Agent x.y.z），说明 CLI 安装成功。

2.3 初始化配置

hermes setup

按交互引导完成初始配置：

1. 选择模型供应商 — 推荐 OpenRouter（支持最多模型）或 DeepSeek
2. 设置 API Key — 输入对应供应商的 API 密钥
3. 开启工具集 — 选中你需要的工具（terminal、web、file 等）

也可以跳过 setup，直接用：

hermes model

快速选择模型和供应商。

💡 提示： API Key 存在 ~/.hermes/.env 中，可随时编辑。

2.4 验证配置完整性

hermes doctor

检查各项依赖是否就绪，绿色 ✅ 表示正常。

2.5 启动桌面版（GUI）

hermes desktop

或使用别名：

hermes gui

首次启动会自动下载 Electron 桌面应用包，后续启动会直接打开。

三、桌面版功能一览

Hermes 桌面版是一个原生 Electron 应用，功能包括：

四、首次启动后的配置

4.1 设置系统权限（如果提示）

桌面版部分功能需要辅助功能权限：

• 屏幕截图（computer_use） → 系统设置 > 隐私与安全性 > 屏幕录制 > 添加 Hermes
• 通知 → 系统设置 > 通知 > Hermes > 允许通知

4.2 更换模型

在桌面版窗口右下角状态栏点击模型名称，或使用 Cmd+K 搜索 "change model"。

五、常见问题

Q1：安装脚本执行失败

检查网络能否访问 hermes-agent.nousresearch.com：

curl -I https://hermes-agent.nousresearch.com/install.sh

如果能访问但脚本报错，尝试手动安装：

# 先安装 uv（如果没装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 然后用 uv 安装 hermes-agent
uv tool install hermes-agent

Q2：hermes desktop 报错 command not found

重新加载 shell 配置：

source ~/.zshrc

或用完整路径：

~/.local/bin/hermes desktop

Q3：桌面版启动后白屏/闪退

清理缓存后重试：

rm -rf ~/.hermes/cache/desktop
hermes desktop

Q4：Apple Silicon 兼容问题

Hermes 桌面版已原生支持 Apple Silicon（arm64），无需 Rosetta。如果你使用的是 Intel Mac，安装脚本会自动下载 x86_64 版本。

Q5：如何卸载

hermes uninstall

这会移除 Hermes CLI、桌面版和配置文件。如需保留配置只删桌面版，直接删除 ~/.hermes/cache/desktop 目录即可。

六、进阶玩法

6.1 使用 Profiles（多身份切换）

创建多个独立配置：

hermes profile create work    # 工作环境
hermes profile create coding  # 开发环境
hermes profile list           # 查看所有 profile

桌面版启动时自动使用当前默认 profile。

6.2 启动 Web 仪表盘

hermes dashboard

在浏览器中打开全功能管理面板——可配置消息通道、MCP 目录、Webhook、记忆系统等。

6.3 接入 iMessage

Hermes 支持通过 Photon 桥接 iMessage：

hermes photon setup

无需 Mac 中继（BlueBubbles 后继方案），直接集成。

文档版本：v1.0
适用平台：macOS (Apple Silicon + Intel)
最后更新：2026-06-29

七、安装 Computer Use（桌面操控）

Hermes 的 computer_use 工具依赖 cua-driver 在底层驱动。macOS 上安装方式如下：

7.1 安装 cua-driver

打开终端执行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)"

脚本会自动：

1. 检测 macOS 版本和芯片架构（Apple Silicon / Intel）
2. 下载对应平台的 cua-driver 二进制
3. 安装到系统路径
4. 注册为 MCP 服务器

7.2 验证安装

cua-driver --version

能输出版本号即安装成功。

7.3 集成到 Hermes

hermes computer-use install

这个命令会自动将 cua-driver 注册为 Hermes 的 MCP 工具。或者手动注册：

hermes mcp add --transport stdio cua-driver -- cua-driver mcp

7.4 授权系统权限

macOS 对桌面操控有严格的权限限制，必须手动授权。

屏幕录制权限（必须）：

1. 打开 系统设置 > 隐私与安全性 > 屏幕录制
2. 点击锁图标解锁（输入密码）
3. 点击 + 添加应用
4. 在文件选择器中按 Cmd+Shift+G，输入 /usr/local/bin/cua-driver，点击前往
5. 选中 cua-driver 并添加
6. 如果列表中没有 cua-driver，改用路径 /opt/homebrew/bin/cua-driver（Apple Silicon，如果是通过 Homebrew 安装的）或 ~/.local/bin/cua-driver

辅助功能权限（强烈建议）：

1. 打开 系统设置 > 隐私与安全性 > 辅助功能
2. 同样添加 /usr/local/bin/cua-driver
3. 勾选启用

注意： 添加后需要重启终端（完全退出再打开）才能生效。

7.5 验证 computer_use 是否就绪

hermes computer-use doctor

如果每项检查都显示 ✅，说明安装完成，Hermes 已经可以在终端对话中调用 computer_use 工具操控 Mac 桌面了。

预期输出示例：

🔍 cua-driver health report (macOS)

cua-driver binary    ✅  /usr/local/bin/cua-driver
cua-driver version   ✅  0.6.8
Screen recording     ✅  Enabled
Accessibility        ✅  Enabled
MCP server           ✅  Running
Display              ✅  Built-in Retina (1512 x 982)

7.6 测试基本操作

运行 Hermes 终端对话后，你可以让它：

帮我打开 Safari 浏览器，搜索"成都理工大学 2025 考研分数线"

Hermes 会自动调用 computer_use 完成截图、点击、输入等一系列操作。

💡 关于 MacBook + WSL 的区别：
你在 Windows 上用 WSL 时，computer_use 需要 Windows 端的 Hermes + cua-driver，因为 WSL 本身没有桌面环境。但 MacBook 是原生 macOS，直接在同一台电脑上装 Hermes + cua-driver 就能用，不需要跨系统桥接。

7.7 常见问题

文档版本：v1.0
适用平台：macOS (Apple Silicon + Intel)
最后更新：2026-06-29

八、沙箱配置——防止 Hermes 随意更改系统

Hermes 默认的 terminal.backend: local 意味着它执行的终端命令直接在 MacBook 上跑，有修改文件系统的能力。如果要限制它的操作范围，有以下几个层级的安全措施，建议从轻到重逐步配置。

8.1 审批模式（最轻量，推荐起步）

Hermes 默认已经开启了命令审批（approvals.mode: manual），执行危险命令时会询问你是否允许。

# config.yaml 中默认
approvals:
  mode: manual       # 每次危险操作前都弹确认
  timeout: 60        # 超时 60 秒未响应则拒绝
  cron_mode: deny    # 定时任务默认拒绝危险命令

可切换为智能模式：

hermes config set approvals.mode smart

智能模式下，辅助模型会自动判断：低风险操作（读文件、查信息）直接放行，高风险操作（删除、修改系统文件）才弹确认。

对比：manual = 每次问 → 安全但烦；smart = 低风险自动过，高风险弹确认 → 省心也安全

8.2 Docker 沙箱（中等强度，墙裂推荐）

把终端命令的执行环境从 Mac 本机切换到 Docker 容器，这是最实用的隔离手段。

前提： MacBook 上需要安装 Docker Desktop。

# 下载安装 Docker Desktop（Apple Silicon / Intel 自动适配）
# https://www.docker.com/products/docker-desktop/

# 验证安装
docker --version

配置 Hermes 使用 Docker 后端：

hermes config set terminal.backend docker

所有终端命令都会在指定的 Docker 容器内执行，容器无法直接修改 Mac 本机的文件系统（除非显式挂载卷）。

默认镜像说明：

terminal:
  backend: docker
  docker_image: nikolaik/python-nodejs:python3.11-nodejs20  # 预装 Python + Node.js
  container_cpu: 1          # 限制 1 核 CPU
  container_memory: 5120    # 限制 5GB 内存
  container_disk: 51200     # 限制 50GB 磁盘
  container_persistent: true # 会话间保持容器状态
  docker_volumes: []         # 默认不挂载宿主机目录
  docker_mount_cwd_to_workspace: false  # 不挂载当前目录

挂载特定目录（如果你想让 Hermes 能读写某些目录）：

terminal:
  docker_volumes:
    - "/Users/你的用户名/projects:/workspace/projects"
    - "/Users/你的用户名/Downloads:/workspace/downloads"

这样 Hermes 只能操作你允许的目录，系统文件目录碰不到。

⚠️ 注意： 切换到 Docker 后端后，Hermes 仍然可以读写当前工作目录（因为传给容器的 prompt 和文件是通过内容传的，不是通过直接写文件系统），所以要配合下面 8.3 节限制工具集。

8.3 工具集限制（精准控制能力范围）

# 禁用 computer_use（不让它操控桌面）
hermes config set platform_toolsets.cli '["clarify","file","memory","session_search","skills","terminal","todo","vision","web"]'

# 或者更严格——只保留对话和文件读取
hermes config set platform_toolsets.cli '["clarify","memory","session_search","web","file"]'

工具集更改后需要新开会话才生效。

也可以只禁用个别工具：

hermes tools disable computer_use   # 禁用桌面操控
hermes tools disable terminal       # 禁用终端命令（只留文件读写和对话）
hermes tools disable execute_code   # 禁用 Python 代码执行

8.4 命令白名单（精确管控终端命令）

# config.yaml
command_allowlist:
  - delete in root path          # 禁止在根路径删除文件
  - script execution via -e/-c   # 禁止通过 -e/-c 传参执行脚本
  - execute_code                 # 控制 execute_code 的执行

8.5 策略引擎 Tirith

Tirith 策略引擎默认已开启：

security:
  tirith_enabled: true    # 策略引擎已开启
  tirith_fail_open: true  # 策略不可用时默认放行（改为 false 即默认拒绝）

Tirith 使用 Open Policy Agent (OPA) 策略。如果要配置自定义策略规则，可以将 OPA 策略文件放到指定路径并在 config 中配置 tirith_path。

8.6 推荐配置清单

按使用习惯选择一种方案：

🟢 方案 A：日常开发用（安全兼顾便捷）

# 开启智能审批
hermes config set approvals.mode smart
# 开启 Docker 沙箱
hermes config set terminal.backend docker
# 禁用桌面操控
hermes tools disable computer_use

🟡 方案 B：只做对话/查询（最严格）

# Docker 沙箱
hermes config set terminal.backend docker
# 只保留基本工具
hermes config set platform_toolsets.cli '["clarify","memory","session_search","web"]'
# 禁用所有可能修改系统的工具
hermes tools disable terminal
hermes tools disable computer_use
hermes tools disable execute_code

🔵 方案 C：需要桌面操控但怕误操作

# 保留 manual 审批模式
hermes config set approvals.mode manual
# Docker 沙箱
hermes config set terminal.backend docker
# 不挂载系统目录
# docker_volumes 留空，Hermes 只能读写容器内部

8.7 注意事项

文档版本：v1.0
适用平台：macOS (Apple Silicon + Intel)
最后更新：2026-06-29

本文由 admin 原创，转载请注明出处。