2026年了OpenClaw社区里大伙儿更习惯叫它“AI龙虾”已经成为本地AI智能体玩家里绕不开的名字。很多人第一次听说它是因为那句“1分钟安装”的口号——但真上手之后发现有的人确实一分钟跑起来了有的人折腾一下午还卡在报错页面。这篇教程就是把OpenClaw的安装流程里里外外捋清楚前置环境、核心命令、配置要点、常见报错全部照着抄就行。适合刚接触AI Agent的新手也适合从Clawdbot老版本迁移过来的老玩家做参考。1. OpenClaw到底是个啥为什么中文圈都叫它AI龙虾1.1 从Clawdbot到OpenClaw项目到底啥来头OpenClaw不是一个全新的项目它是Clawdbot的开源延续版本早期内部代号叫Moltbot。Clawdbot当年在AI Agent圈子里火过一阵主打“本地优先、多智能体协作”但项目发展过程中经历了一些波折社区干脆另起炉灶把核心代码继续维护下去这就是OpenClaw的由来。名字里的“Claw”就是龙虾钳子的那个claw项目图标也是一只龙虾。中文社区叫着叫着就把OpenClaw叫成了“AI龙虾”连带着把安装部署这事也叫成了“养龙虾”——所以你在网上搜“AI龙虾安装”搜到的就是这玩意。这个称呼虽然带着玩梗的味道但挺形象龙虾有两只钳子OpenClaw做的就是让多个AI角色分工协作各管一摊像钳子一样把任务夹得死死的。1.2 它能干什么多智能体、记忆系统和模型路由OpenClaw的核心能力拆开说其实就三件事。第一是多智能体协作。它不是单个聊天机器人而是一个“AI总指挥”框架。你可以定义规划者、程序员、研究员等不同角色任务进来之后先由规划角色拆解再分派给对应角色执行最后汇总结果。这种架构在处理“查资料→写代码→跑测试→出报告”这类链条式任务时比单次调用大模型要可靠得多。第二是记忆系统。OpenClaw支持把长期记忆接入到Obsidian、Notion这类笔记工具里。AI在对话中产生的关键信息会写入记忆库下次再聊同类话题时能直接调出来用相当于给AI装了一个长期大脑。这一点对做知识管理、个人助理场景的人来说是刚需。第三是模型路由。框架本身不绑定某一家大模型OpenAI、Anthropic、各家兼容接口甚至本地跑的Ollama模型都能接进去。你可以让日常问答用便宜的小模型复杂任务自动切到能力更强的大模型省钱和效果两不误。1.3 适合谁玩先别急着装确认你是不是目标用户说句实在话OpenClaw的目标用户是“愿意折腾的人”。它的安装门槛其实已经比早期版本低了很多但依然需要你碰终端、改配置、看日志不可能像点开一个手机App那样零成本上手。如果你是下面这几类人这篇教程值得你完整读完第一类是AI开发者想在一个开源框架上调试多智能体流程第二类是自动化爱好者想把AI接入聊天软件、定时任务、笔记系统打造个人工作流第三类是Clawdbot老用户想了解新版怎么迁移、怎么配置。如果你只是想找个网页聊天窗口随便聊聊那这玩意对你来说属于杀鸡用牛刀——当然装完拿来当聊天入口也完全没问题。2. 装之前先自查环境3个前置条件决定你能不能1分钟搞定2.1 Node.js和Git绕不开的基石所谓“1分钟安装”成立的前提是你的电脑已经具备一套完整运行环境。最容易卡住的第一道坎就是Node.js。OpenClaw整个框架跑在Node.js上安装脚本、依赖管理、本地服务全都离不开它。我建议你安装Node.js 18或20以上的长期支持版本LTS太老的版本会出现语法不兼容、依赖装不上这类奇怪问题。装好之后在终端里跑一下node -v npm -v能看到版本号就说明Node环境和包管理器没问题。看不到版本号就去Node官网下载对应你操作系统的安装包装完重开终端再验证一次。Git也是必需项。安装过程中需要从代码仓库拉取项目模板没有Git什么都干不了。验证方式同样简单git --versionmacOS和多数Linux发行版自带GitWindows用户装一个Git for Windows就行。这两个工具属于“必须有但一般不会出幺蛾子”的部分真正容易翻车的是下面这个WSL2。2.2 Windows用户必看WSL2环境怎么补如果你用的是Windows这是整个安装流程里最容易劝退人的一步——OpenClaw的安装脚本和运行脚本很多基于Linux的Shell环境Windows原生PowerShell跑起来会有路径、权限、环境变量等一系列兼容问题。官方推荐的做法是在Windows上用WSL2也就是Windows Subsystem for Linux 2。具体操作分三步。第一步以管理员身份打开PowerShell执行wsl --install执行完重启电脑系统会自动装好WSL内核并默认启用。第二步打开Microsoft Store搜索Ubuntu装一个最新的长期支持版本22.04 LTS或24.04 LTS都行。第三步启动Ubuntu设置好你的Linux用户名和密码。之后凡是涉及OpenClaw安装启动的命令都建议在Ubuntu终端里执行而不是Windows的PowerShell里。这一点特别重要很多人的报错就是因为在PowerShell里跑了Linux脚本结果出现路径解析失败、命令找不到之类的问题。我见过最典型的一句话是“无法安全验证WSL2环境请在PowerShell中运行 wsl --status”——这种提示不是说WSL没装而是说你的WSL环境没有被正确识别通常用wsl --status和wsl -l -v两条命令检查一下状态缺哪个补哪个就好。2.3 资源和网络装到一半才知道就晚了最后说两个很多人忽略的点。一是内存和磁盘。OpenClaw本身占用不大但它要跑Node服务、多个AI角色进程还要给大模型调用留缓存空间。我建议至少预留4GB可用内存和5GB磁盘空间。电脑配置太低的话跑起来会明显卡顿甚至有进程被杀的风险。二是网络情况。OpenClaw安装时需要从npm仓库下载大量依赖包从GitHub拉取项目模板。如果你的网络访问这些源比较吃力建议提前给npm换一个速度更快的镜像源比如国内常用的npmmirrornpm config set registry https://registry.npmmirror.com这是个可选项但实测下来对安装速度的提升非常明显。把这三类前置条件都搞定后面的“1分钟安装”才是名副其实的1分钟否则光搭环境就能耗掉你一下午。3. 1分钟快速安装实操终端命令一步步抄3.1 最简路线npx一行命令拉起你的龙虾环境齐了之后安装其实就是一条命令的事。在终端里执行npx openclawlatest init my-lobster这条命令会做三件事先通过npx临时下载OpenClaw的最新版本然后执行初始化脚本最后在当前目录下创建一个名为my-lobster的项目文件夹。整个过程是全自动的不需要你手动去GitHub下载代码包也不用管依赖安装顺序——脚本会自己处理。如果这条命令执行成功你会看到类似“OpenClaw initialized successfully”的提示然后进入交互式配置流程。这一步通常耗时一分钟以内前提是网络通畅。这里插一句如果你是从老版本Clawdbot迁移过来的阶段性地跑一下npx openclawlatest init在新的空目录里再把旧配置改一改搬过来比直接覆盖升级要省心得多——毕竟社区版迭代节奏快直接升级容易踩到配置格式不兼容的坑。3.2 交互式配置初始化时要回答哪些问题初始化脚本跑起来之后会一个接一个地提问。不同版本的问题可能略有差异但核心问题基本就这几类项目名称默认用你创建目录时的名字直接回车即可。选择一个模型提供商OpenAI、Anthropic、Ollama等按你手头有哪个API密钥来选。暂时没有密钥也可以先跳过后面手动改配置。是否启用某个开放协议的支持这里说的是Model Context ProtocolMCP简单理解就是让AI能调用外部工具和数据的统一接口建议选“是”以后接插件会方便很多。记忆存储方式有Obsidian、Notion、简单文件存储等选项初次体验可以先选简单文件存储跑通了再换Obsidian。这里的原则是“能回车就回车别在交互界面里纠结”。初始化阶段的主要任务是生成一个能跑起来的骨架具体调优全部放到配置文件里去做。你手抖选错了也没关系配置文件里随时能改不用重新初始化。3.3 启动与验证怎么确认它真的跑起来了初始化完成之后进入项目目录并启动服务cd my-lobster npx openclaw start第一次启动会加载模型配置、初始化记忆存储、拉起本地服务日志会逐行刷出来。看到类似“Server is running on http://localhost:3000”的输出就说明本地服务已经起来了。验证方式有两个。最直接的是打开浏览器访问 http://localhost:3000进入Web控制台找到一个聊天输入框随便输入一句“你好简单介绍一下你自己”。如果AI能正常回复说明整个链路已经通了。第二种方式是直接看终端日志启动成功后日志里会打印当前运行的角色列表、接入的模型名称、记忆库状态——这些信息在日志里扫一眼就心里有数。需要提醒的是首次启动因为没有配置任何模型密钥AI可能回复“模型未配置”之类的错误提示。这很正常不是装坏了下一步把模型配置补上就好。3.4 Windows Companion想要图形界面可以加装如果你在Windows上用WSL跑OpenClaw但又不想每次都去开Ubuntu终端敲命令官方还有一个叫Windows Companion的桌面辅助工具相当于给OpenClaw配了一个图形化的控制面板。Companion的作用是托管状态显示、快捷启动、日志查看本质上它连接的还是那套本地服务。安装方式是在项目官方发布页面下载最新版本装好之后首次打开时让它指向你的本地服务地址通常是localhost加对应端口它会自动检测服务状态。我的建议是把它当作一个便捷开关但核心配置和命令操作还是放在终端里做更顺手毕竟图形界面能展示的信息始终有限真要排查问题还得看日志。4. 装完只算一半模型接入、记忆配置和权限设置要跟上4.1 模型接入让AI龙虾真正张嘴说话安装完成和“能用”之间还差一个关键的配置步骤——让OpenClaw连上一个大模型。没有模型龙虾就没有脑子。模型配置通常在项目根目录下的.env文件里完成。初始化时可能会生成一个.env.example模板你要做的是把它重命名为.env然后填入自己的信息。以OpenAI兼容接口为例MODEL_PROVIDERopenai MODEL_NAMEgpt-4o-mini OPENAI_API_KEYsk-你的密钥这里有个容易被忽视的细节很多国内模型服务提供的是OpenAI兼容接口只是地址不同。这种场景不需要改MODEL_PROVIDER只需要额外指定一个BASE_URLOPENAI_BASE_URLhttps://你的模型服务地址/v1把API密钥和地址填进去重启服务OpenClaw就会用你指定的模型来做任务规划。如果你想接本地模型比如很多玩家喜欢的Qwen2.5小尺寸版本可以先在电脑上装好Ollama然后把模型提供商切到ollamaMODEL_PROVIDERollama MODEL_NAMEqwen2.5:3b本地模型的优势是不用依赖外部API私有性强、没有调用费用但回答质量、响应速度和参数量直接相关3B的小模型适合日常轻量任务复杂推理还是得靠云端大模型。4.2 Obsidian记忆集成给龙虾装一个长期大脑OpenClaw最吸引人的功能之一就是记忆系统而Obsidian是社区里用得最多的记忆载体。原因很简单Obsidian的笔记就是本地Markdown文件可读、可控、可迁移还不依赖某个云厂商。配置Obsidian记忆只需要在配置文件里指定记忆提供者和你的笔记库路径。比如你的Obsidian库在Windows的D:\Documents\ObsidianVault下那么在WSL环境里路径要写成Linux格式{ memory: { provider: obsidian, vaultPath: /mnt/d/Documents/ObsidianVault } }这里要注意路径写法。WSL2会把Windows磁盘挂载到/mnt/c、/mnt/d这样的位置直接写D:\xxx这种Windows路径会报找不到目录。这个细节不少人踩过坑。配置好之后AI在对话中产出的关键信息会按照一定的结构写入你的笔记库比如项目进展、用户偏好、任务清单。下次再谈起相关话题它能从笔记里调取上下文而不是每次都从零开始。实际体验下来记忆系统接入前后的差别很大没接入的时候AI像金鱼聊过就忘接入之后像有了一本随身笔记本。4.3 权限模式从plan到auto别一上来就放养最后是权限设置这个环节直接关系到你用得安不安全。OpenClaw默认提供几种执行模式plan计划模式、auto自动模式、suggest建议模式。plan模式下AI做的每个操作都要经过你批准适合刚开始上手时使用auto模式下AI可以自主执行任务链适合跑你已经验证过很多次的日常流程suggest模式介于两者之间AI给出建议但不会直接动手。新手我的建议很明确先用plan模式跑一周。你在Web控制台或聊天入口里让AI帮你整理文件、查资料、写小工具它会先把步骤列出来你确认一下它才实际执行。这样你既能看清它的工作逻辑也能在它犯傻的时候及时喊停。等你对它的行为模式熟悉了再针对特定任务打开auto模式绝对不要一上来就放养。5. 翻车现场实录OpenClaw安装常见报错与排查5.1 WSL2环境校验失败最容易被卡住的一关先说我遇到最多的一次报错场景。很多Windows用户在安装时会被一句提示拦在半路大意是“无法安全验证WSL2环境请在PowerShell中运行 wsl --status”。这句话看着吓人其实核心信息是“OpenClaw的安装脚本没有在系统里找到可用的WSL2环境”。原因通常有三种一是你压根没装WSL那就在管理员PowerShell里跑wsl --install重启电脑后再试二是装了WSL但默认版本还是1WSL1在很多情况下不满足脚本要求需要在PowerShell里执行wsl --set-default-version 2三是WSL2内核组件太旧这时候跑一下Windows更新把它补到最新就好。排查完用wsl --status确认状态再执行wsl -l -v看看发行版版本号是不是2确认无误后重装OpenClaw大概率就能顺利通过。这个问题本身不难但因为它出现在安装早期容易让人觉得项目有问题其实完全是环境问题。5.2 Node版本与npm网络问题两条高频翻车路另一类高频报错集中在Node和npm环节。“node: command not found”这类错误常见于刚装完WSL但没在Linux环境里装Node的情况。注意你在Windows里装的Node在WSL里是不生效的需要在Ubuntu终端里单独装。推荐用nvm管理curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20装完再用node -v验证。还有一类错误长这样npm ERR! code ENETUNREACH或者npm ERR! network后面跟着一串超时信息。这大概率是npm拉依赖包时网络不畅解决办法就是我前面提过的换registry镜像源npm config set registry https://registry.npmmirror.com换完之后重新跑安装命令即可实测速度提升非常明显。这类问题不是OpenClaw本身的bug是依赖下载环节的网络瓶颈所以排查时别一头扎进项目代码里。5.3 配置类报错和端口冲突启动时的拦路虎成功装上依赖之后启动阶段还会遇到几类常见问题。一类是密钥类报错比如启动日志里出现 “API key missing” 或 “model provider not configured”。这说明OpenClaw读取不到你的模型配置先检查项目根目录下是否有.env文件注意前面有个点别漏了再检查文件里的MODEL_PROVIDER和对应密钥字段是否填对。还有一个隐蔽的坑填好配置后忘了重启服务配置没被重新加载——这个问题排第一。另一类是端口冲突报错信息通常包含EADDRINUSE。比如默认端口3000被别的程序占用了两个解决办法要么在配置文件里把端口改成3001、8080之类空闲端口要么找到占用进程把它停掉。Linux下可以用lsof -i :3000查看占用情况。5.4 排查思路速查表报错现象可能原因优先排查动作WSL2环境校验失败WSL未安装 / 版本为1 / 内核过旧PowerShell执行 wsl --status、wsl -l -v补齐后重启node: command not foundWSL内未安装Node在Ubuntu终端用nvm安装Node 20npm ERR! network / ENETUNREACHnpm拉包网络不通畅配置npmmirror镜像源后重试API key missing.env未创建 / 字段名错误 / 未重启检查.env文件、核对字段、重启服务EADDRINUSE端口冲突默认端口被占修改配置端口或停止占用进程Obsidian记忆目录找不到路径写法用了Windows格式改为/mnt/xxx形式的Linux路径排查的总原则其实就一句话先看日志再百度报错原文最后检查环境。OpenClaw的日志输出比较详细每次启动都会打印关键节点信息定位问题时按时间顺序从上往下看通常几分钟就能找到问题在哪。我个人在实际操作中的体会是安装OpenClaw这件事80%的时间都花在环境问题上真正项目自身的问题反而少见。耐心把WSL2、Node.js、npm镜像这老三样弄明白再装任何类似的Node项目都会顺畅很多。最后再分享一个小技巧——每次升级OpenClaw版本之前先备份.env和你自定义的配置文件升级完再放回去能省掉很多不必要的新旧配置对齐时间。