Hermes Agent 在 Mac（Apple Silicon）上的部署与使用完整指南

1核心概念与架构

开始前先理解一个极易混淆的点：本方案里的 Docker 不是用来「装 Hermes 本体」的，而是给 agent 执行的命令做隔离沙箱。

Hermes 的 terminal.backend 设为 docker 后，agent 执行的每条命令、每次文件增删改都发生在容器内。容器默认看不到你 Mac 的任何文件。只有开关 docker_mount_cwd_to_workspace: true 会把「你启动 hermes 时所在的那个目录」挂载进容器的 /workspace。隔离策略很简单：只在 ~/hermes-workspace 这个目录里启动 hermes，容器就只能看到这一个目录，其余全部不可见。

官方文档明确：在隔离类后端（docker / ssh / singularity / modal / daytona）下，连危险命令检查都会跳过，因为「容器本身就是安全边界」。容器内即使 rm -rf，删的也只是容器/工作目录里的东西。

2安装 OrbStack 与 Hermes

2.1 安装 OrbStack（容器引擎）

OrbStack 原生支持 Apple Silicon，空闲几乎不占内存，并完全兼容 docker 命令，Hermes 无需任何额外适配。

brew install orbstack

安装后打开一次 OrbStack.app 完成首次初始化（它会自动接管 docker 命令）。

验证 docker 可用，并提前拉取 Hermes 默认镜像（省得首次运行时等待）：

docker version
docker run --rm hello-world                              # 看到 "Hello from Docker!" 即正常
docker pull nikolaik/python-nodejs:python3.11-nodejs20   # Hermes docker 后端官方默认镜像

2.2 安装 Hermes Agent

安装脚本会自动装好 uv / Python 3.11 / Node.js / ripgrep / ffmpeg 等依赖：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.zshrc        # 重新加载 shell（Mac 默认是 zsh）
hermes --help          # 能打印帮助即安装成功

3运行 Setup Wizard（初始化向导）

hermes setup

向导会依次询问以下各项，按下面说明操作。完整速查见 附录 C。

3.1 各步骤配置说明

OpenClaw 数据迁移

◆ OpenClaw Installation Detected
  Found OpenClaw data at /Users/xxx/.openclaw
  Would you like to see what can be imported? [Y/n]:

没有旧数据要迁移 → 输入 n 回车跳过；想看看有什么可导入 → 输入 Y（只看不改，后面还会再确认）。

Setup 模式选择

选 Full setup → 按 ↓ 移到它，回车。

模型 Provider

向导会列出所有支持的 provider。如果你用小米 MiMo，选中后按提示填写：API Key（tp- 开头的 Token Plan Key）、Base URL（https://token-plan-cn.xiaomimimo.com/v1）、Model（选 mimo-v2.5-pro）。

聊天平台

用 ↑↓ 移到 🪽 Feishu / Lark，按 SPACE 勾选；其他平台不要勾；按 ENTER 确认。

工具配置

Tools for 🖥️  CLI
   [✓] 🔍 Web Search & Scraping
   [✓] 🌐 Browser Automation
   ...
   [✓] 🖱️  Computer Use (macOS)  ← 必须取消！

Browser Provider

选 Local Browser（默认项，免费，本地 headless Chromium），直接回车。

Image Generation / Vision / Search

Image Generation 和 Vision 均选 Skip（MiMo Key 不支持图像生成；Vision 以后需要再配，见 4.4）。Search 选 DuckDuckGo (ddgs) —— 免费、不需要 Key、开箱即用。

3.2 向导完成后的注意事项

全部选完后出现「Installation Complete」界面：

┌─────────────────────────────────────────────────────────┐
│              ✓ Installation Complete!                   │
└─────────────────────────────────────────────────────────┘

📁 Your files:
   Config:    /Users/你的用户名/.hermes/config.yaml
   API Keys:  /Users/你的用户名/.hermes/.env
   Data:      /Users/你的用户名/.hermes/cron/, sessions/, logs/
   Code:      /Users/你的用户名/.hermes/hermes-agent

