需配置Notion Integration API Key并启用双向同步：一、创建Integration获取Token并授权数据库读写；二、通过.env注入NOTION_INTEGRATION_TOKEN；三、在config.yaml绑定database_id及字段映射；四、部署Webhook实现变更实时回传。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望将HermesAgent与Notion数据库打通，实现任务状态自动更新与笔记内容反向写入，则需正确配置Notion Integration API Key，并启用双向同步机制。以下是完成该集成的具体操作步骤：
一、创建Notion Integration并获取API Key
Notion通过Integration方式授权第三方应用访问指定数据库，HermesAgent需使用其提供的Bearer Token进行身份认证。该密钥必须具备对应数据库的读写权限，否则同步任务将因401或403错误中断。
1、登录Notion网页端，进入设置与成员 → Integrations → Develop your own integration。
2、填写Integration名称（如“HermesAgent-Tasks”），选择“Personal bot”类型，点击Submit。
3、在新生成的Integration详情页中，复制Internal Integration Token字段值（格式为secret_开头的长字符串）。
4、在Integration权限设置中，点击“Add a database”，搜索并添加目标任务数据库，勾选Read content与Write content两项权限。
5、点击Save changes并确认权限已生效。
二、在HermesAgent中配置Notion API Key
HermesAgent支持通过环境变量注入Notion密钥，该方式优先级高于配置文件，且避免敏感信息硬编码。密钥加载后，Agent内部的notion_sync模块将自动初始化HTTP客户端并验证连接可用性。
1、进入HermesAgent项目根目录，检查是否存在.env文件；若无，则新建一个。
2、在.env文件末尾新增一行：NOTION_INTEGRATION_TOKEN=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx，注意等号前后无空格。
3、确保该.env文件位于执行python main.py命令的当前工作目录下。
4、重启HermesAgent服务进程，使环境变量重新加载；若使用systemd管理，执行sudo systemctl restart hermes。
三、绑定Notion数据库ID并启用双向同步
数据库ID是Notion中唯一标识某张表的字符串，HermesAgent需据此定位目标表格并建立字段映射关系。双向同步依赖于预设的字段名约定：Task Name、Status、Due Date、Notes四个字段为必需项，缺失任一将导致同步失败。
1、打开目标Notion数据库页面，在浏览器地址栏URL中截取最后一段UUID，即为Database ID（格式类似8a4b2c1d-ef56-7890-g1h2-i3j4k5l6m7n8）。
2、在HermesAgent配置文件config.yaml中定位notion节点，填入以下内容：
notion:
database_id: "8a4b2c1d-ef56-7890-g1h2-i3j4k5l6m7n8"
sync_direction: "bidirectional"
field_mapping:
task_name: "Task Name"
status: "Status"
due_date: "Due Date"
notes: "Notes"
3、确认YAML缩进为两个空格，不得使用Tab字符，否则解析时抛出yaml.scanner.ScannerError。
4、保存config.yaml后，执行hermes sync --source notion --mode full触发首次全量同步。
四、配置Webhook实现实时状态回传
Notion原生不支持主动推送变更事件，需借助第三方服务（如Zapier或自建FastAPI微服务）监听数据库变更，并通过HermesAgent暴露的HTTP端点回调更新内存状态。该机制绕过轮询，降低延迟与API调用频次。
1、启动HermesAgent时确保--webhook-enabled参数已启用，或在config.yaml中设置webhook: enabled: true。
2、在config.yaml中指定webhook_secret（任意32位随机字符串），用于校验回调请求签名。
3、部署轻量Webhook接收器（如Cloudflare Workers），将Notion数据库变更事件POST至HermesAgent的/webhook/notion端点，Header中携带X-Hermes-Secret头，值为前述webhook_secret。
4、接收器需将Notion事件中的page_id、properties字段结构化为JSON，按HermesAgent文档定义的schema提交。
