最近后台和群里被问得最多的一个事就是 OpenClaw 到底怎么装。这个被社区戏称为“小龙虾”的开源项目这段时间在技术圈刷屏的频率实在有点高有人管它叫下一代个人助理有人说它是自动化工作流发动机还有人把它当成能接入微信的智能体框架来折腾。我在 Windows、macOS、Linux 服务器和安卓 Termux 上都实际部署过一轮踩了不少坑也把安装脚本、离线整合包、WSL2 检测、微信插件报错这类问题逐一查了个遍。这篇就把从零到能跑通的完整过程按保姆级标准拆给你安装路线、前置环境、初始化配置、模型切换、技能扩展以及最容易卡住的报错排查全部按实操顺序讲清楚。如果你正准备部署 OpenClaw但连“它到底是什么”都还没完全搞清楚别急这很正常。这个项目名字本身就容易让人误解——它不是一个单一软件而是一套可以连接大模型、消息平台和自动化工具的智能体框架。本文适合刚接触 OpenClaw 的新手也适合已经在安装脚本上折腾过一轮、卡在某一步没走下去的进阶用户。我会尽量用大白话把原理和步骤一起讲确保你照着操作就能把这只“小龙虾”养起来。1. 装之前的三个判断小龙虾到底是啥、你要装到哪、走哪条安装路线1.1 项目本体一个自带爪子的开源智能体框架OpenClaw 的核心定位是用开源方式把大模型的对话能力和现实世界里的工具连接起来。你可以把它理解成“大模型的操作系统”大模型负责理解意图OpenClaw 负责执行动作比如调用技能、读取文件、发消息、处理定时任务、剪辑视频甚至对接第三方 API。它在架构上主要分成三层主程序负责调度和状态管理Gateway 负责和外部渠道通信Skill 是真正干活的技能包。拿人来做类比主程序是大脑Gateway 是神经Skill 是手脚。理解这个分层特别重要因为你安装完以后看到一堆逻辑多数配置工作其实就是告诉大脑你的神经该连哪些渠道手脚要带哪些工具。社区里管它叫“小龙虾”一方面是因为 Claw 本身就是爪子的意思OpenClaw 直译过来就是“张开的爪子”中文社区顺着这个梗就叫成了小龙虾另一方面也暗示了这个项目的扩展方式——像小龙虾一样钳子多能夹住的东西多各种技能插件都可以往上面挂。1.2 先想清楚你要部署在哪一个环境安装之前先做环境判断否则后面容易走弯路。我见过不少人一上来就照着 Windows 教程跑结果机器上连 WSL2 都没有报错以后再回头补环境白白折腾一晚上。OpenClaw 的典型部署环境有这么几类目标环境难度适合场景推荐安装方式Windows 本机中等个人体验、日常使用离线整合包或脚本安装 WSL2macOS 本机低开发者日常调试官方安装脚本Linux 云服务器低7x24 小时在线运行官方安装脚本 systemd安卓手机 Termux中高随身携带、无服务器场景Termux 原生部署无 prootESP32 开发板高极客玩具、轻量客户端MicroPython pycoclaw先用一张小表想清楚自己的目标再往下看对应的章节。如果你只是想快速体验优先选“Windows 离线整合包”或“Linux 服务器脚本安装”这两条路线最省心如果你手里只有一台安卓机也是有原生方案的后面会单独讲。1.3 安装路线的本质区别源码、整合包、脚本OpenClaw 的安装方式虽然看起来很多本质上只有三条一是从 GitHub 的 main 分支直接检出源码再构建二是使用官方整合好的离线包解压即用三是通过安装脚本引导整个流程脚本可以指定 git 安装方式自动拉取源码、安装依赖、生成配置。离线整合包适合网络条件一般、不想折腾环境的人Windows 上尤其明显下载解压就能跑省掉了 Python、Node、Git 版本不一致的烦恼脚本安装适合想掌握完整目录结构、之后要二次开发的人因为源码、依赖和配置都在你自己指定的路径下后面改插件、更新版本都更可控。我个人建议第一次尝试优先用整合包跑通再用脚本安装做正式部署。先用整合包把“它能做什么”搞清楚再用脚本方式把项目“种”到系统里两条路都走一遍你对这个框架的理解会完全不同。2. Windows 平台两种安装路线的完整操作与 WSL2 检查2.1 路线A离线整合包解压即用最省心的体验方式Windows 上最快的启动方式其实是直接找社区打包好的离线整合包通常通过夸克网盘这类渠道分享。整合包的好处是运行时、依赖、主程序全部打好包你不需要提前安装任何开发环境。操作步骤很简单但有几个细节直接决定成败下载整合包后先校验压缩包完整性再解压避免解压到一半报错。解压路径不要出现中文、空格和特殊符号。我见过有人解压到C:\Users\张三\桌面\小龙虾最新版结果启动脚本直接跑不起来换成C:\openclaw就好了。这背后原因是部分内置脚本在解析带中文或空格的路径时会出错属于典型的“看不见的坑”。解压完成后找到启动文件一般是start.bat或启动OpenClaw.bat右键以管理员身份运行不要直接双击。首次启动会生成配置目录和密钥文件稍等片刻终端会显示服务地址默认一般在localhost的某个端口上复制到浏览器打开就是控制台。整合包路线最容易翻车的点反而不是解压而是杀毒软件拦截。因为整合包里包含了可执行文件和自动脚本Windows Defender 或其他杀软经常会误报或者直接隔离部分文件。遇到这种情况先到隔离区把文件恢复再在杀软里把 OpenClaw 的目录加入信任区然后重新解压一次。这一步不处理好你会反复遇到“明明解压了但启动就报缺文件”的诡异问题。2.2 路线B官方安装脚本 Git main 分支源码安装如果你打算长期使用或者后面要改源码、写自定义技能脚本安装是更正规的路线。OpenClaw 的安装脚本支持指定 git 安装方式安装时会从 GitHub 的 main 分支把源码检出到目标目录然后自动处理依赖和初始化。整体流程大概是# 进入你准备存放项目的目录 cd ~/workspace # 执行官方安装脚本指定 git 安装方式和目标分支 bash install.sh --method git --branch main --prefix ~/openclaw这里有两个参数值得展开解释--branch main表示固定使用 main 分支。为什么社区里专门有人强调这一点因为 OpenClaw 迭代速度非常快预发布分支可能包含未稳定的功能而 main 分支相对经过了更多验证。对于生产环境或者长期运行场景锁定 main 分支比默认拉最新代码要稳得多。--prefix则是告诉脚本把源码装到哪个目录选一个你记得住的纯英文路径。脚本安装过程中会检查系统依赖通常需要 Git、Python版本有要求以及一个可用的 Node.js 环境。如果你的机器上这些工具版本太旧脚本会在检查阶段停下来并提示你具体缺什么。这里不要绕过检查老老实实装好再执行脚本省得后面跑起来各种诡异报错。源码装完以后目录结构大致长这样~/openclaw/ ├── main.py # 主程序入口 ├── config/ # 配置文件目录 ├── skills/ # 技能包目录 ├── gateway/ # 网关模块 ├── scripts/ # 辅助脚本 └── logs/ # 运行日志看到这些目录你就明白它为什么是“框架”而不是“软件”了——每个目录都是可替换、可扩展的模块。2.3 Windows 下绕不开的 WSL2 检查以及那个著名的验证报错Windows 上走脚本安装最常遇到的一个坎就是 WSL2 验证失败。安装脚本为了确保部分 Linux 依赖能正常运行会先检测 WSL2 环境如果检测不过就会抛出“could not safely verify the WSL2 environment”这类报错。很多人在这一步直接卡死其实问题并不复杂大多是下面几个原因没有启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”这两个 Windows 功能。安装的是 Windows 10 旧版本对 WSL2 支持不完整。已经装了 WSL但默认版本还是 WSL1不符合要求。当前终端不是管理员权限检测脚本无法读取系统信息。最稳妥的排查步骤是这样先以管理员身份打开 PowerShell执行wsl --status wsl --set-default-version 2如果提示未安装 WSL直接执行wsl --install装好内核然后重启系统再重新跑 OpenClaw 的安装脚本。这里有个很容易被忽略的小坑检测脚本有时需要你在 PowerShell 里先启动过一次 WSL 发行版它才能真正读到子系统的版本号。也就是说装完 WSL 后先随便打开一个 Ubuntu 终端等它初始化完成再回去装 OpenClaw成功率会高很多。3. macOS、Linux 服务器与安卓 Termux 的差异化部署细节3.1 macOS从脚本安装到开机自启的完整流程macOS 的安装路径和 Linux 基本一致但有几个细节不一样。首先macOS 自带的 Git 其实是 Xcode Command Line Tools 的包装第一次执行git --version时会弹出安装提示装完再继续。其次OpenClaw 部分依赖在 macOS 上需要编译如果没有安装 Xcode Command Line Tools编译阶段会报缺少头文件的错误。在 macOS 上我用的是 Homebrew 补齐依赖步骤如下# 安装基础工具链 xcode-select --install brew install git python node # 拉取源码 git clone -b main https://github.com/openclaw/openclaw.git ~/openclaw # 进入目录执行初始化 cd ~/openclaw bash scripts/init.sh初始化完成以后正常启动一次确认服务能跑起来然后可以配置开机自启。macOS 上我用的是 LaunchAgent 方式在~/Library/LaunchAgents/下建一个 plist 文件把启动命令指向 OpenClaw 的入口脚本同时把标准输出和错误日志重定向到logs/目录下方便以后排查。一个小提醒macOS 的 Gatekeeper 偶尔会拦截从网上下载的未签名脚本如果执行安装脚本时报“无法验证开发者”到“系统设置-隐私与安全性”里点允许运行即可。这是苹果的安全机制不是项目本身的问题。3.2 Linux 云服务器注意 systemd 服务和端口放行Linux 服务器是我最推荐的长期运行环境——因为 OpenClaw 这种智能体框架一旦配置好各种技能就适合 7x24 小时挂在后台随时响应消息。云服务器上部署重点有三个地方和本机不一样。第一个是 systemd 服务。手动在终端里跑python main.py虽然能启动但一旦 SSH 断开服务就跟着没了。正确做法是写一个 systemd 服务文件让它在后台托管[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] User你的用户名 WorkingDirectory/home/你的用户名/openclaw ExecStart/usr/bin/python3 main.py Restartalways RestartSec5 [Install] WantedBymulti-user.target把这个文件放到/etc/systemd/system/openclaw.service然后执行systemctl daemon-reload systemctl enable --now openclaw以后开机自动拉起崩了自动重启。第二个是端口放行。OpenClaw 的控制台和网关默认会监听本机端口云服务器需要在安全组和系统防火墙两个层面都放行对应端口。我踩过的一个坑就是在腾讯云控制台放行了端口却忘了服务器内部的ufw或firewalld还在拦截导致外部永远访问不到控制台。排查的时候两头都检查一遍。第三个是数据备份。服务器的优势是稳定但风险也在这——一台机器挂了你配置的所有流程和技能可能就没了。至少把config/目录和logs/目录做定期快照其他源码可以随时从 GitHub 重新拉取配置文件丢了才叫真麻烦。3.3 安卓 Termux无 proot 的原生部署方案手机部署 OpenClaw 这件事开始我以为只是图一乐实际跑通以后发现用途还真不小——出门在外手机就是一台随身服务器通过 Termux 跑着 OpenClaw配合微信或其他渠道等于随身带了一个智能助理。Termux 部署的关键词是“无 proot”。proot 方案虽然能模拟完整的 Linux 环境但性能损耗大、安装体积臃肿现在社区推荐的方式是利用 Termux 原生环境直接跑轻量很多。大致步骤# 更新软件源并安装依赖 pkg update pkg upgrade pkg install git python nodejs-lts termux-exec # 克隆 OpenClaw 源码 git clone -b main https://github.com/openclaw/openclaw.git ~/openclaw cd ~/openclaw # 安装 Python 依赖 pip install -r requirements.txt # 启动 python main.py原生部署需要注意两个点。第一Termux 的后台进程容易被系统杀死需要借助termux-wake-lock保持 CPU 唤醒否则息屏一段时间后 OpenClaw 就断了。第二Termux 的文件目录结构跟普通 Linux 不完全一样安装脚本如果写死了/usr/lib之类的路径可能找不到依赖遇到这种情况优先选 pip 安装依赖不要强行走系统级安装。手机端还有一个隐藏限制部分 Android 系统对 Termux 访问通知栏、后台运行有严格策略需要在系统设置里把 Termux 的“电池优化”改成“不限制”否则运行半小时就被系统回收。这一条不设置好你前面所有部署工作都可能白费。3.4 轻量设备跑 OpenClawESP32 的另一种玩法热搜词里有一条“micropythonpycoclaw3 分钟搞定 esp32 跑上 openclaw”这确实是个特别有意思的方向。不过要把概念说清楚ESP32 上的 pycoclaw 并不是跑完整的 OpenClaw 主程序而是跑一个轻量级客户端/遥控器。它通过 MicroPython 在 ESP32 上实现与 OpenClaw 服务的通信把开发板变成一个可以语音触发、按键触发或者传感器触发的交互终端。实际体验下来更准确的定位是ESP32 是 OpenClaw 的一个物理入口而不是运行环境。用 MicroPython 固件烧录后通过串口或 WiFi 连接你的 OpenClaw 服务然后就能在开发板上调用技能。适合做桌面摆件、智能开关、语音助手原型这类场景。本质上与在手机、电脑上跑 OpenClaw 是两码事但如果你手头正好有 ESP32 开发板3 分钟烧个固件体验一下控制和调用还是挺有成就感的。4. 装完不算完初始化配置、模型接入与技能扩展4.1 首次启动后的初始化流程到底要做哪几件事很多人以为“装完了”就等于“能用了”实际上 OpenClaw 装完只是框架距离正常使用还要做三件初始化工作生成配置文件、接入大模型 API、启用消息渠道。首次启动时程序会在配置目录下生成一份默认的config.yaml或类似格式的配置模板。打开这个文件你会看到几个关键节点模型提供商、模型名称、Gateway 配置、技能开关、日志级别。这些配置项的名字在不同版本里可能略有不同但逻辑都是一样的。第一件事是改日志级别。默认日志详细级别较低一旦出问题根本看不出原因我习惯在调试阶段把它调到 debug确认运行正常后再调回 info。这个小习惯帮我省下了大量排查时间。第二件事是确认数据目录。OpenClaw 会把会话记录、记忆数据、技能缓存存放在数据目录里。请记下这个路径之后升级程序、迁移服务器时只需要备份这个目录就能完整迁移状态。4.2 用 ccswitch 切换模型接上硅基流动这类 APIOpenClaw 本身不绑定某家大模型而是通过配置接入各类模型 API。社区里大量讨论的 ccswitch 就是专门用于切换模型的工具它让你不用改主配置文件就能在多个模型之间来回切换配合不同任务使用不同模型——例如日常对话用便宜快速的模型复杂推理任务用更强的大模型。以接入硅基流动平台为例配置流程是这样的到模型服务商的控制台申请 API Key。在 OpenClaw 的控制台页面或命令行执行 ccswitch 相关命令添加一个新的模型配置。填入模型的 Base URL、API Key、模型名称。执行切换命令把当前默认模型指向新配置。用一条测试消息验证是否生效。说到这个就不得不提一个很实际的建议接入模型时不要只配一个。OpenClaw 框架里不同技能的模型需求差异很大比如自动视频剪辑对视觉理解模型要求高定时总结任务用普通对话模型就够。多配几个模型再按技能维度指定默认模型成本和效果都能兼顾。配置方法通常是直接编辑配置文件里的模型映射表把技能 ID 和模型名对应起来。4.3 微信集成扫码接入与 ilinkai 风控的预防OpenClaw 最有吸引力的功能之一就是接入微信让智能体直接出现在你的微信对话框里。基本原理是启用微信渠道插件通过扫码登录微信网页版协议或中间服务实现消息收发。微信集成这一块的坑比较深社区里报得最多的问题就是“触发了 ilinkai 服务端风控或会话残留”。我实际排查过这个报错通常是两个原因叠加导致的一是频繁登录或者登录设备过多触发了中间服务的安全风控二是上一次会话没有正常关闭残留的会话状态导致新请求被拒。处理方案按顺序来先退出所有已登录的 OpenClaw 微信会话清掉会话缓存文件。在配置文件里把微信渠道临时禁用重启服务再重新启用。如果还不行检查配置里是否有历史会话 ID手动删除。触发风控后不要频繁重试等几分钟再做连续重试反而更容易被拉长封禁时间。另外微信这个入口虽然很香但我建议把它当作“通知和轻交互”通道不要在微信里直接跑高强度任务。原因很简单微信消息是即时同步的如果 OpenClaw 处理任务耗时较长体验会非常差而且消息频次太高很容易触发风控。我自己的做法是微信通道只接收指令和发送结果真正的重活通过定时任务错峰执行。4.4 技能推荐从定时提醒到自动化视频剪辑OpenClaw 的“技能”机制是整个项目最值钱的地方。一个技能本质上就是一个封装好的能力模块比如定时提醒、网页摘要、知识库问答、自动化视频剪辑、日程管理等等。社区里可以找到大量现成技能安装方式基本是复制到skills/目录然后刷新技能列表。给初次上手的朋友几个技能选择建议定时提醒最基础的技能也是最容易跑通的适合验证整体链路是否正常。网页摘要粘贴一个 URL自动生成结构化摘要。用来测试模型接入是否正常很合适。知识库问答把本地文档作为背景资料用自然语言问答。这个技能能让你直观感受到 OpenClaw 和普通聊天机器人的区别。自动化视频剪辑依赖视觉模型和 FFmpeg适合有视频处理需求的用户但依赖较多建议前面几个技能跑通后再尝试。每安装一个技能都要注意它的依赖声明。有些技能需要额外的 Python 库、命令行工具或者 API Key漏掉一个就会导致技能加载失败。技能加载失败通常不会让主程序崩溃只是在调用时报错所以建议每次装完技能后先到控制台看技能列表里是否显示正常再实际调用测试。5. 安装过程中高频报错的全链路排查笔记5.1 WSL2 环境验证失败的完整复盘前面提到过 WSL2 验证问题这里把完整的排查链路展开讲。报错信息“could not safely verify the WSL2 environment”字面上是“无法安全验证 WSL2 环境”但它背后的真实原因可能有十几种你得按照优先级逐个排除。我的排查顺序是这样的确认是否安装了 WSL终端执行wsl --status如果提示“未安装”直接wsl --install。确认默认版本是 2 而不是 1执行wsl --list --verbose如果显示 VERSION 是 1执行wsl --set-version 发行版名 2。确认 Windows 功能已启用控制面板-程序-启用或关闭 Windows 功能勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”重启。确认以管理员身份运行检测部分系统信息需要管理员权限才能读取。确认路径中无中文和空格尤其是系统用户名是中文的机器安装目录很容易踩雷建议把项目放到C:\openclaw或者D:\openclaw。确认至少启动过一次 WSL 发行版只装不开会导致检测脚本读不到版本信息。按照这个顺序基本能覆盖九成以上的情况。如果所有检查都通过了还报错最后一招是删除.wslconfig自定义配置如果有的话因为某些全局配置会导致 WSL 子系统网络模式异常同样会让验证脚本无法安全确认环境。5.2 微信插件触发 ilinkai 风控的定位思路这个报错在微信接入时很容易出现处理起来需要一点耐心。先说结论ilinkai 风控触发通常跟这三个因素强相关——登录频次、会话残留、内容触发。定位步骤查看日志里报错的时间点和对应动作判断是登录时触发还是发消息时触发。如果是登录时触发多半是短时间频繁登录或者是网络出口 IP 变动太频繁。换个网络环境等一段时间再登录。如果是发消息时触发先看消息内容是否包含营销、敏感词之类的高频风控特征词换一条普通消息测试。如果所有消息都报错大概率是会话残留。到数据目录里找到会话缓存文件删除后重启服务重新登录。这里有一个容易被忽略的操作微信插件报错后不要只重启主程序还要检查 Gateway 是否也重启了。因为会话状态往往缓存在 Gateway 层主程序重启了但 Gateway 还保持着旧会话问题依然存在。正确顺序是停掉主程序和 Gateway清缓存再一起拉起。5.3 依赖冲突、端口占用、卸载残留的通用处理套路除了 WSL2 和微信这两类典型报错新手还会遇到依赖冲突、端口占用、卸载不干净这老三样这里给一套通用处理思路。依赖冲突的典型表现是“ModuleNotFoundError”或者某库版本不兼容。直接改全局环境是下策强烈建议为 OpenClaw 单独建一个虚拟环境python -m venv ~/openclaw/venv source ~/openclaw/venv/bin/activate pip install -r requirements.txt端口占用的表现是启动时报“Address already in use”。先用lsof -i :端口号或netstat -ano | findstr 端口号找到占用进程确认不是系统关键进程后再处理。如果是之前残留的 OpenClaw 进程占用了端口直接杀掉重启即可。卸载残留主要出现在你装过旧版本、想换新版本的时候。很多人卸载只删了项目目录结果重新安装后发现配置还是旧的、服务自动重启了——这是因为配置文件写在用户目录启动项也还挂在系统里。标准卸载流程应该是先停服务再清理开机启动项最后删除配置目录和数据目录。脚本方式安装的通常自带了卸载参数执行后会自动处理这些步骤手动安装的就要注意不要把~/.openclaw之类的配置目录漏掉否则会“装了又好像没装”。最后分享几个我反复踩过之后总结的小习惯如果你打算把 OpenClaw 当作长期工具来用有几个操作习惯强烈建议从一开始就建立起来。首先是养成“先看日志再提问”的习惯。OpenClaw 的日志信息其实非常详细90% 的报错看一眼日志就能明白原因。很多人在社区里发帖问问题贴一张报错截图但其实日志里已经把定位信息写得明明白白——先打开 debug 日志再复现一次问题你自己就能解决一半。其次是定时更新要谨慎。OpenClaw 迭代非常快main 分支几乎天天有提交。我见过不少用户看到新版本出现就立刻拉取结果依赖变了、配置结构变了整个服务起不来。建议明确区分“体验环境”和“生产环境”生产环境锁定版本打算升级时先在测试环境跑一遍确认没问题再动。最后是注意“小步验证”。每做完一个配置就重启一次服务并测试对应功能不要攒十个改动再一次性验证。因为 OpenClaw 的配置项是联动的一次改太多出问题时根本不知道哪里出了问题。一次只动一个变量维持可回滚的状态这个习惯能让所有开源框架的使用体验都提升一大截。这只“小龙虾”能做的事远不止装完跑起来这么简单真正好玩的是把它接上你日常的工作流、接入不同的技能、让它替你处理重复劳动。希望这篇教程能帮你把环境顺利跑通少走我当初走过的弯路。