使用OpenClaw实现Notion与飞书任务双向同步

1. 项目背景与核心价值

最近在折腾一个特别实用的自动化场景：把Notion里的待办事项自动同步到飞书。作为一个重度Notion用户，我每天的任务管理都靠它，但团队协作又在飞书上，手动两边同步实在太痛苦。正好手头在玩OpenClaw这个AI Agent开发框架，就决定用它来打造一个定制化Skill解决这个问题。

OpenClaw是个挺有意思的框架，它把AI能力封装成可组合的Skill单元。相比直接调用API写脚本，用OpenClaw开发有几个明显优势：首先是内置了对话式交互，可以自然语言触发同步；其次是错误处理机制完善，网络波动时能自动重试；最重要的是技能可复用，开发好后团队其他成员也能直接调用。

这个项目最核心的价值在于：

1. 真正实现了双向同步 - 在Notion勾选完成的任务会自动更新飞书状态
2. 智能字段映射 - 自动匹配两个平台的任务属性（截止日期、负责人等）
3. 增量同步机制 - 只同步变更内容，避免频繁调用API被限流

提示：开发前需要准备好Notion和飞书的开发者权限，建议先在测试环境验证接口调用

2. 环境准备与SDK集成

2.1 开发环境配置

我用的开发环境是：

• Python 3.10（必须≥3.8）
• OpenClaw 0.4.2最新稳定版
• 开发工具VS Code + Jupyter插件

安装核心依赖：

bash复制pip install openclaw-sdk notion-client flywheel-sdk

验证OpenClaw安装：

bash复制openclaw gateway run

如果报错[openclaw] could not start the cli，通常是端口冲突导致，换个端口即可：

bash复制openclaw gateway run --port 5001

2.2 双平台API接入

Notion侧配置：

1. 在Notion集成页面创建新integration
2. 记下API密钥（形如secret_xxxxxx）
3. 把integration添加到目标数据库的"Share"选项里

飞书侧配置：

1. 进入飞书开放平台创建自建应用
2. 开通"消息与群组"和"多维表格"权限
3. 记下App ID和App Secret

测试API连通性：

python复制from notion_client import Client
notion = Client(auth="your_notion_secret")

# 获取数据库示例
database = notion.databases.retrieve(database_id="your_db_id")
print(database.title)

3. 核心同步逻辑实现

3.1 数据库字段映射设计

Notion和飞书多维表格的字段类型需要建立对应关系：

特别要注意的是人员映射，需要提前建立邮箱对照表：

python复制USER_MAPPING = {
    "notion_user_id1": "feishu_user_id1",
    # ...
}

3.2 增量同步机制

核心同步流程分三步：

1. 获取Notion最新变更（通过last_edited_time过滤）
2. 对比飞书现有记录（通过自定义ID字段关联）
3. 只推送差异内容

关键代码片段：

python复制def get_updates(last_sync_time):
    # 查询Notion变更
    results = notion.databases.query(
        database_id=DB_ID,
        filter={
            "timestamp": "last_edited_time",
            "last_edited_time": {"after": last_sync_time}
        }
    )
    return results["results"]

def apply_updates(updates):
    for item in updates:
        # 转换字段格式
        converted = convert_fields(item) 
        # 查找飞书对应记录
        feishu_id = find_feishu_record(item.id)
        if feishu_id:
            update_feishu_record(feishu_id, converted)
        else:
            create_feishu_record(converted)

3.3 状态回写设计

当飞书任务状态变更时，也需要同步回Notion。这里用飞书的"事件订阅"功能实现：

1. 配置飞书事件订阅，监听多维表格变更
2. 收到变更事件后解析变更内容
3. 通过Notion的update接口回写状态

事件处理示例：

python复制@app.route("/webhook", methods=["POST"])
def handle_webhook():
    event = request.json
    if event["table_id"] == TARGET_TABLE:
        record = event["event"]["record"]
        notion_id = record["fields"].get("NotionID")
        if notion_id and record["fields"]["Status"] == "Done":
            notion.pages.update(
                page_id=notion_id,
                properties={"Status": {"checkbox": True}}
            )

4. OpenClaw Skill封装

4.1 Skill元数据定义

在skill.yaml中声明技能能力：

