第九章 安全与最佳实践

墨鱼很能干，但能力越大，责任越大。本章讲解 Hermes Agent 的七层安全防线，以及日常使用的最佳实践。

七层安全模型

Hermes Agent 采用纵深防御（Defense-in-Depth）架构：

┌─────────────────────────────┐
│  第 1 层：命令审批           │  ← 危险命令需人工确认
├─────────────────────────────┤
│  第 2 层：用户授权           │  ← Gateway 访问控制
├─────────────────────────────┤
│  第 3 层：容器隔离           │  ← Docker / 沙箱
├─────────────────────────────┤
│  第 4 层：终端后端安全       │  ← 后端选择与权限
├─────────────────────────────┤
│  第 5 层：环境变量隔离       │  ← 密钥管理
├─────────────────────────────┤
│  第 6 层：网络传输安全       │  ← TLS / WebSocket
├─────────────────────────────┤
│  第 7 层：数据存储安全       │  ← 本地加密、权限
└─────────────────────────────┘

---

命令审批系统

Agent 执行终端命令前，会检查是否匹配危险模式。如果匹配，需要用户显式批准。

审批模式

# ~/.hermes/config.yaml
approvals:
  mode: default    # default | off

模式	行为
default	危险命令弹出审批提示
off	禁用所有安全提示（仅 CI/CD、容器等受信环境）

YOLO 模式

临时跳过所有危险命令审批：

/yolo          # 切换开/关

或启动时启用：

hermes --yolo

危险

YOLO 模式会禁用所有命令安全检查。仅在完全信任命令的环境中使用（如一次性容器、测试环境）。

审批超时

# ~/.hermes/config.yaml
approvals:
  timeout: 300    # 默认 300 秒，超时自动拒绝（fail-closed）

审批流程

CLI 模式：行内提示，输入 y/n

Gateway/聊天模式：发送交互式卡片，用户点击按钮：

• Allow Once — 本次允许
• Session — 本次会话允许
• Always — 永久加入白名单
• Deny — 拒绝

永久白名单

# ~/.hermes/config.yaml
approvals:
  allowlist:
    - "git push"
    - "npm test"

白名单中的命令模式不会触发审批。

---

用户授权（Gateway）

授权检查顺序

1. 检查 GATEWAY_ALLOW_ALL_USERS
   ↓ 如果为 false
2. 检查 GATEWAY_ALLOWED_USERS（用户 ID 列表）
   ↓ 如果不匹配
3. 检查 DM 配对记录
   ↓ 如果未配对
4. 拒绝访问

平台级 Allowlist

可以为不同平台设置不同的允许用户：

# 全局
GATEWAY_ALLOWED_USERS=user_a,user_b

# 平台专属
TELEGRAM_ALLOWED_USERS=123456789
DISCORD_ALLOWED_USERS=987654321

DM 配对系统

最推荐的方式。新用户 DM 机器人时收到配对码，你在 CLI 中确认即可：

hermes gateway pair <code>

配对码特性：加密随机、1小时有效、速率限制。

---

容器隔离

在 Docker、Singularity、Modal 等容器后端中运行时，危险命令检查自动跳过——容器本身就是安全边界，容器内的破坏性命令不会影响宿主机。

Docker 安全配置

hermes --backend docker

Docker 运行时的安全标志：

• 只读根文件系统
• 禁止特权升级
• 资源限制（CPU、内存）

资源限制

# ~/.hermes/config.yaml
container:
  memory: 2g
  cpus: 2

---

环境变量安全

密钥管理原则

1. 永远不要在聊天中输入密钥 — 使用 hermes setup 或编辑 ~/.hermes/.env
2. 不要把 .env 提交到 Git — 确保 .gitignore 包含 .env
3. 使用最小权限原则 — API Key 只给必要的权限

环境变量传递

Skill 声明的环境变量会自动传递给 execute_code 和 terminal 沙箱。非 Skill 的环境变量需要显式配置：

# ~/.hermes/config.yaml
terminal:
  env_passthrough:
    - MY_CUSTOM_VAR

---

最佳实践清单

安装阶段

• [ ] 使用最新版本的 Hermes Agent
• [ ] 在独立目录安装，不与其他项目混合
• [ ] 确保 Python 虚拟环境隔离
• [ ] 验证 hermes doctor 输出无错误

配置阶段

• [ ] 不要使用 GATEWAY_ALLOW_ALL_USERS=true（除非本地测试）
• [ ] 配置 GATEWAY_ALLOWED_USERS 或启用 DM 配对
• [ ] API Key 存放在 ~/.hermes/.env，权限设为 600
• [ ] 审批模式保持 default，不要设为 off

运行阶段

• [ ] 定期更新：hermes update
• [ ] 定期检查 hermes gateway status
• [ ] 检查 Cron 任务输出日志
• [ ] 审查 Agent 自动创建的 Skill 内容

多用户环境

• [ ] 每个 Agent 实例使用独立的 HERMES_HOME
• [ ] 不同用户使用不同的 Allowlist
• [ ] 敏感操作设置审批超时
• [ ] 定期审查白名单中的命令模式

---

常见安全问题

场景	风险	建议
在公网 VPS 运行 Gateway	任何人可能联系到你的 Bot	配置 Allowlist + DM 配对
使用 --yolo 模式	Agent 可执行任意命令	仅在容器中使用
API Key 泄露	他人可冒用你的配额	定期轮换 Key，检查用量
多人共用 Bot	一个人可影响所有人的会话	使用 Profile 隔离
Cron 执行失败	任务静默失败	检查 cron/output/ 日志

深入阅读

• 官方文档：Security
• Docker 运行：Hermes Agent Docker
• FAQ 与故障排查：FAQ & Troubleshooting

---