1. 为什么第一次装 OpenClaw 总卡在环境这一步OpenClaw 是一个可以本地跑起来的 AI 智能体运行框架能接模型、接工具、接消息通道适合想自己搭一套可控 Agent 环境的开发者。它本身安装脚本不复杂真正让人抓狂的是环境Node.js 版本不对、WSL2 没开、build tools 缺一半、装到一半 SSH 掉线最后你根本不知道是装完了还是卡住了。这篇就按 Ubuntu 24.04 64 位 WSL2 两条路把 OpenClaw 环境搭建从零跑通每一步都给可复制命令和验证动作。先说清楚适合谁如果你在 Windows 上想用 OpenClawWSL2 是最省事的路径如果你手上就是 Ubuntu 24.04 桌面版或云主机直接原生装。两条路的依赖要求一致核心就是 Node.js 22 或 24、Git、以及 make/g/cmake/python3 这套 Linux build tools。我试过在没装 build tools 的干净系统上直接跑安装脚本前面下载都正常到编译原生依赖那一步才报错回头补依赖又得重来所以顺序很重要先把系统依赖补齐再装 Node最后跑 OpenClaw 安装脚本。还有一个高频误区很多人以为安装脚本跑完就完事了其实脚本只是把二进制和运行环境放好真正的初始化选模型、填 API Key、配通道是交互式的会一步步问你。如果你在远程 SSH 里跑中途没输出、没进度条很容易以为卡死。实测下来安装阶段没有进度显示是正常的你只要定时敲个回车保持连接就行。下面按「原问题 → 前置准备 → 可复制配置 → 验证 → 排障 → 后续」的顺序展开。WSL2 和原生 Ubuntu 的差异我会在每一步标出来你按自己环境选对应的命令即可。2. WSL2 与 Ubuntu 24.04 前置准备Node.js 版本选择和依赖安装这一节解决「装之前系统里该有什么」。OpenClaw 官方推荐 Node.js 22 或 24我建议直接上 24 LTS避免 22 早期版本里某些原生模块编译告警。Git 用来拉依赖build tools 用来编译原生扩展缺一个都会在安装中途炸。先处理 WSL2。如果你已经在 Windows 上装了 WSL2 并且有一个 Ubuntu 24.04 实例直接跳到依赖安装。没有的话在 PowerShell管理员里执行wsl --install -d Ubuntu-24.04装完重启首次进入会让你设用户名和密码。进去后先更新源sudo apt update sudo apt upgrade -y接着装基础依赖。这一条命令把 Git、编译工具链、Python 全带上sudo apt install -y git curl build-essential cmake python3 python3-pipbuild-essential里已经包含 make 和 g不用单独再装。装完可以验证一下node -v || echo node 未安装 g --version | head -n1 cmake --version | head -n1 python3 --version如果 node 那行提示未安装说明你还没装 Node继续往下。Node.js 的安装我推荐用 NodeSource 的 24.x 源比 apt 自带的版本新curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt install -y nodejs装完再验一次node -v npm -v正常应该输出 v24.x.x 和对应的 npm 版本。这里有个坑如果你之前用 apt 装过旧版 nodeNodeSource 脚本可能会和旧包冲突先sudo apt remove -y nodejs再跑上面的命令。WSL2 用户额外注意两点。第一项目别放在/mnt/c/下跨文件系统 IO 慢且权限容易出问题放在 WSL 自己的家目录~/projects里。第二WSL2 默认内存可能吃满如果你机器内存小在 Windows 用户目录下建.wslconfig[wsl2] memory8GB processors4 swap2GB改完在 PowerShell 里wsl --shutdown再重进生效。原生 Ubuntu 24.04 用户不需要这步直接确认依赖齐全即可。到这一步系统层的前置就齐了下一节跑 OpenClaw 安装脚本。3. OpenClaw 安装脚本与初始化配置可复制命令与 settings 片段依赖齐了就可以装 OpenClaw 本体。官方一键脚本截止目前仍是主推方式curl -fsSL https://openclaw.ai/install.sh | bash跑起来后你会看到类似Installing OpenClaw v2026.4.11的输出然后就是一段没有进度条的等待。远程 SSH 的话隔一会儿敲个回车防止连接超时断开。安装完成后脚本会提示你重启 shell 或 source 一下配置照做即可。装完先确认版本这也是判断「到底装没装上」的最直接动作openclaw --version能打印出版本号说明二进制已经在 PATH 里了。如果提示 command not found多半是 PATH 没刷新执行source ~/.bashrc或重开终端。接下来是初始化。直接运行openclaw它会进入交互式配置流程。第一步通常让你选模型提供方比如 DeepSeek、Ollama 或其他兼容 OpenAI 协议的服务。这里我建议你提前准备好一个 API Key。以 DeepSeek 为例选完后粘贴 Key 即可。如果你用的是 TaoToken 这类聚合入口模型对话和 API Key 管理可以走它的控制台Base URL 填https://taotoken.net/apiKey 在 API Keys 页面生成模型 ID 按你实际选的填。三件套Base URL Key Model ID缺一不可这是后面请求能通的关键。初始化过程中还会问你要不要配飞书、Google 地图 Key、Notion Key、OpenAI Key、Elevenlabs Key 等。没有就直接跳过不影响基础环境跑通。Skill 选择那步也可以先跳过后面按需再加。如果你想把配置写成文件而不是每次交互OpenClaw 的配置一般落在用户目录下的配置文件中。以常见的 settings 结构为例你可以手动维护一段类似这样的片段路径按你实际安装位置调整{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: 你的_API_KEY, modelId: deepseek-chat }, gateway: { port: 18789 } }注意baseUrl不要带多余路径modelId必须和你所选服务商文档里的一致写错了会在请求阶段报reading choices之类的解析错误。配置改完重启 OpenClaw 生效。初始化全部走完后脚本会提示重启 OpenClaw。到这里安装和配置就完成了下一节做一次真实启动验证。4. 启动验证gateway 端口、版本查询与一次成功请求配置完成后最关键的验证动作是启动网关并确认端口在监听。手动启动openclaw gateway启动后默认监听 18789 端口。在浏览器里访问http://localhost:18789/WSL2 用户注意WSL2 的 localhost 转发在较新版本里是自动的Windows 浏览器直接访问 localhost:18789 通常能通。如果打不开先在 WSL 里用curl自测curl -I http://localhost:18789/返回 200 或 3xx 说明服务本身正常问题在 Windows 到 WSL 的端口转发可以试wsl --shutdown重启或检查 Windows 防火墙。再做一个模型侧验证确认 API Key 和 Base URL 配对了。OpenClaw 一般提供命令行对话入口你可以直接问它版本信息比如openclaw --version这是本地版本不经过模型。要验证模型连通用对话命令发一句简单的话观察是否正常返回。如果返回内容里出现模型回复说明 Base URL、Key、Model ID 三件套都对了。如果报 401是 Key 问题报连接失败是 Base URL 或网络问题报reading choices多半是 Model ID 写错或服务返回结构不匹配。关闭 OpenClaw 很简单在运行 gateway 的终端里按CtrlC即可退出。想后台跑可以用nohup openclaw gateway 但调试阶段建议前台跑方便看日志。验证通过后你的 OpenClaw 基础环境就算真正跑通了。接下来可以按需接工具、接消息通道或者把模型换成你常用的服务。5. 常见报错排查401、local proxy failed、reading choices、OAuth装和跑的过程中报错基本集中在几类。我按真实遇到的顺序列一下方便你对照。第一类401 Unauthorized。这是 API Key 不对或没带上。检查三件事Key 是否复制完整前后别带空格、Base URL 是否写成了带/v1或其他后缀的错误形式、请求头里的认证字段是否符合服务商要求。用 TaoToken 的话Key 在 API Keys 页面生成Base URL 用https://taotoken.net/api别自己拼路径。第二类local proxy failed或连接超时。这通常是 Base URL 填错、端口不通或者本地网络策略拦截。先在终端里curl一下你的 Base URL看能不能通。WSL2 用户如果访问外部服务正常但访问 localhost 服务异常检查是不是服务没起来或端口被占。第三类reading choices或返回结构解析失败。这几乎都是 Model ID 写错或者你用的服务返回格式和 OpenAI 协议不一致。确认 Model ID 拼写确认服务商是否兼容 OpenAI 的/chat/completions结构。换模型时尤其容易出这个错。第四类OAuth 相关报错。如果你在接某些需要 OAuth 的通道比如飞书报 OAuth 失败一般是回调地址、应用权限或 token 过期问题。基础环境阶段可以先跳过这些通道不影响 OpenClaw 本体运行。第五类安装脚本跑完但openclaw命令找不到。这是 PATH 没生效source ~/.bashrc或重开终端。如果还不行检查安装脚本把二进制放到了哪个目录手动加进 PATH。第六类SSH 远程安装中途断开。安装阶段没有进度输出长时间无操作会被 SSH 踢掉。解决办法是定时敲回车或者用tmux挂一个会话再跑安装断开也不影响。排查的核心思路就一条先分清是「本地环境问题」还是「模型服务问题」。本地问题看命令是否存在、端口是否监听、依赖是否齐全服务问题看 Key、Base URL、Model ID 三件套。分清了定位就快。6. 跑通之后把 OpenClaw 接上你的模型与后续步骤基础环境跑通只是起点。接下来你可以做几件事把模型换成你日常用的服务接上工具或消息通道或者把 OpenClaw 当成一个本地 Agent 网关长期跑。如果你还没定模型入口可以先用 TaoToken 的模型对话页试一下请求是否通确认 Key 和 Base URL 没问题再填进 OpenClaw 配置。API Key 在控制台的 API Keys 页面生成接入细节看接入文档。想长期跑编码类或 Agent 类任务可以了解下 Coding Plan适合需要稳定调用额度的场景。最后留一个实用习惯每次改完配置先openclaw --version确认命令在再openclaw gateway前台启动看日志确认端口监听后再去浏览器验证。三步走完基本不会出现「不知道装没装上」的情况。环境这东西跑通一次后面就顺了。