notion-sync-obsidian
自动将Notion文章同步到本地Obsidian目录的完整解决方案。支持定时检查、完整内容导出、智能标题提取、移动端优化通知。
✨ 功能特性
✅ 核心功能
- 自动同步: 定时检查Notion更新并同步到本地Obsidian目录
- 完整导出: 导出文章标题、元数据、完整内容
- 智能标题: 自动识别文章原始标题（非摘要内容）
- 移动通知: 移动端优化格式，只在有更新时通知
✅ 高级特性
- 定时检查: 可配置检查频率（默认15分钟）
- 安静时段: 支持配置安静时段（默认00:00-08:30）
- 强制检查: 支持用户手动触发检查，忽略安静时段
- 增量同步: 基于时间戳避免重复导出
- 错误处理: 完善的错误处理和日志记录
✅ 技术特性
- Python支持: 使用Python requests库进行完整API调用
- 环境兼容: 自动处理Python依赖安装
- 配置灵活: 支持自定义API密钥、导出目录、检查频率
- 跨平台: 支持Linux/macOS/Windows（容器环境已验证）
🚀 快速开始
1. 前置要求
- Notion API密钥（从 https://notion.so/my-integrations 获取）
- Obsidian目录路径
- Python 3.6+（可选，用于完整内容导出）
2. 基础配置
# 1. 进入skill目录
cd ~/.openclaw/workspace/skills/notion-sync-obsidian
# 2. 编辑配置文件
nano config.json
配置文件示例 (config.json):
{
"notion": {
"api_key": "ntn_your_api_key_here",
"api_version": "2022-06-28"
},
"obsidian": {
"root_dir": "/path/to/your/obsidian/notion"
},
"sync": {
"check_interval_minutes": 15,
"quiet_hours_start": "00:00",
"quiet_hours_end": "08:30",
"enable_notifications": true
}
}
3. 启动同步系统
# 启动定时同步（每15分钟检查一次）
./scripts/start_timer.sh
# 手动检查（忽略安静时段）
FORCE_CHECK=1 ./scripts/simple_checker.sh
# 查看状态
./scripts/status_timer.sh
# 停止同步
./scripts/stop_timer.sh
📁 目录结构
notion-sync-obsidian/
├── SKILL.md # 技能说明文档
├── config.json # 配置文件模板
├── scripts/ # 核心脚本
│ ├── real_notion_checker.py # 完整Python检查器
│ ├── simple_checker.sh # 简化Shell检查器
│ ├── timer_checker.sh # 定时检查器
│ ├── start_timer.sh # 启动定时器
│ ├── stop_timer.sh # 停止定时器
│ ├── status_timer.sh # 查看状态
│ ├── list_recent_articles.sh # 列出最近文章
│ └── debug_page_structure.py # 调试页面结构
├── references/ # 参考文档
│ └── NOTION_API_GUIDE.md # Notion API使用指南
└── examples/ # 示例文件
└── exported_article.md # 导出文件示例
🔧 详细配置
Notion API配置
- 访问 https://notion.so/my-integrations 创建集成
- 复制API密钥（以
ntn_开头） - 将集成分享到你的Notion工作空间
- 在
config.json中配置API密钥
导出目录配置
- 默认路径:
/hellox/openclaw/obsidian/notion/ - 组织结构: 按年月分目录
YYYY-MM/ - 文件命名: 使用文章原始标题，特殊字符自动过滤
定时检查配置
- 检查频率: 默认15分钟，可配置
- 安静时段: 默认00:00-08:30，避免夜间打扰
- 强制模式:
FORCE_CHECK=1环境变量忽略所有限制
🛠️ 脚本说明
核心脚本
real_notion_checker.py: 完整Python检查器，导出完整内容simple_checker.sh: 简化Shell检查器，快速检查更新timer_checker.sh: 定时检查器，管理定时任务
管理脚本
start_timer.sh: 启动定时同步系统stop_timer.sh: 停止定时同步系统status_timer.sh: 查看系统状态和日志list_recent_articles.sh: 列出Notion最近文章
调试脚本
debug_page_structure.py: 调试Notion页面结构test_title_fix.py: 测试标题提取修复
📊 系统状态
查看状态
./scripts/status_timer.sh
输出示例:
📊 Notion定时同步状态检查
检查时间: 2026-02-24 15:44:53
时区: Asia/Shanghai
========================================
🟢 状态: 运行中
进程PID: 4538
运行时间: 10:29
📋 日志信息:
日志文件: ./sync_timer.log
日志行数: 1179
📁 目录状态:
文章目录: /hellox/openclaw/obsidian/notion
文章数量: 78
⏰ 下次检查时间:
15:59 (15分钟后)
查看日志
tail -f sync_timer.log
🔍 故障排除
常见问题
Q: 同步失败，提示API错误 A: 检查API密钥是否正确，确保集成已分享到工作空间
Q: 文件名使用摘要而非标题
A: 这是已知问题，已修复。确保使用最新版本的 real_notion_checker.py
Q: Python依赖安装失败 A: 容器环境可能需要特殊处理，脚本已包含自动安装逻辑
Q: 定时器不运行 A: 检查进程状态，可能需要重启定时器
调试步骤
- 运行
./scripts/debug_page_structure.py检查API连接 - 运行
FORCE_CHECK=1 ./scripts/simple_checker.sh手动测试 - 检查
sync_timer.log日志文件 - 验证配置文件路径和权限
📈 高级用法
自定义导出格式
修改 real_notion_checker.py 中的 export_page_to_markdown 函数来自定义Markdown格式。
集成到其他系统
脚本输出标准化格式，可轻松集成到：
- CI/CD流水线
- 其他自动化工具
- 自定义监控系统
扩展功能
- 标签同步: 同步Notion标签到Obsidian标签
- 图片下载: 自动下载文章中的图片
- 双向同步: 支持从Obsidian同步回Notion
- 多数据库: 支持同步多个Notion数据库
🤝 贡献指南
欢迎贡献代码、报告问题或提出建议！
开发环境
# 克隆仓库
git clone https://github.com/your-username/notion-sync-obsidian.git
# 安装依赖
pip install -r requirements.txt
# 运行测试
python -m pytest tests/
代码规范
- 遵循PEP 8 Python代码规范
- 添加适当的注释和文档
- 编写单元测试
- 更新CHANGELOG.md
📄 许可证
MIT License - 详见 LICENSE 文件
🙏 致谢
- Notion官方API文档
- OpenClaw社区
- 所有贡献者和用户
版本: 1.0.0
最后更新: 2026-02-24
维护者: kk (你的私人助理)
状态: ✅ 生产就绪