1. 项目概述当飞书机器人学会“动手”最近在折腾一个挺有意思的自动化项目核心是把飞书机器人和浏览器自动化这两件事给彻底打通。想象一下你只需要在飞书群里一下机器人说一句“帮我查一下今天下午3点的会议室预定情况”它就能自动打开内部系统登录、查询、截图然后把结果直接发回群里。这听起来像是未来办公的场景但其实用现有的开源工具链比如OpenClaw再配合一些脚本完全可以在自己的开发环境里跑起来。这个项目的核心价值在于它让机器人的能力从“被动应答”升级到了“主动操作”。传统的聊天机器人大多依赖于预设的问答库或者大语言模型的文本生成能力它们能“说”但不能“做”。而通过集成浏览器自动化机器人就获得了一双能在数字世界里“动手”的手——可以点击按钮、填写表单、抓取数据、执行一系列标准的Web操作流程。这对于处理那些需要登录、有固定操作步骤的内部系统任务如数据查询、报表生成、状态监控、信息录入来说效率提升是颠覆性的。我这次实战的目标就是构建一个从飞书消息触发到OpenClaw调度执行最终通过无头浏览器完成具体网页操作并返回结果的全链路。过程中会涉及 Linux 环境下的服务部署、网络通信、鉴权处理以及一些不可避免的“坑”。无论你是对机器人开发感兴趣还是想深入了解浏览器自动化如何与即时通讯工具结合这篇从零到一的记录应该都能给你提供一份可复现的参考。2. 核心工具链选型与架构设计2.1 为什么是 OpenClaw Puppeteer/Playwright在开始动手之前工具选型是决定项目成败和后期维护成本的关键。我最终敲定的核心组合是OpenClaw作为机器人的“大脑”和调度中心搭配Puppeteer或Playwright作为“双手”来操作浏览器。OpenClaw是一个开源的、可扩展的机器人框架。它吸引我的地方在于其清晰的模块化设计和对多种消息平台如飞书、钉钉、企业微信的良好支持。它不像一些“黑盒”SaaS服务你可以完全掌控代码根据业务逻辑深度定制。更重要的是它能很方便地集成各种技能Skill这正是我们接入浏览器自动化能力的入口。至于浏览器自动化工具Puppeteer和Playwright是当前的主流选择。两者都提供了一套高阶API来控制Chromium浏览器。Puppeteer由Google Chrome团队维护与Chromium绑定紧密生态成熟稳定。Playwright由微软推出支持Chromium、Firefox和WebKit三大内核API设计更现代内置了更多如自动等待、网络拦截等便利功能。在这个项目中我选择了Playwright。主要原因有两个一是其更智能的等待机制page.wait_for_load_state(networkidle)等能显著减少因页面加载时间不确定导致的脚本失败二是它对多浏览器引擎的支持虽然本项目用不上但其背后体现的工程严谨性让我更放心。当然如果你对Chrome DevTools协议更熟悉用Puppeteer也完全可行核心思路是一致的。注意在Linux无图形界面的服务器上运行浏览器自动化必须使用无头模式headless: true。同时建议安装完整的浏览器包如playwright install chromium而不是依赖系统可能不存在的Chrome这能保证环境一致性。2.2 整体数据流与架构拆解整个系统的运行流程可以概括为“事件驱动”的链条。理解这个数据流对于后续的调试和问题排查至关重要。事件触发用户在飞书群聊中机器人并发送一条指令例如“查询订单 123456”。消息接收飞书服务器将这条消息事件推送到我们部署的OpenClaw服务提供的公网回调地址上。意图解析OpenClaw 接收到事件后首先进行鉴权验证验证请求确实来自飞书然后解析消息内容。这里可以集成一个简单的规则引擎或调用大语言模型API来理解用户意图。例如识别出“查询订单”是动作“123456”是参数。技能路由根据解析出的意图OpenClaw 将任务路由到对应的“技能”Skill处理器。我们将创建一个专门的“浏览器自动化技能”。自动化执行该技能处理器启动一个 Playwright 控制的浏览器实例或无头浏览器导航到目标内部系统执行登录可能需要处理验证码、跳转到订单查询页面、输入订单号、点击查询等一系列操作。结果捕获操作完成后技能处理器捕获结果。结果可能是页面上的某段文本、一张截图、一个表格的HTML或是一个状态码。消息回复技能处理器将捕获的结果格式化如生成一段文本描述或附上截图回传给 OpenClaw。OpenClaw 再调用飞书的机器人消息发送接口将最终结果发送回原来的群聊。资源清理浏览器实例被关闭释放系统资源。这个架构的关键在于解耦飞书交互逻辑、业务意图解析、具体的浏览器操作被分离在不同的模块中。这样当需要支持新的指令如“生成周报”或更换消息平台如切换到钉钉时只需要修改或增加对应的模块而不必重写整个系统。3. 环境准备与核心服务部署3.1 Linux 服务器基础环境搭建我选择在 Ubuntu 22.04 LTS 的云服务器上进行部署。一个干净、稳定的Linux环境是后续所有工作的基础。首先进行系统更新和安装基础依赖sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git vim net-tools接下来是安装 Node.js。OpenClaw 基于 Node.js我们需要一个长期支持版本。这里使用 NodeSource 提供的仓库安装 Node.js 18curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs安装后验证版本node -v和npm -v。对于浏览器自动化Playwright 需要一些系统库才能运行。运行以下命令安装这些依赖可以避免后续启动浏览器时出现“缺少共享库”的错误sudo apt install -y libgbm-dev libnss3 libatk-bridge2.0-0 libdrm-dev libxkbcommon-dev libxcomposite-dev libxdamage-dev libxrandr-dev libgtk-3-0 libasound23.2 Docker 容器化部署 OpenClaw可选但推荐虽然 OpenClaw 可以直接通过 npm 安装运行但在服务器上我更倾向于使用Docker进行容器化部署。这能保证环境隔离、依赖一致并且部署和更新非常方便。首先确保服务器上安装了 Docker 和 Docker Compose# 安装Docker curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # 将当前用户加入docker组避免每次用sudo # 需要重新登录生效 # 安装Docker Compose sudo curl -L https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose sudo chmod x /usr/local/bin/docker-compose接下来创建一个项目目录并编写docker-compose.yml文件mkdir openclaw-feishu-bot cd openclaw-feishu-bot vim docker-compose.ymldocker-compose.yml内容示例version: 3.8 services: openclaw: image: openwebui/openclaw:latest # 请替换为实际的OpenClaw镜像此处为示例 container_name: openclaw-core restart: unless-stopped ports: - 3000:3000 # 将容器内3000端口映射到宿主机 environment: - NODE_ENVproduction - FEISHU_APP_IDyour_app_id - FEISHU_APP_SECRETyour_app_secret - API_KEYyour_secure_api_key # 用于技能调用的密钥 volumes: - ./data:/app/data # 挂载数据卷持久化配置和会话 - ./skills:/app/skills # 挂载自定义技能目录 networks: - bot-network # 可以添加一个Nginx容器做反向代理和SSL对于生产环境是必须的 nginx: image: nginx:alpine container_name: openclaw-nginx restart: unless-stopped ports: - 80:80 - 443:443 volumes: - ./nginx.conf:/etc/nginx/nginx.conf:ro - ./ssl:/etc/nginx/ssl:ro # 存放SSL证书 depends_on: - openclaw networks: - bot-network networks: bot-network: driver: bridge实操心得在volumes映射时务必确保宿主机目录如./skills存在且权限正确chmod 755。否则容器可能因无法写入而启动失败。生产环境强烈建议通过Nginx配置HTTPS因为飞书回调地址要求必须是HTTPS。3.3 飞书机器人创建与配置这是连接飞书的关键一步。我们需要在飞书开放平台创建一个机器人应用并获取必要的凭证。创建企业自建应用登录 飞书开放平台 进入“开发者后台”。点击“创建企业自建应用”填写应用名称和描述。获取凭证在应用的“凭证与基础信息”页面找到App ID和App Secret。这两个值至关重要需要填入我们 OpenClaw 的环境变量或配置文件中。配置权限在“权限管理”页面为机器人添加必要的权限。至少需要im:message接收与发送单聊、群聊消息im:message.group_at_msg接收群聊中机器人的消息根据你的业务可能还需要contact:user.id:readonly获取用户ID等。配置事件订阅这是核心。在“事件订阅”页面你需要设置一个请求地址 URL。这个URL就是你部署的 OpenClaw 服务提供的、能被公网访问的回调接口例如https://your-domain.com/feishu/event。飞书会将所有机器人相关的事件如被、加入群聊以HTTP POST请求的形式推送到这个地址。验证请求保存URL时飞书会发送一个带challenge参数的GET请求进行校验。你的服务必须能正确解析并原样返回这个challenge值。OpenClaw 框架通常已经内置了这个验证逻辑。启用机器人在“版本管理与发布”中创建一个版本并申请发布。审核通过或在企业内直接生效后机器人才能被添加到群聊中使用。将获取到的App ID和App Secret更新到之前的docker-compose.yml环境变量中然后启动服务docker-compose up -d。4. 开发浏览器自动化技能SkillOpenClaw 的功能通过“技能”来扩展。我们需要编写一个自定义技能作为接收指令、驱动浏览器、返回结果的枢纽。4.1 技能项目结构与初始化在宿主机挂载的./skills目录下创建我们的技能项目mkdir -p ./skills/browser-automation cd ./skills/browser-automation npm init -y npm install playwright axios # 安装Playwright和用于HTTP请求的axios npx playwright install chromium # 安装Chromium浏览器创建核心文件index.js这是技能的入口点const { Skill } require(openclaw-sdk); // 假设SDK名称根据实际框架调整 const { chromium } require(playwright); const axios require(axios); class BrowserAutomationSkill extends Skill { constructor() { super(); this.name browserAutomation; this.description 执行浏览器自动化任务如查询数据、填写表单等; // 定义技能能处理的指令模式 this.patterns [ /^查询订单\s(\w)$/i, // 匹配“查询订单 123456” /^查看会议室\s(\d{4}-\d{2}-\d{2})\s(\d{2}:\d{2})$/i, // 匹配“查看会议室 2023-10-27 15:00” /^截图\s(.)$/i // 匹配“截图 https://example.com” ]; } /** * 技能执行入口 * param {Object} context - 执行上下文包含消息、用户、机器人等信息 * param {Array} matches - 正则表达式匹配的结果 * returns {PromiseObject} - 返回给用户的结果 */ async execute(context, matches) { const command context.message.text.trim(); const userId context.user.id; console.log([BrowserSkill] 用户 ${userId} 触发指令: ${command}); try { let result; // 根据匹配到的模式路由到不同的处理函数 if (matches[0][0].includes(查询订单)) { const orderId matches[0][1]; result await this.handleOrderQuery(orderId); } else if (matches[0][0].includes(查看会议室)) { const date matches[0][1]; const time matches[0][2]; result await this.handleMeetingRoomQuery(date, time); } else if (matches[0][0].includes(截图)) { const url matches[0][1]; result await this.handleCaptureScreenshot(url); } else { result { type: text, content: 抱歉我暂时无法理解这个指令。 }; } return result; } catch (error) { console.error([BrowserSkill] 执行失败:, error); return { type: text, content: 任务执行失败: ${error.message}。请检查指令或稍后重试。 }; } } // 具体的处理函数将在下一小节实现 async handleOrderQuery(orderId) { ... } async handleMeetingRoomQuery(date, time) { ... } async handleCaptureScreenshot(url) { ... } } module.exports BrowserAutomationSkill;4.2 实现订单查询的自动化流程以handleOrderQuery为例我们详细拆解如何用 Playwright 操作一个假设的内部订单管理系统。async handleOrderQuery(orderId) { console.log([BrowserSkill] 开始查询订单: ${orderId}); const browser await chromium.launch({ headless: true, // 服务器上必须为true args: [--no-sandbox, --disable-setuid-sandbox] // Linux容器中运行的必要参数 }); const context await browser.newContext({ viewport: { width: 1920, height: 1080 }, userAgent: Mozilla/5.0 (X11; Linux x86_64) ... // 可设置UA避免被识别为机器人 }); const page await context.newPage(); try { // 1. 导航到登录页 await page.goto(https://internal-order-system.example.com/login, { waitUntil: networkidle }); // 2. 处理登录假设是用户名密码表单 await page.fill(#username, process.env.INTERNAL_USERNAME); await page.fill(#password, process.env.INTERNAL_PASSWORD); await page.click(#submit-btn); // 等待登录后跳转完成 await page.waitForURL(**/dashboard, { timeout: 10000 }); // 3. 导航到订单查询页 await page.click(nav a[href/orders]); await page.waitForSelector(#order-search-input, { state: visible }); // 4. 输入订单号并查询 await page.fill(#order-search-input, orderId); await page.click(#search-button); // 等待查询结果加载这里假设结果出现在一个表格里 await page.waitForSelector(.order-detail-table tbody tr, { timeout: 8000 }); // 5. 提取结果数据 const orderData await page.evaluate(() { const row document.querySelector(.order-detail-table tbody tr); if (!row) return null; const cells row.querySelectorAll(td); return { id: cells[0].innerText, status: cells[1].innerText, amount: cells[2].innerText, customer: cells[3].innerText }; }); if (!orderData) { throw new Error(未找到订单号: ${orderId}); } // 6. 可选对关键信息进行截图 const screenshotBuffer await page.screenshot({ fullPage: false, clip: { x: 0, y: 0, width: 800, height: 400 } }); // 7. 格式化返回结果 return { type: post, // 可以是 text, post, image 等取决于飞书消息类型 content: { title: 订单查询结果 - ${orderId}, content: [ [ { tag: text, text: **订单号**: ${orderData.id} }, { tag: text, text: \n**状态**: ${orderData.status} }, { tag: text, text: \n**金额**: ${orderData.amount} }, { tag: text, text: \n**客户**: ${orderData.customer} } ] ] }, // 如果需要发送图片可以上传图片到飞书并附上image_key // image_key: await this.uploadImageToFeishu(screenshotBuffer) }; } catch (error) { // 发生错误时可以截取当前页面帮助调试 const errorScreenshot await page.screenshot({ fullPage: true }); // 将errorScreenshot保存到日志或临时文件 console.error([BrowserSkill] 订单查询过程出错: ${error.message}); throw error; // 重新抛出由execute统一处理 } finally { // 8. 无论如何确保关闭浏览器释放资源 await browser.close(); } }避坑指南浏览器自动化脚本最常遇到的问题就是“元素未找到”或“超时”。这通常是因为页面加载速度或JavaScript渲染导致的。Playwright 提供了强大的等待选择器page.waitForSelector(selector, { state: visible })等待元素出现在DOM中且可见。page.waitForLoadState(networkidle)等待页面网络活动基本停止。page.waitForFunction()等待自定义的JavaScript条件成立。 在编写脚本时不要使用固定的page.waitForTimeout(5000)而应尽量使用上述基于条件的等待这样脚本更健壮、更快速。4.3 技能注册与 OpenClaw 集成技能开发完成后需要让 OpenClaw 主服务知道它的存在。这通常通过在 OpenClaw 的配置目录中注册来实现。在 OpenClaw 的配置文件例如config/skills.json或通过环境变量指定中添加我们的技能{ skills: [ { name: browserAutomation, path: /app/skills/browser-automation/index.js, config: { internalSystemUrl: https://internal.example.com, credentials: { username: ${ENV_INTERNAL_USER}, password: ${ENV_INTERNAL_PASS} } } } ] }然后重启 OpenClaw 服务以加载新技能docker-compose restart openclaw。5. 全链路联调与问题排查实录将各个部分部署和开发完成后真正的挑战在于让整个链条顺畅地跑起来。这个阶段会遇到各种网络、鉴权、时序和逻辑问题。5.1 飞书事件订阅验证失败这是第一个拦路虎。在飞书开放平台保存事件订阅URL时提示“验证失败”。排查思路检查网络可达性首先确保你的服务器IP和端口通常是443在公网可访问。可以使用curl https://your-domain.com或在线端口检测工具。检查HTTPS飞书要求回调地址必须是HTTPS。如果你在测试环境使用HTTP飞书验证必然失败。生产环境必须配置SSL证书可以使用Let‘s Encrypt免费证书。检查验证逻辑OpenClaw 服务必须正确处理飞书发来的验证请求GET请求带challenge参数。查看 OpenClaw 的日志看是否收到了请求以及响应是否正确。正确的响应应该是直接返回一个JSON{ “challenge”: “收到的challenge值” }。检查路径确保飞书填写的URL路径与 OpenClaw 服务中定义的路由路径完全一致包括大小写。解决方案我遇到的问题是Nginx配置中将飞书的验证请求代理到了错误的上游路径。修正Nginx配置确保/feishu/event路径的请求被正确转发到 OpenClaw 容器的对应端口。5.2 浏览器自动化脚本执行超时或无响应在技能被触发后飞书消息发出去了但机器人迟迟没有回复。排查思路查看技能日志首先在技能代码中加入详细的console.log并在服务器上通过docker logs -f openclaw-core查看实时输出。确认技能是否被正确触发执行到了哪一步。检查浏览器启动在Linux无头环境中Playwright/Chromium 启动可能需要特定参数或依赖。确保启动配置中包含args: [--no-sandbox, --disable-setuid-sandbox]这是容器化环境下的常见要求。模拟执行写一个简单的测试脚本直接在服务器上运行看Playwright能否成功启动浏览器并打开一个网页如https://example.com。这能隔离出是环境问题还是业务脚本逻辑问题。页面加载问题内部系统可能加载缓慢或者有复杂的前端框架。增加waitUntil选项的超时时间或者将networkidle改为domcontentloaded试试。资源限制检查服务器内存和CPU使用情况。启动一个无头浏览器实例会消耗不少内存几百MB如果服务器资源不足可能导致进程卡死或崩溃。解决方案我遇到的问题是内部登录系统有一个动态加载的验证码原脚本的等待策略失效。通过使用page.waitForSelector(‘#captcha-img’, { state: ‘visible’ })显式等待验证码图片加载完成并在填充后增加一个手动延迟page.waitForTimeout(2000)让前端逻辑处理解决了问题。5.3 消息成功处理但飞书收不到回复技能执行成功日志显示也调用了飞书发送消息的API但群聊里就是看不到机器人的回复。排查思路检查权限确认飞书应用的“发送消息”权限是否已开通并发布生效。检查API调用查看 OpenClaw 调用飞书发送消息API的日志。重点看HTTP状态码和响应体。常见的错误有code: 99991663租户已过期或被停用。code: 99991668应用未被启用或不在可用范围内。code: 99991664无群聊发送消息权限。检查消息体格式飞书消息API对消息体的格式要求非常严格。确保你构建的消息内容content符合飞书的消息类型规范文本、富文本、卡片等。一个字段名拼写错误或结构不对都会导致发送失败。检查群聊确认机器人是否已成功添加到目标群聊中。解决方案我遇到的是消息格式错误。我试图发送一个混合了文本和图片的复杂消息但构建的JSON结构不符合飞书“交互卡片”的格式。后来简化为先只发送纯文本消息确认通道畅通后再逐步调试复杂的卡片消息格式。使用飞书提供的 消息体验工具 来构建和预览消息体非常有帮助。5.4 性能优化与稳定性提升当脚本能基本运行后就需要考虑如何让它更稳定、更高效。浏览器实例复用频繁启动和关闭浏览器开销很大。可以考虑使用browser.newContext()创建多个独立的浏览器上下文Context它们共享同一个浏览器进程但拥有独立的会话、cookies和缓存。对于需要不同登录态的任务这比反复启动浏览器要快得多。设置合理的超时与重试对网络请求、元素查找等操作设置全局或局部的超时时间。对于非关键性失败如短暂的网络波动可以在技能逻辑中加入重试机制。资源泄漏防范确保在try...catch...finally块中无论成功与否都执行browser.close()或context.close()。也可以考虑设置一个全局的浏览器实例管理器并定期清理闲置过久的实例。异步任务队列如果机器人可能同时处理多个请求直接为每个请求启动浏览器可能会导致资源竞争和系统负载过高。可以引入一个任务队列如 Bull 基于 Redis让技能处理器作为消费者顺序地处理浏览器自动化任务。监控与告警为技能添加更详细的日志记录每个任务的开始时间、结束时间、状态和关键数据。可以集成 Sentry 等工具捕获未处理的异常并配置飞书机器人给自己发送错误告警。经过以上步骤的搭建、开发和调试一个能够通过飞书指令驱动浏览器完成复杂操作的自动化机器人就初具雏形了。从在群里发出指令到看到机器人返回的查询结果或截图这个闭环带来的成就感远超简单的脚本。这个框架的扩展性很强你可以继续为它添加更多的技能比如定时巡检网页、自动填报数据、监控价格变化等等让机器人为你处理更多重复性的网页操作任务。