name: notion description: Notion API for creating and managing pages, databases, and blocks. Also includes 想法點子庫（💡）持久化 workflow，當用戶說"入庫"、"記錄這個想法"、"這個先記下來"、"持久化這個"時觸發。 homepage: https://developers.notion.com metadata: {"clawdbot":{"emoji":"📝"}}

notion

Use the Notion API to create/read/update pages, databases, and blocks.

Setup

mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key

Integration API key starts with ntn_ or secret_. Share target pages/databases with your integration (click "..." → "Connect to" → your integration name).

API Version Decision Tree

Critical: Wrong version = silent failures.

Always include Notion-Version header. Default in this skill: 2025-09-03.

Quick Reference Cheatsheet

NOTION_KEY=$(cat ~/.config/notion/api_key)

# Search
curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "keywords"}'

# Get page
curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

# Query database (newer endpoint, use data_source_id)
curl -s -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"sorts": [{"property": "建立時間", "direction": "descending"}], "page_size": 20}'

# Create page (use database_id as parent, version 2022-06-28)
curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"parent": {"database_id": "xxx"}, "properties": {"Name": {"title": [{"text": {"content": "Title"}}]}}}'

# Update page properties
curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

Parse response (Python):

import subprocess, json
result = subprocess.run(['curl', '-s', ...], capture_output=True, text=True)
data = json.loads(result.stdout)
page_id = data.get('id')
error = data.get('message')  # if 'object' == 'error'

💡 想法點子庫

資料庫 ID: 339d8e39-9e68-814b-8fc9-c06adfb3ae00 里程碑資料庫 ID: 339d8e39-9e68-8130-932c-ecf46af154b5 父頁面: Winnie (321d8e39-9e68-8037-9c2f-d55fd4e9a54c)

資料庫欄位

里程碑資料庫欄位

入庫流程（觸發詞: "入庫"/"記錄這個想法"/"持久化這個"）

1. 從訊息提取：時間戳 → 標題（≤20字） → 摘要 → 決策結論 → 來源/狀態/重要性
2. 組裝 JSON（見下方模板）
3. 呼叫確認指令碼：python3 ~/.openclaw/skills/notion/scripts/notion-write-idea.py create < idea.json
4. 指令碼展示內容 → 使用者輸入 y 確認 → 才寫入 Notion
5. 寫入後腳本自動驗證並返回 Notion 頁面連結

入庫 API

不直接調 curl，統一走指令碼確保確認環節：

cat > /tmp/idea.json << 'EOF'
{
  "名稱": "無頭伺服器網站登入解法",
  "想法摘要": "agent-browser在無頭伺服器無法登入需驗證碼網站。解法：Cookie匯入、Xvfb虛擬顯示器、本地登入匯出session。",
  "決策結論": "優先試方案1（Cookie匯入），最可行。",
  "來源": "臨時想法",
  "相關專案": "agent-browser",
  "標籤": ["伺服器部署", "Cookie匯入"],
  "狀態": "待實現",
  "重要性": "中",
  "建立時間": "2026-04-04T22:38:00+08:00"
}
EOF

python3 ~/.openclaw/skills/notion/scripts/notion-write-idea.py create < /tmp/idea.json

想法→計劃 轉化流程

觸發詞: "轉計劃"、"開始規劃"、"這是個好想法"

1. 讀取想法頁面的 page_id
2. 展示並確認"規劃內容"（想法→計劃的推導）
3. 更新想法狀態為"已規劃"（規劃內容欄位填入推導）
4. 使用者確認後才寫入

建立里程碑（觸發詞: "添加里程碑"/"新建里程碑"）

cat > /tmp/milestone.json << 'EOF'
{
  "里程碑標題": "方案1測試：Cookie匯入",
  "所屬想法ID": "想法頁面的page_id",
  "處理過程": "測試EditThisCookie匯出Chrome Cookie，匯入agent-browser",
  "決策記錄": "Cookie匯入可行，但B站登入態有效期僅24h，需定期重新整理",
  "產物連結": "https://github.com/...",
  "狀態": "進行中",
  "建立時間": "2026-04-05T13:00:00+08:00"
}
EOF

python3 ~/.openclaw/skills/notion/scripts/notion-write-milestone.py create < /tmp/milestone.json
7w4.net小蔥技能站，你的AI助手技能庫。

更新狀態（觸發詞）

查詢所有想法（按時間倒序）

curl -s -X POST "https://api.notion.com/v1/data_sources/339d8e39-9e68-814b-8fc9-c06adfb3ae00/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"sorts": [{"property": "建立時間", "direction": "descending"}], "page_size": 20}'

查詢某想法的里程碑

curl -s -X POST "https://api.notion.com/v1/data_sources/339d8e39-9e68-8130-932c-ecf46af154b5/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"property": "所屬想法", "relation": {"contains": "想法page_id"}}}'

Operations

Search pages and data sources

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "keywords", "filter": {"value": "page", "property": "object"}}'

Get page

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

Get page blocks

curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

Create database

curl -s -X POST "https://api.notion.com/v1/databases" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "page_id", "page_id": "xxx"},
    "title": [{"text": {"content": "Database Title"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
      "Date": {"date": {}}
    }
  }'

Add blocks to page

curl -s -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"children": [{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Text"}}]}}]}'

Property Types

Key Differences (2025-09-03 vs 2022-06-28)

• Databases → Data Sources: Query uses /data_sources/ endpoint; create uses /databases
• Two IDs: Each database has database_id (for creating pages) and data_source_id (for querying)
• Creating databases: Only 2022-06-28 works reliably — 2025-09-03 silently drops custom properties
• Creating pages: Either version works, but 2022-06-28 is more predictable

Error Handling

import subprocess, json

def notion_req(method, endpoint, body=None, version="2025-09-03"):
    key = open("/root/.config/notion/api_key").read().strip()
    cmd = ["curl", "-s", "-X", method,
           f"https://api.notion.com/v1/{endpoint}",
           "-H", f"Authorization: Bearer {key}",
           "-H", f"Notion-Version: {version}",
           "-H", "Content-Type: application/json"]
    if body:
        import json
        cmd += ["-d", json.dumps(body)]
    r = subprocess.run(cmd, capture_output=True, text=True)
    data = json.loads(r.stdout)
    if data.get("object") == "error":
        raise Exception(f"Notion API error {data.get('code')}: {data.get('message')}")
    return data

Common error codes: - object_not_found: 頁面/資料庫 ID 不存在或無權訪問 - validation_error: 屬性格式錯誤，檢查 property type 是否匹配 - restricted_resource: 頁面未分享給 integration - rate_limited: 限速，等 1 秒重試

Notes

• IDs are UUIDs with or without dashes (both work)
• Rate limit: ~3 req/s，平均值，突發會限速
• API 無法設定資料庫檢視篩選器（UI 操作）
• 建立資料庫時用 is_inline: true 可嵌入頁面

這個 Notion 技能整體質量不錯，能夠幫助使用者將零散的想法和靈感系統化地記錄到 Notion 中。它的工作流設計很貼心——寫入前會先展示內容讓你確認，避免誤操作。主要缺點是配置不夠靈活，資料庫 ID 寫死在程式碼裡，改動起來比較麻煩；另外當操作失敗時，提示資訊有時不夠清晰。總體來說，這是一個上手簡單、功能實用的 Skill，適合經常需要整理創意的使用者使用。