How to Connect Notion to OpenClaw: AI-Powered Knowledge Base

Notion is where most teams keep their knowledge: meeting notes, project databases, specs, decisions. The problem is getting that knowledge out when you need it. You either search through nested pages manually or hope you remember which database holds the answer. OpenClaw fixes this by turning your Notion workspace into a queryable knowledge base you can talk to from Telegram, WhatsApp, or any chat interface.

This guide covers the full setup: creating a Notion integration token, writing a custom OpenClaw skill that calls the Notion REST API, and three practical automations you can run on day one. The whole process takes about 25 minutes if OpenClaw is already installed.

---

What You Get After Connecting

Once the skill is active, your OpenClaw agent can do anything the Notion API supports. In practice, the operations you will use most are:

• Query databases by filtering on properties (status, date, assignee, tags)
• Search across pages by title or content keywords
• Create new pages with structured properties and body content
• Update existing pages by changing property values (move a task to “Done”, update a due date)
• Append content blocks to existing pages (add notes to a running document)

All of this happens through natural language. You message your agent “What action items came out of last Friday’s standup?” and it queries your meeting notes database, filters by date, and returns the results. No clicking through Notion’s sidebar.

The agent uses Notion’s REST API directly through curl commands. No Composio plugin, no Zapier middleware, no third-party service between your machine and Notion’s servers. Your data stays on the direct path.

---

Before You Start

Three prerequisites:

1. OpenClaw installed and running. If you have not set this up yet, follow our OpenClaw setup guide. That guide covers installation, workspace files, memory, and Telegram configuration.

2. A Notion workspace where you have admin access. The free Notion plan supports API integrations. You do not need Notion AI or a paid tier for this.

3. At least one Notion database you want to query. If you only have loose pages, that works too, but databases unlock the most useful queries (filtering by status, date ranges, assignees).

---

Step 1: Create a Notion Integration Token

Notion calls these “internal integrations.” They give your agent a token scoped to your workspace, and you control which pages and databases the token can access.

1. Go to notion.so/my-integrations
2. Click + New integration
3. Name it OpenClaw Agent
4. Select your workspace
5. Under Capabilities, enable:

Capability	Why
Read content	Query pages and databases
Update content	Edit properties, append blocks
Insert content	Create new pages

6. Click Submit and copy the Internal Integration Secret (starts with ntn_)

This token is your agent’s credential. Treat it like a password.

Store the Token

Add it to your .env file, not your skill file:

# ~/.env or ~/openclaw/.env
NOTION_API_TOKEN=ntn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

OpenClaw reads environment variables at runtime. This keeps the secret out of any file your agent might include in context or logs.

Share Pages with the Integration

Here is the step most guides bury and most users miss: Notion integrations have zero access by default. You must explicitly share each page or database with your integration.

For every database or page you want OpenClaw to access:

1. Open the page or database in Notion
2. Click the … menu (top right)
3. Select Add connections
4. Find and select OpenClaw Agent

If you skip this, your agent will get 404 errors when trying to read pages. The API does not tell you “permission denied”; it tells you “not found.” It is common to spend an hour debugging this before realizing the page simply was not shared.

---

Step 2: Write the OpenClaw Notion Skill

The skill file tells your agent what Notion can do, how to authenticate, and which API endpoints to call. Create it in your workspace’s skills directory:

mkdir -p ~/.openclaw/workspace/skills/notion

Create ~/.openclaw/workspace/skills/notion/SKILL.md with this content:

---
name: notion
description: Read, create, update, and query Notion pages and databases. Use the Notion REST API to manage workspace content.
tools:
  - shell
---

# Notion Skill

## Authentication

Use the environment variable `NOTION_API_TOKEN` for all requests.
All requests go to `https://api.notion.com/v1/` with these headers:

Authorization: Bearer $NOTION_API_TOKEN
Content-Type: application/json
Notion-Version: 2022-06-28

## Available Operations

### Search Pages by Title

Find pages across your workspace:

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  -d '{
    "query": "SEARCH_TERM",
    "filter": { "property": "object", "value": "page" },
    "page_size": 5
  }' | jq '.results[] | {id: .id, title: .properties.title.title[0].plain_text}'

### Query a Database

Filter and sort database entries. Replace DATABASE_ID with the actual ID:

curl -s -X POST "https://api.notion.com/v1/databases/DATABASE_ID/query" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  -d '{
    "filter": {
      "property": "Status",
      "select": { "equals": "In Progress" }
    },
    "sorts": [{ "property": "Due Date", "direction": "ascending" }]
  }' | jq '.results[] | {title: .properties.Name.title[0].plain_text, status: .properties.Status.select.name}'

### Create a New Page in a Database

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  -d '{
    "parent": { "database_id": "DATABASE_ID" },
    "properties": {
      "Name": { "title": [{ "text": { "content": "PAGE_TITLE" } }] },
      "Status": { "select": { "name": "Not Started" } },
      "Assignee": { "people": [{ "object": "user", "id": "USER_ID" }] }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{ "text": { "content": "PAGE_BODY_TEXT" } }]
        }
      }
    ]
  }' | jq '{id: .id, url: .url}'

### Update Page Properties

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

### Append Blocks to a Page

Add content to an existing page:

curl -s -X PATCH "https://api.notion.com/v1/blocks/PAGE_ID/children" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
          "rich_text": [{ "text": { "content": "HEADING_TEXT" } }]
        }
      },
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{ "text": { "content": "PARAGRAPH_TEXT" } }]
        }
      }
    ]
  }' | jq '.results[].id'

## Rules

- Always confirm before creating or updating pages. Show the user what will be written before executing.
- When querying databases, ask which database to use if multiple exist. Use the database name or a saved ID from memory.
- Notion's API rate limit is 3 requests per second. Space requests if running batch operations.
- Never log the API token in responses or memory files.
- If a 404 error occurs, remind the user to share the page or database with the OpenClaw Agent integration in Notion.

Why Direct API Calls Instead of a Plugin

Some guides recommend Composio or other middleware plugins for this integration. We prefer the direct approach for three reasons:

1. No vendor dependency. Composio is a service that can change pricing, go down, or deprecate features. Curl calls to the Notion API will work as long as Notion exists.
2. Full visibility. You can read every API call in the skill file and understand exactly what your agent can do. Plugin abstractions hide this.
3. Easier debugging. When something breaks, you can copy the curl command, paste it into a terminal, and test it yourself. With a plugin, you are debugging someone else’s code.

You spend more time on the initial setup. But for a skill you will use daily, 15 minutes of writing curl templates beats an ongoing dependency.

---

Step 3: Test the Connection

Restart OpenClaw to load the new skill:

openclaw gateway restart

Open your Telegram (or WhatsApp) chat with your OpenClaw agent and run these tests:

Search test:

“Search Notion for pages about Q1 planning”

The agent should call the search endpoint and return matching page titles.

Database query test:

“Show me all tasks in my Projects database that are In Progress”

The agent should query the database with a status filter and return matching entries. If it asks which database to use, provide the database name or ID.

Write test:

“Create a new page in my Tasks database: title ‘Review OpenClaw Notion integration’, status ‘Not Started’”

The agent should show you the page details and ask for confirmation before creating it.

Troubleshooting

Symptom	Likely Cause	Fix
404 Not Found	Page not shared with integration	Open the page in Notion, click … then Add connections, select your integration
401 Unauthorized	Token is wrong or expired	Regenerate at notion.so/my-integrations
400 Bad Request	Mismatched property type in query	Check if the property name and type (select, multi_select, date) match your database schema
429 Rate Limited	Too many requests per second	Add a note to your skill: “Wait 1 second between consecutive API calls”
Empty results	Filter does not match any entries	Verify the exact property name and value in your Notion database

The 404 issue trips up nearly everyone on first setup. If you see it, check the page sharing before anything else.

---

Three Automations to Build First

The connection is useful for ad-hoc queries, but the real value comes from automations that run without you asking. Here are three worth building.

1. Meeting Notes Database with Action Item Extraction

Set up a Notion database with these properties:

Property	Type	Purpose
Name	Title	Meeting title
Date	Date	When the meeting happened
Attendees	Multi-select	Who was there
Action Items	Rich text	Extracted next steps
Status	Select	Open / Closed

After each meeting, message your agent:

“Create a meeting note for today’s product sync with Sarah and Mike. We discussed the Q2 roadmap. Action items: Sarah to finalize pricing by April 5, Mike to send the updated wireframes by Thursday.”

The agent creates the page in your database with structured properties and the action items in the body. No more switching to Notion mid-meeting to log notes.

