如果最近你在刷技术社区多少会看到 OpenClaw 和“部署”这两个词频繁出现在 agent 框架、自动化工作流的帖子里。我第一次看到“5分钟部署 OpenClaw”这个标题时下意识以为又是某个换皮机器人框架的营销话术等到我把源码、文档和几个实际场景完整跑过一遍才发现值得聊的点并不在“几分钟能装完”而在于它把模型调度、技能体系和跨端连接组装成了一个可以自己掌控的开源运行环境。这篇文章不打算念官方 README而是把我从第一次跑通到踩坑修复的全过程整理出来。你不需要会 C也不用先啃一遍论文只要机器上能装 Node.js、能起 WSL 或者 Docker照着下面的顺序操作大概率能在半小时内把 OpenClaw 从零跑到能正常对话。适合三类人想在本地拥有一个可控 AI 助手的人、想研究 agent 工作流的同学以及想在企业内网或云端跑自动化任务的工程师。对小白我说得尽量直白对老手可以直接跳着看“坑”的部分。1. 先把 OpenClaw 拆清楚它到底解决什么问题1.1 OpenClaw 是什么适合谁用OpenClaw 本质上是一个可自托管的智能体运行时核心由三部分组成任务入口、模型路由、技能执行。任务入口负责接收来自 Windows 客户端、移动端、Webhook 的请求模型路由决定这条请求交给云端 API 还是本地模型处理技能执行则把模型的意图转化为具体操作比如读文件、跑命令、查日志、发消息。它跟常见的“机器人框架”最大的区别是OpenClaw 把“大脑”和“手脚”拆开了。大脑是各种大模型你可以随时切换手脚是技能目录里一个个独立模块可以按需新增。这种设计带来的直接好处是今天用本地便宜的 3B 模型跑日常明天换更强的 API 模型处理复杂任务底层任务流程不用大改。从我实际使用的角度看它解决了两个具体问题——本地数据不出内网、想跑自动化任务但不想被某个平台锁定。1.2 部署形态与算力路线API 还是本地模型很多人在开始之前会纠结一个点OpenClaw 是不是只能用 API 接入算力答案是否定的。它的配置思路里同时支持两条路线一条是直接调用 DeepSeek、OpenAI 等云端的 API另一条是接 Ollama、vLLM 这类本地推理服务。实际部署时我强烈建议先准备一条 API 用来保底同时把本地模型也配置好这样即使云端接口出问题OpenClaw 还能退到本地继续工作。至于部署形态从轻到重有三种常见选择第一种是单机裸跑Windows 下开 WSL2核心服务跑在 Linux 环境里适合个人折腾第二种是用 Docker 容器跑环境隔离最干净卸载也彻底第三种是企业内网或云主机部署一般要配合私有模型服务后面我会单独讲。新手第一次验证我推荐第一种成本最低出问题也容易定位。2. Windows 环境准备WSL2、Node.js 与安装 OpenClaw2.1 前置依赖WSL2、Node.js 与仓库拉取所谓 5 分钟部署前提是依赖已经装好否则光装环境就能折腾一晚上。在 Windows 上跑 OpenClaw最省心的路径是先把核心服务放进 WSL2。为什么不是直接在 Windows 里跑因为大部分运行依赖命令、路径处理和技能脚本都是按 Linux 写的Windows 裸跑经常会遇到路径分隔符、权限模型不一致的问题。WSL2 可以理解成 Windows 里的轻量虚拟机和宿主机共享文件系统但拥有完整的 Linux 内核这是目前最接近生产环境的本地模拟。具体步骤如下打开 PowerShell管理员模式执行# 首次安装 WSL2 和默认发行版 wsl --install # 查看当前 WSL 状态和版本 wsl --status wsl -l -v然后打开 WSL 终端安装基础工具和 Node.jssudo apt update sudo apt install -y git curl build-essential # 安装 Node.js 18 或 20建议用 nvm 管理版本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 node -v npm -v我踩过的第一个坑就在这里直接用系统 apt 装的 Node.js 版本往往太老OpenClaw 的依赖包对异步 API 要求高老版本 Node 会莫名报语法错误。用 nvm 装 20 系是最稳的选择。2.2 绕过“无法安全验证”报错WSL 状态检查与版本对齐如果你在 PowerShell 里运行wsl --status看到类似“无法安全验证”的提示先别急着重装。这个报错按我的经验九成是三类问题之一。第一类是 Windows 功能没有完全启用。检查“控制面板-启用或关闭 Windows 功能”里的“适用于 Linux 的 Windows 子系统”和“虚拟机平台”是否勾选没勾就勾上重启。第二类是内核太旧。直接在 PowerShell 里执行wsl --update把内核更新到最新再重新启动 WSL。第三类是系统时间不对。WSL 在初始化某些安全验证时会依赖本机的时间校验如果系统时间差太多就会出现“无法安全验证”这种看起来莫名其妙的问题。建议先同步一次系统时间再执行wsl --shutdown重启 WSL。如果实在修不好还有一个偏方从微软官网下载 WSL2 内核更新包手动安装然后确保默认版本是 2。wsl --set-default-version 2我自己的经验是Win11 上几乎不会遇到这个问题Win10 老版本出现概率极高。遇到也不用心烦按上面的顺序排查十分钟内能解决。2.3 Windows Companion 的作用与配置搜索热词里出现了“openclaw windows companion 怎么配置”很多人看到“Companion”以为是核心程序其实它只是一个桌面壳层用来展示会话、输入指令和查看任务状态。真正干活的进程在 WSL 或 Docker 里。首次启动 Companion 后需要在配置界面填入核心服务的地址默认一般是http://localhost:端口。新版 WSL2 默认支持 localhost 回环你在 WSL 里启动的服务可以直接被 Windows 访问。如果 Companion 一直提示连不上几个常见原因WSL 里的核心进程根本没起来端口被 Windows 防火墙拦截或者你在 WSL 里监听的是0.0.0.0之外的地址。排查时先到 WSL 里看进程是否活着再在 Windows 里执行netstat -ano | findstr 端口号看看端口有没有监听。3. 服务启动与首次运行让 OpenClaw 真正开口说话3.1 初始化配置模型路由与 skill 目录环境准备好之后把仓库克隆到本地。注意不同版本的初始化命令可能有差异务必以官方 README 的最新写法为准我这里描述的是通用流程。git clone 官方仓库地址 cd openclaw npm install初始化之后OpenClaw 通常会在用户目录下生成一个配置目录比如~/.openclaw/里面有核心的配置文件。配置里最关键的三个字段是模型提供商、模型名称、API 地址。我习惯先把这份配置理解成“电话簿”OpenClaw 是接线员技能是分机模型是背后的客服人员。接线员需要知道该打哪个电话、向谁提问。一个极简的 JSON 风格配置大致长这样{ model: { provider: ollama, base_url: http://localhost:11434, model_name: qwen2.5:3b, api_key: ollama }, skills_dir: ./skills, listen_host: 0.0.0.0, listen_port: 3456 }skills_dir指向技能目录OpenClaw 启动时会扫描这个目录下所有符合规范的技能包。每个技能包用单独的文件夹组织文件夹里至少有一个描述文件和一个可执行脚本。描述文件告诉模型“这个技能是干什么的、什么时候触发、需要哪些参数”可执行脚本负责真正干活。3.2 接入本地模型Ollama 与 Qwen2.5-3b 的实战热词里反复出现“ollama部署openclaw”“qwen2.5-3b 关联到openclaw”本地模型这块确实是最常见的玩法。推荐先装 Ollama它把模型管理做成了跟 Docker 一样的拉取模式对新手非常友好。在 WSL 或 Linux 终端里执行curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:3b下载完成后先用一个简单的调用来验证模型服务是否正常curl http://localhost:11434/api/generate -d {model:qwen2.5:3b,prompt:你好简单自我介绍}能返回内容就说明 Ollama 这一层 OK。然后把 OpenClaw 配置里的provider设为ollamabase_url填http://localhost:11434模型名填qwen2.5:3b。重启核心服务后在客户端里发一句测试消息只要模型能正常回你就说明路由成功。这里想多说一句3B 模型跑中文日常对话完全没问题但在复杂工具调用上明显吃力。我的建议是本地至少用 7B 级别起步如果机器只有 16G 内存且没有独立显卡3B 这个档次作为体验入口还好但别指望它能稳定地玩多步 agent 任务。3.3 API 方式接入云端算力DeepSeek 等配置要点如果你没有显卡或者本地模型响应太慢API 路线是更实际的选择。配置逻辑和本地模型几乎一样只是把地址换成了云端服务的接口。以 DeepSeek 为例先在开放平台拿到 API Key然后在配置里填{ model: { provider: openai-compatible, base_url: https://api.deepseek.com/v1, model_name: deepseek-chat, api_key: sk-你的密钥 } }很多以“openai-compatible”方式接入的模型OpenClaw 都可以直接兼容。核心技巧就一条先单独用 curl 测试 API 是否通再检查 OpenClaw 的日志不要一上来就怀疑是 OpenClaw 自己出了问题。密钥千万不要明文写进仓库或配置文件我有一个折中的习惯本地开发用.env文件生产环境用系统环境变量。3.4 让第一个 skill 跑起来配置完成只是开始OpenClaw 真正好用起来要靠技能。拿一个最简单的场景举例把某个目录下的临时文件按日期整理到对应的文件夹。在 skills 目录下新建file_organizer文件夹里面放两个文件一个描述文件一个 Python 脚本。描述文件可以写成这样name: file_organizer description: 整理指定目录中的临时文件按修改日期归档到子目录 trigger: 当用户提到整理文件、归档、按日期分类时触发 parameters: - name: directory required: true description: 需要整理的目标目录脚本就用 Python 写一个按月份归档的逻辑。OpenClaw 启动时会扫描这些描述把“技能说明”塞进模型的系统提示里模型在对话中发现匹配意图就会调用对应的脚本。我第一次跑通时最大的感悟是技能的描述质量决定了模型能不能正确触发描述写得太含糊模型宁可自己硬答也不会调用工具。所以别急着堆几十个技能先把两三个技能的描述打磨清楚体验会完全不一样。4. 常见问题排查与避坑实录4.1 WSL 相关报错速查我把这段时间遇到频率最高的几个 WSL 报错整理成了一张表方便你直接对照报错现象常见原因解决办法wsl --status无法安全验证Windows 功能未全部开启 / 内核太旧 / 系统时间错误检查可选功能、运行wsl --update、同步时间后wsl --shutdownWslRegisterDistro failed with error: 0x80070050发行版名称冲突或残留注册表用wsl --unregister清掉旧发行版后重装vmmem内存占用过大WSL2 会动态占内存且不自动归还在.wslconfig里设置memory4GB限制在 WSL 里启动服务Windows 访问不到监听地址不是 0.0.0.0 或防火墙拦截监听地址改成 0.0.0.0检查 Windows Defender 防火墙入站规则这里有一个很反直觉的坑WSL2 的内存回收机制很“佛系”你跑过一次模型推理vmmem可能一直占用几个 G 不释放。解法是在用户目录下创建.wslconfig文件把内存上限写死[wsl2] memory4GB swap8GB4.2 网络与安装失败问题我第一次执行npm install的时候就遇到了依赖下载超时。这种问题在国内网络环境下几乎是必经之路解法也简单把 npm 源切到国内镜像npm config set registry https://registry.npmmirror.comPython 技能依赖同理用pip config set global.index-url切换镜像。下载大模型的时候如果 Ollama 拉取慢可以设置镜像源参数或者干脆换用支持断点续传的下载工具先把模型文件拉下来再导入 Ollama。还有一个小提醒如果下载中途断掉别反复重试同一个命令先看磁盘空间是否充足很多“下载失败”其实是根目录满了。4.3 运行期崩溃、内存与端口问题核心服务起来之后崩溃大概率来自两处一是 Node 进程被系统杀掉二是技能脚本抛出异常。定位方法很直接看日志。OpenClaw 的日志一般输出在~/.openclaw/logs/或终端控制台看到SyntaxError就回头查 Node 版本看到EADDRINUSE就是端口被占。端口被占是新手最容易一头雾水的问题。比如你明明配置了listen_port: 3456启动却提示端口占用。先用下面的命令找出是谁占用了端口# Linux / WSL sudo lsof -i :3456 # Windows netstat -ano | findstr 3456确认是残留进程后清理掉再启动别图省事直接改端口改端口只能绕过问题本身。内存不足方面如果是 Ollama 和 OpenClaw 同时跑在同一台 8G 机器上我建议只保留 3B 模型常驻内存用完就ollama stop。4.4 手机端/安卓 Termux 部署的坑搜索热词里“如何用 termux 安装 openclaw 手机版下载步骤”出现频率很高我也实际试过在 Termux 里部署。Termux 相当于安卓上的 Linux 终端环境流程是安装 Termux 后执行pkg update再安装 nodejs、git、python克隆仓库然后和 Linux 上一样启动。但说实话手机端部署我只能给及格分。最大的问题是安卓系统本身的后台限制锁屏几分钟后进程就可能被系统回收网络连接也经常断。如果只是想在手机上远程操作家里的 OpenClaw更推荐的做法是核心服务跑在服务器或电脑上手机上装客户端或直接用浏览器访问而不是把服务端也压在手机里。手机端的意义更多是“应急测试”和“跑通流程”长时间无人值守还是交给 Linux 服务器更靠谱。5. 进阶场景内网私有化、Docker 与云端部署5.1 企业内网部署私有化模型与技能沙箱企业场景下最常听到的两类诉求是“模型不出内网”和“技能执行要有边界”。模型不出内网通常要把推理服务也私有化常见组合是 vLLM 或 Ollama 起一个内网模型服务OpenClaw 通过内网地址接入。部署时注意几个点模型文件要提前下发到内网机器别指望部署时现拉内网 npm 和 pip 源提前配好技能脚本要用专门的低权限账号运行不能给 root。“技能执行边界”是我认为更重要的一环。OpenClaw 的技能能执行 shell、读写文件这既是它能干活的原因也是企业合规上最敏感的地方。建议把核心服务跑在隔离的 Docker 容器里用非 root 用户启动文件系统改成只读只挂载必要的数据卷。不要图省事给 agent 一个能访问生产环境的万能密钥这是我见过最危险的操作。5.2 Docker Compose 一键编排如果机器上已经装了 Docker Desktop 或 Linux 上的 Docker用容器编排更干净。一个最简的docker-compose.yml大概长这样version: 3.9 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped environment: - PROVIDERollama - BASE_URLhttp://ollama:11434 - MODEL_NAMEqwen2.5:7b - SKILLS_DIR/skills volumes: - ./skills:/skills - ./data:/data ports: - 3456:3456 depends_on: - ollama ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped volumes: - ollama_data:/root/.ollama volumes: ollama_data:注意镜像名和字段名会随版本变化这里只是常用写法真正部署时先看官方仓库指定的构建方式。这个编排方案的好处是 OpenClaw 和 Ollama 之间通过容器名互通数据卷把技能和配置外置升级时不丢数据。再强调一次不要在容器里挂载宿主机整盘给最小化挂载技能目录只读更安全。5.3 Railway 云平台部署搜索词里提到 Railway 部署云服务器我也用类似平台做过实验。Railway 这类平台的思路是“用 Git 仓库触发构建”把 OpenClaw 仓库推送上去平台自动安装依赖并启动。操作上需要做的准备在环境变量里配置PROVIDER、BASE_URL、MODEL_NAME、API_KEY然后设定一个公网端口。数据库或持久化存储如果技能需要可以再接平台自带的内置数据库否则存本地文件系统的内容重启会丢这点一定要提前意识到。另外一个实际体验云端实例如果长时间没流量会被平台休眠。OpenClaw 这种需要保持长连接的应用非常依赖保活机制比如让客户端定时发心跳否则一觉醒来你会发现会话已经断了。个人测试问题不大生产使用要有心理准备。5.4 与 Dify 等 LLMOps 工具的简单联动有人会问 OpenClaw 和 Dify 这类工具是什么关系。简单说Dify 更像是一个可视化的 LLM 应用开发平台重点在编排 prompt、知识库、工作流OpenClaw 则更偏“agent 运行时”重点在技能执行和多端接入。两者不冲突典型的做法是把 Dify 发布的 API 作为 OpenClaw 的一个技能来调用或者反过来用 OpenClaw 的事件触发 Dify 的工作流。至于 WorkBuddy 这类产品是不是参考了 OpenClaw我无法替对方回答但从时间线看这类“本地可控 agent 技能扩展”的思路在最近一两年确实集中爆发只能说英雄所见略同。5.5 其他热门关联项目的辨别建议热词里还混着不少项目的名字比如 clawdbot、rosclaw、mineru、dgraph、doris 等。这些有的是 OpenClaw 衍生的机器人项目有的是统计上不太相干的关联项。我建议新入坑的同学先专注官方仓库本体把核心服务跑通后再去看衍生项目否则容易陷入“收藏了几十个仓库一个都没用起来”的状态。我在很多技术群里看到新手同时折腾七八个项目最后全挂在环境上属实可惜。6. 部署完成后的日常维护心得6.1 维护 OpenClaw 的日常清单部署不是终点维护才是日常。我自己的习惯是固定一个更新节奏每周看一次仓库 release 日志确认没有破坏性变更再升级升级前把~/.openclaw和技能目录备份一遍用 Git 管理技能文件夹改动可追溯模型层面如果本地模型换了版本在 OpenClaw 配置里改模型名后一定要重启服务并做一次冒烟测试哪怕只是问一句话。日志管理方面我会定期清掉旧的日志文件避免磁盘被日志塞满。还有一点容易被忽略OpenClaw 如果暴露在公网默认端口不要用常见端口至少把访问加上 Token 鉴权别把测试期“懒得配”的坏习惯带到生产环境。6.2 我给新手的最终建议如果你现在还在“看完这篇马上就想装”的状态我的建议顺序是先在 Windows 上用 WSL2 跑通最简单配置再试着接一个 Ollama 本地模型和一个云端 API然后写一个自己的技能最后才考虑 Docker、内网、手机端这些进阶姿势。前面每一步都踩踏实比一口气上全套要高效得多。最后分享一个小技巧每次改了配置先看日志里有没有新的error或warn再去看模型返回内容多数配置错误在日志阶段就能发现不必反复重启整个环境。