很多人第一次接触 OpenClaw 这个项目时大概率都是被又要装 Node.js这一步给劝退的。明明只是想在本机跑一个能对接本地大模型、能执行任务的 AI 代理结果光是把 Node 环境理顺就得花掉半天版本不对报错、npm 依赖装不上、装到一半发现系统里还有旧的 node 在捣乱。我当初踩这些坑时也一度想放弃。但后来我发现OpenClaw 的本地部署其实有完全绕开 Node 的路径而且按照正确顺序操作成功率高到离谱。这篇指南就是围绕不装 Node、100% 成功这个目标来写的把从环境检测到最终跑起 OpenClaw 的每一步都拆开讲透适合被 Node 折腾过的人也适合刚入坑本地 AI 的小白直接照抄作业。1. 为什么部署 OpenClaw 总卡在 Node 上先聊点背景。OpenClaw 这类 AI 代理框架本质上是把大模型对话、工具调用、任务执行这些能力打包成一个可以常驻后台的服务。它本身依赖 JavaScript/TypeScript 生态所以正常情况下需要宿主机提供 Node.js 运行时。但 Node 恰恰是本地部署里最容易翻车的环节版本乱、安装残留、npm 网络问题、node-gyp 编译失败每一个都能让部署进度直接卡死。1.1 传统部署方式有哪些隐藏的坑市面上大多数人会选择先装 Node.js再克隆 OpenClaw 代码仓库最后用 npm 安装依赖并启动。这套流程本身没什么问题问题全出在环境差异上。比如很多人的电脑里已经装了某个旧版本的 Node而 OpenClaw 某个子模块要求 Node 18 以上两个版本冲突后你会看到一堆莫名其妙的崩溃日志但日志里根本不会直接告诉你是版本不匹配。更麻烦的是 npm 依赖安装。有些依赖包需要从 GitHub 拉取二进制文件有些需要本地编译只要网络稍有波动或者缺少 C 构建工具安装就会中断。市面上流传的升级 Node 版本用 nvm 切换版本给 npm 配镜像其实都是在做环境修补对新手来说每一个都是新坑。还有常见的一个场景通过 SSH 连到服务器上部署结果连接一断node 服务也跟着停了这又是另一个层面的事故。1.2 容器化部署为什么能彻底绕开 Node无需 Node并不是说 OpenClaw 不需要 Node 运行时而是说宿主机的操作系统不需要感知 Node 的存在。实现方式就是容器化官方或社区维护者把 Node.js 运行时、项目依赖、启动脚本全部打进了一个 Docker 镜像里。你只需要有 Docker 环境拉镜像、跑容器Node 就被封装在镜像内部跟你本机完全隔离。用容器化还有一个额外的好处版本是固化在镜像里的。你不需要关心 Node 高版本能不能兼容低版本、npm 全局配置对不对、环境变量有没有残留因为这些在镜像里都是确定不变的。就好比你以前要自己攒机箱、装系统、配驱动现在直接买一个品牌整机通电就能用。部署失败率自然大幅下降。2. 部署前的环境准备想做到 100% 成功前置环境必须干净。以 Windows 电脑为例最稳妥的组合是 WSL2 Docker Desktop Ollama。如果你用 Linux 或 macOS思路完全一样只是少了 WSL2 这一步。下面我按 Windows 的顺序讲过程中会说明每一步的目的方便你判断哪些是必须的。2.1 先检查 WSL2 环境别急着装 Docker很多人在 Windows 上装 Docker Desktop 失败十有八九是 WSL 没配对。WSL 是 Windows 上跑 Linux 子系统的功能Docker Desktop 的 Windows 版默认就是靠 WSL2 来承载 Linux 容器。OpenClaw 的镜像基本都是 Linux 镜像所以必须确认 WSL2 可用。检查方式很简单打开 PowerShell 运行wsl --status wsl --list --verbose第一条返回的信息里会明确写着默认版本: 2或者Default Version: 2这说明 WSL2 正常。第二条会列出你本机安装的 Linux 发行版如果你之前装了 Ubuntu这里就能看到它的状态。如果 wsl --status 报错或者提示环境不完整那就得先去启用虚拟化平台相关功能。启用方法在 PowerShell 里用管理员身份运行下面两条命令然后重启电脑dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart注意很多教程让你直接去微软商店下载 WSL但如果你的系统版本比较老商店版可能装不上。最稳的办法是先确认 Windows 版本号大于 2004然后用上面的命令启用功能重启后再用商店装一个 Ubuntu 发行版。2.2 安装 Docker Desktop 并设置 WSL2 后端Docker 安装包可以从官网下载安装时不需要额外勾选默认选项即可。装完后打开 Settings在 General 里确认Use the WSL 2 based engine是勾选状态。然后在 Resources - WSL Integration 里把你要用的 Linux 发行版比如 Ubuntu开关打开。这一步的目的是让 Docker 命令能直接在 WSL 里跑同时让 Windows 和 WSL 之间共享 Docker 引擎。安装完 Docker 后先跑一个测试命令确保引擎正常docker --version docker run hello-world如果 hello-world 能正常拉镜像并打印欢迎信息说明 Docker 环境没问题后面装 OpenClaw 就不会卡在基础设施上。2.3 安装 Ollama准备本地大模型OpenClaw 本身不带模型权重它需要一个推理后端来提供大模型能力。Ollama 是目前最省事的本地模型管理工具一条命令就能拉模型、启动 API 服务。下载对应系统的安装包装上就好Windows 版装完会自动在后台运行服务默认监听 11434 端口。然后拉一个适合你硬件的模型。比如显存在 8GB 左右的可以直接拉 7B 参数级别的模型ollama pull qwen2.5:7b ollama pull deepseek-r1:7b这两个模型在中文指令和理解能力上表现都还行跑在本地也够用。拉完可以直接在终端里聊天试一下ollama run qwen2.5:7b能正常对话说明模型已经准备就绪。后面 OpenClaw 会通过 HTTP 调用 Ollama 的接口就像调用一个远程大模型 API 一样。2.4 目录规划与端口规划在开始拉镜像之前先想清楚两个事情数据目录放哪里、端口用哪些。OpenClaw 在运行过程中会产生配置、日志、技能文件等数据这些数据应该通过 Docker 的卷映射挂载到宿主机。我一般会在本机建一个专门目录比如D:\openclaw-dataWindows 下映射到容器的/data。这样后面想备份或者迁移直接拷贝这个目录就行。端口方面OpenClaw 默认会开一个 Web 管理界面具体端口根据你使用的版本略有不同一般用 3000 或 8080 的比较多。如果本机这两个端口被其他服务占用了可以改成 3100 或者其他空闲端口。为了避免后期混淆我建议在部署前就用命令排查一下占用情况netstat -ano | findstr 3000 8080 11434有输出就说明端口被占用换一个即可。11434 是 Ollama 的服务端口这个不用改后面配置里要专门指向它。3. 核心实操三步完成 OpenClaw 部署环境准备完毕进入正题。整个过程分成三步写 compose 文件、启动容器、进入容器完成初始化配置。全程我们不会在宿主机上执行 node、npm、nvm 中的任何一个命令。3.1 第一步编写 docker-compose.yml我在实际部署中用的是 Docker Compose 来管理容器因为一个up命令就能完成拉镜像、建网络、挂卷、启动的全部工作后面重启也方便。在刚才建好的数据目录下新建一个文件命名为docker-compose.yml写入以下内容version: 3 services: openclaw: image: ghcr.io/openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 3000:3000 volumes: - ./data:/data environment: - OLLAMA_HOSThttp://host.docker.internal:11434 extra_hosts: - host.docker.internal:host-gateway逐项解释一下image用的是 GitHub Container Registry 上的官方镜像latest 标签跟随最新稳定版restart: unless-stopped保证容器在系统重启或异常掉线后能自动拉起来ports把容器内的 3000 端口映射到宿主机volumes把当前目录下的data子目录映射为容器里的/data最关键的是OLLAMA_HOST环境变量我把它指向了host.docker.internal这个地址在 Docker 容器内代表宿主机。为什么要用host.docker.internal因为 OpenClaw 跑在容器里Ollama 跑在宿主机上容器内直接访问localhost:11434访问到的是容器自己不是你的宿主机。使用host.docker.internal加上extra_hosts里的host-gateway映射就能让容器稳定地找到宿主机的 Ollama 服务。这一步容易漏漏了之后 OpenClaw 能启动但连不上模型报错还很不直观。3.2 第二步启动容器并确认运行状态在 docker-compose.yml 所在目录打开终端Windows 上建议直接在当前目录打开 PowerShell或者用 VSCode 集成终端执行docker compose up -d第一次执行会拉取镜像根据网络情况可能需要几分钟。看到输出里出现Started或者Running字样就说明容器起来了。接着验证一下容器状态和日志docker ps docker logs --tail 100 openclawdocker ps结果里应该能看到名为openclaw的容器状态是 Up。日志里如果出现 OpenClaw 的标志输出、监听地址之类的内容就说明服务已经在跑。注意这一步完全没有任何 Node 相关的操作。你不需要下载 node 安装包、不需要配置 PATH、不需要跑 npm install。镜像内部已经把 Node 运行时和依赖全部准备好了你只负责告诉 Docker 把哪个镜像跑起来。3.3 第三步进入容器完成首次初始化容器启动后OpenClaw 会在/data目录下生成默认配置文件。我们需要进入容器内部用它的管理命令完成对 Ollama 的对接和账号初始化。Windows 的 PowerShell 里执行docker exec -it openclaw bash进去之后你会看到一个 Linux 的 shell此时才需要用一些命令行操作。先看一下默认生成的文件结构ls -la /data正常情况下能看到config.yaml或类似命名的配置文件。然后用自带的 CLI 工具完成初始化。不同版本命令格式可能略有差异但大致是这样openclaw init openclaw model add ollama --base-url http://host.docker.internal:11434 --model qwen2.5:7b openclaw service start第一条命令会创建默认配置和管理员账号第二条命令把 Ollama 里的模型注册为可用模型第三条启动内部服务。每一步执行后如果有success或者ok字样就说明成功了。执行完这些再回到 Windows 浏览器里访问http://localhost:3000能看到 OpenClaw 的 Web 界面就算彻底跑通了。首次登录用init时设置的管理员账号和密码。3.4 补充说明为什么我用 Compose 而不是直接 docker run有人可能觉得绕直接docker run一条命令不更简单我试过但 Compose 的好处是设计上的稳定配置是声明式的、写在文件里不需要每次启动都翻历史命令。而且docker-compose.yml就是你的部署说明书换一台机器拷过去docker compose up -d就能复现整个环境这才是真正做到100% 成功的关键。相比之下docker run这种命令式做法参数一多就容易漏漏一个映射或环境变量后面排查起来要比写文件麻烦得多。4. 对接 Ollama让 OpenClaw 真正用上本地模型容器起来只是第一步OpenClaw 要想真正对话、执行任务必须把本地模型配置好。这个环节最容易出的问题就是地址写错导致界面显示模型连接失败。当你完成 3.3 节的初始化后Ollama 对接基本已经完成我再补充一些细节因为实际使用中你会遇到模型切换、上下文长度、并发对话这些调优需求。4.1 Ollama 跨容器访问的正确姿势OpenClaw 容器内访问宿主机 Ollama 的关键是地址。Ollama 默认只监听127.0.0.1:11434也就是只有宿主机自己能访问。如果 Windows 防火墙把 11434 端口卡住了容器里的请求同样会被拦下来。我遇到过好几次类似情况表现就是 OpenClaw 日志里出现连接超时但本地浏览器里访问 Ollama 却完全正常。解决办法是两步第一在 Ollama 的启动环境变量里加上OLLAMA_HOST0.0.0.0:11434让服务监听所有网卡第二在 Windows 防火墙里放行 11434 端口。如果你平时用 Windows 桌面版 Ollama设置方法是在系统托盘找到 Ollama 图标退出后在环境变量里加上这一项再重新启动。用 WSL 里跑 Ollama 的用户直接在启动命令前加上OLLAMA_HOST0.0.0.0:11434 ollama serve我这里补充一句host.docker.internal在 Docker Desktop 的 WSL2 模式下天然可用所以上面 yml 里extra_hosts那行在大多数场景下是防御性写法但别删因为某些老版本 Docker 或者 Linux 服务器上确实需要这一行才能解析。4.2 模型配置与参数调优OpenClaw 里模型是按名称 服务地址 参数管理的。对话时它会把当前会话的消息按 OpenAI 兼容格式封装后发给 Ollama所以理论上 Ollama 上挂的任何模型都能用。不同模型对参数要求不太一样常用的是覆盖上下文长度和请求超时时间。我自己常用的模型配置参考如下模型参数规模适合任务建议上下文长度备注qwen2.5:7b7B通用对话、工具调用8192中文能力均衡8GB 显存可跑量化版deepseek-r1:7b7B推理分析类任务4096推理链强速度略慢llama3.1:8b8B英文任务、代码生成4096英文表现好中文一般在 OpenClaw 的界面里或者配置文件中找到模型设置项把context_window设为 8192timeout设为 300 秒。超时时间别设太短本地大模型在没有 GPU 加速的纯 CPU 环境下生成长回答可能超过 120 秒设短了经常看到请求超时的红色报错。显存不够的用户可以用 Ollama 的量化版模型。比如 7B 模型的 4bit 量化版本ollama pull qwen2.5:7b-q4_K_M大概占用 4GB 显存普通游戏本都能跑。我在这台显卡一般的老机器上实测对话响应速度在 10 到 20 token 每秒体感和云端小模型差不多完全能日常用。4.3 用最小化对话测试验证整个链路配置完不要急着搞复杂的 skill 和工具链先做一次最小的冒烟测试。在 OpenClaw 的对话界面里输入一句简单的指令比如你好介绍一下你自己。正常流程是OpenClaw 收到消息 - 封装成 API 请求 - 通过host.docker.internal转发到宿主机 Ollama - Ollama 加载模型推理 - 返回文本 - 对话界面展示。整个过程里任一环节出问题界面上基本都有对应提示。如果是模型都找不到检查模型名是否写对如果是超时检查 timeout 配置如果是一连串连接错误先回到 PowerShell 里用docker exec openclaw curl http://host.docker.internal:11434/api/tags测一下容器内到 Ollama 的通路是否顺畅。这一步一定要有耐心。我第一次部署时就是卡在看起来全配好了但就是不回复后来用 curl 一测才发现是防火墙没放行 11434 端口白白排查了两个小时。5. 常见问题与排查技巧实录部署到这其实已经比大多数教程多走了一层完整链路。但本地部署没有一帆风顺的我把最常碰到的问题按频率列出来每个都附上我实际排查的思路你可以把这一节当成速查表遇到啥翻啥。5.1 WSL2 环境报错与修复现象运行wsl --status时提示无法安全验证 sl2 环境或者直接报错说未安装 WSL。这个我见过不少次了通常是因为系统版本较老、或者之前用过旧版 WSL 留下了残留。解决办法是彻底重装一次先在 PowerShell 管理员模式里执行wsl --shutdown wsl --unregister Ubuntu然后执行wsl --install这个命令会自动启用所需功能并安装新版的 WSL 内核。装完重启电脑再跑一次wsl --status看到默认版本: 2就干净了。如果wsl --install报错也可以从微软官网手动下载 WSL2 内核更新包安装后再回来执行上面的状态检查。5.2 Docker 镜像拉取和 metadata 加载错误现象执行docker compose up时出现类似error [keep-frontend-dev internal] load metadata for docker.io/library/node:这样的错误。这个报错看着吓人其实就是拉取镜像时源站不稳定Docker 引擎在获取镜像 metadata 阶段失败了。解决办法是给 Docker 配置国内可用的镜像加速器。打开 Docker Desktop Settings - Docker Engine在 registry-mirrors 里填入你所在网络环境可用的加速地址保存并重启 Docker 引擎。更大的坑是这一步失败会诱导很多人去升级 Node 或修复 npm但你看报错里关键的docker.io/library/node它是镜像路径是容器构建时在拉取基础镜像跟本机 Node 环境没有一丝关系。千万别被报错带到沟里去。5.3 端口被占用与服务反复重启现象容器启动了但无法访问localhost:3000docker logs里看到地址被占用的错误。如果你之前跑过别的 Web 服务3000 很容易被占。解决方案有两个一是改 OpenClaw 的对外端口把 compose 文件里的3000:3000改成3100:3000二是用docker ps -a看看是不是有同名容器在占用端口如果有旧的 openclaw 容器docker rm -f openclaw删掉再docker compose up -d。这里有个心得很多容器反复重启不是因为软件坏而是端口冲突或卷目录权限问题。出现反复重启时先看最后两行日志别急着重装。5.4 磁盘空间和资源不足现象容器启动后一会儿就挂了日志里出现node was low on resource: ephemeral-storage之类的内容。这个报错明确告诉你容器所在的磁盘空间或者临时存储快满了。本地大模型部署最容易被低估的就是磁盘占用量。Docker 镜像、模型文件、日志文件堆在一起轻松上 20GB。处理思路是清理 Docker 的构建缓存和悬空镜像docker system prune -a --volumes在 Windows 上还要注意 WSL2 的虚拟磁盘文件ext4.vhdx会自动膨胀清理完 Docker 之后最好再用wsl --shutdown停一下 WSL然后执行wsl --manage Ubuntu --set-sparse true可以把这个虚拟磁盘标记为稀疏文件让它在删除文件后自动缩减占用空间。这个操作对长期本地跑大模型的人非常实用。5.5 SSH 断开后服务停止的问题现象你通过 SSH 远程连接到服务器部署一切正常一旦 SSH 会话断开OpenClaw 也跟着停了。这个问题根源在于启动服务时被挂在了 SSH 会话的进程树下。解决办法就是在 compose 文件里设置restart: unless-stopped我 3.1 节的模板里已经写了同时让容器由 Docker 守护进程托管。Docker 的守护进程在系统里是独立常驻的不依赖你的 SSH 会话。如果你是在 WSL 里启动 Docker 而不是用 Docker Desktop还要注意 WSL 本身会不会在会话结束后自动关闭。我的做法是把 Ubuntu 的 WSL 配置里加一行[automount] enabled true并且在 WSL 里把 Docker 服务设为开机自启sudo systemctl enable docker sudo systemctl start docker这样只要 Windows 开机WSL 里 Docker 服务就会跟着起来容器也会自动恢复。6. 一些我觉得值得说明的实践心得写到最后分享几个我反复试验后沉淀下来的体会不一定写进传统教程里但实际帮了我很大忙。第一不要在一台机器上既用 nvm 又手动装 Node 还装了一堆全局 npm 包。部署 OpenClaw 时确实可以完全不碰它们但如果之前环境已经混乱Docker 不会受影响因为容器是隔离的。反过来讲这也正是无需 Node这条路的最大价值它不关心你的宿主机有多乱只要 Docker 能跑OpenClaw 就能跑。第二日志是第一排查工具。每次修改配置后我最先做的永远是docker logs --tail 50 openclaw。看到日志里出现connect ECONNREFUSED 127.0.0.1:11434你就知道是容器内地址写错了看到model not found就知道是 Ollama 没拉对应模型。日志里的关键字比任何报错弹窗都诚实。第三尽量固定镜像版本。最开始我一直用latest标签图省事结果某次更新后界面和配置文件格式全变了。现在我的 compose 文件里写的是具体的版本号比如ghcr.io/openclaw/openclaw:0.6.2。如果想升级手动改版本号再docker compose up -d万一出问题还能秒回退到旧版本。最后再补充一个我踩过的小坑Windows 防火墙在 Docker 网络上的拦截行为有时很隐蔽。如果你确认所有配置都对、容器内 curl 也通但外部就是连不上可以暂时把 Docker 相关的网络从防火墙的阻止列表里移除试试。很多玄学问题到最后其实都是这个原因。这套部署方案我前前后后给三台不同配置的电脑装过从 AMD 老台式机到 WSL2 环境复杂的开发本没有一次需要手动安装 Node。只要前置环境检测做扎实剩下的容器化操作基本就是复制粘贴多一点耐心看日志100% 成功不是口号是流程设计的结果。希望这篇记录能帮你少走我已经走过的弯路。