OpenClaw 部署与飞书对话集成

实验时间： 2026-03-02
状态： 🟡 进行中
类型： AI 助手集成

---

📋 项目概述

本项目记录了在个人 Mac mini 上部署 OpenClaw AI 助手系统，并集成飞书机器人实现对话功能的完整实践过程。

核心目标

• ✅ 在 macOS 环境部署 OpenClaw 网关
• ✅ 配置飞书机器人实现双向对话
• ✅ 建立多 Agent 协作系统
• ✅ 实现开发任务自动化管理

---

🏗️ 架构设计

┌─────────────────────────────────────────────────────────────┐
│                    用户设备 (飞书 App)                        │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ WebSocket 长连接
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              OpenClaw Gateway (Mac mini)                     │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Feishu Channel Plugin                              │    │
│  │  - App ID: cli_a92fa020ccb81cc8                     │    │
│  │  - WebSocket 长连接接收消息                          │    │
│  └─────────────────────────────────────────────────────┘    │
│                            │                                  │
│                            ▼                                  │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Agent System                                        │    │
│  │  - main (主对话)                                     │    │
│  │  - ingredient-ios (iOS 开发)                         │    │
│  │  - ingredient-backend (后端开发)                     │    │
│  │  - ingredient-test (测试 QA)                         │    │
│  │  - realtech-* (RealTech Hub 内容)                    │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    本地工作空间                              │
│  - /Users/ywj/.openclaw/workspace/                          │
│  - Git 仓库管理                                              │
│  - CSV 任务追踪                                              │
└─────────────────────────────────────────────────────────────┘

---

🚀 部署步骤

1. 环境准备

系统要求：

• macOS 14+ (Apple Silicon)
• Node.js 22.17.0+
• pnpm (包管理器)

安装 OpenClaw：

npm install -g openclaw

2. 飞书应用配置

2.1 创建企业自建应用

1. 访问 飞书开放平台
2. 创建企业自建应用
3. 获取凭证：
   • App ID: cli_a92fa020ccb81cc8
   • App Secret: (妥善保管)

2.2 配置权限

批量导入以下权限：

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:chat",
      "im:resource",
      "sheets:spreadsheet",
      "docs:doc"
    ]
  }
}

2.3 启用机器人能力

• 开启机器人能力
• 配置事件订阅：im.message.receive_v1
• 选择 长连接模式 (WebSocket)

3. OpenClaw 配置

3.1 启用飞书插件

{
  "plugins": {
    "entries": {
      "feishu": { "enabled": true }
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_a92fa020ccb81cc8",
          "appSecret": "***"
        }
      }
    }
  }
}

3.2 配置多 Agent 系统

{
  "agents": {
    "list": [
      { "id": "main" },
      { 
        "id": "ingredient-ios",
        "workspace": "/Users/ywj/.openclaw/workspace/ingredient-checker-ios"
      },
      { 
        "id": "ingredient-backend",
        "workspace": "/Users/ywj/.openclaw/workspace/ingredient-checker-backend"
      },
      { 
        "id": "ingredient-test",
        "workspace": "/Users/ywj/.openclaw/workspace/ingredient-checker"
      }
    ],
    "defaults": {
      "model": { "primary": "bailian/qwen3.5-plus" },
      "maxConcurrent": 4
    }
  }
}

4. 启动网关

openclaw gateway

检查状态：

openclaw status

---

🔧 关键技术点

1. WebSocket 长连接

飞书使用 WebSocket 长连接接收消息，无需公网 URL：

优势：

• ✅ 无需反向代理
• ✅ 内网部署即可
• ✅ 连接稳定，实时性高

配置要点：

• 确保网关处于运行状态
• 事件订阅选择"长连接模式"
• 添加事件：im.message.receive_v1

2. 多 Agent 协作

通过 agents.list 配置多个专用 Agent：

{
  "agents": {
    "list": [
      { "id": "ingredient-ios", "model": "qwen3-coder-plus" },
      { "id": "ingredient-backend", "model": "qwen3-coder-plus" },
      { "id": "ingredient-test", "model": "qwen3.5-plus" }
    ]
  }
}

每个 Agent 有独立的：

• 工作空间 (workspace)
• 模型配置
• Skills 配置

3. 任务追踪系统

使用 CSV 文件管理开发任务：

文件结构：

ingredient-checker/
├── task-tracker-ios.csv        # iOS 任务
├── task-tracker-backend.csv    # Backend 任务
└── task-tracker-milestones.csv # 里程碑

自动化更新：

• 每日站会 Cron (工作日 9:00)
• Heartbeat 定期检查
• 状态变更自动记录

4. 代码审查流程

用户请求 → Main Agent → ingredient-ios Agent
                              │
                              ▼
                    读取源代码
                              │
                              ▼
                    分析架构/规范/安全
                              │
                              ▼
                    生成 code_review.md
                              │
                              ▼
                    更新 task-tracker.csv

---

📊 实践成果

已完成功能

功能	状态	说明
飞书对话集成	✅	私聊/群聊支持
多 Agent 系统	✅	9 个专用 Agent
代码审查	✅	iOS 项目完成审查
任务追踪	✅	CSV + 飞书文档
自动化站会	✅	工作日 9:00 执行

代码审查发现

iOS 项目审查结果：

• ⭐⭐⭐⭐ (4/5) 良好代码质量
• P0 问题：2 个 (Token 存储、超时配置)
• P1 问题：3 个 (请求取消、本地化、日志)
• P2 问题：3 个 (重构、防抖)

---

⚠️ 遇到的问题与解决方案

问题 1：飞书权限不足

现象： 机器人无法创建文档

原因： 缺少 docs:doc 权限

解决：

1. 飞书开放平台 → 权限管理
2. 批量导入 docs:doc 权限
3. 重新发布应用

问题 2：Agent 配置未生效

现象： sessions_spawn 提示 agentId 不允许

原因： allowlist.json 未更新

解决：

{
  "agents": [
    "main",
    "ingredient-ios",
    "ingredient-backend",
    "ingredient-test"
  ]
}

问题 3：飞书 API 调用失败

现象： feishu_doc.create 返回 400 错误

原因： API 格式限制

解决： 改用 CSV 文件管理任务，避免复杂 API 调用

---

📈 经验总结

✅ 成功经验

1. CSV 优于 API - 简单的 CSV 文件比飞书 API 更可靠
2. 多 Agent 隔离 - 每个项目独立 Agent，避免上下文污染
3. Cron + Heartbeat - 定期检查确保任务不遗漏
4. 代码审查先行 - 开发前先审查现有代码质量

⚠️ 待改进

1. Token 安全存储 - 需要使用 Keychain
2. 错误本地化 - 支持多语言错误提示
3. 日志系统 - 生产环境需要更好的可观测性
4. 测试覆盖率 - 缺少自动化测试

---

🔗 相关资源

• OpenClaw 官方文档
• 飞书开放平台
• RealTech Hub 项目
• Ingredient Checker 项目

---

📝 更新日志

• 2026-03-02 - 初始版本，记录部署过程和实践经验

---

本文档由 AI 自动生成并维护