Notion Enhanced

# Notion Integration

将您的 Notion 工作区连接到 OpenClaw，实现无缝的知识管理和项目跟踪。

## 何时使用此技能

当用户想要以下操作时，请使用 Notion： - **向数据库添加项目**（backlog、待办事项、跟踪） - **在数据库中或作为现有页面的子页面创建新页面** - **查询/搜索**他们的 Notion 工作区以获取信息 - **更新现有页面**（状态、备注、属性） - **阅读页面内容**或数据库条目

## 设置

### 1. 创建 Notion 集成 1. 访问 [notion.so/my-integrations](https://www.notion.so/my-integrations) 2. 点击 **New integration**（新建集成） 3. 命名（例如，“OpenClaw”） 4. 选择您的工作区 5. 复制 **Internal Integration Token**（内部集成令牌，以 `secret_` 开头） 6. 将此令牌安全地保存在 OpenClaw 配置或环境中：`NOTION_TOKEN=secret_...`

### 2. 与集成共享页面 **重要：** Notion 集成默认没有任何访问权限。您必须显式共享：

1. 在 Notion 中转到任意页面或数据库 2. 点击 **Share**（分享）→ **Add connections**（添加连接） 3. 选择您的“OpenClaw”集成 4. 该技能现在可以读取/写入该特定页面/数据库

### 3. 获取数据库/页面 ID

**从 URL 获取：** - 数据库：`https://www.notion.so/workspace/XXXXXXXX?v=...` → ID 为 `XXXXXXXX`（32 个字符） - 页面：`https://www.notion.so/workspace/XXXXXXXX` → ID 为 `XXXXXXXX`

**注意：** 使用 ID 时请移除连字符。使用 32 个字符的字符串。

## 核心操作

### 查询数据库

从您已共享的任何数据库中检索条目。

```typescript // 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"}}'` }); ```

**返回：** 页面数组，包含在您的数据库中配置的属性。

### 添加数据库条目

在数据库中创建一个新行。

```typescript // 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" } } })}'` }); ```

### 获取页面内容

读取任何页面（包括数据库条目）的内容。

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

**返回：** 页面标题、属性和块内容（文本、标题、列表等）。

### 更新页面

修改属性或将内容追加到现有页面。

```typescript // 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` }); ```

### 搜索 Notion

在您共享的工作区中查找页面。

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

## 常见用例

### 内容流水线（内容创作者工作流）

**数据库结构：** - 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 集成：** ```typescript // 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..." } }] } })}'` }); ```

### 项目管理（个体创业者）

**数据库结构：** - 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)

**每周审查集成：** ```typescript // 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"}}'` }); ```

### 客户/报价 CRM（3D 打印业务）

**数据库结构：** - 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 集成：** ```typescript // 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 } }] } })}'` }); ```

### 知识库（MEMORY.md 的 Wiki 替代方案）

**结构：** 带有嵌套页面的中心页面： - 🏠 Home (已与集成共享) - SOPs - Troubleshooting - Design Patterns - Resource Links

**查询以供快速参考：** ```typescript // Search for "stringing" to find 3D print troubleshooting await exec({ command: `node ~/.agents/skills/notion/notion-cli.js search "stringing"` }); ```

## 属性类型参考

创建/更新数据库条目时，请使用以下属性值格式：

```typescript // 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": "[email protected]" }

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

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

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

## 安全性与权限

**关键安全模型：** - ✅ 集成只能看到您显式共享的页面 - ✅ 您可以控制每个页面/数据库的访问权限 - ✅ 令牌安全地存储在 `~/.openclaw/.env` 中（绝不在代码中） - ❌ 永远不要将 `NOTION_TOKEN` 提交到 git - ❌ 集成无法访问私有团队空间或其他用户的私有页面

**最佳实践：** 1. 使用专用集成（不要复用个人集成） 2. 仅共享最少必要的页面（细粒度 > 宽泛） 3. 如果令牌泄露，请通过 Notion 集成设置轮换令牌 4. 定期审查共享的连接

## 环境设置

添加到 `~/.openclaw/.env`： ```bash NOTION_TOKEN=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ```

或按命令设置： ```bash NOTION_TOKEN=secret_xxx node notion-cli.js ... ```

## 错误处理

常见错误及修复方法：

| 错误 | 原因 | 修复方法 | |-------|-------|-----| | "API token is invalid" | 令牌错误或集成已删除 | 在 notion.so/my-integrations 检查令牌 | | "object_not_found" | 页面未与集成共享 | 共享页面：Share → Add connections | | "validation_error" | 属性格式不正确 | 检查数据库中的属性类型 | | "rate_limited" | 请求过多 | 在请求之间添加延迟 |

## 快速安装（一条命令）

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

**手动安装（如果上述方法失败）：** ```bash cd ~/.agents/skills/notion npm install ```

就这样！独立版本不需要构建步骤。

## 快速测试

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

## 智能 ID 解析

通过 **Notion 自动 ID**（例如 `#3`）或 **直接 UUID** 引用条目。

### 通过 Notion ID（推荐用于手动使用）

使用您在数据库 ID 列中看到的数字：

```bash # 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 ```

### 通过直接 UUID（用于自动化）

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

**自动检测：** 以 `#` 开头 = Notion ID 查找。32 位十六进制 = 直接 UUID。

**专业提示：** 添加一个 `ID` 属性（类型：unique ID）以将条目自动编号为 #1、#2、#3……

## 页面正文编辑

向页面正文添加丰富内容，而不仅仅是属性。

### 追加内容块

```bash # 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 ```

### 支持的块类型

| 类型 | 描述 | 示例用途 | |------|-------------|-------------| | `paragraph` | 常规文本（默认） | 描述、说明 | | `h1`, `h2`, `h3` | 标题 | 章节组织 | | `bullet` | 无序列表 | 主要发现、功能 | | `numbered` | 有序列表 | 分步说明 | | `todo` | 复选框项目 | 行动项目、任务 | | `quote` | 引用块 | 来源引用 | | `code` | 代码块 | 代码片段、命令 | | `divider` | 水平线 | 章节分隔 |

### 获取带有正文内容的页面

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

返回： - 页面属性 - 格式化的正文块（类型 + 内容预览） - 块计数

### 高级：原始 JSON 块

对于复杂的布局，请使用原始 Notion 块 JSON：

```bash 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"}} ]' ```

## 高级：Webhook 同步

用于双向同步（Notion 更改 → OpenClaw）：

1. 设置 Notion webhook 集成（需要 Notion 合作伙伴账户） 2. 将 webhook 端点配置到您的 OpenClaw Gateway 3. 技能处理传入的 webhook 并更新内存文件

有关实现详细信息，请参阅 [references/webhooks.md](references/webhooks.md)。

---

**需要帮助？** 在 https://www.notion.so/my-integrations 检查您的 Notion 集成设置

## 在 OpenClaw 中使用

### 快速设置

```bash # 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 ```

### 从 OpenClaw Agent

```typescript // 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 使用

更新您的研究主题侦察员以推送到 Notion：

```typescript "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\"}]}}'" ```