最后重新加载一次 shell，让 hermes 命令生效：

source ~/.zshrc

4配置模型

4.1 两个配置文件的分工

两个文件运行时都会被读取：config.yaml 决定「用哪个模型、打哪个地址」，.env 提供鉴权密钥。config.yaml 是主配置；.env 中的 TERMINAL_* 等变量是「强制覆盖」机制，一般不需要用（见 5.3）。

4.2 MiMo 模型一览与单模型配置

结论：主对话模型只能选 mimo-v2.5-pro、mimo-v2-pro 或 mimo-v2-omni。语音类模型不能当主模型。

~/.hermes/config.yaml 单模型配置：

model:
  default: mimo-v2.5-pro
  provider: xiaomi
  base_url: https://token-plan-cn.xiaomimimo.com/v1

~/.hermes/.env 对应密钥：

XIAOMI_API_KEY=tp-你的密钥
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1

4.3 多模型配置（小米 + 中转站）

Hermes 支持配置多个 provider，运行时用 /model 或 hermes model 切换。

config.yaml 多模型示例（小米 + AnyRouter）：

model:
  default: mimo-v2.5-pro          # 默认启动时用的模型
  provider: xiaomi                # 默认 provider
  base_url: https://token-plan-cn.xiaomimimo.com/v1

providers:
  xiaomi:
    base_url: https://token-plan-cn.xiaomimimo.com/v1
    models:
      - mimo-v2.5-pro             # 主力对话
      - mimo-v2-omni             # 多模态（能看图）
  anyrouter:
    base_url: https://anyrouter.top/v1
    models:
      - gpt-5.5                  # 复杂任务
      - gpt-5.4

.env 对应密钥：

# 小米 MiMo（Token Plan）
XIAOMI_API_KEY=tp-你的小米密钥
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1

# AnyRouter 中转站
ANYROUTER_API_KEY=sk-你的anyrouter密钥

扩展：再加 OpenRouter / OpenAI 直连（按需追加到 providers: 下）：

  openrouter:
    base_url: https://openrouter.ai/api/v1
    models:
      - anthropic/claude-sonnet-4
      - anthropic/claude-opus-4
      - google/gemini-2.5-pro
  openai:
    base_url: https://api.openai.com/v1
    models:
      - gpt-4o
      - o1

# .env 对应补充（可选）
OPENROUTER_API_KEY=sk-or-v1-你的openrouter密钥
OPENAI_API_KEY=sk-你的openai密钥

4.4 Vision 配置与运行时切换

想让 agent 能「看图」，在 config.yaml 中增加 vision 配置。小米 mimo-v2-omni 支持图像理解：

vision:
  model: mimo-v2-omni
  provider: xiaomi

或用 OpenRouter 的多模态模型：

vision:
  model: anthropic/claude-sonnet-4
  provider: openrouter

运行时切换模型有三种方式：

# 切回小米的示例
hermes config set model.default mimo-v2.5-pro
hermes config set model.provider xiaomi

# 验证配置
hermes config          # 查看当前完整配置，确认 model 部分正确
hermes doctor          # 自检，会验证 API Key 是否有效

5配置 Docker 沙箱与隔离工作目录

5.1 创建专用工作目录

以后只在这个目录里启动 hermes：

mkdir -p ~/hermes-workspace

5.2 配置 Docker 后端

以下命令直接在 Mac 终端里执行（不需要先进入 hermes 或 Docker）：

hermes config set terminal.backend docker
hermes config set terminal.docker_mount_cwd_to_workspace true
hermes config set terminal.container_memory 5120
hermes config set terminal.container_cpu 2

然后打开配置文件补全其余设置：

hermes config edit       # 打开 ~/.hermes/config.yaml

