OpenClaw Skills Notion CLI（Notion 命令行控制器）

一款轻量、极速的 Notion 命令行工具，无需打开界面即可管理页面、数据库、文本块、任务等所有内容。 支持：查询、创建、编辑、删除、列表展示、搜索、数据库筛选。

👤 作者：Peter Steinberger
👉 Skills 下载地址：notion-1.0.0.zip

安装（中文注释版）

## 通过 Homebrew 安装 Notion 命令行工具
brew install steipete/tap/notion


## 验证安装
notion --version

配置（必须）

## 配置 Notion API 令牌（从 Notion 开发者后台获取）
notion configure


## 或直接设置环境变量
export NOTION_TOKEN="你的API令牌"

基础使用（全中文注释）

1. 工作区与页面查询

## 列出所有工作区
notion workspace list


## 列出最近访问的页面
notion page list


## 列出指定父页面下的子页面
notion page list --parent "页面ID或页面名称"


## 搜索页面（关键词搜索）
notion search "会议记录"

2. 页面操作

## 创建新页面（指定标题与父页面）
notion page create "今日待办" --parent "工作区/任务"


## 查看页面完整内容
notion page view "页面ID或名称"


## 更新页面标题
notion page update "旧标题" --title "新标题"


## 删除页面
notion page delete "页面名称"

3. 数据库操作（最常用）

## 列出所有数据库
notion database list


## 查看数据库结构（字段、属性）
notion database view "数据库ID"


## 查询数据库内容（默认全部）
notion database query "任务数据库"


## 筛选数据库（状态=进行中）
notion database query "任务数据库" --filter "状态=进行中"


## 数据库新增条目
notion database create "任务数据库" --name "完成文档" --status "待办"

4. 文本块（Block）操作

## 查看页面内所有块
notion block list "页面ID"


## 添加文本块
notion block create "页面ID" --text "这是一段正文内容"


## 添加待办事项
notion block create "页面ID" --todo "完成CLI翻译" --checked false


## 添加标题
notion block create "页面ID" --heading "章节一：介绍"

5. 快速任务（极简用法）

## 快速添加待办到默认数据库
notion task "购买生活用品"


## 快速添加带日期的任务
notion task "周五会议" --date "2026-03-07"

常用命令速查表（中文版）

工具特点

✅ 无需打开 Notion 界面，终端直接管理
✅ 支持数据库筛选、排序、创建条目
✅ 支持文本、待办、标题等所有块类型
✅ 可用于自动化脚本、工作流
✅ 极快响应，本地执行

官方信息

• 技能地址：https://clawhub.ai/steipete/notion
• 适用平台：macOS / Linux
• 安装命令：brew install steipete/tap/notion

Notion API 使用指南

名称：notion 描述：用于创建和管理页面、数据源（数据库）、区块的 Notion API。 主页：https://developers.notion.com 元数据：{"clawdbot":{"emoji":"📝"}}

一、环境配置

1. 前往 https://notion.so/my-integrations 创建集成应用
2. 复制 API 密钥（以 ntn_ 或 secret_ 开头）
3. 存储密钥（执行以下命令）：

   ## 创建 Notion 配置目录
   mkdir -p ~/.config/notion
   ## 将 API 密钥写入配置文件（替换 ntn_your_key_here 为实际密钥）
   echo "ntn_your_key_here" > ~/.config/notion/api_key

4. 将目标页面/数据源共享给你的集成应用（点击页面右上角「...」→「Connect to」→ 选择你的集成应用名称）

二、API 基础规范

所有请求必须包含以下请求头和鉴权信息：

## 从配置文件读取 API 密钥
NOTION_KEY=$(cat ~/.config/notion/api_key)
## 通用请求示例（替换 ... 为具体接口路径）
curl -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_KEY" \  # 鉴权头（必填）
  -H "Notion-Version: 2025-09-03" \         # API 版本头（必填，当前最新版本）
  -H "Content-Type: application/json"       # 内容类型（JSON 格式）

