notion – OpenClaw Skill

---

name: notion version: 0.1.0 description: Integrate with Notion workspaces to read pages, query databases, create entries, and manage content. Perfect for knowledge bases, project tracking, content calendars, CRMs, and collaborative documentation. Works with any Notion page or database you explicitly share with the integration.

Notion Integration

Connect your Notion workspace to OpenClaw for seamless knowledge management and project tracking.

When to Use This Skill

Use Notion when the user wants to:

• Add items to a database (backlog, todos, tracking)
• Create new pages in a database or as children of existing pages
• Query/search their Notion workspace for information
• Update existing pages (status, notes, properties)
• Read page content or database entries

Setup

1. Create Notion Integration

1. Go to notion.so/my-integrations
2. Click New integration
3. Name it (e.g., "OpenClaw")
4. Select your workspace
5. Copy the Internal Integration Token (starts with secret_)
6. Save this token securely in OpenClaw config or environment: NOTION_TOKEN=secret_...

2. Share Pages with Integration

Important: Notion integrations have NO access by default. You must explicitly share:

1. Go to any page or database in Notion
2. Click Share → Add connections
3. Select your "OpenClaw" integration
4. The skill can now read/write to that specific page/database

3. Get Database/Page IDs

From URL:

• Database: https://www.notion.so/workspace/XXXXXXXX?v=... → ID is XXXXXXXX (32 chars)
• Page: https://www.notion.so/workspace/XXXXXXXX → ID is XXXXXXXX

Note: Remove hyphens when using IDs. Use the 32-character string.

Core Operations

Query Database

Retrieve entries from any database you've shared.

// Using the Notion skill via exec
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js query-database ${databaseId}`
});

// With filters (example: status = "In Progress")
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js query-database ${databaseId} --filter '{"property":"Status","select":{"equals":"In Progress"}}'`
});

Returns: Array of pages with properties as configured in your database.

Add Database Entry

Create a new row in a database.

// Add entry with multiple properties
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js add-entry ${databaseId} \
    --title "My New Content Idea" \
    --properties '${JSON.stringify({
      "Status": { "select": { "name": "Idea" } },
      "Platform": { "multi_select": [{ "name": "X/Twitter" }] },
      "Tags": { "multi_select": [{ "name": "3D Printing" }, { "name": "AI" }] },
      "Priority": { "select": { "name": "High" } }
    })}'`
});

Get Page Content

Read the content of any page (including database entries).

await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js get-page ${pageId}`
});

Returns: Page title, properties, and block content (text, headings, lists, etc.).

Update Page

Modify properties or append content to an existing page.

// Update properties
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js update-page ${pageId} \
    --properties '${JSON.stringify({
      "Status": { "select": { "name": "In Progress" } }
    })}'`
});

// Append content blocks
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js append-body ${pageId} \
    --text "Research Notes" --type h2`
});

Search Notion

Find pages across your shared workspace.

await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js search "content ideas"`
});

Common Use Cases

Content Pipeline (Content Creator Workflow)

Database Structure:

• Title (title)
• Status (select: Idea → Draft → Scheduled → Posted)
• Platform (multi_select: X/Twitter, YouTube, MakerWorld, Blog)
• Publish Date (date)
• Tags (multi_select)
• Draft Content (rich_text)

OpenClaw Integration:

// Research scout adds findings to Notion
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js add-entry ${contentDbId} \
    --title "New 3D Print Technique" \
    --properties '${JSON.stringify({
      "Status": { "select": { "name": "Idea" } },
      "Platform": { "multi_select": [{ "name": "YouTube" }] },
      "Tags": { "multi_select": [{ "name": "3D Printing" }] }
    })}'`
});

// Later: Update when drafting
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js update-page ${entryId} \
    --properties '${JSON.stringify({
      "Status": { "select": { "name": "Draft" } },
      "Draft Content": { "rich_text": [{ "text": { "content": "Draft text here..." } }] }
    })}'`
});

Project Management (Solo Entrepreneur)

Database Structure:

• Name (title)
• Status (select: Not Started → In Progress → Blocked → Done)
• Priority (select: Low → Medium → High → Critical)
• Due Date (date)
• Estimated Hours (number)
• Actual Hours (number)
• Links (url)
• Notes (rich_text)

Weekly Review Integration:

// Query all "In Progress" projects
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js query-database ${projectsDbId} --filter '{"property":"Status","select":{"equals":"In Progress"}}'`
});

Customer/Quote CRM (3D Printing Business)

Database Structure:

• Customer Name (title)
• Status (select: Lead → Quote Sent → Ordered → Printing → Shipped)
• Email (email)
• Quote Value (number)
• Filament Type (select)
• Due Date (date)
• Shopify Order ID (rich_text)

Shopify Integration:

// New order → create CRM entry
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js add-entry ${crmDbId} \
    --title "${customerName}" \
    --properties '${JSON.stringify({
      "Status": { "select": { "name": "Ordered" } },
      "Email": { "email": customerEmail },
      "Shopify Order ID": { "rich_text": [{ "text": { "content": orderId } }] }
    })}'`
});

Knowledge Base (Wiki Replacement for MEMORY.md)

Structure: Hub page with nested pages:

• 🏠 Home (shared with integration)
  • SOPs
  • Troubleshooting
  • Design Patterns
  • Resource Links

Query for quick reference:

// Search for "stringing" to find 3D print troubleshooting
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js search "stringing"`
});

Property Types Reference

When creating/updating database entries, use these property value formats:

// Title (always required for new pages)
{ "title": [{ "text": { "content": "Page Title" } }] }

// Select (single choice)
{ "select": { "name": "Option Name" } }

// Multi-select (multiple choices)
{ "multi_select": [{ "name": "Tag 1" }, { "name": "Tag 2" }] }

// Status (for new Status property type)
{ "status": { "name": "In progress" } }

// Text / Rich text
{ "rich_text": [{ "text": { "content": "Your text here" } }] }

// Number
{ "number": 42 }

// Date
{ "date": { "start": "2026-02-15" } }
{ "date": { "start": "2026-02-15T10:00:00", "end": "2026-02-15T12:00:00" } }

// Checkbox
{ "checkbox": true }

// Email
{ "email": "user@example.com" }

// URL
{ "url": "https://example.com" }

// Phone
{ "phone_number": "+1-555-123-4567" }

// Relation (link to another database entry)
{ "relation": [{ "id": "related-page-id-32chars" }] }

Security & Permissions

Critical Security Model:

• ✅ Integration ONLY sees pages you explicitly share
• ✅ You control access per page/database
• ✅ Token stored securely in ~/.openclaw/.env (never in code)
• ❌ Never commit NOTION_TOKEN to git
• ❌ Integration cannot access private teamspaces or other users' private pages

Best Practices:

1. Use a dedicated integration (don't reuse personal integrations)
2. Share minimum necessary pages (granular > broad)
3. Rotate token if compromised via Notion integration settings
4. Review shared connections periodically

Environment Setup

Add to ~/.openclaw/.env:

NOTION_TOKEN=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Or set per-command:

NOTION_TOKEN=secret_xxx node notion-cli.js ...

Error Handling

Common errors and fixes:

Error	Cause	Fix
"API token is invalid"	Wrong token or integration deleted	Check token at notion.so/my-integrations
"object_not_found"	Page not shared with integration	Share page: Share → Add connections
"validation_error"	Property format incorrect	Check property type in database
"rate_limited"	Too many requests	Add delay between requests

Quick Install (One Command)

cd ~/.agents/skills/notion
./install.sh

Manual install (if above fails):

cd ~/.agents/skills/notion
npm install

That's it! No build step required for the standalone version.

Quick Test

# After setting NOTION_TOKEN in ~/.openclaw/.env
node notion-cli.js test

Smart ID Resolution

Reference entries by Notion auto-ID (e.g., #3) or direct UUID.

By Notion ID (Recommended for Manual Use)

Use the number you see in your database's ID column:

# Get entry #3
node notion-cli.js get-page '#3' DATABASE_ID

# Add content to entry #3
node notion-cli.js append-body '#3' --database DATABASE_ID \
  --text "Research notes" --type h2

# Add bullet to entry #3
node notion-cli.js append-body '#3' --database DATABASE_ID \
  --text "Key finding" --type bullet

By Direct UUID (For Automation)

# Using full UUID from Notion URL
node notion-cli.js get-page 2fb3e4ac...
node notion-cli.js append-body 2fb3e4ac... \
  --text "Content" --type paragraph

Auto-detection: Starts with # = Notion ID lookup. 32-char hex = Direct UUID.

Pro Tip: Add an ID property (type: unique ID) to auto-number entries as #1, #2, #3...

Page Body Editing

Add rich content to page bodies, not just properties.

Append Content Blocks

# Add heading
node notion-cli.js append-body PAGE_ID --text "Research Summary" --type h2

# Add paragraph (default)
node notion-cli.js append-body PAGE_ID --text "Detailed findings go here..."

# Add bullet list item
node notion-cli.js append-body PAGE_ID --text "First key finding" --type bullet

# Add numbered list item
node notion-cli.js append-body PAGE_ID --text "Step one description" --type numbered

# Add TODO checkbox
node notion-cli.js append-body PAGE_ID --text "Create video script" --type todo

# Add quote
node notion-cli.js append-body PAGE_ID --text "Important quote from source" --type quote

# Add code block
node notion-cli.js append-body PAGE_ID --text "const result = optimizeSupports();" --type code --lang javascript

Supported Block Types

Type	Description	Example Use
paragraph	Regular text (default)	Descriptions, explanations
h1, h2, h3	Headings	Section organization
bullet	Bulleted list	Key findings, features
numbered	Numbered list	Step-by-step instructions
todo	Checkbox item	Action items, tasks
quote	Blockquote	Source citations
code	Code block	Snippets, commands
divider	Horizontal line	Section separation

Get Page with Body Content

# Get full page including formatted body
node notion-cli.js get-page PAGE_ID

Returns:

• Page properties
• Formatted body blocks (type + content preview)
• Block count

Advanced: Raw JSON Blocks

For complex layouts, use raw Notion block JSON:

node notion-cli.js append-body PAGE_ID --blocks '[
  {"object":"block","type":"heading_2","heading_2":{"rich_text":[{"text":{"content":"Research Notes"}}]}},
  {"object":"block","type":"bulleted_list_item","bulleted_list_item":{"rich_text":[{"text":{"content":"Finding 1"}}]}},
  {"object":"block","type":"code","code":{"rich_text":[{"text":{"content":"console.log(1)"}}],"language":"javascript"}}
]'

Advanced: Webhook Sync

For bidirectional sync (Notion changes → OpenClaw):

1. Set up Notion webhook integration (requires Notion partner account)
2. Configure webhook endpoint to your OpenClaw Gateway
3. Skill processes incoming webhooks and updates memory files

See references/webhooks.md for implementation details.

---

Need help? Check your Notion integration settings at https://www.notion.so/my-integrations

Using in OpenClaw

Quick Setup

# 1. Install
cd ~/.agents/skills/notion
npm install

# 2. Configure token
echo "NOTION_TOKEN=secret_xxxxxxxxxx" >> ~/.openclaw/.env

# 3. Test connection
node notion-cli.js test

From OpenClaw Agent

// Query database
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js query-database YOUR_DB_ID`
});