把 terminal: 段落确认成下面这样：

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  timeout: 180

  # 隔离核心：把启动目录挂载进容器的 /workspace
  docker_mount_cwd_to_workspace: true

  # gateway/cron 后台模式（如飞书）必须写工作目录绝对路径；
  # 只用交互式 CLI 时保持 "." 即可
  cwd: "/Users/你的用户名/hermes-workspace"

  # 安全：不向容器转发任何宿主环境变量（防止密钥泄露进容器）
  docker_forward_env: []

  # 资源上限
  container_cpu: 2
  container_memory: 5120
  container_disk: 51200
  container_persistent: true

  # 让容器以宿主用户身份运行，避免文件属主变 root
  docker_run_as_host_user: true

5.3 清理 .env 中的重复项

如果 ~/.hermes/.env 文件底部有以下内容，建议删掉（config.yaml 已配好，重复会造成混乱）：

# 以下删掉（已在 config.yaml 中配置）
TERMINAL_ENV=docker
TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE=True
TERMINAL_CONTAINER_MEMORY=5120
TERMINAL_CONTAINER_CPU=2

6配置命令审批与安全策略

即使在容器里，建议初期保留人工审批，熟悉后再放宽。编辑 ~/.hermes/config.yaml，增加/确认 approvals: 段：

approvals:
  mode: manual            # manual=危险命令都问你 | smart=AI判断低风险放行/危险自动拒 | off=关闭所有审批
  timeout: 60             # 超时未确认则拒绝（fail-closed，更安全）
  cron_mode: deny         # 定时任务默认拒绝执行，防止后台自动跑
  destructive_slash_confirm: true

可选：把你信任的命令加入白名单：

command_allowlist:
  - ls
  - cat
  - git

7启动与验证

cd ~/hermes-workspace        # 关键！容器只会挂载这个目录
hermes                       # 启动交互式 CLI
hermes --tui                 # 或：全屏终端界面

验证隔离是否生效：进入 hermes 后，让它执行：

帮我运行 `ls /` 和 `cat /etc/hostname`，并尝试 `ls ~`

验证模型是否正确：在 hermes 里输入 你好，你是什么模型？，它应回答自己是 MiMo（或你配置的默认模型）。如果报 401 错误，检查：

• .env 里的 XIAOMI_API_KEY 是否正确；
• XIAOMI_BASE_URL 是否为 https://token-plan-cn.xiaomimimo.com/v1；
• config.yaml 里 model.base_url 是否一致。

8接入飞书（可选）

8.1 方式一（推荐）：扫码自动创建

hermes gateway setup        # 选 "Feishu / Lark"，按提示扫码

Hermes 会自动创建一个具备正确权限的机器人应用并保存凭据。

8.2 方式二：手动在开发者后台创建

适合企业管控严、必须走审批流程的情况。

① 创建应用并拿到凭据

1. 打开飞书开放平台 https://open.feishu.cn/，登录后「创建企业自建应用」。
2. 进入「凭证与基础信息」，复制 App ID 和 App Secret。
3. 在「添加应用能力」里开启 机器人（Bot） 能力。

② 配置权限（进入「权限管理」添加）

• 必需：im:message、im:message:send_as_bot、im:resource、im:chat、im:chat:readonly
• 推荐：im:message.reactions:readonly、admin:app.info:readonly、contact:user.id:readonly

③ 配置事件订阅

• 连接方式选 长连接（WebSocket）（推荐，家用 Mac 不用公网）。
• 订阅事件：im.message.receive_v1（必需）。

④ 发布版本 —— 创建并发布一个版本。权限只有在版本发布后才生效。

⑤ 把凭据写进 Hermes

hermes gateway setup        # 选 Feishu/Lark → 填入 App ID / App Secret

或手动写入 ~/.hermes/.env：

FEISHU_APP_ID=cli_xxxxxxxx
FEISHU_APP_SECRET=secret_xxxxxxxx
FEISHU_DOMAIN=feishu                 # 国内填 feishu；国际版 Lark 填 lark
FEISHU_CONNECTION_MODE=websocket     # 长连接模式（推荐）
# 可选：限定只有这些用户/群能用
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx           # 默认「主频道」的 chat_id