注意：Notion-Version 请求头为必填项。本指南使用最新版本 2025-09-03，该版本中 API 里的「databases（数据库）」统一称为「data sources（数据源）」。

三、常用操作示例

1. 搜索页面和数据源

curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "页面标题"}'  # 搜索关键词（替换为实际要搜索的标题）

2. 获取页面详情

## 替换 {page_id} 为目标页面的 UUID
curl "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

3. 获取页面内容（区块）

## 替换 {page_id} 为目标页面的 UUID
curl "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

4. 在数据源中创建页面

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},  # 父数据源 ID（替换为实际 ID）
    "properties": {
      "Name": {"title": [{"text": {"content": "新条目"}}]},  # 标题属性
      "Status": {"select": {"name": "待办"}}                 # 选择型属性（状态）
    }
  }'

5. 查询数据源（数据库）

## 替换 {data_source_id} 为目标数据源的 ID
curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "活跃"}},  # 筛选条件
    "sorts": [{"property": "Date", "direction": "descending"}]       # 排序规则（按日期降序）
  }'

6. 创建数据源（数据库）

curl -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},  # 父页面 ID（数据源挂载的页面）
    "title": [{"text": {"content": "我的数据库"}}],  # 数据源名称
    "properties": {                # 数据源属性配置
      "Name": {"title": {}},       # 标题型属性
      "Status": {"select": {"options": [{"name": "待办"}, {"name": "已完成"}]}},  # 选择型属性（含选项）
      "Date": {"date": {}}         # 日期型属性
    }
  }'

7. 更新页面属性

## 替换 {page_id} 为目标页面的 UUID
curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "已完成"}}}}'  # 更新状态为「已完成」

8. 向页面添加区块

## 替换 {page_id} 为目标页面的 UUID
curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      # 添加一个段落区块
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "你好"}}]}}
    ]
  }'

四、数据源属性类型格式

数据源条目常用属性格式说明：

• 标题（Title）：{"title": [{"text": {"content": "内容"}}]}
• 富文本（Rich text）：{"rich_text": [{"text": {"content": "内容"}}]}
• 单选（Select）：{"select": {"name": "选项名称"}}
• 多选（Multi-select）：{"multi_select": [{"name": "选项A"}, {"name": "选项B"}]}
• 日期（Date）：{"date": {"start": "2024-01-15", "end": "2024-01-16"}}（start 为必填，end 可选）
• 复选框（Checkbox）：{"checkbox": true}（true/false）
• 数字（Number）：{"number": 42}
• 链接（URL）：{"url": "https://示例.com"}
• 邮箱（Email）：{"email": "a@b.com"}
• 关联（Relation）：{"relation": [{"id": "关联页面的ID"}]}

五、2025-09-03 版本核心差异

1. 命名变更：「Databases（数据库）」正式改为「Data Sources（数据源）」，查询/获取数据源需使用 /data_sources/ 端点
2. 双 ID 机制：每个数据源同时拥有 database_id 和 data_source_id：
   • 创建页面时，父级需指定 database_id（parent: {"database_id": "..."}）
   • 查询数据源时，需使用 data_source_id（POST /v1/data_sources/{id}/query）
3. 搜索结果：数据源在搜索结果中以 "object": "data_source" 展示，并返回 data_source_id
4. 响应中的父级信息：页面响应会同时包含 parent.data_source_id 和 parent.database_id
5. 获取 data_source_id：可通过搜索数据源，或调用 GET /v1/data_sources/{data_source_id} 接口获取

六、注意事项

1. 页面/数据源 ID 为 UUID 格式（支持带短横线或不带短横线）
2. API 无法设置数据库视图筛选条件（该功能仅支持在 Notion 客户端 UI 操作）
3. 接口限流：平均约 3 次请求/秒
4. 创建数据源时，设置 is_inline: true 可将数据源嵌入到页面中