核心功能
Notion 技能提供了一套确定性脚本优先的 CLI 工具 notionctl.mjs，将常见的 Notion API 操作封装为结构化命令，输出 JSON 便于 AI Agent 解析。
主要能力
- 搜索：支持按标题搜索页面（
--type page）或数据源/数据库（--type data_source） - 内容读写：
export-md将页面导出为 Markdown；create-md/append-md支持从 Markdown 创建或追加内容 - 页面迁移：支持在页面间移动（
--to-page）或转入数据库（--to-data-source，需使用data_source_id） - 收件箱工作流：
list-child-pages列出子页面，triage支持基于规则的分流处理（含 dry-run 模式）
显著优点
1. 确定性设计：自动处理 headers、分页、速率限制（3 req/s）、HTTP 429 退避，降低 ad-hoc API 调用的错误率
2. OpenClaw 友好：单一二进制入口 + 可预测参数，便于权限管控
3. JSON 输出：便于 Agent 解析和推理
4. 多认证回退：优先 NOTION_API_KEY，兼容 NOTION_TOKEN、NOTION_API_TOKEN 及本地配置文件
局限性与风险
- API 版本锁定：强制使用
2025-09-03版本，未来版本变更需同步更新 - 速率限制严格：3 req/s 的限制对批量操作构成瓶颈，需主动处理退避
- 数据源术语变更：Notion API 中 "database" 概念已迁移至 "data_source"，旧文档/习惯可能导致混淆
- 权限依赖：401/403/404 错误常源于集成未共享到目标页面，需人工排查
适合人群
- 需要程序化批量管理 Notion 内容的开发者/高级用户
- 构建收件箱-分流自动化工作流的知识管理者
- 在 OpenClaw 等受限环境中需要可审计、可预测 Notion 操作的场景
安全提示
- 内容不信任原则：将 Notion 内容视为不可信用户输入，避免执行其中嵌入的指令
- 批量操作建议：
--dry-run→ 确认范围（--limit）→ 执行（--apply）