附录

本地安全运行指南

在 Mac 上用 Apple Container 搭建隔离的 Hermes Agent 环境——进程 VM 级隔离、对外暴露 API、数据不出本机。

预计阅读时间：15 分钟 · 前置：模块 2

📑 本附录目录

快速开始
方案概述
分层架构
完整搭建流程
调用方法
安全设计
运维命令
常见问题

0 快速开始

# 1. 安装 Apple container（macOS 15+ / Apple 芯片）
brew install --cask container
container system start


# 2. 建数据目录
mkdir -p ~/.hermes


# 3. 交互式配置模型
container run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup


# 4. 配置 API Server（追加到 ~/.hermes/.env）
API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642
API_SERVER_KEY=<你的随机密钥>


# 5. 启动容器
container run -d --name hermes -c 4 -m 8G \
  -v ~/.hermes:/opt/data \
  -p 127.0.0.1:9119:9119 -p 127.0.0.1:8642:8642 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run


# 6. 使用
#   Web 控制台：http://localhost:9119
#   API：       http://localhost:8642/v1

1 方案概述

目标	本地搭建可隔离、可编程调用的 AI Agent 执行环境
底座	Apple container（轻量 VM）运行 Hermes Agent，进程 VM 级隔离
接口	OpenAI 兼容 API（`http://127.0.0.1:8642/v1`），任意 OpenAI SDK 直连
模型	可接任何 OpenAI 兼容端点（OpenRouter / Anthropic / 自定义网关 / 本地模型）
能力	Agent 能真正调工具（终端 / 文件 / 浏览器）执行任务
入口	HTTP API + Web Dashboard + 飞书/Telegram 等消息平台

2 分层架构

flowchart TD A["调用方
Python SDK / curl / 自动化流程"] --> B["接入层
API Server :8642 / Dashboard :9119"] B --> C["Agent 运行时
Hermes Agent
工具调用 · 推理 · 记忆"] C --> D["隔离层
Apple Container (VM)
仅挂载 ~/.hermes"] D --> E["宿主机 macOS"]

3 完整搭建流程

3.1 前提：安装 Apple container

需要 macOS 15+ / Apple 芯片。

brew install --cask container
container --version  # 应 ≥ 1.0
container system start  # 首次启动系统

3.2 建数据目录

mkdir -p ~/.hermes

配置、密钥、会话、Agent 自装依赖全落在这里。容器删了也不丢。备份整个 ~/.hermes 即可迁移。

3.3 交互式配置模型

container run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup

向导关键选择：

Provider → 选你用的（OpenRouter / Anthropic / Custom 等）
如果用自定义端点（如内网模型网关或本地 Ollama）→ 选 Custom OpenAI-compatible endpoint，填 base_url + API key + 模型名
其余（TTS/图像/消息平台）可先 Skip

配置写到 ~/.hermes/config.yaml 和 ~/.hermes/.env。

3.4 开启 Dashboard 认证

编辑 ~/.hermes/config.yaml，加入：

dashboard:
  basic_auth:
    username: 'admin'
    password_hash: 'scrypt$...'

生成密码哈希：

container run --rm nousresearch/hermes-agent \
  python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('<你的密码>'))"

3.5 开启 API Server

在 ~/.hermes/.env 追加：

# OpenAI-Compatible API Server
API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642
API_SERVER_KEY=<你的随机长字符串>

生成随机 key：openssl rand -base64 32，调 API 时当 Bearer token 用。

3.6 启动容器

container rm -f hermes 2>/dev/null
container run -d \
  --name hermes \
  -c 4 -m 8G \
  -v ~/.hermes:/opt/data \
  -p 127.0.0.1:9119:9119 \
  -p 127.0.0.1:8642:8642 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

⚠ 各参数说明：

`-c 4 -m 8G`	必须带。默认只给 1GB 内存，Agent 跑任务会卡死
`-p 127.0.0.1:...`	绑 127.0.0.1 只允许本机访问，不暴露给局域网
`-e HERMES_DASHBOARD=1`	开启 Web 控制台

改了 .env 必须 rm 重建：container start 不会重读环境变量。

4 调用方法

🔑 接入信息

Base URL: http://127.0.0.1:8642/v1 · API Key: 你配的 API_SERVER_KEY · Model: hermes-agent

同步请求

curl http://127.0.0.1:8642/v1/chat/completions \
  -H "Authorization: Bearer <API_SERVER_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"hermes-agent","messages":[{"role":"user","content":"你的任务"}],"stream":false}'

Python SDK

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8642/v1", api_key="<API_SERVER_KEY>")
r = client.chat.completions.create(
    model="hermes-agent",
    messages=[{"role": "user", "content": "任务描述"}])
print(r.choices[0].message.content)

会话连续性

每次请求带同一个 X-Hermes-Session-Id header，Agent 就能续在同一会话里：

curl ... -H "X-Hermes-Session-Id: my-chat-001" ...

# Python SDK
r = client.chat.completions.create(
    model="hermes-agent",
    messages=[...],
    extra_headers={"X-Hermes-Session-Id": "my-chat-001"})

5 安全设计

进程隔离	Agent 跑在 Apple Container（VM）内，宿主机文件系统不可达
文件边界	仅挂载 `~/.hermes` 一个目录，Mac 其他文件碰不到
网络封闭	API/Dashboard 端口只绑 127.0.0.1，局域网不可访问
密钥本地	配置与凭证全部存本地 `~/.hermes`，不上传第三方

⚠ 安全提醒：~/.hermes/.env 和 config.yaml 里包含你的 API key 和密码。不要把这些文件或真实凭证分享出去。本文档中所有示例均为通用占位符，不含真实凭证。

6 常用运维命令

container ls                 # 查看运行中的容器
container logs -f hermes      # 实时日志
container stop hermes        # 停止
container start hermes       # 启动（不重读 .env）
container rm -f hermes       # 删除容器（配置保留）
container exec -it hermes bash  # 进入容器排查

# 健康检查
curl -s http://127.0.0.1:9119/api/status | python3 -m json.tool

7 常见问题

Q: localhost:8642/9119 连不上？

确认启动命令带了对应的 -p 端口映射，且 container logs hermes 没报错。Dashboard 是 9119，API 是 8642。

Q: Dashboard 拒绝启动？

没配认证。按 3.4 节填 basic_auth 用户名 + 密码哈希后重建容器。

Q: 执行任务很卡？

内存不够。确认启动带了 -m 8G（默认才 1G）。

Q: 改了 .env 不生效？

container start 不会重读环境变量。需要 container rm -f hermes 然后重新 container run。

Q: 重启后容器 IP 变了？

正常。Apple container IP 每次重启重分配。用 -p 127.0.0.1:端口:端口 映射后，始终用 localhost 访问即可。

← 模块 10：进阶特性