Day 4 / 7

第4天:连接外部世界

让OpenClaw接入Notion,打造你的第二大脑

📖 阅读时间:约25分钟🎯 难度:中级
学习进度4/7

📚 今天你将学到

  • 为什么工具系统是AI助手的核心
  • TOOLS.md的完整设计逻辑和编写规范
  • 实战:从零接入Notion数据库(完整代码)
  • 3个真实场景:选题管理、任务追踪、知识检索
  • 工具调试技巧和常见问题解决
  • 进阶:多工具协作和错误处理

前三天,我们搭建了OpenClaw,给它写了身份文件。但现在它只能"说",不能"做"。就像雇了一个只会聊天的助理,问他"帮我查一下上周的选题",他只能回答"你可以去Notion里找找"。

今天,我们要给它装上"手脚",让它能真正帮你干活。我们会从最实用的场景入手:让OpenClaw连接你的Notion知识库

为什么是工具系统?

很多人以为AI助手的核心是"聊天能力",其实不是。真正的核心是执行能力

对比维度纯聊天AI有工具的AI
你的需求"查一下上周的选题""查一下上周的选题"
AI的回应"你可以去Notion里搜索""找到3条:AI工具评测、Prompt技巧、..."
你的操作打开Notion,手动搜索什么都不用做
节省时间0秒2-3分钟

这就是工具系统的价值:让AI从"顾问"变成"员工"

真实场景对比

场景1:内容创作者的选题管理

❌ 没有工具

你:"帮我看看最近有哪些AI工具类的选题"

AI:"建议你在Notion的选题库里筛选标签为'AI工具'的记录"

→ 你还得自己去Notion翻

✅ 有了工具

你:"帮我看看最近有哪些AI工具类的选题"

AI:"找到5条:1. Claude Code深度评测 2. Cursor使用技巧 3. ..."

→ 直接拿到结果,节省3分钟

场景2:项目经理的任务追踪

❌ 没有工具

你:"今天有哪些任务要完成?"

AI:"你可以查看Notion的任务看板"

→ 废话,我当然知道

✅ 有了工具

你:"今天有哪些任务要完成?"

AI:"今天有3个任务:1. 完成Day4教程(截止18:00)2. 审核设计稿 3. ..."

→ 直接获取今日待办

场景3:知识工作者的信息检索

❌ 没有工具

你:"我之前记录的那个API文档链接是什么?"

AI:"你可以在Notion里搜索'API文档'关键词"

→ 还得自己搜,可能搜不到

✅ 有了工具

你:"我之前记录的那个API文档链接是什么?"

AI:"找到了:https://docs.anthropic.com/claude/reference,记录在《技术资源》页面"

→ 秒级响应,精准定位

核心结论:工具系统不是"锦上添花",而是"质变"。没有工具,AI只是个聊天机器人;有了工具,AI才是真正的助手。

TOOLS.md:AI的能力说明书

Day 3我们写了SOUL.md,定义AI"是谁"。今天的TOOLS.md定义AI"能做什么"。

工作原理(完整流程)

1

用户发送指令

"帮我查一下上周写了哪些选题"

→ OpenClaw接收到消息

2

AI读取TOOLS.md

发现有"query_notion_database"工具,功能是"查询Notion数据库"

→ AI判断:这个工具可以完成任务

3

AI生成调用指令

构造命令:query_notion_database --db "选题库" --filter "上周"

→ 根据TOOLS.md的参数说明生成

4

OpenClaw执行脚本

运行 tools/notion.py,调用Notion API,获取数据

→ 返回JSON格式的结果

5

AI整理并回复

将JSON数据转换成人类可读的格式,回复用户

→ "上周写了3个选题:1. AI工具评测 2. ..."

TOOLS.md的标准格式(重要!)

每个工具必须包含以下7个部分,缺一不可:

## 工具名称(简短、语义明确)
**名称:** query_notion_database
**描述:** 查询Notion数据库中的记录,支持按标签、日期、状态筛选
**适用场景:**(至少写3个具体场景)
- 查找特定主题的选题记录
- 检索包含某个关键词的笔记
- 获取本周/本月的任务列表

**调用方式:**
```bash
python3 tools/notion.py --action query --database <数据库名> --filter <筛选条件>
```

**参数说明:**(每个参数都要解释清楚)
- action: 操作类型(query/create/update)
- database: 数据库名称(如"选题库"、"任务看板")
- filter: 筛选条件(支持标签、日期、关键词)

**返回格式:**(告诉AI会返回什么)
JSON数组,每条记录包含:
- title: 标题
- tags: 标签列表
- created_time: 创建时间
- url: Notion页面链接

**示例对话:**(这是最重要的部分!)
用户:"帮我看看最近有哪些AI工具类的选题"
AI:"正在查询..." → 调用工具 → "找到5条记录:..."

用户:"上周写了哪些内容?"
AI:"查询上周的记录..." → 调用工具 → "上周完成3篇:..."

⚠️ 三个常见错误

错误1:没写"示例对话"

AI不知道什么时候该用这个工具,永远不会主动调用。

错误2:工具名称太抽象

比如"tool1"、"helper",AI无法理解功能。应该用"query_notion"这种语义明确的名称。

错误3:参数说明不清楚

只写"--filter 筛选条件",AI不知道能筛选什么。要写清楚"支持标签、日期、关键词"。

实战:接入Notion数据库(完整教程)

接下来我们用40分钟,从零完成Notion集成。

步骤1:创建Notion Integration(10分钟)

1. 创建Integration

