name

notion-sync

description

Backup and restore OpenClaw agent configuration to/from Notion databases. Use this skill whenever the user wants to sync, backup, push, pull, clone, migrate, or check the status of their agent configuration with Notion. Also trigger when the user mentions backing up their agent, moving to a new device, recovering agent settings after a crash, or syncing soul files to the cloud. Trigger on Chinese keywords too: "备份", "同步到Notion", "搬家", "恢复配置", "同步状态".

Notion Sync — Agent Backup & Restore

Sync OpenClaw agent soul files, skills, models, and bindings to Notion databases. Your agent's soul is backed up to the cloud and can be restored to any device.

Prerequisites

Python 3.11+
NOTION_TOKEN environment variable set (get it at https://www.notion.so/my-integrations)
The Notion integration must be connected to your target page

Installation

pip install -e /path/to/openclaw-notion-sync

Or if installed globally, the openclaw-notion command is available directly.

Workflows

First-Time Backup

Run these two commands to back up your agent for the first time:

openclaw-notion init --parent-page <notion-page-id>
openclaw-notion sync

The page ID is found in your Notion page URL: notion.so/Page-Name-<this-is-the-id>

This creates 12 Notion databases (Agents, Soul, Instructions, Tools, Identity, User, Heartbeat, Bootstrap, Memory, Skills, Models, Bindings) plus a Dashboard page, then pushes all local config to Notion.

Daily Backup

openclaw-notion sync

Only changed files are synced (incremental via mtime detection). Use --force to push everything.

Restore to New Device

On the new machine, after installing openclaw-notion-sync and setting NOTION_TOKEN:

openclaw-notion clone --parent-page <page-id>

This discovers existing databases on Notion and pulls all agent config to the local machine. Paths are automatically adapted (Mac ↔ Windows).

To skip model/binding config (configure locally instead):

openclaw-notion clone --parent-page <page-id> --skip-models --skip-bindings

Pull Changes from Notion

If you edited soul files in Notion's web editor:

openclaw-notion pull

Check Status

openclaw-notion status

Shows sync state, tracked databases, agent pages, and file counts.

Command Reference

openclaw-notion init --parent-page <id>    # Create databases + Dashboard
openclaw-notion sync                       # Push local → Notion
openclaw-notion sync --only soul           # Push only soul files
openclaw-notion sync --force               # Force full push
openclaw-notion push                       # Alias for sync
openclaw-notion pull                       # Pull Notion → local
openclaw-notion pull --only identity       # Pull only identity files
openclaw-notion clone --parent-page <id>   # Clone to new device
openclaw-notion migrate                    # Add new databases/properties
openclaw-notion status                     # Show sync state

Sync Types

Per-Agent Filtering

In the Notion Agents table, each agent has a Sync Enabled checkbox. Uncheck it to exclude that agent from sync/pull operations.

Security

API keys, bot tokens, and passwords are automatically redacted before upload (shown as ****xxxx)
Local files are never modified by the sync tool
Pulling from Notion preserves your local secrets — redacted values won't overwrite real ones

Troubleshooting

"NOTION_TOKEN not set" — Create a .env file with NOTION_TOKEN=ntn_... in your working directory, or set the environment variable
"Not initialized" — Run openclaw-notion init --parent-page <id> first
Timeout errors — The tool automatically retries with exponential backoff. If persistent, try --only to sync fewer items at once
"Can't find Agents database" — Make sure the Notion integration is connected to your target page (Settings → Connections)