⑥ 启动并验证

cd ~/hermes-workspace
hermes gateway

在飞书里给机器人发一条消息（或拉进群 @ 它），能正常回复即接入成功。

8.3 飞书进阶配置（可选）

group_sessions_per_user: true

platforms:
  feishu:
    allow_bots: none
    extra:
      ws_reconnect_interval: 120
      ws_ping_interval: 30
      default_group_policy: "open"
      admins:
        - "ou_管理员的open_id"

9日常使用

9.1 每次启动与界面操作

# 1. 确保 OrbStack 已运行（菜单栏有它的图标即可）
# 2. 进入隔离工作目录（关键：容器只会挂载这个目录）
cd ~/hermes-workspace
# 3. 启动
hermes            # 经典 CLI；全屏界面用 hermes --tui

退出：在 hermes 里输入 /exit（或 /quit）或按 Ctrl+C。

在 hermes 界面里，直接输入需求即可，agent 会自己决定调用工具、在容器里执行命令。常用斜杠命令：

9.2 文件处理与配置管理

因为容器只能看到 ~/hermes-workspace，处理文件请按「拷进 → 处理 → 拷出」来：

# 1. 把要处理的文件拷进工作目录（在另一个普通终端里操作）
cp ~/Downloads/报表.xlsx ~/hermes-workspace/

# 2. 进 hermes 让它处理（它在容器里看到的就是 /workspace/报表.xlsx）

# 3. 处理完，把结果从工作目录拷出来
cp ~/hermes-workspace/result.csv ~/Desktop/

常用配置管理命令：

hermes config                       # 查看当前完整配置
hermes config edit                  # 打开 ~/.hermes/config.yaml 手动编辑
hermes config set <key> <value>     # 设置单项（如 model.default）
hermes config check                 # 检查缺失配置
hermes model                        # 交互式选择 provider 和模型
hermes tools                        # 配置可用的工具集

9.3 安全使用习惯（记住这几条）

1. 只在 ~/hermes-workspace 里启动 —— 容器唯一能碰到的真实目录。
2. 要处理的文件，先拷进工作目录 —— 处理完再拷出来。
3. 不把密钥/私钥/密码放进工作目录 —— 容器能读到挂载的东西。
4. 初期保持人工审批（approvals.mode: manual）。
5. 别开 off/YOLO 模式。
6. 给模型 API Key 设用量上限/额度告警。
7. 不要勾选 Computer Use (macOS) 工具 —— 它绕过 Docker 隔离，直接操控宿主桌面。

10后台长期运行（tmux / 开机自启）

10.1 用 tmux 挂后台

tmux 让进程在「关窗口」后继续跑，适合临时挂后台；重启 Mac 后会话消失，需手动重开。

brew install tmux

# 挂交互式 hermes
tmux new -s hermes
cd ~/hermes-workspace && hermes

# 或：挂飞书网关
tmux new -s feishu
cd ~/hermes-workspace && hermes gateway

常用 tmux 操作：

tmux attach -t feishu           # 重新进入查看
tmux ls                         # 查看所有后台会话
tmux kill-session -t feishu     # 彻底停掉
# 干净 detach：按住 control(⌃)+b → 松开 → 再按 d；或 tmux detach-client -s feishu

10.2 装成开机自启服务（推荐长期方案）

开机自动在线、崩溃自动拉起，才是免维护的长期方案。仅适用于 gateway（飞书等消息 + 定时任务）模式。

hermes gateway install        # 装成 launchd 后台服务（消息 + 定时任务）

11进阶答疑

11.1 Hermes 到底能看到我 Mac 的哪些目录？

只能看到你启动 hermes 时所在的那个目录，其余一律看不到。 在 docker 后端 + docker_mount_cwd_to_workspace: true 下：