yaml复制name: notion_feishu_sync
description: 双向同步Notion待办和飞书任务
triggers:
  - type: scheduled
    interval: 30m
  - type: manual
    command: "/sync-tasks"
parameters:
  - name: database_id
    type: string
    required: true

4.2 异常处理策略

针对常见API错误设计重试机制：

python复制def safe_api_call(func, max_retries=3):
    for i in range(max_retries):
        try:
            return func()
        except APIError as e:
            if e.code == 429:  # 限流
                time.sleep(2 ** i)  # 指数退避
            else:
                raise
    raise Exception("Max retries exceeded")

4.3 性能优化技巧

1. 批量操作：飞书API支持批量写入，每次同步合并多个操作
2. 本地缓存：用SQLite缓存最近的同步状态，避免重复查询
3. 字段预加载：初始化时预加载所有用户映射关系

实测优化前后对比：

5. 部署与监控

5.1 生产环境部署

推荐用Docker容器化部署：

dockerfile复制FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["openclaw", "gateway", "run", "--port=5001"]

启动命令：

bash复制docker build -t sync-bot .
docker run -d -p 5001:5001 sync-bot

5.2 监控告警配置

在OpenClaw仪表板添加监控：

1. 配置Prometheus采集指标
2. 设置关键指标告警：
   • API错误率 > 5%
   • 同步延迟 > 10分钟
3. 飞书机器人通知

关键监控指标示例：

python复制# 记录指标
statsd.gauge('sync.latency', processing_time)
statsd.increment('sync.records', count)

6. 踩坑实录与解决方案

6.1 Notion API分页陷阱

初期实现时没处理分页，导致只能获取前100条记录。正确做法：

python复制results = []
start_cursor = None
while True:
    batch = notion.databases.query(
        database_id=DB_ID,
        start_cursor=start_cursor
    )
    results.extend(batch["results"])
    if not batch.get("has_more"):
        break
    start_cursor = batch["next_cursor"]

6.2 飞书字段类型限制

飞书多维表格的"成员"字段必须用开放平台用户ID，不能直接填姓名。需要通过接口转换：

python复制def get_user_id(email):
    resp = feishu.contact.users.search(query=email)
    if resp["data"]["users"]:
        return resp["data"]["users"][0]["user_id"]
    return None

6.3 时区同步问题

两个平台默认时区不同，需要在转换时显式指定：

python复制def convert_date(notion_date):
    if not notion_date:
        return None
    dt = parser.parse(notion_date["start"])
    return dt.astimezone(pytz.timezone("Asia/Shanghai")).isoformat()

7. 完整代码结构

最终项目目录结构：

code复制notion-feishu-sync/
├── skill.yaml            # Skill元数据
├── main.py               # 主逻辑
├── adapters/
│   ├── notion_adapter.py # Notion接口封装
│   └── feishu_adapter.py # 飞书接口封装
├── models/
│   └── task.py           # 数据模型
└── utils/
    ├── sync_manager.py   # 同步核心逻辑
    └── error_handlers.py # 异常处理

核心类关系：

python复制class NotionAdapter:
    def get_tasks(self, since): ...
    def update_task(self, task_id, changes): ...

class FeishuAdapter:
    def get_records(self): ...
    def batch_update(self, updates): ...

class SyncManager:
    def __init__(self, notion, feishu): ...
    def incremental_sync(self): ...
    def handle_webhook(self, event): ...

关键实现技巧：

1. 使用策略模式封装不同平台的适配器
2. 采用中间模型(Task)解耦两端数据结构
3. 用事务日志保证同步操作的幂等性

8. 扩展优化方向

1. 智能冲突解决：当两端同时修改时，基于修改时间/优先级自动合并
2. 附件同步：把Notion中的文件同步到飞书云文档
3. 自然语言查询：通过聊天窗口询问"今天有哪些截止任务"
4. 移动端快捷操作：飞书小程序快速创建同步任务

性能优化实验数据：

这个项目最让我惊喜的是OpenClaw的错误恢复机制——有次网络中断后，重启服务时自动从断点继续同步，完全不用人工干预。建议大家在开发Skill时重点利用这个特性，在代码中加入足够的上下文标记，让框架能更好地帮你管理状态。