Notion

通过 Maton 平台安全连接 Notion，支持查询、搜索与读取内容，写操作需用户确认。

已扫描

项目

内容

适合谁

需要自动化管理 Notion 内容的个人用户、希望集成 Notion 数据到工作流的开发者

不适合谁

无需与 Notion 交互的普通用户、无法访问网络或配置 API 密钥的环境

国内可用性

需网络配置。可能需要网络配置或第三方服务可访问。

安装难度

新手友好（★☆☆）。基于终端操作、依赖、API Key 和本地环境要求的初步判断。

安装与下载

复制命令安装

openclaw skills install @byungkyu/notion-api-skill

官方 ZIP下载官方 ZIP

Skill 说明

命令、参数、文件名以原文为准

Notion

通过已管理的 OAuth 认证访问 Notion API。可查询数据库、搜索页面并读取工作区内容。所有写操作（创建、更新或删除页面、块和数据库）均需用户在执行前明确确认目标资源及连接。

快速开始

CLI：

maton notion search 'meeting notes'

maton api '/notion/v1/search'

Python：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': 'meeting notes'}).encode()
req = urllib.request.Request('https://api.maton.ai/notion/v1/search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://api.maton.ai/notion/{native-api-path}

Maton 将请求代理至 api.notion.com，并自动注入您的 OAuth 令牌。写操作（POST、PATCH、DELETE）仅可在用户确认目标页面/数据库 ID 及预期连接后执行。

必需请求头

所有 Notion API 请求均需包含版本头：

Notion-Version: 2025-09-03

安装

NPM：

npm install -g @maton-ai/cli

Homebrew：

brew install maton-ai/cli/maton

认证

CLI：

maton login                          # 打开浏览器获取 API 密钥
maton login --interactive            # 跳过浏览器，直接粘贴 API 密钥
maton whoami                         # 显示当前认证状态

手动方式：

访问 [maton.ai](https://maton.ai) 登录或注册账户
进入 [maton.ai/settings](https://maton.ai/settings)
复制您的 API 密钥
将 API 密钥设置为环境变量 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

连接管理

在 https://api.maton.ai 管理您的 Notion OAuth 连接。

列出连接

CLI：

maton connection list notion --status ACTIVE

maton api -X GET /connections -f app=notion -f status=ACTIVE

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=notion&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

CLI：

maton connection create notion

maton api /connections -f app=notion

Python：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'notion'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

CLI：

maton connection view {connection_id}

maton api /connections/{connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "notion",
    "method": "OAUTH2",
    "metadata": {}
  }
}

请在浏览器中打开返回的 url 以完成 OAuth 授权流程。

删除连接

CLI：

maton connection delete {connection_id}

maton api -X DELETE /connections/{connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

若您拥有多个 Notion 连接，请明确指定使用哪一个：

CLI：

maton notion search 'meeting notes' --connection {connection_id}

maton api /notion/v1/search --connection {connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': 'meeting notes'}).encode()
req = urllib.request.Request('https://api.maton.ai/notion/v1/search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

若存在多个连接，始终指定连接以确保请求发送至正确的账户。

核心概念：数据库 vs 数据源

在 API 版本 2025-09-03 中，数据库与数据源是独立的概念：

概念	使用场景
数据库	创建数据库、获取数据源 ID
数据源	查询数据、更新模式、修改属性

使用 GET /databases/{id} 获取 data_sources 数组，然后调用 /data_sources/ 相关接口：

{
  "object": "database",
  "id": "abc123",
  "data_sources": [
    {"id": "def456", "name": "My Database"}
  ]
}

安全与权限

权限范围限定在连接的 Notion 账户中的页面、数据库、块、用户以及搜索操作。
所有写入操作均需用户明确授权。 在执行任何创建、更新或删除操作前：

1. 与用户确认目标对象（页面 ID、数据库 ID、块 ID）。

2. 若存在多个连接，验证正确的连接 ID。

3. 明确说明该操作是否可逆或具有破坏性。

不可逆或高风险操作（需特别谨慎）：

- 删除页面或块（虽为归档状态，非永久删除，但可能影响工作流）

- 对多个页面或数据库进行批量更新

- 修改对其他团队成员可见的共享工作区页面

作用范围边界：

- 仅对用户明确命名或标识的页面和数据库进行操作。不得枚举或修改当前任务上下文以外的资源。

- 使用任务所需的最小权限 Notion 连接。

- 未经用户明确批准，不得执行批量或批处理操作。

API 参考

搜索

搜索页面：

POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "query": "meeting notes",
  "filter": {"property": "object", "value": "page"}
}

示例：

maton notion search 'meeting notes' --filter page

搜索数据源：

POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "filter": {"property": "object", "value": "data_source"}
}

示例：

maton notion search --filter data_source

数据源

获取数据源

GET /notion/v1/data_sources/{dataSourceId}
Notion-Version: 2025-09-03

示例：

maton notion data-source view <dataSourceId>

查询数据源

POST /notion/v1/data_sources/{dataSourceId}/query
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "filter": {
    "property": "Status",
    "select": {"equals": "Active"}
  },
  "sorts": [
    {"property": "Created", "direction": "descending"}
  ],
  "page_size": 100
}

示例：

maton notion data-source query <dataSourceId> \
  --filter '{"property":"Status","select":{"equals":"Active"}}' \
  --sorts '[{"property":"Created","direction":"descending"}]' \
  --page-size 100

更新数据源

PATCH /notion/v1/data_sources/{dataSourceId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "title": [{"type": "text", "text": {"content": "Updated Title"}}],
  "properties": {
    "NewColumn": {"rich_text": {}}
  }
}

示例：

maton notion data-source update <dataSourceId> \
  --body '{"title":[{"type":"text","text":{"content":"Updated Title"}}],"properties":{"NewColumn":{"rich_text":{}}}}'

数据库

获取数据库

GET /notion/v1/databases/{databaseId}
Notion-Version: 2025-09-03

示例：

maton notion database view <databaseId>

创建数据库

POST /notion/v1/databases
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"type": "page_id", "page_id": "PARENT_PAGE_ID"},
  "title": [{"type": "text", "text": {"content": "New Database"}}],
  "properties": {
    "Name": {"title": {}}
  }
}

