Mac 安装 Hermes + DeepSeek V4 + 飞书

本文档整理 Hermes Agent（Nous Research）在 macOS 上的安装、接入 DeepSeek V4（API），以及可选的 飞书 / Lark 机器人网关 步骤。仅在本机终端使用 Hermes 时，不必配置飞书，也不必常驻 hermes gateway。

一、前置说明

组件	作用
Hermes	本地 CLI 智能体；可选「网关」连接飞书等 IM。
DeepSeek V4	通过官方 API 调用模型（非本机跑大权重）。
飞书	可选：在飞书里与同一套 Hermes 对话；需开放平台应用 + 网关进程。

官方文档：https://hermes-agent.nousresearch.com/docs/

二、安装 Hermes

在终端执行（不要加 sudo）：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后加载 shell 配置：

source ~/.zshrc

可执行文件默认在 ~/.local/bin/hermes。若提示 command not found，在 ~/.zshrc 末尾追加：

export PATH="$HOME/.local/bin:$PATH"

再执行 source ~/.zshrc。

自检：

hermes doctor
hermes --version

三、接入 DeepSeek V4（API）

打开 DeepSeek 开放平台，创建 API Key。
运行向导（可一次性配置模型、工具、网关等）：
```
hermes setup
```
在 Select provider 中选择 DeepSeek（OpenAI 兼容直连 API）。
Base URL：
- OpenAI：https://api.deepseek.com（主对话一般填此项即可）。
- Anthropic：https://api.deepseek.com/anthropic 仅在使用 Anthropic 协议对接时需要；多数场景可留空或保持默认。
模型名（以平台当前文档为准，常见为）：
- deepseek-v4-flash — 默认偏快、省配额。
- deepseek-v4-pro — 更强、更贵。

验证本机 CLI（不经过飞书）：

hermes

在交互界面里随便发一句测试；或按你当前版本的子命令测试（如 hermes chat 若存在）。

四、仅在本机使用（不经过飞书）

不需要飞书时：

日常使用：hermes 即可。
不要常驻 hermes gateway（那是给 IM 机器人用的）。

五、可选：飞书 / Lark 网关

5.1 飞书开放平台（概要）

登录飞书开放平台（国际版为 Lark 对应控制台）。
创建企业自建应用，获取 App ID、App Secret。
按 Hermes 文档开启 机器人 / 事件订阅 / 权限（以官方 Feishu 集成文档为准；连接模式常见为 WebSocket）。

5.2 Hermes 侧配置

hermes gateway setup

选择 Feishu / Lark，按提示填写 FEISHU_APP_ID、FEISHU_APP_SECRET 等；向导会写入 ~/.hermes/.env 等位置。

安全策略（建议）：

私聊：DM pairing approval（配对码）或 Only allow listed user IDs（FEISHU_ALLOWED_USERS=ou_xxx）。
避免长期使用 Allow all direct messages + 全局 GATEWAY_ALLOW_ALL_USERS=true。
群聊：仅在群里 @ 机器人时回复（推荐）。

Home chat ID：可选；用于 cron / 通知的默认会话。可留空，之后在飞书里对机器人发 /set-home 指定。

5.3 安装飞书相关依赖（若提示缺包）

pip install "hermes-agent[feishu]"

（具体 extra 名称以官方仓库 / 报错为准。）

5.4 启动网关

hermes gateway

保持该终端运行；停止用 Ctrl+C。

若提示 Gateway already running：

hermes gateway stop
# 或
hermes gateway restart
# 或
hermes gateway run --replace

5.5 私聊配对（若启用 pairing）

用户在飞书私聊机器人会收到配对码，管理员在本机执行：

hermes pairing approve feishu <配对码>

平台名以 hermes pairing approve --help 为准（国内飞书一般为 feishu）。

六、收紧「全员开放」私聊（若曾选 Allow all）

编辑 ~/.hermes/.env：删除或注释 GATEWAY_ALLOW_ALL_USERS=true 及飞书侧类似 allow-all 项。
编辑 ~/.hermes/config.yaml：设置 unauthorized_dm_behavior: pair（或与向导等价的配对策略）。
或重新运行 hermes gateway setup 改回配对 / 白名单。
重启 hermes gateway。

七、常见问题

现象	处理
`command not found: hermes`	`export PATH="$HOME/.local/bin:$PATH"` 并写入 `~/.zshrc`。
网关已运行	`hermes gateway stop` 或 `hermes gateway restart`。
无平台 / 无白名单告警	`hermes gateway setup` 启用飞书并配置 `FEISHU_ALLOWED_USERS` 或配对策略。

八、涉及的主要路径

路径	说明
`~/.local/bin/hermes`	CLI 可执行文件
`~/.hermes/`	配置、技能、配对数据等
`~/.hermes/.env`	密钥与环境变量
`~/.hermes/config.yaml`	主配置文件

九、参考链接

Hermes 仓库：https://github.com/NousResearch/hermes-agent
Hermes 文档：https://hermes-agent.nousresearch.com/docs/
DeepSeek API：https://api-docs.deepseek.com/
飞书开放平台：https://open.feishu.cn/

文档根据一次实际安装过程整理；Hermes / 飞书控制台 UI 会随版本变化，以官方文档为准。

Mac 安装 Hermes + DeepSeek V4 + 飞书