先说一段真实经历。上个月我拿到一台 Windows 笔记本本来只想装个轻量 AI 助手结果一搜发现 OpenClaw 能本地部署还能接入飞书机器人直接在聊天窗口里使唤它干活这个思路很对我的胃口。结果一上手才发现网上教程写得要么太简略要么默认读者是后端老手。光 WSL2 环境验证就卡了两个小时飞书机器人又因为事件订阅方式不对折腾到半夜才跑通。这篇文章写出来的时候这套环境我已经连续跑了两周连同事都跟着装上了。所以这篇不是官方文档的翻译而是把实际能跑通的完整路径、每一步背后的原因、以及那些坑都重排一遍专门给零基础的朋友看。OpenClaw 是一个开源的 AI Agent 框架它的核心作用是把大模型变成一个长在电脑上的数字员工。你可以通过消息平台跟它对话它能调用工具、读写文件、执行各种自动化任务。模型可以接云端 API也可以接本地跑的 Qwen、DeepSeek数据不出机器。这篇教程围绕两个核心目标展开在 Windows 本地把 OpenClaw 跑起来以及把它接入飞书机器人让 Agent 真正出现在你的 IM 里。如果你是第一次接触 Agent 部署完全不用慌。文中每个命令、每个配置项我都会解释为什么这么做。这篇内容适合三类人想在局域网或本机跑 AI Agent 的技术爱好者、想给团队接入统一 AI 助手但又不想买云服务的同学、以及被各种部署教程绕晕的小白。1. 先把 OpenClaw 的架构搞清楚1.1 大脑、身体和办公桌我第一次打开 OpenClaw 的项目文档满屏都是 Channel、Provider、Session 这样的词直接看晕。后来我习惯用一个比喻来理解它大脑模型也就是 LLM。它可以是云端的 GPT 类服务也可以是本地 Ollama 跑的 Qwen、DeepSeek。身体OpenClaw 本身。它负责接收指令、规划步骤、调用工具、读写文件把模型的想法变成实际动作。办公桌Channel也就是消息入口。飞书机器人就是它的办公桌之一。你在飞书里发一句消息相当于给它递了一张纸条。这套架构最大的价值在于解耦。模型决定智商OpenClaw 决定行动力Channel 决定你在哪里跟它说话。换模型不用动 Channel换入口也不用动模型各自独立排查问题的时候特别方便。1.2 为什么要在本地装而不是直接用云端服务可能有人会问现在云端 Agent 平台那么多干嘛还要在自己电脑上折腾我用下来有三个理由。第一是数据边界。公司内部的需求、自己脚本里的密钥、不想传到第三方服务器的对话内容放在本地最安心。第二是成本。本地模型跑起来之后对话基本不再按 token 计费适合高频试错你可以随便问不怕烧钱。第三是可定制性。开源框架意味着配置、工具、系统提示词全部握在自己手里想加什么能力自己写而不是等平台开放。对个人和小团队来说本地部署的代价是需要一点动手能力收益是完全自主。这也是为什么我宁愿花一晚上踩坑也要把这套环境跑通。1.3 安装前的物料清单这一步别省。我第一次因为漏掉了 WSL2 的检查后面报错报得莫名其妙。下面表格里是我这套环境的最终配置可以作为参考。项目要求说明操作系统Windows 10 2004 或 Windows 11需要支持 WSL2WSL2已安装 Ubuntu 22.04 发行版部署容器依赖它Docker Desktop4.x 以上启用 WSL2 后端用来跑 OpenClaw 容器Ollama最新版本地模型服务默认端口 11434模型qwen2.5:7b / deepseek-r1:7b按显存选择8GB 显存起步飞书企业或个人开发者账号开放平台创建应用用如果你机器没有独立显卡或者显存小于 8GB也不是不能用后面 2.3 节我会专门说怎么选小模型。2. 环境准备地基不牢后面全是坑这一部分看起来和 OpenClaw 没有直接关系但我见过最多的报错恰恰都出在这两层WSL2 环境验证不过、Docker 起不来。所以单独拎出来仔细说。2.1 WSL2用两三行命令把 Linux 子系统装好WSL2 说白了就是 Windows 里的一个轻量虚拟机Docker Desktop 在 Windows 上跑的容器最终都运行在 WSL2 里。OpenClaw 的镜像如果检测不到 WSL2 的合法环境就会直接拒绝启动报出could not safely verify the wsl2 environment这个经典错误。安装方式很简单。以管理员身份打开 PowerShell执行wsl --install重启电脑后系统会自动装好默认的 Ubuntu。然后确认一下版本wsl -l -v输出里看到 Ubuntu 那行写着 2就说明 WSL2 已经启用。如果写着 1执行wsl --set-version Ubuntu-22.04 2 wsl --set-default-version 2如果你之前从来没装过 WSLwsl --install之后可能会遇到两个问题一是 BIOS 里的虚拟化没开需要开机进 BIOS 打开 Intel VT-x 或 AMD SVM二是 Windows 版本太老需要先更新系统。这些都排查完WSL2 基本就稳了。提示WSL2 默认会占用不少内存如果你机器只有 16GB 内存建议在用户目录下建一个.wslconfig文件限制 WSL2 的资源占用。我的配置是 memory8GB、processors4够用且不卡 Windows。2.2 Docker Desktop记得勾选 WSL2 后端Docker Desktop 下载安装时安装向导里会有一步让你选择后端。这里务必勾选 Use WSL 2 based engine。安装完成后进 Settings → Resources把内存和 CPU 限制一下别让它把整机资源都吃光我一般给 8GB 内存加 4 核。docker --version docker ps两条命令能正常输出就说明 Docker 环境可用。这里有一个容易被忽略的点Docker Desktop 启动后WSL2 里会自动多出两个发行版一个叫 docker-desktop一个叫 docker-desktop-data。OpenClaw 的容器是跑在 WSL2 里的所以你在 Windows 的终端里看到的一切其实已经被 WSL2 包了一层。后面排查日志的时候要用对查看路径。注意如果docker ps提示权限错误或者 Docker Desktop 一直卡在 Starting多半是 WSL2 后端没选对或者 Docker 服务和 WSL 版本不匹配。先重启 Docker Desktop不行就退出来用管理员身份重新打开。2.3 模型服务本地大脑的安装与选择OpenClaw 本身不带模型它需要对接一个模型服务。云端 API比如 DeepSeek 开放平台可以直接填密钥但对零基础用户我更推荐先用 Ollama 把本地模型跑起来因为不涉及花钱、不用注册 key出错也好排查。Ollama 的安装就是下载安装包装完在终端执行ollama pull qwen2.5:7b如果你需要更强的推理和代码能力可以再拉一个ollama pull deepseek-r1:7bpull 完之后验证服务是否正常curl http://localhost:11434返回Ollama is running就说明模型服务在线。模型选择上我列一个配置参考表按显存或者内存大小对号入座模型参数量建议显存适用场景qwen2.5:7b70 亿8GB综合对话、工具调用deepseek-r1:7b70 亿8GB代码、推理qwen2.5:3b30 亿4GB轻量任务、低配机器deepseek-r1:1.5b15 亿2GB纯文本、极限低配如果只有 CPU 没有独立显卡也能跑小尺寸模型就是反应慢一些。建议从 3b 开始试跑通了再换大模型。说实话7b 模型在响应速度和效果之间是比较平衡的但它对显存的要求也摆在那里硬撑着跑会非常痛苦。3. 在 Windows 上把 OpenClaw 跑起来3.1 两条路Docker 还是源码OpenClaw 提供了两种安装方式Docker 容器和源码运行。我给零基础读者的建议是直接用 Docker。理由很简单源码运行需要装 Node 环境、装依赖、手动处理版本兼容对 Windows 用户来说变量太多Docker 镜像把运行环境打包好了配置挂载进去就能跑出问题大不了删了容器重来成本低。当然源码方式也有它的优势想改框架内部逻辑、做二次开发时更灵活。先把 Docker 跑通后面有需要再切源码这是最平滑的路径。3.2 用 Docker Compose 一次性起服务在某个目录下比如D:\openclaw新建docker-compose.yml内容如下version: 3.8 services: openclaw: image: ghcr.io/openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 8090:8090 volumes: - ./data:/app/data - ./config:/app/config environment: - TZAsia/Shanghai然后在同目录创建config文件夹里面放一个config.yaml。先写最核心的模型配置agent: name: my-agent model: provider: ollama base_url: http://localhost:11434 model: qwen2.5:7b channels: {} server: port: 8090注意base_url这里有个细节OpenClaw 跑在 Docker 容器里容器访问宿主机不能用localhost要用host.docker.internal。所以 Ollama 的地址应该写成base_url: http://host.docker.internal:11434这个点非常经典我第一次没改启动后模型调用全部超时。改成host.docker.internal就通了。Windows 下 Docker Desktop 默认支持这个域名指向宿主机Linux 下要加extra_hosts好在 Windows 用户不用关心这个。配置写好后在D:\openclaw目录下执行docker compose up -d然后看日志docker compose logs -f openclaw看到类似 Agent is ready 的日志说明核心服务起来了。3.3 先别接飞书先在终端里和 Agent 说句话这一步很重要很多同学一上来就配置飞书结果模型没通飞书机器人回个网络错误根本不知道在哪查。我的建议是先只配模型用最直接的方式验证 Agent 核心能跑再动 Channel。启动起来之后OpenClaw 通常自带一个 CLI 交互入口在容器里执行docker exec -it openclaw cli或者直接用它的命令行参数发一条消息测试。如果用的是源码方式也可以直接pnpm cli。这时输入一句你好简单介绍一下你自己如果模型返回了内容说明大脑和身体都正常。确认没问题再进入飞书配置。4. 飞书接入把 Agent 变成你同事列表里的一员4.1 在飞书开放平台创建企业自建应用飞书接入这件事本质上是让 OpenClaw 以飞书机器人的身份接收用户在聊天窗口里发给它的消息。第一步打开飞书开放平台登录后进入开发者后台点击创建企业自建应用。名字随意比如我的 Agent。创建完成后在凭证与基础信息里记下两个关键值App ID 和 App Secret。这两个值就是 OpenClaw 和飞书服务器握手的通行证。第二步在添加应用能力里找到并添加机器人。机器人也就是我们说的 Bot添加后应用才具备收发消息的入口。4.2 权限与事件订阅本地部署必须用长连接这是整个接入过程最容易踩坑的地方我给你拆成两小块讲。权限方面在权限管理里搜索并开通以下权限im:message.p2p_msg读取用户发给机器人的单聊消息im:message.group_at_msg读取群聊中 机器人的消息im:message:send_as_bot以机器人的身份发送消息权限名称在不同版本可能略有差异但你按收发消息、读单聊、读群聊 这几个方向去找基本不会漏。事件订阅是重头戏。飞书有两种接收事件的方式一种是请求网址也就是 Webhook 回调需要你有一个公网可达的 HTTPS 地址另一种是长连接也就是 WebSocket不需要公网回调地址机器人和飞书服务器之间保持一条长连接。对于本地部署的 OpenClaw强烈建议选择长连接方式。家里或办公网的机器没有公网 IP用回调方式还得折腾内网穿透麻烦且不安全。在事件订阅页面勾选使用长连接接收事件然后订阅im.message.receive_v1这个事件。4.3 把 App ID 和 Secret 填进 OpenClaw回到 OpenClaw 的配置文件在channels下开启飞书通道channels: lark: enabled: true app_id: cli_xxxxxx app_secret: xxxxxx这里为什么叫lark因为飞书开放平台的底层 API 标识沿用了国际版 Lark 的命名OpenClaw 里也统一用lark作为飞书通道的标识。改好配置后重启服务docker compose restart openclaw然后看日志docker compose logs -f openclaw出现类似 Lark channel connected 的日志说明长连接已经建立。4.4 发布应用并在飞书里测试配置还没完还差最后一步在开放平台左侧找到版本管理与发布创建一个新版本。企业自建应用创建后默认只有你自己可见需要创建版本并发布管理员审核通过后再在管理后台把可用范围设置成公司全员或指定成员。审核通过后在飞书里搜索你创建的应用名找到机器人点进去发一条你好。同时可以把它拉进一个群在群里 机器人 也可以触发对话。如果这时机器人没反应先别急着怀疑配置。绝大多数情况是以下三个原因之一应用还没审核通过、可用范围没包含当前账号、事件订阅没有真正启用。按这个顺序排查基本都能解决。4.5 一条关于安全边界的提醒接上飞书之后你的 Agent 就是一个能收到公司同事消息的在线服务了。建议在系统提示词里把它的权限边界写清楚例如哪些操作需要明确确认、哪些文件不能动、不要读取聊天记录之外的敏感信息。另外不要用机器人去做违背公司制度的自动化操作比如远程打卡、代替审批之类的事。技术的价值是帮人省时间而不是给人惹麻烦。5. 高频报错排查这些问题我全都遇到过5.1 WSL2 环境无法安全验证报错原文大概是could not safely verify the wsl2 environment。这个错误几乎都出在 WSL2 本身没就绪或 Docker Desktop 没正确使用 WSL2 后端。排查链路如下管理员 PowerShell 执行wsl -l -v确认发行版存在且状态正常。如果这里输出为空说明 WSL 内核没装好执行wsl --update更新内核。确认 Docker Desktop 的 Settings → General 里勾选了 Use the WSL 2 based engine。没勾选的话容器不会调度到 WSL2OpenClaw 自然不认。重启 Docker Desktop。有时候改了 WSL 设置不重启Docker 使用的还是旧环境。这三步走完这个报错基本可以消除。我遇到这种情况十次里有八次是第二步没勾选剩下两次是 WSL 内核太旧。5.2 session file locked (timeout 60000ms)这个报错我在热词里也看到很多完整输出是agent failed before reply: session file locked (timeout 60000ms)。它翻译过来是Agent 在处理你这条消息前发现会话对应的锁文件被占用了等了 60 秒也没等到锁释放。原因基本逃不出两个一是上次进程没有优雅退出Session 文件被残留的锁占住二是不小心起了两个 OpenClaw 实例两个进程抢同一个会话文件。排查步骤先停掉当前 OpenClawdocker compose stop查看./data/sessions目录下有没有.lock结尾的文件有就删掉。确认系统里没有残留的 OpenClaw 进程Windows 任务管理器里找相关名字的进程结束掉。再docker compose start启动重新发消息。之后尽量用docker compose stop正常停止容器而不是直接把终端窗口关掉。这就好比你写文档正常关闭会保存断电强制关机就有文件损坏的风险。锁文件也是一样的道理。5.3 飞书机器人收到消息但不回复如果日志显示长连接已经建立飞书机器人也收到了消息但一直没有回复我建议按下面的清单逐项检查检查项操作事件订阅确认订阅了im.message.receive_v1且长连接状态为正常应用发布确认版本已发布、可用范围包含自己模型服务确认 Ollama 在线curl http://localhost:11434正常上下文超时本地模型速度慢把 OpenClaw 的响应超时时间调长到 120 秒以上日志报错看 OpenClaw 日志里有没有权限、API 返回异常等关键词还有一个隐藏问题如果你同时配了多个模型服务OpenClaw 默认可能走了没配好的那一个。检查配置里model.provider和model.base_url是否和实际服务一致。5.4 本地模型回复慢或者内容被截断小显存机器跑 7b 模型回复确实会慢。这里有两个调整方向。一是选对模型尺寸。日常对话、信息整理用 7b 完全够用如果只是跑个定时任务、简单问答换 3b 模型速度会快很多副作用是理解能力弱一些。二是在模型服务端调参数。Ollama 启动时可以通过环境变量调整上下文长度OpenClaw 的配置里也可以设置max_tokens。一般来说把max_tokens从默认值提到 2048可以避免长回复被硬截断但也会增加等待时间。具体数值根据你的显存和任务类型去调建议先 1024 起步试再逐步加大。另外别忘了检查 Windows 防火墙有没有拦截 11434 端口的本地回环请求个别安全软件会干这种事。最后说点个人体会。这套环境我跑了两周最大的感受是门槛其实没有想象中那么高。真正消耗时间的不是敲命令而是对概念的理解和对环境的排查。只要把 WSL2 和模型服务这两块地基打牢OpenClaw 本身反而非常省心它就是一个标准的 Docker 服务再加一份 YAML 配置。飞书接好之后我每天的工作流变成了群里 机器人 让它整理会议纪要回家路上用手机给它发消息让它跑个脚本团队内部文档的初稿也让它先过一遍。这种随身带着一个能干活的下属的感觉值得你花一个晚上把它跑起来。