OpenClaw这名字第一次见就记住了一半因为它那个图标带个红色大钳子社区里玩着玩着就喊它AI龙虾。我大概是去年底开始折腾这个开源AI助手的从最开始的命令行bot到后来接微信、飞书、定时任务、知识库现在它基本7x24小时跑在我家里一台闲置小主机上。一句话概括OpenClaw也叫Clawdbot就是一个能自己控制数据、自己定义行为的开源AI Agent框架它把大模型和各种日常用的IM工具串起来相当于给你打工的24小时在线管家。这篇教程就是写给完全没接触过的小白看的目标是在Windows上10分钟把它跑起来从装环境、启动服务到接上微信、配上国内大模型每一步都掰开揉碎地讲。踩过的坑我会专门拉一个章节出来你照着抄就行。1. 动手之前先花5分钟弄明白OpenClaw到底是个啥很多新手容易一上来就敲命令敲完发现根本不知道自己在装什么一出问题就抓瞎。所以我在讲部署之前先花点时间把概念讲透这部分看懂了后面遇到问题你自己都能推出来个大概。1.1 它和普通聊天机器人有什么本质区别传统聊天机器人是你问一句它答一句能力边界写在代码里改个问题模板都要动程序。OpenClaw不是这样它是一个Agent框架核心是大模型 工具调用 消息渠道三层结构。你可以把大模型理解成大脑它负责理解你说什么、决定该干什么工具调用是手比如联网搜索、读文件、定时任务、调API这些动作消息渠道就是嘴和耳朵微信、飞书、Telegram、网页控制台都是它的入口。OpenClaw负责把这三层粘在一起让AI不仅能聊天还能主动帮你干活。另一个关键点是自托管。数据、配置、日志全部存在你自己的机器上不经过第三方平台。这点对在意隐私的人很重要相当于你给自己养了一个私有化AI秘书而不是把对话记录都交给某个App。1.2 名字里的龙虾是哪来的OpenClaw的项目名其实叫Clawdbot后面开源版改叫OpenClaw。Claw在英文里是爪子、钳子的意思项目图标又画了一个大龙虾钳子中文社区图省事直接叫它AI龙虾。你现在搜OpenClaw搭建AI龙虾部署搜出来是同一个东西别被名字吓到。项目最早的核心思路是让AI接管你的数字生活比如自动回复消息、整理内容、定时汇报、跨平台转发。后来社区越玩越大有人拿它当个人知识库入口有人拿它做团队协作机器人还有人拿它连智能家居。总之它不是一个玩具而是一个可以长期用的基础设施。1.3 OpenClaw和其他AI助手怎么选对比参考我在决定使用OpenClaw之前也对比过WorkBuddy和几个主流闭源助手这里直接给结论对比维度OpenClawClawdbotWorkBuddy闭源AI助手是否开源完全开源闭源闭源部署位置自己机器云端/按需云端数据归属完全自己掌控平台托管平台掌控可扩展性插件、工具、多模型都可以改固定工作流几乎不可扩展上手难度有一定门槛但可接受较低极低成本只需要模型API费用订阅费订阅费适合人群愿意折腾、看重隐私不想折腾但需要Agent普通用户我的观点很明确如果你只是拿AI聊聊天没必要折腾OpenClaw但如果想让它住在你的微信里、按你的规则干活、数据还不外流OpenClaw就是当前开源阵营里很值得选的一个。1.4 部署方式那么多小白选哪个OpenClaw可以跑在很多地方但不同方式对应不同人群别一上来就看到什么教程都跟着做Windows WSL2 Docker最适合小白Windows系统不用重装Docker负责把环境全部打包好出问题删掉重建即可。本文主推。Linux物理机/云服务器官方最推荐的生产方式稳定、省资源但需要你会基础的Linux命令。群晖NAS家里有群晖的可以装在NAS套件里Docker套件拉个镜像就行好处是NAS本来就不关机。飞牛OSfnOS最近社区热度很高的国产NAS系统装OpenClaw的人越来越多。其实飞牛底层也是Docker操作路径比群晖还简单搜飞牛安装openclaw能找到很多视频教程核心逻辑和本文Windows版一样。Windows原生不太推荐因为依赖环境太乱很容易把系统搞脏。我之前试过一次Python版本、Node版本、DLL缺失各种问题折腾了半天还不如重开一个WSL2干净。如果你手头已经有Linux服务器或者NAS直接跳到第2.3节看镜像启动部分的原理就行命令几乎通用如果你只有一台普通Windows电脑放心跟着下一章走就够了。2. Windows 10分钟喂饭级部署全流程这一步我会把命令和操作完整贴出来你照着敲就行。前提是你用Windows 10或Windows 11最好是64位家庭版以上。整个流程其实就三件事装WSL2和Docker、拉镜像启动、打开控制台接渠道。2.1 开工之前先对着清单打勾不要嫌我啰嗦这一步省了后面全是坑。我用最通俗的话解释一下为什么需要这些Windows 10/11 64位系统太老会缺后面需要的虚拟化组件。至少8GB内存建议16GBWSL2虚拟机本身占2GB左右Docker容器占1GB再跑个大模型推理8GB会有点紧。磁盘预留20GB空间镜像加数据卷干净安装大概6-8GB但日志和模型缓存会慢慢涨。管理员权限后面要执行系统级安装命令。先把Windows更新到最新WSL2的安装程序依赖最新系统组件老版本成功率低。很多人卡在could not safely verify the WSL2 environment这个报错绝大多数就是系统更新没打全或者虚拟化没开。提前处理掉后面就顺了。2.2 第一步一次性装好WSL2和Docker DesktopWSL2全称叫适用于Linux的Windows子系统第二版简单理解就是Windows里开了一个轻量Linux虚拟机。OpenClaw官方镜像是为Linux容器设计的所以需要这个环境来接住容器。操作步骤右键点击开始菜单选择终端管理员或PowerShell管理员。输入下面这行命令回车让它去装WSLwsl --install装完后必须重启电脑别偷懒很多教程漏了这一步导致后面全乱套。重启后重新打开终端输入wsl --status确认默认版本是2如果显示WSL版本为1执行wsl --set-default-version 2切换。去 Docker 官网下载 Docker Desktop 安装包安装时保持默认选项。装完打开它的设置Settings→ Resources → WSL Integration确保Enable integration with my default WSL distro是开着的。验证Docker是否工作终端里执行docker version能看到Client和Server两段信息就说明Docker跑起来了。Server出现才表示Docker引擎在工作。这一步比较常见的坑一是BIOS里虚拟化没开表现为WSL安装时报错或者Docker一直起不来二是老版本系统装不上WSL2所以系统更新要跑完。2.3 第二步拉取OpenClaw镜像并启动Docker装好后剩下就是一条命令的事。首先在磁盘上建一个数据目录比如C:\openclaw\data这个目录用来存OpenClaw的配置、会话记录和日志以后升级容器不怕丢数据。然后打开PowerShell不用管理员权限也行执行docker run -d --name openclaw --restart unless-stopped -p 18650:18650 -v C:\openclaw\data:/data openclaw/clawdbot:latest这条命令拆开解释一下-d后台运行不占住你的终端窗口。--name openclaw给容器起个名字以后操作它就用这个名字。--restart unless-stopped开机自启容器崩溃自动拉起这是长期运行的关键。-p 18650:18650把容器里的18650端口映射到本机OpenClaw的Web管理控制台就跑在这个端口。-v C:\openclaw\data:/data数据目录挂载让容器里的数据落在Windows硬盘上。openclaw/clawdbot:latest官方镜像latest表示最新版。第一次拉镜像可能比较慢如果一直不动可以考虑配置Docker的国内镜像加速源这个在Docker Desktop的Settings → Docker Engine里加一段registry-mirrors配置具体地址网上搜一下就有属于常规操作。看到容器运行起来之后建议打开一个新终端看日志确认启动状态docker logs -f openclaw日志里出现service started或者类似字样就说明起来了。2.4 第三步打开管理控制台把微信/飞书接进来浏览器访问http://localhost:18650这就是OpenClaw的Web管理控制台。第一次打开会让你设置管理员账号密码设置完进入主界面。对着左侧菜单找到Channels渠道页面这里就是接各种消息平台的地方。我讲两个最常用的接微信官方支持扫码方式接入个人微信。点WeChat渠道会生成一个二维码用你准备当机器人的微信号扫码登录。注意这里有两个建议一是强烈建议用小号或者专门注册的号来做机器人别用日常主号因为机器人特性一旦接入消息处理逻辑和你平时手动聊天的预期差异很大主号容易误事二是扫码登录的方式依赖微信网页版协议存在被风控的概率如果遇到登录失效需要重新扫码这是个人微信接入的通病不是OpenClaw本身的问题。接飞书飞书官方开放平台更正规去飞书开放平台创建一个企业自建应用拿到App ID和App Secret再到事件订阅里配置回调地址为http://你的公网IP或域名:18650/feishu/callback把Config填回OpenClaw的Feishu渠道配置里保存完事。飞书是团队协作场景最稳的选择我目前工作群用的就是飞书渠道。配好渠道后在控制台右侧的测试对话里先跟AI说句话确认核心链路通着再用微信或飞书给自己发一条消息试试。到这里OpenClaw的最小闭环就跑通了。2.5 到这里你其实已经完成了一个最小Agent系统让我帮你理一下现在的数据流你的微信发一条消息 → 微信服务器把消息推给OpenClaw → OpenClaw判断会话状态调用你配置的大模型API → 模型返回结果 → OpenClaw把回答从微信发回给你。这个闭环的价值在于以后你要扩展任何能力比如接知识库、接定时任务、接联网搜索都是在微信消息进来 → 处理 → 回复这条主线上加插件、加工具不用再改底层。所以第一次跑通闭环之后不要急着装一堆插件先让这个链条稳定运行一两天摸一下日志格式后面才好排查问题。3. 把大模型接进来千问、魔塔等国内模型桥接配置OpenClaw本身不提供模型它只是个调度中心。模型API是它的燃料所以装完环境之后最重要的一件事就是配好大模型。3.1 为什么我推荐直接用国内大模型API如果你什么都不配OpenClaw默认可能指向海外模型服务。对国内用户来说海外模型API有两个现实问题一是网络访问不稳定二是充值麻烦。所以我的建议是直接接国内大模型最常见的就是阿里云百炼的千问Qwen系列以及魔塔社区ModelScope提供的开源模型推理服务。千问、DeepSeek这些国产模型日常对话、写代码、处理文档都够用而且OpenAI兼容协议支持得很好OpenClaw接起来只需要改几个环境变量就行。3.2 配置千问的两种方式任选一种先说准备工作去阿里云百炼控制台开通模型服务创建一个API Key拿到的Key格式一般是sk-开头。这一步别嫌麻烦不创建Key后面什么都连不上。方式A通过环境变量配置推荐新手用如果你还没启动容器可以在docker run的时候直接传环境变量完整命令变成这样docker run -d --name openclaw --restart unless-stopped \ -p 18650:18650 \ -v C:\openclaw\data:/data \ -e OPENCLAW_LLM_PROVIDERopenai_compatible \ -e OPENCLAW_LLM_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 \ -e OPENCLAW_LLM_API_KEY你的APIKey \ -e OPENCLAW_LLM_MODELqwen-max \ openclaw/clawdbot:latest这里openai_compatible是关键表示用OpenAI兼容协议去对接千问。BASE_URL指向阿里云百炼的兼容地址MODEL填模型名。如果你之前已经启动过容器可以先用docker rm -f openclaw删掉旧容器再重新执行上面命令数据目录挂载的配置不会丢。方式B通过管理控制台配置适合已经跑起来的情况在Web控制台找到Settings或者模型管理选择自定义模型/OpenAI兼容把同样的地址、Key、模型名填进去保存后重启容器一次。配置生效后在控制台的测试对话里问一句你好介绍一下你自己能收到回复就说明通链路了。3.3 魔塔ModelScope模型的对接细节魔塔社区是阿里系的开源模型平台上面有很多优质开源模型可以免费调用最近社区里OpenClaw对接魔塔的讨论很多因为它能把手头开源模型直接变成Agent的大脑不用额外花钱。对接方式和千问几乎一样只是地址和模型名不同关键环境变量如下-e OPENCLAW_LLM_PROVIDERopenai_compatible \ -e OPENCLAW_LLM_BASE_URLhttps://api-inference.modelscope.cn/v1 \ -e OPENCLAW_LLM_API_KEY你的魔塔APIKey \ -e OPENCLAW_LLM_MODELQwen/Qwen2.5-7B-Instruct注意两点魔塔的API Key要去ModelScope控制台的API-KEY管理里生成。模型名一定要写全带上组织名和版本路径比如Qwen/Qwen2.5-7B-Instruct少写一个斜杠都会报模型不存在。我的实际使用感受是魔塔适合想体验不同开源模型、或者刚入门预算有限的用户如果追求稳定、响应快千问的qwen-max系列更省心因为它是商业APISLA有保障魔塔的免费推理队列偶尔要排队。3.4 模型怎么选才不浪费钱也不卡顿我用过几个模型直接给一个参考表模型擅长场景速度成本我的建议qwen-max复杂推理、长文分析中中等偏高重要任务用qwen-plus日常对话、写作、代码快较低默认主力qwen-turbo简单问答、实时回复极快最低高并发场景DeepSeek-V3系列代码、逻辑推理中中等程序员朋友可以试魔塔开源7B/14B学习、离线体验慢免费/低入门折腾用我的经验是给OpenClaw配两个模型一个贵的写复杂任务一个便宜的做日常回复在配置里通过工具或者指令切换。比如让它早上推送新闻摘要用贵的模型平时闲聊用便宜模型一个月能省不少。4. 高频报错排查实录遇到就照抄这一章是我最想写的内容。社区里大家搜OpenClaw的报错翻来覆去就那么几条我全部实测过把排查步骤整理成笔记你遇到哪个就直接照着做。4.1 报错openclaw could not safely verify the WSL2 environment.这个报错一般出现在Windows环境启动Docker时我自己也在换电脑重装环境时碰到过完整提示就是你搜到的那句。它背后的含义是OpenClaw启动时检查WSL2环境发现无法安全确认WSL2处于可用状态。原因基本逃不出这三个WSL2没有真正安装成功。很多人执行wsl --install后没重启或者系统组件不完整。排查方法终端执行wsl --status正常会显示默认版本是2如果提示没有已安装的分发版执行wsl --update拉最新内核再执行wsl --set-default-version 2。Docker Desktop没启用WSL集成。打开Docker Desktop设置 → Resources → WSL Integration确保开关是开的。改完设置后建议重启Docker Desktop。主板BIOS的虚拟化没开。进入BIOS设置找到Intel VT-x或AMD-V设置为开启。怎么判断打开任务管理器 → 性能 → CPU右下角虚拟化一栏如果显示已禁用就是这个问题。按这个顺序排查基本能在5分钟内解决。如果都检查了还不行最后的杀手锏是卸载Docker Desktop重新装一遍装的时候选中Use WSL 2 instead of Hyper-V。4.2 报错agent failed before reply: session file locked (timeout 60000ms)这个错误很让人抓狂因为它不像前面的报错那么有指向性。我系统性地排查过一次最终定位到根因多个OpenClaw实例同时操作同一个会话数据导致会话文件被锁住。常见的触发场景你同时启动了桌面版和容器版OpenClaw两个进程指向同一个数据目录。上次容器没正常退出被强制kill了残留的锁文件还在。多个渠道微信、飞书几乎同时给同一个会话发消息触发并发写入。解决办法先检查是不是多实例冲突终端执行docker ps确认只有一个openclaw容器在跑如果你还装了桌面版客户端先退掉。进入数据目录C:\openclaw\data或挂载卷对应路径找到sessions子目录这里会有后缀为.lock的锁文件。先备份一份然后把.lock文件删掉或者对整个sessions目录重命名再新建一个空目录。重启容器docker restart openclaw如果频繁出现建议减少同一个Agent绑定多个渠道同时输入的情况尤其在调试阶段。我踩坑最惨的一次是同时开着Docker容器和本地开发模式折腾了一下午才想起来是两个进程抢同一份数据。所以这个坑写出来希望大家别重蹈覆辙。4.3 现象微信能发消息但AI一直不回这个现象在社区里问得特别多症状是从微信发消息给机器人收不到任何回复但在控制台看消息其实已经收到了。排查顺序按下面来不要跳先用Web控制台的测试对话发一句看AI回不回。如果控制台里也不回那就是模型配置有问题要么API Key不对要么模型名打错了要么欠费了。查看日志docker logs -f openclaw出现4xx状态码就沿着这个方向查。控制台回但微信不回问题就在通道侧。重点看日志里有没有报发送失败的记录比如send message failedinvalid token这类。检查是不是多Channel路由问题。OpenClaw支持同时挂多个渠道消息进来默认回到来源渠道。如果你在飞书和微信同时登录但AI回复被路由到了飞书微信自然收不到。这时候去控制台的会话管理里看那个会话到底是哪个渠道在接管。扫码登录的微信偶发掉线。这是个人微信接入最常见的坑表现就是控制台能看到消息但发送动作被微信侧拦截了。解决就是打开控制台看二维码状态重新扫码登录。给新手的建议排查这类问题永远先看日志别瞎猜。docker logs -f openclaw是你的第一信息来源错误提示比任何经验都准。4.4 现象飞书输出内容容易被截断OpenClaw在飞书输出容易被截断这个关键词最近搜索量很高我估计很多人是被长文本回复坑了。原因有三个层面飞书消息长度限制普通的文本消息有最大长度限制超过部分会被截断。模型单次输出长度限制大模型每次reply的token数是有限的如果你让它写一篇长文本来就写不完。事件回调超时限制飞书要求事件回调在有限时间内返回如果模型推理时间过长回调就挂了。解决办法给模型加系统提示词让它分条回复。在OpenClaw的System Prompt里加上一句如果回答内容较长请分点分条输出不要一次性输出超长段落。 简单有效。配置最大输出长度限制。在模型配置里调低max_tokens到合理范围比如1024宁可让它分多次回答也不要一次吐太多。长内容改用文件或富文本方式发送。有些商业版实现会检测内容长度超长时自动封装成文件发送飞书里点开文件看全文绕开消息长度限制。4.5 其他杂项问题速查表问题可能原因解决办法镜像拉取非常慢未配置国内加速源Docker Engine配置registry-mirrors容器启动后马上退出数据目录权限不对 / 端口被占用检查端口占用确认目录完全可写控制台打不开容器没起 / 端口映射错docker ps看状态docker logs看日志所有渠道都没反应API Key欠费或限流去模型服务商控制台看余额与配额时间同步异常宿主机或容器时间不准重启Docker服务确认系统时间自动同步5. 跑起来之后还能怎么把它玩出花部署只是开始OpenClaw的价值在运行中才体现得出来。这一章我讲几个我实际在用的扩展方向每个都简单可落地。5.1 多Channel共存与channel怎么选一个OpenClaw可以同时接微信、飞书、Telegram所有渠道的消息都会进入同一个Agent它天然知道消息从哪来回答就回哪去。不需要你手动干预。但在多渠道场景下可能遇到我想主动给它发一条指令不想在那个渠道里打字的情况。OpenClaw的机制是支持在对话中切换channel的。比如你人在飞书想让它把结果发到微信可以这样在对话里指定把刚才的总结发到微信或者在控制台的会话管理里手动指定默认回话渠道。我自己的分配方案是微信负责日常自用和提醒飞书负责工作协作Telegram专门当API调试口。这样互不干扰一条消息也不会串台。5.2 让AI按时主动找你定时任务OpenClaw最香的功能之一就是定时主动发消息。我现在每天早上8点会收到一条总结内容是昨晚到今早的日志摘要、待办提醒和天气。这就是在配置里加一个定时任务实现的核心是cron表达式比如schedules: - name: morning_report cron: 0 8 * * * channel: wechat prompt: 根据最近的记录给我一份早上好简报包括今日待办和天气提醒。配置完重启容器就生效。cron表达式别怕格式是分 时 日 月 周0 8 * * *表示每天早上8点。注意时区问题容器的默认时区可能是UTC最好在启动命令里加-e TZAsia/Shanghai否则定时任务会整整晚8个小时触发。5.3 让它变成第二大脑知识库和记忆扩展跑通基础对话之后很多人想让它记得住东西。OpenClaw支持对接知识库、文件存储和各类插件你可以把工作文档、笔记、常用资料导进去之后提问时它会先把知识库检索一遍再回答。我的建议是分阶段引入先把文档文件夹挂载到数据卷里然后用标准的插件市场装一个知识库插件把文件夹路径配置进去。初期不用追求特别复杂文档数量先从几十个开始跑顺了再逐步扩展。知识库检索质量很大程度取决于文档格式PDF、Word要转成文本或Markdown再导入效果会好很多。5.4 7x24小时稳定运行的小经验OpenClaw这东西跑起来不难难的是稳定跑几个月不管它。我总结几条实用经验启动命令一定要带--restart unless-stopped容器崩溃自动拉起省心。数据卷一定放到独立目录我放在C:\openclaw\data定期打包备份重装系统也不慌。注意磁盘膨胀日志和会话数据会持续增长建议每个月清理一次大日志或者配置日志轮转。内存控制Docker容器默认可以吃满宿主机内存如果机器内存紧张可以在docker run时加--memory4g限制上限避免它把内存吃光导致整个系统卡顿。模型API的成本日常对话用便宜模型复杂的任务切贵模型长期跑下来能省不少。如果你家里正好有NAS比如群晖或者飞牛fnOS把OpenClaw迁过去是更好的归宿——NAS本身7x24小时运行功耗低数据也在内网比用Windows主机长期开机更划算。最后再分享一点我的个人体会OpenClaw这台AI龙虾前10分钟的搭建真的不难难的是后面养它的过程——教会它你的表达习惯、你的待办节奏、你的知识结构。所以你不用急着一次性把所有功能都接满先把今天这套Windows部署跑通让它先当个合格的聊天秘书之后每加一个新技能都会像给手机装App一样自然。我敢说跑通那一刻你会回来感谢现在耐心看完这篇教程的自己。