Tip: Use Select and Multi-select properties instead of free text wherever possible. These are filterable, which means your agent can later query “Show me all open action items assigned to Sarah” and get precise results. Free-text fields require full-text search, which is less reliable.

2. Task Sync Between Chat and Notion

If your team tracks tasks in a Notion database, your agent can serve as the interface:

“What tasks are due this week?”

“Mark the ‘API documentation’ task as Done”

“Create a task: ‘Set up staging environment’, assigned to me, due next Monday”

This works best when your database has consistent property names. We recommend standardizing on: Name (title), Status (select: Not Started, In Progress, Done), Assignee (person), Due Date (date), Priority (select: Low, Medium, High).

3. Daily Summary via Heartbeat

Add this to your OpenClaw heartbeat.md to get a morning briefing pulled from Notion:

## Morning Notion Brief (runs at 8:00 AM)

Query my "Tasks" database for all items where Status is "In Progress" or Due Date is today or earlier.
Query my "Meeting Notes" database for meetings from the last 24 hours that have open action items.

Send me a summary with:
- Tasks due today or overdue, grouped by priority
- Action items from yesterday's meetings that are still open
- Count of total in-progress tasks

This turns Notion from a place you visit into a system that reports to you. For the heartbeat setup, see our OpenClaw heartbeat scheduling guide.

---

Security and Access Control

Your Notion token grants read and write access to every page shared with the integration. Handle it accordingly.

Least-privilege sharing. Only share the specific databases and pages your agent needs. Do not share your entire workspace root page. If you share a parent page, all child pages inherit the integration access.

Token storage. Keep the token in .env, never in your skill file, soul.md, or workspace files. If the token appears in context that gets sent to your LLM provider, it is exposed.

Confirmation rules. The skill’s Rules section requires the agent to confirm before any write operation. This prevents your agent from creating duplicate pages or overwriting data if it misinterprets a message.

Audit trail. Notion tracks all API changes. If something looks wrong, go to Settings > Connections > OpenClaw Agent to review what your integration has accessed.

For more on securing your OpenClaw deployment, see Step 9 of our OpenClaw setup guide.

---

Frequently Asked Questions

Do I need a paid Notion plan to connect OpenClaw?

No. Notion’s free plan includes full API access. You can create internal integrations, query databases, create pages, and update properties without upgrading. Paid Notion plans add features like unlimited file uploads and advanced permissions, but the API itself works on the free tier.

How do I find my Notion database ID?

Open the database as a full page in Notion. The URL looks like notion.so/your-workspace/DATABASE_ID?v=VIEW_ID. The database ID is the 32-character string before the ?v= parameter. Copy it and use it in your skill file or provide it to your agent when asked.

Can OpenClaw handle Notion’s 3-request-per-second rate limit?

For conversational use, you will never hit it. A typical query-and-response cycle makes 1-2 API calls. Batch operations (like scanning all pages in a large database) could trigger rate limiting. Add a note to your skill’s Rules section: “If you receive a 429 response, wait 2 seconds and retry.” OpenClaw will follow this instruction.

What is the difference between using Composio and a custom skill?

Composio is a managed service that handles authentication and provides pre-built tool definitions. A custom skill is a Markdown file you write yourself with direct API calls. Composio is faster to set up (5 minutes versus 20). A custom skill gives you full control, no vendor dependency, and easier debugging. For production use where you want to understand and audit every API call your agent makes, we recommend the custom skill approach.

Can I use this to sync data between Notion and other tools?

Through your agent, not a direct sync. You could tell your agent: “Every morning, check my HubSpot deals closing this week and create a summary page in my Notion Sales database.” The agent calls the HubSpot skill and the Notion skill in sequence. This is not real-time bidirectional sync, but it is flexible and requires no integration platform.

---

Key Takeaways

• Connect Notion to OpenClaw by creating an internal integration token at notion.so/my-integrations and writing a SKILL.md file with direct API call templates
• Share every page and database you want the agent to access; integrations have zero access by default, and missing this step causes 404 errors
• Use Select and Multi-select properties in your Notion databases for reliable filtering; free-text fields are harder for agents to query precisely
• Start with read-only queries (search, database lookups) before enabling write operations
• Automate daily briefings with OpenClaw’s heartbeat feature to turn Notion into a system that reports to you