如果你跟我一样电脑上常年开着飞书、浏览器、一堆文档窗口和终端每天有大量时间花在“搬运信息”上——把群聊里的需求整理成任务把表格里的数据核对一遍再把文件从一个目录挪到另一个目录——那你大概率也想要一个能听人话、能跑腿的 AI 助手。OpenClaw 就是这样一个开源 AI 代理框架它跑在 Windows 上用自然语言接收指令自己拆解步骤、调用工具去执行关键还能接进飞书机器人等于给团队配了一个 7x24 小时在线的数字员工。这篇教程是我自己在 Windows 电脑上从零配置 OpenClaw 并接入飞书的完整记录包括踩过的坑和排查过程照着走一遍基本能跑通。如果你对这类工具的印象还停留在“就是个聊天机器人”那建议你先花五分钟看完第一部分。OpenClaw 跟普通对话式 AI 最大的区别是它能真正动你的电脑读文件、跑命令、操作浏览器、调用接口。接上飞书之后你可以在群里直接对它说“帮我把这份周报整理成表格发出来”它会自己完成剩下的事。1. OpenClaw 整体思路与在 Windows 上的落地路径1.1 OpenClaw 到底是什么它和普通 AI 有什么区别OpenClaw早期社区里也叫 Clawdbot是一个基于大语言模型 API 的 AI Agent 框架。你可以把它理解成一个“会使用电脑的 AI 员工”你给它一个目标它会自己规划步骤调用内置工具比如执行终端命令、读写文件、控制浏览器、调用 HTTP 接口来完成目标而不是只给你输出一段建议。举个例子你让它“把桌面所有 pdf 文件按文件大小排序生成一个清单发到飞书群”它能自己列出目录、筛选文件、计算大小、生成 CSV再调用飞书 API 把文件发出去。这个过程里你可以完全不管中间步骤只需要看结果。这个定位决定了它跟 ChatGPT 网页版、飞书自带 AI 这类“对话式产品”有本质区别。对话式产品是“你问我答”OpenClaw 是“你说目标我干活”。它更适合办公场景里的重复性、流程性任务而不是知识问答。1.2 为什么选择“Windows WSL2 OpenClaw”这条组合OpenClaw 本身是 Node.js 写的理论上 Windows 原生环境能跑但它的核心工具尤其是文件操作和命令执行很多依赖 Linux 生态的习惯所以官方更推荐在 WSL2Windows Subsystem for Linux 2Windows 自带的一个轻量 Linux 子系统里运行。用 WSL2 的好处有三个第一文件系统和命令行为和 Linux 服务器一致社区里绝大多数教程、脚本能直接复用不会遇到 Windows 路径分隔符这类问题第二性能开销比虚拟机小很多日常使用基本感受不到额外负担第三OpenClaw 在启动时会自动检测 WSL2 环境如果用的是 Docker 或其他方式可能反而会报环境未验证通过的提示。飞书接入的部分有两种典型做法一种是“自定义机器人 Webhook”简单但只能单向推送另一种是“自建应用 事件订阅 长连接”能实现双向聊天。这篇教程我两种都会讲清楚你按自己的需求选。1.3 需要准备的材料清单在正式开始之前先把需要准备的东西列出来避免中途到处找一台 Windows 10/11 电脑建议磁盘剩余空间 20GB 以上内存 8GB 以上。一个 GitHub 账号用于后续拉取模板和更新不是强制但建议有。Node.js 18 或更高版本。WSL2 及一个 Ubuntu 发行版。一个大模型 API 的 KeyAnthropic 或 OpenAI 兼容接口都行本地模型也能跑后面细说。一个飞书管理员账号以及创建自建应用的权限。这些看起来多其实大部分一次就能配好。真正的难点不在环境而在后续让 OpenClaw 理解你的工作流。2. Windows 环境准备WSL2、Node.js、Git 一步到位2.1 WSL2 安装与常见验证报错处理我在实际配置时第一步就遇到了 OpenClaw 最著名的那个报错openclaw could not safely verify the WSL2 environment.。这句提示的意思是OpenClaw 检测到你的 WSL2 环境不可用或者版本太老无法确认能不能安全地读写文件、执行命令。绝大多数情况是下面几个原因之一没装 WSL2、装了但默认版本还是 WSL1、Linux 内核没更新。正确安装顺序是这样的。先用管理员身份打开 PowerShell执行wsl --install这个命令会默认安装 WSL2 和 Ubuntu并且会自动启用需要的 Windows 功能。安装完成后重启电脑。重启完确认一下版本wsl --status如果显示默认版本是 2那就没问题。如果显示的是 WSL1需要手动指定默认版本wsl --set-default-version 2还有一种情况是 Linux 内核太旧OpenClaw 会一直在验证环节卡住。这时候执行wsl --update更新完再wsl --status确认。提示如果你电脑上之前装过 WSL1 的发行版建议先备份重要文件再考虑是否迁移。迁移命令是wsl --set-version 发行版名称 2但迁移过程可能因为分区问题失败不如直接重装一个。2.2 Node.js 和 Git 安装版本选择有讲究OpenClaw 是基于 Node.js 的工具Node 版本太老会导致安装依赖失败版本太新又可能跟某些原生模块不兼容。我实测下来 Node.js 20 LTS 版本最稳装 18 也行但不建议直接上最新版。去 Node.js 官网下载 Windows LTS 安装包一路下一步就行。安装完成后在 PowerShell 里验证node -v npm -vGit 的安装更简单Windows 版直接默认配置下一步。唯一要注意的是在“选择 SSH 可执行文件”那一步选“Use OpenSSH”而不是内置的 Git SSH这样后面 OpenClaw 拉取依赖时不容易出现密钥认证问题。验证 Gitgit --version这两个装好后我建议把 npm 的镜像源改一下再继续因为 OpenClaw 依赖的包很多默认源在国内环境下安装速度很折磨。执行npm config set registry https://registry.npmmirror.com改完用npm config get registry确认一下即可。2.3 创建并初始化 OpenClaw 的工作目录环境准备好后先切到 WSL2 里建一个专门放 OpenClaw 的目录。Windows 和 WSL2 有文件互通的路径比如C:\Users\你的用户名\openclaw-workspace在 WSL2 里对应/mnt/c/Users/你的用户名/openclaw-workspace。但因为跨文件系统访问有性能损耗我建议把工作目录放在 WSL2 自己的文件系统里比如~/openclaw-workspace让 OpenClaw 读写文件更快更稳。cd ~ mkdir openclaw-workspace cd openclaw-workspace接下来全局安装 OpenClawnpm install -g openclaw安装完成后运行openclaw --version能输出版本号就说明装好了。然后我推荐在项目目录下执行初始化openclaw init这个命令会引导你创建配置文件并生成一个openclaw.yaml也可能是config.yaml不同版本命名有差异以生成的注释为准。初始化过程会问你要模型提供商和 Key可以先随便填后面我们手动改配置文件更清晰。3. OpenClaw 核心配置模型选择、工作目录与工具开关3.1 配置 AI 模型Anthropic / OpenAI 兼容接口 / 本地模型怎么选OpenClaw 的模型配置是整个配置过程里最核心的一步因为它直接决定了 Agent 的“智商”和稳定性。配置文件里大概是这样model: provider: anthropic name: claude-sonnet-4-20250514 apiKeyEnv: ANTHROPIC_API_KEYprovider指定模型服务商name指定具体模型名apiKeyEnv是环境变量的名字OpenClaw 会在环境变量里读取 Key而不是直接明文写在配置文件里这样更安全。如果你用的是 Anthropic 的 API就在~/.bashrc或~/.zshrc里加一行export ANTHROPIC_API_KEY你的key然后source ~/.bashrc生效。如果你用的是 OpenAI 兼容接口国内很多模型服务商都提供这种接口配置稍有不同model: provider: openai name: qwen-plus # 或其他模型名 apiKeyEnv: OPENAI_API_KEY baseUrl: https://example.com/v1这里的baseUrl要填你使用的那家服务商提供的 API 地址。配置好后同样需要设置OPENAI_API_KEY环境变量。如果你手头没有云 API也可以用本地模型比如通过 Ollama 跑 qwen2.5。OpenClaw 支持接入 Ollama但本地模型的推理速度和控制能力目前跟顶级云模型比还有差距跑简单任务可以复杂任务容易“犯迷糊”。所以我的建议是能用云 API 优先用云 API本地模型作为调试备选。注意API Key 属于敏感信息任何时候都不要提交到 GitHub 或者发到群聊。配置里尽量用环境变量引用而不是硬编码这是我在生产环境踩过坑之后的教训。3.2 工作目录权限让 OpenClaw 知道它能碰哪些文件默认情况下OpenClaw 为了安全只会允许 Agent 读写它自己的工作目录不会满盘乱翻。这是好事但很多人第一次用会觉得“为什么它找不到我的文件”其实就是权限没配。配置文件里会有一个workspace的区块大概长这样workspace: path: /home/你的用户名/openclaw-workspace allowlist: - /home/你的用户名/openclaw-workspace - /mnt/c/Users/你的用户名/Desktop - /mnt/c/Users/你的用户名/Documentspath是 Agent 的主工作目录allowlist是允许它额外访问的目录。如果你想让 OpenClaw 能处理 Windows 桌面上的文件就把对应路径加进 allowlist。路径一定要写 WSL2 里的路径格式Windows 的C:\Users\...在 WSL2 里是/mnt/c/Users/...这个尽量别搞错。我的习惯是把日常要处理的目录都加进 allowlist比如桌面、下载、某个固定的项目文件夹但不要给整个 C 盘权限。给 Agent 的权限越大风险也越大尤其是当它能执行任意命令的时候。3.3 工具有哪些、什么时候关掉它们OpenClaw 内置了不少工具常见的有bash执行 shell 命令最强大也最容易出事。file读写文件、创建目录。computer模拟键盘鼠标操作做 UI 自动化用。browser控制浏览器访问网页、抓取信息。http发起 HTTP 请求调用 API。配置里可以控制哪些工具启用、哪些禁用。对于纯飞书办公助手场景我建议先关闭computer和browser因为这两个工具涉及图形界面操作在服务器环境或无人值守环境里容易卡死或误操作。等你把基本流程跑通了再按需开启。这个“节制”的思路很多人不重视但实际用起来很重要。Agent 能用的工具越多它选择路径时就越“发散”本来一条命令能解决的问题它可能会绕一大圈。限制工具范围反而能提升任务的成功率和速度。配置好之后可以先在命令行里跑一个简单的测试openclaw run 帮我看看当前目录里有哪些文件如果它能正确列出文件说明模型连接、工具调用、文件权限都正常可以进入下一步接飞书了。4. 飞书接入实操从 Webhook 到双向机器人4.1 先搞一个最简单的飞书自定义机器人飞书群里可以添加“自定义机器人”本质是一个 Webhook 地址。只要你往这个地址 POST 一段 JSON机器人就会把内容发到群里。这是最快能看到效果的接入方式适合做“单向通知”型助手比如定时汇报、任务完成提醒。在飞书群里这样操作群设置 → 群机器人 → 添加机器人 → 自定义机器人创建后你会拿到一个 Webhook 地址。然后任意支持 HTTP 请求的工具都能调用它比如用 curlcurl -X POST -H Content-Type: application/json \ -d {msg_type:text,content:{text:OpenClaw 已启动}} \ 你的webhook地址群里就会收到这条消息。但这种方式有个明显局限机器人只能“说话”不能“听”。群里成员 它它收不到因为 Webhook 是单向的。所以如果你想要的是“在群里直接对话、下达任务、让它执行完后回复”就必须用企业自建应用的方式。4.2 创建飞书企业自建应用App ID 与权限配置先进入飞书开放平台用管理员账号登录创建企业自建应用。创建完成后你会看到两个关键凭证App ID 和 App Secret。这两个值后面接 OpenClaw 和调用飞书 API 都会用到妥善保管。然后在应用的功能列表里添加“机器人”能力。此时你的自建应用就有了一个机器人账号可以把它拉进群里或者让它处理单聊。接下来是权限配置。飞书的权限体系特别细每个 API 都要有对应的权限点才能调用。如果是做消息收发至少要开这几个im:message读取消息im:message:send_as_bot以机器人身份发消息im:message:receive_v1接收消息事件这些权限在“权限管理”页面搜索添加。添加完权限后需要发布应用版本才会生效。很多人容易漏掉这一步在开发阶段配置的权限改了但没重新发布结果线上一直报权限不足。4.3 事件订阅 长连接让 OpenClaw 听到并处理飞书消息要让飞书机器人“听到”群里的消息并按需回复需要订阅消息事件。做法是在飞书开放平台应用后台找到“事件与回调”添加事件选择“接收消息im.message.receive_v1”。事件订阅有两种接收方式一种是“请求地址”回调需要你提供一个公网可以访问的 HTTPS 地址另一种是“长连接”模式飞书会通过 WebSocket 主动把事件推送到你的本地程序不需要公网地址。单机本地跑 OpenClaw 的话用长连接是最省事的。飞书开放平台的 Node SDK 里直接支持长连接模式。下面是我实际用的一段示意代码它做了这几件事建立长连接监听消息事件收到消息后把文本提取出来调用本地 OpenClaw 的命令行执行任务拿到结果后以机器人身份回复到原会话const lark require(larksuiteoapi/node-sdk); const { execSync } require(child_process); const client new lark.Client({ appId: process.env.FEISHU_APP_ID, appSecret: process.env.FEISHU_APP_SECRET, }); const eventDispatcher new lark.EventDispatcher({}) .register({ im.message.receive_v1: async (data) { const message data.message; const content JSON.parse(message.content).text; // 只响应 机器人的消息避免群里其他消息也触发 if (!content) return; try { const result execSync(openclaw run ${content.replace(//g, \\)}, { encoding: utf-8, timeout: 120000, }).trim(); await client.im.message.reply({ path: /open-apis/im/v1/messages/:message_id/reply, params: { message_id: message.message_id }, data: { content: JSON.stringify({ text: result.slice(0, 3900) }) }, }); } catch (e) { await client.im.message.reply({ path: /open-apis/im/v1/messages/:message_id/reply, params: { message_id: message.message_id }, data: { content: JSON.stringify({ text: 处理失败 e.message }) }, }); } }, }); client.wsClient.start({ eventDispatcher });这里要注意几个细节。第一openclaw run这个命令在启动时会初始化上下文耗时可能在几秒到十几秒所以我把执行超时设置到了 120 秒避免任务没跑完就被中断。第二飞书消息回复的单条文本长度有限制所以我把结果截断到了 3900 个字符内超过的部分下次可以做成文件发送。第三如果没有做“只响应 机器人的消息”的判断群里的任何消息都会触发一次 Agent 调用既浪费 API 额度又容易让机器人神经质。这段代码跑起来之后你在飞书机器人对话窗口发一句“查看一下我的桌面有哪些文件”它就会回到 WSL2 里去执行文件列举然后把结果回复给你。5. 实战让飞书 AI 助手真正干活5.1 本机文件查询与汇总接好飞书之后我先用日常场景测试。比如我在飞书里对它说“帮我在 /mnt/c/Users/我的用户名/Downloads 里找出所有 PDF 文件按大小从大到小排序并把文件名和大小列出来。”OpenClaw 收到指令后会调bash工具执行类似这样的命令find /mnt/c/Users/我的用户名/Downloads -name *.pdf -type f -exec ls -lh {} \;然后它自己把输出整理成清晰的列表再通过飞书回复回来。这里有个经验提问越具体任务成功率越高。你说“整理一下下载目录”它可能不知道该按什么规则整理你说“按文件类型分类列出每类文件数量和总大小”它就知道要做什么。把任务描述成“目标 约束条件”是最适合 Agent 的提问方式。5.2 把结果发送为表格文件飞书机器人不仅能发文本还能发文件。比如让 OpenClaw 生成一个 CSV 表格然后通过飞书 API 上传并发送到会话里。OpenClaw 自己就能完成 CSV 的生成再通过脚本或 HTTP 工具调用飞书 API。核心流程是先拿到tenant_access_tokencurl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \ -H Content-Type: application/json \ -d {app_id:你的APP_ID,app_secret:你的APP_SECRET}然后用这个 token 上传文件curl -X POST https://open.feishu.cn/open-apis/im/v1/files \ -H Authorization: Bearer 你的tenant_access_token \ -F file_typexlsx \ -F file./report.csv上传成功后拿到file_key再发送 file 类型消息curl -X POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_typeopen_id \ -H Authorization: Bearer 你的tenant_access_token \ -H Content-Type: application/json \ -d { receive_id: 目标用户的open_id, msg_type: file, content: {\file_key\: \上传返回的file_key\} }有几次我懒得写这么长的命令就让 OpenClaw 自己通过 HTTP 工具去调飞书 API它反而比我手写的更准确因为飞书开放平台的接口文档它见过很多。这里要提醒一点如果要用这种“Agent 自助调用 API”的方式务必在配置里把飞书 App Secret 作为环境变量注入而不是直接告诉 Agent。否则它可能会在回复里原样带出敏感信息。5.3 多维表格写入与自动打卡提醒类任务飞书多维表格是很多团队常用的轻量数据库。让 OpenClaw 写入多维表格的思路跟发消息类似调用多维表格的 API在指定的数据表里新增记录。假设你的多维表格 App Token 是AppToken数据表 ID 是TableId插入一条记录的接口是curl -X POST https://open.feishu.cn/open-apis/bitable/v1/apps/AppToken/tables/TableId/records \ -H Authorization: Bearer 你的tenant_access_token \ -H Content-Type: application/json \ -d { fields: { 任务名称: 整理周报, 状态: 待处理, 负责人: 张三 } }这种能力非常适合“信息汇总”类场景比如把群里零散的任务收集起来自动写入多维表格替代人工复制粘贴。至于“自动打卡”这类涉及个人行为和定时任务的功能我个人的建议是谨慎使用。技术上你确实可以让 OpenClaw 定时执行脚本、调用打卡接口或模拟点击但从规范角度讲企业考勤系统通常不允许非本人操作而且一旦接口或权限设计不合理容易引发合规风险。我更推荐把能力用在“提醒”而不是“代替操作”上让它每天早上 9 点提醒大家打卡而不是直接帮你打。如果你确实需要定时调度OpenClaw 本身或系统 cron 都能做但请确保所有自动化行为都在公司制度允许的范围内。5.4 补充飞书机器人“触发”和“群聊上下文”实际使用中群聊场景最容易困扰人的是“上下文”。OpenClaw 每次执行任务都是独立的它不会记住群里之前聊了什么除非你在消息里带上足够的背景信息。比如你说“看一下刚才那份表”它是不明白“刚才”是哪份的。正确做法是把文件信息写清楚“看一下 /mnt/c/... 路径下的销售数据表总结一下本周趋势。” 我做了个小改进让飞书机器人收到消息后自动把当前会话最近 20 条消息取出来一起传给 OpenClaw 做上下文。这样体验会自然很多代价是 API 消耗会增加因为每次都要带上之前的对话内容。6. 常见问题与排查技巧实录6.1 “could not safely verify the WSL2 environment” 排查全记录这个报错是 Windows 上最常遇到的。实测有几个常见原因现象可能原因处理方式执行wsl --status报错或找不到命令没安装 WSL2wsl --install重启WSL 默认版本是 1WSL2 没设为默认wsl --set-default-version 2系统提示内核版本过旧Linux 内核需要更新wsl --update能进 WSL2 但 OpenClaw 仍报错发行版文件权限异常在 WSL2 里执行sudo apt update sudo apt upgrade还有一个小众情况如果你用第三方终端软件连接 WSL2环境变量可能没正确传递导致 OpenClaw 检测不到关键路径。遇到这种情况直接打开微软官方的 Windows Terminal重新进入 WSL2 再运行。6.2 “session file locked (timeout 60000ms)” 是什么情况这个报错很典型我遇到的时候第一反应是“配置坏了”排查后发现其实是 OpenClaw 的会话锁机制在起作用。OpenClaw 为了保证同一个工作区不会被多个进程同时操作会创建一个 session 锁文件。如果上一个进程没有正常退出比如终端被强制关闭、电脑休眠后进程僵死锁文件还留在原地新的进程就只能等它释放直到 60 秒超时。处理方法分两步。第一步在 Windows 任务管理器里找一下遗留的 node 进程结束掉。第二步进入工作目录删除锁文件rm -f /home/你的用户名/openclaw-workspace/.lock建议用ls -la先看一下锁文件名再删不同版本锁文件命名可能不同。删除之后重新运行一般就正常了。如果这个报错频繁出现说明你的使用姿势有问题不要在多个终端里同时启动 OpenClaw更不要让它前后台同时跑同一个工作区。要用多实例就复制多个工作目录各自独立运行。6.3 飞书机器人收不到消息或回复失败飞书机器人接入时的问题通常来自身份、权限和事件订阅这三个环节收不到任何消息先检查应用是否已发布版本。飞书自建应用在修改权限后必须重新发布才会生效很多人卡在这一步。能收到消息但无法回复检查有没有开启im:message:send_as_bot权限。能收到消息但 OpenClaw 不响应大概率是事件订阅没配置成功或者长连接程序挂了。看本地程序的日志确认是否打印了接收事件的信息。我就犯过一个低级错误把 App ID 填成了机器人 ID导致 API 始终认证失败。这两个值长得像但完全不是一回事调试时优先核对。6.4 任务执行超时或回复未结束OpenClaw 执行复杂任务时耗时可能很长比如让它写一个脚本并运行、抓取网页并分析数据。飞书对响应时间有一定的预期如果长时间没有回复用户就会以为机器人死了。我的经验是两个方向同时处理。一是给openclaw run设置合理的超时时间二是把异步化收到飞书消息后立刻回复“任务已开始执行”等 OpenClaw 跑完再单独发消息通知结果。这样用户不会焦虑任务也有足够时间完成。异步化实现上就是把执行逻辑放到后台线程或独立队列里。这属于小优化但体验提升非常明显。7. 个人把玩一圈之后的几点实在体会这套东西我从装好到稳定跑通前后折腾了两天主要时间都花在 WSL2 环境验证和飞书权限配置上。真正把链路跑通之后你会发现OpenClaw 的效率不在于它能回答多难的问题而在于它能把你脑子里的“操作步骤”变成“说出来就行”的自然语言指令。有几个心得值得分享第一先在小范围试。不要一开始就把它接入大群先在单聊里跑熟确认它的行为符合预期再拉到测试群。第二任务描述要写清楚边界比如“只看 /workspace 目录不要动其他文件”避免 Agent 过度发挥。第三API Key 和 App Secret 这类敏感信息一定要用环境变量管起来别为了省事写在配置文件里。后续你可以继续扩展的方向有很多接入多维表格做自动化信息收集、定时任务推送日报、甚至让它调用更多企业内部 API。顺着这条链路往前走OpenClaw 能替人干掉的重复劳动比想象中要多得多。
