Subtopic 8.1 was the generic API integration process — find docs, get key, store in .env, teach, test, save. Subtopic 8.2 is the most-asked concrete example: how do I connect my agent to Notion? The channel's framing for why Notion is the canonical second integration is that it's where humans already keep notes, trade journals, project trackers, and knowledge bases — and the bot can read and write all of it. The result is the "second brain" pattern: anything you would have written down anyway goes into Notion, and the agent retrieves and updates it on demand.

The integration itself is the standard 6-step process from §8.1 with Notion-specific mechanics: create an internal integration at notion.so/my-integrations, copy the secret, store in .env, share each database you want the agent to touch. The interesting decisions are around permissions (read-only vs read+write vs read+insert+update), multi-database setup (tasks, knowledge base, trade journals on one integration), and the semantic search pattern that turns Notion into long-term agent memory.

This article walks through the Notion setup, the permission decision tree, and the three use cases the channel keeps coming back to: trade-journal analysis, knowledge-base journaling, and task management.

What you'll learn

  • The Notion integration setup is the 6-step process from §8.1 with Notion-specific URLs: create the integration at notion.so/my-integrations, copy the "Internal Integration Secret," store as NOTION_API_KEY in ~/.openclaw/.env.
  • The database connection step is Notion-specific and easy to miss: after creating the integration, you have to add it to each database individually via the "..." menu → Connections. Without this, the integration exists but has access to nothing.
  • The permissions decision has three modes — read-only (data analysis), read+insert+update (task management), and read+insert (semi-trusted automation) — and the right default depends on whether you trust the agent to write to the workspace. The channel's default is read+write, because read-only breaks the "second brain" pattern.
  • The three flagship use cases are: trade journal analysis (the bot counts your trades, finds patterns, flags concentration risk), knowledge base journaling (the bot writes daily research findings to a searchable Notion database), and task management (the bot creates and updates tasks from chat).
  • The multi-database pattern is one integration, many databases. Notion lets one internal integration read+write any database it's been added to — you don't need a separate API key per database.
  • The semantic search pattern turns Notion into the agent's long-term memory: "search my past 6 months of notes for anything about prompt engineering" is the kind of question the integration enables.
  • The automated daily journal pattern is the canonical cron + skill + Notion combo from Course 1 §1.6 — a skill that writes a summary entry to a Notion database every evening, which the agent can then semantic-search the next morning.

The Notion integration setup

The video is a short, mechanical walkthrough. The integration exists because Notion itself ships a public API for "internal integrations" — bot accounts that can read and write on behalf of a user. The setup is six screens and the failure mode for each one is "you forgot the next screen and the agent can't see anything."

Create the integration

Navigate to notion.so/my-integrations and click "+ New integration." Three fields matter:

  • Name — something descriptive. The channel uses "OpenClaw Agent." The name shows up in the Connections menu of every database you add it to.
  • Associated workspace — pick the workspace where your databases live. The integration is workspace-scoped; you can't bridge workspaces with one key.
  • Icon — optional, but nice for the audit trail when you're staring at a Notion page and wondering which bot edited it.

Submit. The next screen shows the integration's settings. The only field you need from this screen is the Internal Integration Secret — click "Show," then "Copy." Treat this token like a password. The format is secret_abc123XYZ456def789.... If you ever leak it (screenshot, commit, Discord message), regenerate immediately.

Store the secret in .env

nano ~/.openclaw/.env

Add:

NOTION_API_KEY=secret_your_internal_integration_secret_here

chmod 600 ~/.openclaw/.env. Restart the OpenClaw gateway if your install requires it (openclaw gateway restart). Verify the env var is loaded:

ls -la ~/.openclaw/.env
cat ~/.openclaw/.env | grep NOTION

The -rw------- permissions and the presence of the NOTION_API_KEY=... line are the two checks. If the gateway can't see the var, the integration won't authenticate and the agent will get a 401 on every call.

Connect the integration to each database

This is the step the channel calls out as the most-forgotten. The integration exists at the workspace level, but Notion's permission model is database-scoped — the integration can't see a database until you add it. The flow:

  1. Open the database in Notion (e.g., "Trade Journal," "Knowledge Base," "Tasks")
  2. Click the "..." menu in the top-right corner
  3. Select "Connections" (or "Add connections" on older Notion versions)
  4. Scroll to find your integration name
  5. Click "Connect"