示例：

maton notion database create --parent-page PARENT_PAGE_ID --title 'New Database'

在 API 版本 2025-09-03 中，POST /databases 仅接受 title 属性——properties 中的其他字段将被静默忽略。如需定义结构，请在创建后调用 PATCH /data_sources/{dataSourceId}（参见 [更新数据源](#update-data-source)），使用创建返回的 data_sources[0].id。

页面

获取页面

GET /notion/v1/pages/{pageId}
Notion-Version: 2025-09-03

示例：

maton notion page view <pageId>

创建页面

POST /notion/v1/pages
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"page_id": "PARENT_PAGE_ID"},
  "properties": {
    "title": {"title": [{"text": {"content": "New Page"}}]}
  }
}

示例：

maton notion page create --parent-page PARENT_PAGE_ID --title 'New Page'

在数据源中创建页面

POST /notion/v1/pages
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"data_source_id": "DATA_SOURCE_ID"},
  "properties": {
    "Name": {"title": [{"text": {"content": "New Page"}}]},
    "Status": {"select": {"name": "Active"}}
  }
}

示例：

maton notion page create --data-source DATA_SOURCE_ID --title 'New Page' \
  --properties '{"Status":{"select":{"name":"Active"}}}'

更新页面属性

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "properties": {
    "Status": {"select": {"name": "Done"}}
  }
}

示例：

maton notion page update {pageId} --properties '{"Status":{"select":{"name":"Done"}}}'

更新页面图标

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "icon": {"type": "emoji", "emoji": "🚀"}
}

示例：

maton notion page update {pageId} --icon 🚀

或使用图片 URL：

maton notion page update {pageId} --icon https://example.com/icon.png

归档页面

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "archived": true
}

示例：

maton notion page archive {pageId}

块

获取块子项

GET /notion/v1/blocks/{blockId}/children
Notion-Version: 2025-09-03

示例：

maton notion block children <blockId>

追加块子项

name: Notion

version: 1.0.10

description: 与 Notion API 集成，支持页面、数据库、块等操作。

summary: 通过 Maton CLI 或 API 与 Notion 进行交互，实现数据查询、页面管理、块操作等功能。

块（Blocks）

在块末尾追加子块

PATCH /notion/v1/blocks/{blockId}/children
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [{"type": "text", "text": {"content": "New paragraph"}}]
      }
    }
  ]
}

