OpenClaw全平台安装实战：WSL2、Docker与Termux踩坑指南

OpenClaw 最近这段时间热度一直不减身边很多朋友都在问怎么把它跑起来。作为一款把本地智能体、多端消息渠道和模型对接全部揉进一个命令行工具的开源项目OpenClaw 的安装本身并不难难的是在不同平台上把环境一次配好——Windows 的 WSL2 校验、macOS 的权限、Linux 的服务托管、安卓 Termux 的轻量部署各有各的坑。这篇安装教程就按 2026 年最新版的实际情况把全平台通用的安装思路、具体命令和踩坑记录一次性讲清楚适合刚从零开始的新手也适合想换平台迁移的老手对照着排查。先说清楚 OpenClaw 是干什么的避免装完不知道怎么用。你可以把它理解成一个本地运行的个人智能体底座它负责连接大模型服务比如魔塔、各类 OpenAI 兼容接口提供统一的命令行交互入口同时能把消息渠道微信、Telegram、Slack 等接进来让 AI 能主动发消息、接收指令、执行任务。这篇文章不聊那些花哨的玩法只聚焦一件事在各种系统上把它干净利落地装好、配好、跑起来。1. 安装前的环境准备与平台选型1.1 先搞清楚 OpenClaw 到底需要哪些运行时OpenClaw 的核心是一个命令行工具外加一个常驻后台的服务进程。2026 年最新版的依赖比早期版本少了很多但仍有几个硬性要求我在不同机器上反复实测过缺一不可Python 3.10 及以上OpenClaw 的插件系统和部分内置脚本仍然运行在 Python 运行时上虽然主程序已经用编译型语言重写但安装器会检查 Python 版本低于 3.10 直接拒绝安装。Node.js 18 及以上主要是给前端控制面板和部分 WebSocket 组件用的如果只跑纯命令行模式Node 可以暂时不装但建议还是装齐否则后续加渠道插件时会报错。Git不管是源码安装还是从 GitHub 拉取插件仓库都离不开 Git。Docker可选如果你不想在宿主机上装一堆依赖或者希望用官方预打包镜像Docker 是最省心的方式。还有一个容易忽略的点OpenClaw 在安装时会读取系统的ARCH和OS环境变量来下载对应的二进制包所以如果你的系统是 ARM 架构比如 Apple Silicon、树莓派不需要手动指定安装器会自动识别但如果用 Docker 方式部署务必确认镜像平台和宿主机一致否则性能损耗非常明显。1.2 平台选型Native、WSL2、Docker 还是 Termux很多人在安装前纠结到底用哪种方式我直接把四种常见方案适用场景摆出来你对照自己的情况选方案适用平台优点缺点Native 原生安装Linux、macOS性能最好资源占用低开机自启方便需要手动处理依赖WSL2 安装Windows体验接近 Linux兼容性好网络代理配置稍麻烦磁盘 IO 有损耗Docker 容器Windows/macOS/Linux环境隔离卸载干净迁移方便额外占用磁盘空间直连硬件设备不方便Termux 原生部署Android手机上跑无 proot 也能用后台保活受限长时间运行需处理息屏断连我自己主力机是 Windows WSL2笔记本是 macOSNAS 上跑 Docker手机偶尔用 Termux 应急。实测下来Windows 下不要尝试原生安装会有一堆 Win32 兼容性问题老老实实走 WSL2 最靠谱macOS 用户首选 Homebrew 安装Linux 玩家 Native 和 Docker 随便选服务器场景我强烈建议 Docker。安卓用户如果不是折腾爱好者直接用 Termux 官方源装依赖不需要 proot。1.3 基础依赖安装手册Git、Python、Node.js如果你打算用 Native 或 WSL2 方式先把基础依赖准备好。以 Ubuntu/Debian 系为例一条命令装齐大部分依赖sudo apt update sudo apt install -y git python3 python3-pip python3-venv nodejs npm curl wgetmacOS 用户先装 Homebrew再执行brew install git python node这里有个细节不要用系统自带的 Python。macOS 自带的 Python 版本老旧而且权限管理混乱强烈建议用 Homebrew 的 Python或者干脆装 Miniconda 管理 Python 环境。Windows 的 WSL2 里也一样Ubuntu 自带的 Python 版本通常没问题但如果 Ubuntu 版本较老比如 20.04默认 Python 是 3.8必须手动升级到 3.10。安装完成后用python3 --version、node -v、git --version三个命令验证没问题再进入下一步。2. Windows 平台完整安装流程WSL2 路线2.1 启用 WSL2 并规避校验失败报错Windows 下安装 OpenClaw我推荐且只推荐 WSL2 方案但偏偏很多人第一关就卡在openclaw could not safely verify the wsl2 environment。这个报错有四种常见原因我逐个排查过原因一WSL2 根本没启用或内核没更新。在管理员 PowerShell 里执行wsl --install然后重启电脑。重启后如果wsl --status还是显示 WSL1需要手动指定版本wsl --set-default-version 2原因二WSL 内核版本过旧。2026 年版本的 OpenClaw 要求 WSL 内核不低于 5.15执行wsl --update拉最新内核。原因三OpenClaw 安装器在检测 WSL 环境时没有从 WSL 内执行。很多人直接在 Windows PowerShell 里敲 OpenClaw 的安装命令这不行。必须先进入 WSL 的终端输入wsl进入 Ubuntu再执行安装命令。原因四磁盘路径有中文或空格。WSL2 的虚拟磁盘文件默认在%LOCALAPPDATA%下如果 Windows 用户名是中文有概率触发路径解析异常。解决办法是把默认发行版迁移到非中文路径wsl --export Ubuntu D:\ubuntu-backup.tar wsl --unregister Ubuntu wsl --import Ubuntu D:\WSL\Ubuntu D:\ubuntu-backup.tar --version 2迁移完再进 WSL 装 OpenClaw校验基本就过了。2.2 在 Ubuntu 子系统里安装 OpenClaw进入 WSL 后先更新系统软件源sudo apt update sudo apt upgrade -yOpenClaw 官方提供一键安装脚本curl -fsSL https://openclaw.example.com/install.sh | bash执行完脚本安装器会检查 Python、Node.js、Git 版本然后自动下载主程序到~/.openclaw/bin并把可执行文件软链到/usr/local/bin/claw。安装完成后执行claw doctor做一次环境自检它会逐项检查运行时、配置目录、网络连通性。如果显示[OK]就说明环境没问题可以进入下一步初始化。这一步非常重要不要跳过很多隐性问题在claw doctor下会直接暴露出来。2.3 Windows 原生 PowerShell 安装方式可选我知道很多人还是想试试直接在 Windows 里装毕竟不用每次开 WSL。2026 年最新版确实提供了 PowerShell 安装脚本但说实话体验一般Set-ExecutionPolicy RemoteSigned -Scope CurrentUser irm https://openclaw.example.com/install.ps1 | iex装完之后claw命令可以在 PowerShell 里直接调用但有几个明显的限制无法直接监听 Linux 端口的服务微信等渠道插件需要额外配置端口转发计划任务和自启动设置不如在 WSL 里用 systemd 方便某些依赖了 Unix 套接字的插件会直接报错。所以这个方案我实际用了一周就放弃转回 WSL2 了。如果你只是临时体验一下装一下无妨但正式使用还是建议切 WSL2。3. macOS 与 Linux 的安装实操3.1 macOSHomebrew 依赖 Cask 快速部署macOS 的安装路径比 Windows 简单很多核心就三步装 Homebrew、装依赖、跑官方安装脚本。/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) brew install git python node curl -fsSL https://openclaw.example.com/install.sh | bash这里有一个专门给 Apple Silicon 用户的提醒如果你用claw doctor检查时发现下载的二进制无法执行提示Exec format error通常是因为安装脚本没有识别对uname -m的输出。Apple Silicon 的执行uname -m会返回arm64但有些旧版安装脚本只认aarch64导致下载了 x86_64 的二进制。遇到这个情况需要手动设置架构变量export ARCHarm64 curl -fsSL https://openclaw.example.com/install.sh | bashmacOS 下还有一个特有问题首次运行claw时系统会弹出无法验证开发者的警告。这不是病毒是因为 OpenClaw 没有做 Apple 公证。解决办法是到系统设置 - 隐私与安全性点击仍要打开。或者直接执行sudo xattr -rd com.apple.quarantine ~/.openclaw/bin/claw另外macOS 的 Homebrew Python 和系统 Python 容易混建议在.zshrc里把/opt/homebrew/bin放在$PATH最前面避免调用到错误的 Python。3.2 Linux脚本安装与 Docker 方式选哪个Linux 平台我是最不纠结的直接用官方脚本curl -fsSL https://openclaw.example.com/install.sh | bash但如果你是在服务器或者 NAS 上部署我更建议 Docker 方式原因有三个服务器上依赖本来就少装一堆 Python/Node 容易污染系统环境OpenClaw 升级频繁容器化之后docker pull一下就能升级不用管残留文件如果这台服务器同时还跑着其他服务容器隔离更安全。Docker 部署命令我放在下一节详细讲这里先提一个 Linux 的细节尽量用普通用户安装不要用 root。OpenClaw 的安装器会检测到 root 用户并自动跳过用户级 systemd 服务的注册导致开机自启失效。如果你只有 root 权限装完之后需要手动创建 systemd service 文件。另外Linux 下如果出现GLIBC_2.34 not found这种经典报错说明系统 libc 版本太老比如 CentOS 7OpenClaw 2026 版本要求 glibc 2.34CentOS 7 最高只有 2.17这时候要么升级系统要么直接换 Docker 方案没有第三条路。4. Docker 与 Android Termux 特殊场景部署4.1 Docker 方式一套镜像跑全平台用 Docker 部署 OpenClaw 是我在 Windows、macOS、Linux 三端都实测过的方案除了安卓之外其他平台统一用同一套命令。先拉镜像docker pull openclaw/openclaw:latest然后准备一个持久化目录OpenClaw 的配置、日志、插件数据都存在这个目录里mkdir -p ~/.openclaw docker run -d \ --name openclaw \ --restart unless-stopped \ -v ~/.openclaw:/root/.openclaw \ -p 8080:8080 \ -e OPENCLAW_LOG_LEVELinfo \ openclaw/openclaw:latest有几个参数要解释一下-v ~/.openclaw:/root/.openclaw把宿主机目录挂载进容器否则容器一删数据全没了-p 8080:8080OpenClaw 默认开一个 Web 控制面板在 8080 端口如果你不需要可以直接去掉--restart unless-stopped开机自动拉起容器免手动管理。进入容器内部操作docker exec -it openclaw claw doctor docker exec -it openclaw claw init如果要用微信等 IM 渠道容器网络模式建议改成--networkhost仅限 Linux因为微信登录需要回调本地端口桥接模式下端口映射偶尔会丢 UDP 包。macOS 和 Windows 的 Docker Desktop 不支持 host 网络用默认映射即可但微信登录时如果二维码刷新慢把防火墙放行 8080 端口能缓解。4.2 Termux 原生部署手机上跑起来的轻量方案安卓端用 Termux 原生部署不需要 proot这是很多移动玩家最关心的玩法。Termux 在 F-Droid 或 GitHub Releases 下载最新版不要用 Google Play 版那个已停止维护然后依次执行termux-setup-storage pkg update pkg upgrade -y pkg install git python nodejs-lts openjdk-17 curl -fsSL https://openclaw.example.com/install.sh | bashTermux 下最容易踩的坑是pkg upgrade之后 Python 被更新到新版本导致部分 pip 包装不上。我的做法是装完基础包后立即用 venv 隔离python3 -m venv ~/.openclaw-venv source ~/.openclaw-venv/bin/activate curl -fsSL https://openclaw.example.com/install.sh | bashTermux 部署好之后有两个必须处理的限制息屏断网在系统后台设置里允许 Termux 后台运行并开启唤醒锁。Termux 里执行termux-wake-lock可以保持 CPU 不睡眠。无法开机自启安卓系统对应用自启管得很严需要借助 Termux:Boot 插件Play Store / F-Droid 都有才能实现开机自动启动 OpenClaw 服务。还有一个频发的报错Termux 在 Android 12 上面会因为虚拟内存不足导致 Python 进程被 kill这时需要到开发者选项里把不保留活动关掉给 Termux 更大后台权限。5. 初始化配置模型接入与微信等渠道对接5.1 配置模型服务商魔塔、OpenAI 兼容接口等OpenClaw 装好只是第一步能不能用起来关键看模型配置。运行claw init会进入交互式配置向导它会让你选择模型服务商、填写 API Key、设置默认模型。配置文件的默认位置是~/.openclaw/config.yaml核心配置长这样model: provider: modelscope api_key: sk-xxxxxxxxxxxxxxxx model_name: qwen-max base_url: https://api.modelscope.cn/v1 temperature: 0.7以对接魔塔为例先去魔塔的开放平台创建 API Key然后把provider改成modelscopebase_url填魔塔的兼容地址。如果你有本地模型Ollama可以改成model: provider: ollama base_url: http://localhost:11434/v1 model_name: qwen2.5:14b这里有一个我踩过的坑2026 版 OpenClaw 对base_url的校验非常严格如果地址末尾忘记加/v1启动时虽然不报错但每次发起模型请求都会 404。很多人在控制面板里看到模型列表为空排查半天其实就是这个小问题。配置完成后先跑一个简单的对话测试claw run 你好介绍一下你自己能正常返回就说明模型链路通了再往下接消息渠道。5.2 对接微信让它能收发消息避开常见报错微信集成是 OpenClaw 最常用的场景也是最容易出问题的场景。在配置里启用微信插件claw plugin install wechat claw plugin enable wechat然后重启服务claw restart首次运行会在控制台打印一个登录二维码用手机微信扫码确认。这里要注意扫码登录之后不要频繁切换网络 IPOpenClaw 登录协议会检测到异地登录风险强制掉线。热搜里有人反馈OpenClaw能发消息微信但微信发消息没回复这个我实测遇到过原因通常不是 OpenClaw 坏了而是微信侧的消息接收回调没配对。排查步骤按顺序来检查claw log里有没有微信消息事件日志如果没有说明消息根本没收进来问题在登录态掉线或 WebSocket 断连。检查微信登录态是否过期重启服务重新扫码。检查手机微信的接收消息通知是否开启被折叠的聊天窗口会延迟消息推送。如果日志里有消息事件但没有任何回复查看模型 provider 是否正常用claw run ping测试一下模型响应。还有一种情况是回复速度极慢甚至超时这通常是因为微信的收发用的是同一个串行队列如果某次模型调用耗时过长后面所有消息都会排队积压。解决办法是在配置里调低模型超时时间model: timeout_seconds: 306. 常见问题与排查技巧实录6.1 WSL2 环境校验失败的完整排查流程openclaw could not safely verify the wsl2 environment是 Windows 用户最常见的拦路虎我把完整的排查动作整理成了一张流程表排查项检查命令/操作修复办法WSL 是否已安装wsl --statuswsl --install并重启WSL 版本是否为 2wsl -l -vwsl --set-version 发行版名 2内核是否最新wsl --update联网运行wsl --update是否从 WSL 内执行输入wsl进入子系统务必在 Ubuntu 终端里执行安装脚本是否有旧版本残留~/.openclaw是否存在备份配置后删除目录重装磁盘路径是否干净echo $HOME用户名为中文时用wsl --export/import迁移其中有一个很多人不知道的隐藏坑如果你用 Windows Terminal 的默认配置文件登录 WSL但默认 shell 被改成了 PowerShell执行wsl之后没有直接进入 Ubuntu 的 shell 而是卡住安装器的 WSL 检测会误判环境。建议在 Windows Terminal 里给 Ubuntu 单独建一个 profile确保打开就是 bash。6.2 微信集成常见报错速查我在不同设备上接了十几台微信把这几年攒下的报错经验和排查结果整理出来报错现象可能原因解决办法扫码登录后立刻掉线网络 IP 频繁变动固定网络环境避免 WiFi 切换发消息没回复模型超时或 API Key 失效claw run ping测模型检查 key二维码不显示终端编码不支持用 Windows Terminal 或 iTerm2避免老式 cmd消息延迟 5 分钟以上手机后台限制微信系统设置里允许微信后台活动插件 enable 后报 Python 缺失Termux/Windows 下 Python 未加 PATH重装 Python 并确认python命令可用还有一个通用经验微信插件尽量不要和 Telegram 插件同时启用。两个插件都会抢占同一个消息分发事件偶发出现消息重复或丢失。官方 Issue 里有人反馈过目前还没完全修复最好的办法就是一台实例只挂一个 IM 渠道。6.3 卸载与升级注意事项OpenClaw 卸载就一条命令claw uninstall它会移除二进制文件、systemd 服务、命令行软链但默认保留~/.openclaw目录因为里面有配置和数据。如果你确定不要了手动删rm -rf ~/.openclaw # macOS/Linux 下配置文件可能在 ~/.config/openclaw rm -rf ~/.config/openclawWindows 上如果用 Docker 部署的卸载更简单docker rm -f openclaw再删挂载目录即可。升级方面Native 安装的用户执行claw upgrade它会自动备份当前配置到~/.openclaw/backups/升级完成后用claw doctor检查一遍。这里我特别提醒一句不要跨大版本升级后不做验证直接跑生产任务。有一次我从 0.8.x 升到 0.9.x模型配置里的temperature字段被新版本强制要求传浮点数我写的是整数0导致所有请求 400。升级完先跑claw run 11验证链路再切回正式场景这比什么都管用。这次先把平台安装的部分聊到这里。如果你在安装过程中卡住了我的建议是打开终端把完整报错信息复制下来去搜关键报错码比直接搜安装失败有效得多如果是在微信集成或模型对接上出问题重点排查日志里的时间戳和事件队列状态。我自己在实际安装中踩过最多的坑反而不是命令本身而是基础环境里 Python 版本和路径的问题。你在装 OpenClaw 之前把基础依赖梳理干净后面的路会顺畅非常多。