访问 https://www.notion.so/my-integrations,点击"New integration"

2. 配置权限

勾选:Read content、Update content、Insert content

3. 获取Token

复制"Internal Integration Token"(格式:secret_xxx)

4. 连接数据库

打开数据库页面 → 右上角"..." → "Add connections" → 选择你的Integration

5. 获取数据库ID

URL中的32位字符:https://notion.so/xxxxx?v=yyyyy

步骤2:编写工具脚本(20分钟)

创建 tools/notion.py

#!/usr/bin/env python3
import requests, json, argparse, os
from datetime import datetime, timedelta

NOTION_TOKEN = os.getenv("NOTION_TOKEN")
BASE_URL = "https://api.notion.com/v1"

DATABASE_MAP = {
    "选题库": "your_database_id_here"
}

def query_database(db_name, filter_type=None, filter_value=None):
    db_id = DATABASE_MAP.get(db_name)
    if not db_id:
        return {"error": f"未找到数据库:{db_name}"}

    url = f"{BASE_URL}/databases/{db_id}/query"
    headers = {
        "Authorization": f"Bearer {NOTION_TOKEN}",
        "Notion-Version": "2022-06-28"
    }

    payload = {}
    if filter_type == "tags":
        payload["filter"] = {
            "property": "标签",
            "multi_select": {"contains": filter_value}
        }

    response = requests.post(url, headers=headers, json=payload)
    data = response.json()

    results = []
    for page in data.get("results", []):
        title_prop = page["properties"].get("标题")
        title = "".join([t["plain_text"] for t in title_prop["title"]])
        results.append({"title": title, "url": page["url"]})

    return {"count": len(results), "results": results}

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--action", required=True)
    parser.add_argument("--database", required=True)
    parser.add_argument("--filter-type")
    parser.add_argument("--filter-value")
    args = parser.parse_args()

    result = query_database(args.database, args.filter_type, args.filter_value)
    print(json.dumps(result, ensure_ascii=False))

步骤3:配置环境变量(3分钟)

# 编辑 ~/.zshrc
export NOTION_TOKEN="secret_xxxxx"

# 生效
source ~/.zshrc

步骤4:更新TOOLS.md(5分钟)

docs/TOOLS.md 添加:

## Notion数据库查询
**名称:** query_notion
**描述:** 查询Notion数据库中的记录
**适用场景:**
- 查找特定标签的选题
- 检索包含关键词的笔记
- 获取本周创建的任务

**调用方式:**
```bash
python3 tools/notion.py --action query --database "选题库" --filter-type tags --filter-value "AI工具"
```

**示例对话:**
用户:"帮我看看最近有哪些AI工具类的选题"
AI:"正在查询..." → 调用工具 → "找到5条:..."

步骤5:测试(2分钟)

重启OpenClaw,发送测试消息:

"帮我查一下选题库里有哪些内容"

如果AI返回了查询结果,说明集成成功!

3个真实使用场景

场景1:选题灵感管理

你在Notion有个"选题库",每次看到好的选题就记录下来。现在想找"AI工具"相关的选题:

你:"最近有哪些AI工具类的选题可以写?"

AI:"找到5条AI工具选题:

  • 1. Claude Code深度评测(标签:AI工具、编程)
  • 2. Cursor使用技巧(标签:AI工具、效率)
  • 3. ..."

场景2:任务进度追踪

你的"任务看板"里有很多任务,想看看本周完成了哪些:

你:"本周完成了哪些任务?"

AI:"本周完成3个任务:

  • 1. Day3教程编写 ✅
  • 2. 社群答疑整理 ✅
  • 3. PPT模板优化 ✅"

场景3:知识快速检索

你记得之前保存过一个API文档链接,但忘了在哪个页面:

你:"我之前记录的Anthropic API文档在哪?"

AI:"找到了:《技术资源汇总》页面

链接:https://docs.anthropic.com/claude/reference"

工具调试技巧

常见问题排查

问题1:AI不调用工具

原因:TOOLS.md写得不够清楚

解决:

  • • 检查是否写了"示例对话"
  • • 工具名称是否语义明确
  • • 适用场景是否具体
问题2:工具调用失败

排查步骤:

  1. 1. 手动运行脚本,看是否报错
  2. 2. 检查环境变量是否配置
  3. 3. 查看OpenClaw日志(~/.openclaw/logs/)
  4. 4. 确认API Token是否有效
问题3:返回数据格式错误

原因:Notion数据库属性名称不匹配

解决:检查脚本中的属性名(如"标题"、"标签")是否和你的数据库一致

调试技巧

  1. 1. 先手动测试

    在终端直接运行脚本,确认能正常工作

    python3 tools/notion.py --action query --database "选题库"
  2. 2. 查看日志

    OpenClaw会记录所有工具调用

    tail -f ~/.openclaw/logs/openclaw.log
  3. 3. 添加调试输出

    在脚本中加入print语句,查看中间结果

💡 本章要点回顾

  • • 工具系统让AI从"顾问"变成"员工"
  • • TOOLS.md的核心是"示例对话"
  • • Notion集成适合知识管理场景
  • • 调试时先手动测试脚本
  • • 数据库属性名要和脚本匹配

📅 下一章预告

Day 5:自动化工作流

有了工具能力,下一步就是让OpenClaw自动执行任务:定时任务、事件触发、工作流编排。让AI真正成为24小时在线的数字员工。

遇到问题?

加入云途AGI社群,获取配套学习资源、群内答疑,与同学们一起交流进步

了解社群详情