• agent 在容器里执行命令、读写文件，只能看到启动目录（被挂载成容器内的 /workspace）。
• 你 Mac 上的其它目录（家目录、文档、~/.ssh、其它磁盘…）容器一概看不到。容器有它自己一整套 Linux 文件系统。
• 隔离的本质：唯一的口子就是那个启动目录。所以务必只在 ~/hermes-workspace 里启动。

为什么工作目录聊了半天还是空的？ 两种独立原因，多半是第一种：

1. 光聊天不会产生文件。 agent 只有在你明确让它写文件/生成产物时才落盘，问答不会无故造文件。
2. 写了，但没写进挂载的 /workspace。 它可能把文件写到了容器里别处（/tmp、容器 home 等），那些不在挂载范围。

11.2 会话恢复与 gateway 常驻

会话关闭/重启后能恢复吗？

历史记录不会丢；但重新打开默认是开一段新对话，不会自动接着上次的内存上下文。要真正接着旧对话聊，用 hermes --help 查 resume / continue / session 相关选项（不同版本可能不同）。

ls -la ~/.hermes/sessions/        # 查看已有历史

飞书必须 gateway 一直运行才在线。 hermes gateway 是连接飞书和 agent 的「桥」，它停了机器人就立刻离线。它和交互式 hermes 是两个不同进程。三种保活方式：① 前台 hermes gateway（关窗口即停）；② tmux 挂后台（关窗口不停，重启 Mac 要重开）；③ hermes gateway install 装成开机自启服务（推荐，免维护）。详见 第 10 节。

11.3 飞书接入实战排错

① 机器人不回，日志刷 Unauthorized user

WARNING gateway.run: No user allowlists configured. All unauthorized users will be denied.
WARNING gateway.run: Unauthorized user: df9e49e2 (None) on feishu

这不是连接错误（连接成功的标志是日志里有 connected to wss://...feishu.cn），而是没配白名单，Hermes 默认拒绝所有不在白名单里的用户。日志里那个 ID 就是飞书认出的你自己的用户 ID。修复（编辑 ~/.hermes/.env，二选一）：

# 做法 A（推荐，安全）：只允许你自己，填日志里实际打印的那个 ID
FEISHU_ALLOWED_USERS=df9e49e2
# 做法 B（开放，谁都能用，不推荐）
GATEWAY_ALLOW_ALL_USERS=true

改完按 Ctrl+C 停掉 gateway，再 hermes gateway 重启。多个用户用逗号隔开。

② 提示 No home channel is set

这不是报错，是提示。home channel（主频道）是 Hermes 主动给你推消息的默认窗口，只负责两类消息：① 定时任务（cron）结果；② 跨平台/主动通知。没有定时任务在跑就一条都不会来。

③ 启动时的 Docker MEDIA 警告

WARNING gateway.run: Docker backend ... no explicit host-visible output mount ... MEDIA file delivery can fail

不影响文字聊天，只提醒：用 docker 后端时，agent 生成的图片/文件类媒体产物放在容器内路径可能发不回飞书。真要在飞书收发文件/图片时，再给输出目录配个挂载（如 ~/.hermes/cache/documents:/output）即可。

11.4 飞书 vs CLI · 多会话与记忆机制

底下是同一个 agent（同一份 config、同一个模型、同一套工具、同一个 Docker 沙箱），区别只在「怎么交互」。两边的对话上下文相互独立，互不串。

只有一个 agent，但有多条相互独立的会话：CLI 一条、飞书一条，飞书里不同用户/群又各自分开（对应 group_sessions_per_user: true）。它们是同一个大脑下的不同「对话本子」，各记各的上下文，默认不共享。这样你在终端聊的内容不会串到飞书别人那边。

A附录 A：完整配置文件参考

A.1 ~/.hermes/config.yaml 完整示例

# ~/.hermes/config.yaml

# ==================== 模型配置 ====================
model:
  default: mimo-v2.5-pro
  provider: xiaomi
  base_url: https://token-plan-cn.xiaomimimo.com/v1

