给 Hermes Agent 配置 Notion 集成：从踩坑到跑通

icon

网址

type

Post

status

Published

date

Jun 1, 2026

slug

hermes-agent-notion-docker-integration

summary

通过 Docker 部署 Hermes Agent 并使用 Notion Internal Integration Token，实现了在容器内安全、稳定地读写 Notion 页面。文章详细阐述了四大坑：OAuth 回调被容器拦截、Composio 401 错误、env_file 路径不匹配以及变量检测误报，并提供了对应的解决方案，包括在宿主机创建 .env 文件并在 docker‑compose 中使用 env_file、正确共享页面给 Integration、以及使用 curl 验证 token。最终给出四步配置流程，确保 Hermes 在 Docker 环境下顺利访问 Notion。

背景

Hermes Agent 是 Nous Research 开源的 AI Agent 框架，能跑在终端、Telegram、Discord 等十几个平台上，支持任意 LLM。我把它部署在 Docker 里，通过 Telegram 日常使用。

目标很简单：让 Hermes 能直接读写我的 Notion 页面——搜索笔记、创建文档、查询数据库。

听起来不难对吧？Notion 有官方 API，Hermes 有 Notion 技能模块。结果我踩了四个坑。

第一坑：OAuth MCP，回调被 Docker 吞了

最直觉的方案是用 Notion 官方的 MCP Server（@notionhq/notion-mcp-server）。它走 OAuth 授权，在本地跑的时候体验很好——浏览器弹出授权页，点一下就行。

但在 Docker 容器里？完蛋。

OAuth 的回调地址是 http://127.0.0.1:PORT/callback，这个 127.0.0.1 指的是容器内部的 localhost，不是你的宿主机。你在宿主机浏览器里点完授权，回调永远到不了容器里的 MCP Server。

教训：Docker 里跑的任何 OAuth + localhost 回调的方案都会挂。

第二坑：Composio MCP，401 伺候

Composio（connect.composio.dev/mcp）走 HTTP MCP，理论上没 OAuth 问题。但注册完新账号后一直 401。

后来才发现：2026 年 3 月之后的 Composio 新账号，必须先去 dashboard.composio.dev 完成 Getting Started 引导，API Key 才会被激活。不完成这一步，key 看起来正常但永远是 401。

我跳过了。

第三坑：env_file 的路径迷思

既然 MCP 都行不通，那就回归最朴素的方式——Notion Internal Integration Token + 直接 API 调用。Hermes 自带的 productivity/notion 技能模块原生支持这条路。

步骤：

去 notion.so/my-integrations 创建一个 Integration，拿到 ntn_ 开头的 token

在 Notion 里把目标页面 Share → Connect to → 你的 Integration

把 token 写进 ~/.hermes/.env：NOTION_API_KEY=ntn_xxx

但问题是：Docker 容器里的 ~/.hermes/.env 跟宿主机的不是同一个文件！

我的 docker-compose.yml 挂载了数据卷：

但 Hermes 读的是 ~/.hermes/.env（容器内的 home 目录），不是 /opt/data/.env。写在宿主机 ~/.hermes/.env 里的 token，容器根本看不见。

正确做法是在 docker-compose.yml 里用 env_file：

Docker 会读取宿主机的 .env 文件，把里面的变量注入到容器环境。

第四坑：变量明明配了，检测却说没有

改完 env_file 重启容器后，terminal 里 echo $NOTION_API_KEY 能打出来，但 Hermes 会话里用检测脚本却返回空值。

原来是我的 shell 检测写法有问题——2>/dev/null 配合条件判断在特定上下文里误报了空值。实际上变量一直都在，只需要直接用 curl 调 Notion API 验证就行。

正确的验证方式：

最终方案：四步走

总结下来，Docker 部署的 Hermes 接入 Notion 的正确姿势：

Step 1：创建 Integration Token

去 notion.so/my-integrations → New Integration → 复制 ntn_ token

Step 2：分享页面给 Integration

在 Notion 里，对每个你要访问的页面/数据库，右上角 ... → Connect to → 选你的 Integration

Step 3：配置 env_file

docker-compose.yml 里加：

并在宿主机 ~/.hermes/.env 里写入：

Step 4：重启容器

搞定。Hermes 现在能搜、能读、能写 Notion 了。

为什么不用 MCP？

坦白讲，如果你不是 Docker 部署，Notion 官方 MCP 是个好选择——比直接 API 调用省约 91% 的 token。但 Docker + OAuth 的组合目前就是个死结。

Internal Integration Token 方案虽然朴素，但胜在稳。没有回调、没有跳转、没有额外的服务进程。一把 token 走天下。