示例：

maton notion block append <blockId> \
  --children '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"New paragraph"}}]}}]'

删除块

DELETE /notion/v1/blocks/{blockId}
Notion-Version: 2025-09-03

示例：

maton notion block delete <blockId>

用户（Users）

列出所有用户

GET /notion/v1/users
Notion-Version: 2025-09-03

示例：

maton notion user list

获取当前用户信息

GET /notion/v1/users/me
Notion-Version: 2025-09-03

示例：

maton notion whoami

过滤操作符

equals：等于
does_not_equal：不等于
contains：包含
does_not_contain：不包含
starts_with：以...开头
ends_with：以...结尾
is_empty：为空
is_not_empty：不为空
greater_than：大于
less_than：小于

块类型

paragraph：段落
heading_1、heading_2、heading_3：一级、二级、三级标题
bulleted_list_item：无序列表项
numbered_list_item：有序列表项
to_do：待办事项
code：代码块
quote：引用
divider：分隔线

分页机制

Notion 使用基于游标的分页方式。CLI 工具会自动处理分页，使用 --paginate 参数即可。

示例：

maton notion data-source query <dataSourceId> --paginate

代码示例

CLI 命令

# 搜索匹配查询条件的页面
maton notion search 'roadmap'

# 查看特定页面
maton notion page view 0123456789abcdef0123456789abcdef

# 使用过滤器查询数据源
maton notion data-source query <dataSourceId> --filter '{"property":"Status","select":{"equals":"Active"}}'

# 使用 jq 进行筛选 —— 例如仅保留页面（响应被包裹在 {"results": [...]} 中）
# 注意：--jq 需要配合 --json 使用
maton notion search 'roadmap' --json --jq '.results | map(select(.object == "page"))'

JavaScript

const response = await fetch('https://api.maton.ai/notion/v1/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
    'Notion-Version': '2025-09-03'
  },
  body: JSON.stringify({ query: 'meeting' })
});

Python

import os
import requests

response = requests.post(
    'https://api.maton.ai/notion/v1/search',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Notion-Version': '2025-09-03'
    },
    json={'query': 'meeting'}
)

注意事项

所有 ID 均为 UUID 格式（可带或不带连字符）
使用 GET /databases/{id} 可获取包含数据源 ID 的 data_sources 数组
创建数据库需使用 POST /databases 接口
删除块后返回的块对象中 archived 字段为 true
重要提示：使用 curl 命令时，若 URL 包含方括号（如 fields[]、sort[]、records[]），请使用 curl -g 以禁用通配符解析
重要提示：当将 curl 输出管道传递给 jq 等命令时，某些 shell 环境下环境变量（如 $MATON_API_KEY）可能无法正确展开，可能导致“无效 API 密钥”错误

错误处理

状态码	含义
400	缺少 Notion 连接
401	无效或缺失的 Maton API 密钥
429	被限流（每账户每秒最多 10 次请求）
4xx/5xx	透传自 Notion API 的错误

故障排查：API 密钥问题

CLI 环境：

检查当前认证状态：

maton whoami

验证 API 密钥是否有效，列出连接：

maton connection list

手动方式：

检查 MATON_API_KEY 环境变量是否已设置：

echo $MATON_API_KEY

通过脚本验证 API 密钥有效性，列出连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排查：应用名称无效

确保请求路径以 notion 开头。例如：

正确：https://api.maton.ai/notion/v1/search
错误：https://api.maton.ai/v1/search

Notion

安装与下载

Skill 说明

Notion

快速开始

基础 URL

必需请求头

安装

认证

连接管理

列出连接

创建连接

获取连接

删除连接

指定连接

核心概念：数据库 vs 数据源

安全与权限

API 参考

搜索

数据源

获取数据源

查询数据源

更新数据源

数据库

获取数据库

创建数据库

页面

获取页面

创建页面

在数据源中创建页面

更新页面属性

更新页面图标

归档页面

块

获取块子项

追加块子项

块（Blocks）

在块末尾追加子块

删除块

用户（Users）

列出所有用户

获取当前用户信息

过滤操作符

块类型

分页机制

代码示例

CLI 命令

JavaScript

Python

注意事项

错误处理

故障排查：API 密钥问题

故障排查：应用名称无效

相关资源

相关推荐

Change permissions of PDF

WeChat Read CN

File Compression