前三天,我们搭建了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"能做什么"。
工作原理(完整流程)
用户发送指令
"帮我查一下上周写了哪些选题"
→ OpenClaw接收到消息
AI读取TOOLS.md
发现有"query_notion_database"工具,功能是"查询Notion数据库"
→ AI判断:这个工具可以完成任务
AI生成调用指令
构造命令:query_notion_database --db "选题库" --filter "上周"
→ 根据TOOLS.md的参数说明生成
OpenClaw执行脚本
运行 tools/notion.py,调用Notion API,获取数据
→ 返回JSON格式的结果
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. 手动运行脚本,看是否报错
- 2. 检查环境变量是否配置
- 3. 查看OpenClaw日志(~/.openclaw/logs/)
- 4. 确认API Token是否有效
问题3:返回数据格式错误
原因:Notion数据库属性名称不匹配
解决:检查脚本中的属性名(如"标题"、"标签")是否和你的数据库一致
调试技巧
- 1. 先手动测试
在终端直接运行脚本,确认能正常工作
python3 tools/notion.py --action query --database "选题库" - 2. 查看日志
OpenClaw会记录所有工具调用
tail -f ~/.openclaw/logs/openclaw.log - 3. 添加调试输出
在脚本中加入print语句,查看中间结果
💡 本章要点回顾
- • 工具系统让AI从"顾问"变成"员工"
- • TOOLS.md的核心是"示例对话"
- • Notion集成适合知识管理场景
- • 调试时先手动测试脚本
- • 数据库属性名要和脚本匹配
📅 下一章预告
Day 5:自动化工作流
有了工具能力,下一步就是让OpenClaw自动执行任务:定时任务、事件触发、工作流编排。让AI真正成为24小时在线的数字员工。