Do this for every database you want the agent to touch. You can revoke access later from the same menu. The integration now has the permissions you set in the next step, scoped to exactly the databases you connected.

Configure capabilities

The default is read content + update content + insert content — full read+write. The channel's default for new integrations. The read-only mode is for analytical use cases where you want the agent to query but not modify:

  • Data Analysis only — disable "Update content" and "Insert content." The agent can read but not write. Useful for trade journals, analytics dashboards, and any database where you want a one-way data flow.
  • Task Management — keep all capabilities enabled. The agent needs to create, update, and complete tasks.
  • Knowledge Base journaling — read + insert, but not update. The agent writes new entries but doesn't rewrite old ones. This is the safer middle ground for a "second brain."

The decision rule: if you want the agent to be able to update existing records (task status, journal edits, retroactive notes), enable update. If you only want new entries appended, disable update. The §8.3 audit at the end of this course asks you to confirm which mode you picked and why.

The three flagship use cases

The channel runs three Notion use cases repeatedly. They're the canonical "what do I do with this integration" answers.

Trade journal analysis (read-only)

The first worked example in the video. The bot reads a BingX trade journal database with hundreds of trades and answers questions like "how many trades closed in an hour or less?" and "what percentage of my trades were BTC, ETH, or SOL?" The agent's response in the demo:

  • 548 total trades. 365 (66.6%) closed in an hour or less — "an interesting pattern, about 2/3 of your trades are short-term positions."
  • Of the 548, 466 were BTC, ETH, or SOL — 82 trades (15%) were other tokens. "Your portfolio is heavily focused on major cryptocurrencies."

This is read-only mode. The agent never writes back to the journal — it just queries. The mode is appropriate because the source of truth is the trading platform's export, and the agent has no business editing trade records.

Knowledge base journaling (read + insert)

The second worked example. The bot writes daily research findings to a "Knowledge Base" database in Notion. The query pattern is the inverse of the trade journal: instead of querying existing records, the agent appends new entries.

  • "Upload today's research findings to my Knowledge Base in Notion" — agent creates a new entry with today's date and the research summary.
  • "Search my past notes for anything related to prompt engineering" — agent runs a semantic search over the database, returns the most relevant entries.

This is the "second brain" pattern. Anything you'd write down anyway goes into Notion, and the agent can retrieve it on demand. The read + insert mode is the right call — the agent can write new entries but can't rewrite history, which is the appropriate trust level for personal notes.

The semantic search pattern is the load-bearing piece. Without it, the journal is write-only — useful for archival, useless for retrieval. The agent's pattern: query Notion's API for entries matching a keyword, return the top N results, summarize the findings. For larger databases, this is where vector search starts to matter — but for personal-scale knowledge bases (hundreds to low thousands of entries), keyword search is enough.

Task management (read + insert + update)

The third worked example. The bot creates and updates tasks in a Notion database:

  • "Create a task in Notion to review the Q2 financial reports by Friday" — agent creates a task with title, due date, priority, and status.

This is the full-trust mode. The agent can create new tasks, update existing ones (mark complete, change priority, reassign), and read everything. The channel's default for task management is to enable all capabilities and trust the agent to make sensible updates.

The audit pattern: review the database manually once a week. The agent's writes should match your intent. If the bot is creating duplicate tasks or updating fields it shouldn't, you've given it too much capability for the use case — drop back to read + insert.

The multi-database pattern

One Notion integration can connect to many databases. The pattern is:

  • Tasks database — full read+write for task management
  • Knowledge Base — read + insert for journaling
  • Data Analysis — read-only for trade journals, metrics, analytics
  • Meeting Notes — read + insert for daily standup summaries

The integration name shows up in the Connections menu of every database you add it to. You can have one integration handling four databases with four different permission modes — the integration itself doesn't have a single permission level; each database connection inherits the integration's default capabilities, which you can override per database.

The setup pattern:

  1. Create the integration once at notion.so/my-integrations
  2. Add the integration to each database via "..." → Connections
  3. Set capabilities at the integration level (the default applies unless overridden)
  4. Use the same NOTION_API_KEY env var for all of them

The channel's framing: this is why Notion is the canonical "second brain" — one integration, many databases, different trust levels per database, and one env var to manage.

Try it yourself

