Hermes Agent 接入外部服务：API Key 配置 + Notion 实战

Docker 部署 Hermes Agent 后接入 Notion、微信读书、DeepSeek 等外部服务，核心就一步：让 API Key 从宿主机进到工具容器。

架构

Hermes Docker 部署有两层容器：

**网关容器**：跑 Hermes 主程序，负责消息路由

**工具容器**：动态创建，实际执行 terminal、API 调用

Key 传递链路：`宿主机 .env → 网关容器(env_file 加载) → 工具容器(自动透传)`

配置

docker-compose.yml

```yaml

services:

hermes:

env_file:

- .env

```

.env

放在 compose 同级目录：

```

NOTION_API_KEY=ntn_xxxxxxxxxxxx

WEREAD_API_KEY=xxxxxxxxxxxx

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx

```

修改 `.env` 后**重新构建**（不是 restart）：

```bash

docker compose down && docker compose up -d

```

不需要 `docker_forward_env`。env_file 已正确配置时，Key 自动注入网关容器并透传到工具容器。

极空间注意

**env_file 用相对路径**：`- .env`，不要写 `/tmp/zfsv3/...` 绝对路径

**volumes 路径**：用 Compose UI 的「查询路径」按钮获取，不要手写 SSH 路径

**改 .env 后**：点「重新构建」或 `docker compose down && up -d`，不要只用 restart

接入 Notion

[notion.so/my-integrations](https://notion.so/my-integrations) → New Integration（类型选 **Internal**）→ 复制 `ntn_` 开头的 token

每个要访问的 Notion 页面 → 右上角 `...` → Connect to → 选你的 Integration

Token 写入 `.env`，重新构建

验证：`echo $NOTION_API_KEY | head -c 10`

为什么不用 MCP

Notion 官方 MCP Server 走 OAuth 回调 `localhost`。Docker 容器的 `127.0.0.1` 是容器自己的，宿主机浏览器点完授权回调到不了容器。Internal Integration Token + REST API 最稳定。

常见坑

**env_file 不生效** → 写了绝对路径。改为相对路径 `- .env`

**改配置后 Key 还是空** → 只 restart。必须 `down && up -d`

**Notion 返回 404** → 页面没 Connect Integration。去页面 Connect

**微信读书 API 调不通** → Key 含特殊字符，shell curl 转义断裂。用 Python urllib.request

**加了 docker_forward_env 也没用** → env_file 本身就没生效，先修 env_file

验证

```bash

echo $NOTION_API_KEY | head -c 10

# 应输出: ntn_25...

```