# 多 provider 配置
providers:
  xiaomi:
    base_url: https://token-plan-cn.xiaomimimo.com/v1
    models:
      - mimo-v2.5-pro             # 主力对话（纯文本）
      - mimo-v2-omni             # 多模态（能看图）
  anyrouter:
    base_url: https://anyrouter.top/v1
    models:
      - gpt-5.5                  # 复杂任务
      - gpt-5.4

# Vision 配置（可选，让 agent 能看图）
vision:
  model: mimo-v2-omni
  provider: xiaomi

# ==================== 终端 / Docker 沙箱 ====================
terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  timeout: 180
  docker_mount_cwd_to_workspace: true
  cwd: "/Users/你的用户名/hermes-workspace"   # gateway 模式必须写绝对路径
  docker_forward_env: []
  container_cpu: 2
  container_memory: 5120
  container_disk: 51200
  container_persistent: true
  docker_run_as_host_user: true

# ==================== 审批策略 ====================
approvals:
  mode: manual
  timeout: 60
  cron_mode: deny
  destructive_slash_confirm: true

command_allowlist:
  - ls
  - cat
  - git

# ==================== 飞书进阶（可选） ====================
group_sessions_per_user: true
# platforms:
#   feishu:
#     allow_bots: none
#     extra:
#       ws_reconnect_interval: 120
#       ws_ping_interval: 30
#       default_group_policy: "open"

# ==================== 安全（可选） ====================
security:
  allow_private_urls: false

A.2 ~/.hermes/.env 完整示例

# ~/.hermes/.env

# ==================== 模型密钥 ====================
# 小米 MiMo（Token Plan）
XIAOMI_API_KEY=tp-你的小米密钥
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1

# AnyRouter 中转站（GPT-5.5 / GPT-5.4）
ANYROUTER_API_KEY=sk-你的anyrouter密钥

# OpenRouter（可选，一个 Key 用多家模型）
# OPENROUTER_API_KEY=sk-or-v1-你的openrouter密钥
# OpenAI 直连（可选）
# OPENAI_API_KEY=sk-你的openai密钥

# ==================== 飞书 ====================
FEISHU_APP_ID=cli_xxxxxxxx
FEISHU_APP_SECRET=secret_xxxxxxxx
FEISHU_DOMAIN=feishu                 # 国内 feishu；国际版 lark
FEISHU_CONNECTION_MODE=websocket
# FEISHU_ALLOWED_USERS=df9e49e2      # 白名单（见 11.3）
# FEISHU_HOME_CHANNEL=oc_xxx         # /sethome 会自动写入

# ==================== 工具 ====================
# 浏览器路径（Mac 下 Chrome）
AGENT_BROWSER_EXECUTABLE_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

# ==================== 调试（默认关闭） ====================
WEB_TOOLS_DEBUG=false
VISION_TOOLS_DEBUG=false

B附录 B：hermes 命令速查

B.1 启动、安装与配置

常用 config set 示例：

# 切换默认模型
hermes config set model.default gpt-5.5
hermes config set model.provider anyrouter
# Docker 沙箱
hermes config set terminal.backend docker
hermes config set terminal.docker_mount_cwd_to_workspace true
hermes config set terminal.container_memory 5120
hermes config set terminal.container_cpu 2

B.2 模型、工具与网关

B.3 对话内斜杠命令与容器维护

C附录 C：Setup Wizard 选项速查

D附录 D：排错速查表

E附录 E：安全检查清单

• 始终在 ~/hermes-workspace 里启动 hermes
• terminal.backend = docker，docker_mount_cwd_to_workspace = true
• docker_forward_env 为空 []
• docker_run_as_host_user = true
• approvals.mode 初期设为 manual
• approvals.cron_mode = deny
• config.yaml 的 model 部分指向正确的 provider 和 base_url
• .env 中的 API Key 与 config.yaml 的 provider 匹配
• 给模型 API Key 设了用量上限
• 工作目录里不放敏感文件
• Computer Use (macOS) 工具未勾选