The hands-on goal: stand up a Notion integration with at least three databases (tasks, knowledge base, trade journal or equivalent), and verify the agent can read, write, and search across them.

  1. Create the integration at notion.so/my-integrations. Name it "OpenClaw Agent," pick your workspace, submit.
  2. Copy the Internal Integration Secret. The format is secret_.... Don't paste it anywhere except .env.
  3. Add to .env. nano ~/.openclaw/.env, add NOTION_API_KEY=secret_..., save, chmod 600.
  4. Create three databases in Notion. Tasks (full read+write), Knowledge Base (read+insert), Trade Journal or analytics equivalent (read-only). Add a few sample rows so the agent has something to query.
  5. Connect the integration to each database. Open each database → "..." → Connections → pick your integration → Connect. Do this for all three.
  6. Configure capabilities per database. For the analytics database, drop capabilities to read-only via the integration settings page. For tasks, leave all capabilities on.
  7. Restart the gateway (openclaw gateway restart) and verify the env var is loaded.
  8. Test the read-only use case. Send the agent: "count the rows in my analytics database and tell me the distribution by category." Verify it queries but doesn't write.
  9. Test the knowledge-base insert. Send: "create a new entry in my Knowledge Base titled 'Integration test' with today's date." Verify the entry appears in Notion.
  10. Test the task create. Send: "create a task in Notion: 'Review this course,' due Friday." Verify the task appears in the Tasks database with the correct due date.
  11. Test semantic search. Once you have a handful of Knowledge Base entries, send: "search my Knowledge Base for anything about [topic you've written about]." Verify the agent returns relevant entries.
  12. Audit the integration. Open Notion's connection list. Confirm the integration is connected to exactly the databases you intended. Revoke any you don't need.

Common pitfalls

  • Forgetting to connect the integration to the database. The integration exists at the workspace level, but Notion's permissions are database-scoped. The most common failure is "agent says it has no access to that database" — fix: "..." → Connections → add your integration.
  • Setting read-only when you need read+write. The default in Notion is full capabilities, which is the right call for most use cases. If you find yourself wanting the agent to update tasks but you disabled update capabilities, you're in the wrong mode for the use case. Re-enable.
  • Setting read+write when read-only would do. For trade journals and analytics, full capabilities is overkill. The principle of least privilege says: if the agent doesn't need to update, don't let it. If it accidentally writes to the trade journal, your data is corrupted.
  • Pasting the Internal Integration Secret in chat. Same rule as §8.1 step 3 — .env only, never chat. The Notion secret gives full read+write to every database the integration is connected to. A leaked secret is a workspace compromise.
  • Creating one integration per database. One integration handles many databases with different capabilities. Creating three integrations for three databases is unnecessary overhead and three secrets to manage.
  • Notion ≠ memory. The integration reads what's in the database. It doesn't synthesize, doesn't infer, doesn't make connections the user didn't write down. If the agent gives wrong answers to "search my notes for X," check whether X is actually in the database.
  • Skipping the semantic search pattern. A journal that's write-only is useless for retrieval. If you're writing daily entries but never querying them, you're using Notion as a notepad, not a second brain. Add a weekly "summarize what I learned this week" skill that queries the database.
  • Trusting the agent's writes without review. For task management, the agent will create duplicate tasks, miscategorize, and miss priorities. Review the database weekly until you trust the agent's judgment. Until then, treat its writes as suggestions, not state.
  • Not regenerating a leaked key. If the Internal Integration Secret ever appears in a screenshot, a commit, or a Discord message: regenerate immediately, update .env, restart the gateway. The old secret is compromised the moment it's exposed.

Sources

  • OpenClaw + Notion Integration — few thousand views · video_id: xcKBDXO4LLE · the spine of the article. The integration setup (create → secret → .env → connect databases → configure capabilities) is sourced from the video walkthrough. The three flagship use cases (trade journal analysis, knowledge base journaling, task management) are direct examples from the transcript.
  • .env discipline and "AI models are trained not to reveal env vars" — cross-referenced from Course 9: Security & Best Practices §9.1. The storage step is the §8.3 anchor; this article covers the Notion-specific mechanics.
  • Capabilities decision tree — read-only (data analysis), read+insert (knowledge base), read+insert+update (tasks) — sourced from the integration setup video's "Configuration Examples" section.
  • Multi-database pattern — one integration, many databases, different permissions — derived from Notion's connection model as documented in the video and Notion's own developer docs at developers.notion.com.