name: notion-sync-obsidian description: 自動將Notion文章同步到本地Obsidian目錄，支援定時檢查、完整內容匯出、智慧標題提取。 homepage: https://github.com/openclaw/openclaw metadata: {"clawdbot":{"emoji":"📝"}}

notion-sync-obsidian

7w4.net有更好的技能外掛。

自動將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配置

1. 訪問 https://notion.so/my-integrations 建立整合
2. 複製API金鑰（以 ntn_ 開頭）
3. 將整合分享到你的Notion工作空間
4. 在 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: 檢查程序狀態，可能需要重啟定時器

除錯步驟

1. 執行 ./scripts/debug_page_structure.py 檢查API連線
2. 執行 FORCE_CHECK=1 ./scripts/simple_checker.sh 手動測試
3. 檢查 sync_timer.log 日誌檔案
4. 驗證配置檔案路徑和許可權

📈 高階用法

自定義匯出格式

修改 real_notion_checker.py 中的 export_page_to_markdown 函式來自定義Markdown格式。

整合到其他系統

指令碼輸出標準化格式，可輕鬆整合到： - CI/CD流水線 - 其他自動化工具 - 自定義監控系統

擴充套件功能

1. 標籤同步: 同步Notion標籤到Obsidian標籤
2. 圖片下載: 自動下載文章中的圖片
3. 雙向同步: 支援從Obsidian同步回Notion
4. 多資料庫: 支援同步多個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 (你的私人助理)
狀態: ✅ 生產就緒

這是一個功能相對完整的 Notion 同步工具，文件說明詳細，但部分文件內容有重複，且說明中提到的一些檔案實際缺失。對於需要將 Notion 文章備份到本地 Obsidian 的使用者來說基本可用，但建議先仔細閱讀安裝說明，確保理解配置流程後再使用。