// Add entry
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js add-entry YOUR_DB_ID \\
    --title "New Content Idea" \\
    --properties '{"Status":{"select":{"name":"Idea"}}}'`
});

// Search
await exec({
  command: `node ~/.agents/skills/notion/notion-cli.js search "tree support"`
});

Cron Job Usage

Update your Research Topic Scout to push to Notion:

"message": "Research trends and add to Notion: 
  node ~/.agents/skills/notion/notion-cli.js add-entry DB_ID 
    --title '<title>' 
    --properties '{...,\"Platform\":{\"multi_select\":[{\"name\":\"X\"}]}}'"

<div align="center">

🔗 OpenClaw Notion Skill

Seamlessly integrate your Notion workspace with OpenClaw agents

</div>

Transform your Notion workspace into a living knowledge base that your AI agents can read, write, and manage. Perfect for content pipelines, project tracking, CRMs, and collaborative documentation.

---

✨ What It Does

Feature	Description
📊 Query Databases	Pull structured data from any Notion database
📝 Create Entries	Add new rows from agent research and discoveries
🔍 Search Workspace	Find pages across your entire shared workspace
🔄 Update Content	Modify properties and append blocks dynamically
🗂️ View Schemas	Inspect database structures programmatically
🔢 Smart ID Reference	Use Notion ID #3 or direct UUID — your choice

Perfect for:

• Content creators managing editorial calendars
• Solo entrepreneurs tracking projects and leads
• Teams building knowledge bases
• Researchers compiling findings
• Anyone who wants their AI to actually use Notion

---

🚀 Quick Start (5 Minutes)

Install via Clawhub (Coming Soon)

Once published:

openclaw skills install notion-enhanced

Manual Install

1. Create Notion Integration

notion.so/my-integrations → New integration → Copy token

The token starts with secret_. Keep it safe.

2. Install the Skill

git clone https://github.com/MoikasLabs/openclaw-notion-skill.git
cd openclaw-notion-skill
./install.sh

3. Configure

# Add to ~/.openclaw/.env
NOTION_TOKEN=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. Share Your Database

In Notion:

1. Open your database/page
2. Click Share → Add connections
3. Select your integration name

5. Test Connection

node notion-cli.js test

You'll see all accessible pages and databases. ✅

---

🎯 Usage Examples

Command Line

# List all entries in your Content Ideas database
node notion-cli.js query-database abc123def456...

# Filter by status
node notion-cli.js query-database abc123... \
  --filter '{"property":"Status","select":{"equals":"Idea"}}'

# Add a new research finding
node notion-cli.js add-entry abc123... \
  --title "AI-Generated Support Structures in 3D Printing" \
  --properties '{"Status":{"select":{"name":"Idea"}},"Platform":{"multi_select":[{"name":"YouTube"}]}}'

# Search across workspace
node notion-cli.js search "tree support"

# Mark as drafted
node notion-cli.js update-page page-id-123... \
  --properties '{"Status":{"select":{"name":"Draft"}}}'

Smart ID Resolution (Notion ID or UUID)

Reference entries by Notion ID (what you see in the ID column):

# Get page by Notion ID #3 - auto-resolves to actual page ID
node notion-cli.js get-page '#3' DATABASE_ID

# Append content using Notion ID
node notion-cli.js append-body '#3' \
  --database DATABASE_ID \
  --text "Research notes here" \
  --type h2

# Add a link to entry #3
node notion-cli.js append-body '#3' \
  --database DATABASE_ID \
  --text "Example: https://makerworld.com/models/123" \
  --type bullet

Or use direct UUID for automation:

# Direct UUID (copy from URL)
node notion-cli.js append-body 2fb3e4ac... \
  --text "Content here" \
  --type paragraph

The CLI auto-detects:

• Starts with # → Notion ID lookup (requires database ID)
• 32-char hex → Direct UUID (no database needed)

From OpenClaw

// Check your content pipeline
await exec({
  command: `node openclaw-notion-skill/notion-cli.js query-database ${CONTENT_DB_ID}`
});

// Log a discovery
await exec({
  command: `node openclaw-notion-skill/notion-cli.js add-entry ${PROJECTS_DB_ID} \\
    --title "${discoveryTitle}" \\
    --properties '{"Priority":{"select":{"name":"High"}}}'`
});

In Cron Jobs

// Research Topic Scout → Pushes directly to Notion
"Research 3D printing trends and add ideas to Notion database"

---

📁 Database Templates

Content Pipeline

Property	Type	Values
Title	Title	-
Status	Select	Idea → Draft → Scheduled → Posted
Platform	Multi-select	X/Twitter, YouTube, MakerWorld, Blog
Publish Date	Date	-
Tags	Multi-select	3D Printing, AI, Entrepreneurship
Draft Content	Rich Text	-

Project Tracker

Property	Type	Values
Name	Title	-
Status	Select	Not Started → In Progress → Blocked → Done
Priority	Select	Low → Medium → High → Critical
Due Date	Date	-
Est. Hours	Number	-
Links	URL	GitHub, MakerWorld, etc.

CRM (3D Printing Business)

Property	Type	Values
Customer	Title	-
Status	Select	Lead → Quote → Ordered → Printing → Shipped
Email	Email	-
Quote Value	Number	$
Filament	Select	PLA, PETG, ABS, etc.

---

🔐 Security

• Token isolation: Stored in ~/.openclaw/.env — never in code
• Granular permissions: Integration only sees pages you explicitly share
• No blanket access: Cannot touch private pages or unshared teamspaces
• Your control: Revoke anytime via notion.so/my-integrations

# Check what's shared
node notion-cli.js test

---

🛠️ Advanced Usage

Property Types Reference

// Select (single choice)
{ "select": { "name": "In Progress" } }

// Multi-select
{ "multi_select": [{ "name": "Tag 1" }, { "name": "Tag 2" }] }

// Status (new type)
{ "status": { "name": "In progress" } }

// Rich text
{ "rich_text": [{ "text": { "content": "Notes here" } }] }

// Date
{ "date": { "start": "2026-02-15" } }

// Number
{ "number": 42 }

// Checkbox
{ "checkbox": true }

Error Handling

Error	Fix
API token is invalid	Check token at notion.so/my-integrations
object_not_found	Share the page with your integration
validation_error	Check property type matches database schema
rate_limited	Add 350ms delay between requests

---

🧰 Installation Options

Option A: Quick (Standalone)

git clone https://github.com/MoikasLabs/openclaw-notion-skill.git
cd openclaw-notion-skill
npm install

Uses notion-cli.js — no build step.

Option B: Full (TypeScript)

git clone https://github.com/MoikasLabs/openclaw-notion-skill.git
cd openclaw-notion-skill
npm install
npm run build

Uses compiled dist/cli.js with full TypeScript support.

---

📝 CLI Reference

notion-cli.js <command> [options]

Commands:
  test                          Test connection, list accessible pages
  query-database <id>           Query database entries
  add-entry <id>                Add new database row
  get-page <id>                 Get page content
  update-page <id>              Update page properties
  get-database <id>             Show database schema
  search <query>                Search workspace

Options:
  --filter '<json>'             Filter query results
  --title "text"                Set entry title
  --properties '<json>'         Set additional properties
  --help                        Show help

Database ID Format:
  From URL: notion.so/workspace/ABC123...
  Use: ABC123... (32 chars, no hyphens)

---

🌟 Why This Exists

Most AI "integrations" just read a static export. This skill lets your agents:

• ✅ Write findings back to your knowledge base
• ✅ Update project status as work progresses
• ✅ Query structured data for context
• ✅ Build living documentation

Real use case:

Your nightly Research Topic Scout cron job searches 3D printing trends, finds 5 interesting techniques, and automatically adds them to your Content Ideas database with status "Idea" and tags extracted from the source.

---

🤝 Contributing

1. Fork the repo
2. Create a branch: git checkout -b feature/amazing-thing
3. Commit changes: git commit -m 'Add amazing thing'
4. Push: git push origin feature/amazing-thing
5. Open a Pull Request

Ideas welcome: webhooks, bidirectional sync, bulk operations, templates.

---

📜 License

MIT — Built with ❤️ by the OpenClaw community at MoikasLabs

---

🔗 Links

• OpenClaw Docs
• Notion API Docs
• Issue Tracker
• Support Project 💝
• MoikasLabs

---

<div align="center">

Built for agents who actually get work done. 🐉

</div>

---

📦 Quick Start Templates

Don't build from scratch. Use our pre-configured templates:

Template	Best For	File
📝 Content Pipeline	Writers, YouTubers, social media	templates/content-pipeline.json
🎯 Project Tracker	Freelancers, solo entrepreneurs	templates/project-tracker.json
🖨️ 3D Print CRM	Makers, print shops	templates/crm-3d-printing.json
📚 Knowledge Base	SOPs, documentation, wikis	templates/knowledge-base.json

See templates/README.md for detailed setup instructions and automation examples.

---

<div align="center">

Built for agents who actually get work done. 🐉

</div>