在 Windows 上把 OpenClaw 跑起来说简单也简单说麻烦也麻烦。简单在于它本质上就是一个命令行本地智能体工具装好 Node.js 和 Git 就能跑麻烦在于 Windows 的权限策略、文件签名校验、终端环境跟 Linux 默认行为差得有点远初次上手很容易被“无法安全验证”、“daemon 必须在非管理员终端启动”这类报错搞得一头雾水。这篇文章会把完整的部署过程、模型接入方式、技能扩展思路和典型报错全部拆开讲。内容按可直接复现的顺序来写适合做本地自动化、Agent 工具链、机器人仿真联调的开发者和爱好者参考。如果你只是想快速跑通一个能对话、能替你执行命令的本地助手照着下面的步骤做就行。1. 部署前先把架构想清楚原生运行还是容器隔离1.1 这个项目到底解决什么问题OpenClaw 不是又一个大模型聊天客户端它更像一个“管家程序”你给它一个目标它通过内置的工具去调用终端、读写文件、执行脚本、访问本地模型服务把“想做什么”变成“已经做完”。它和普通自动化的区别在于决策层由大模型驱动而不是一堆写死的 if/else。在 Windows 上部署首先要抓住核心诉求你是想让它跑在日常开发机上还是放进虚拟机/容器里当服务。这个选择决定了后面所有步骤。我的建议是如果是个人电脑使用优先走原生 Windows 安装如果是为了跑 ROS2 仿真、想用 Linux 生态的大量依赖WSL2 或者 Docker 会省事得多。两条路最后都能用但中间卡住的点不一样。1.2 两条路线怎么权衡原生 Windows 路线的优点是启动快、文件路径直接、Ollama 等模型服务可以直接访问 Windows 版且之后的图形化 Companion 配置也更自然。缺点是部分依赖是 Linux 优先的遇到需要编译的 npm 包可能要装 Visual Studio Build Tools。WSL2 或 Docker 路线的好处是环境接近 Linux很多 ROS2、Gazebo 相关的工具链可以一键安装缺点是文件跨盘符访问有性能损耗端口转发偶尔会出怪问题。个人实测下来如果只是做文本类和命令行类任务原生 Windows 完全够用只有当你明确要联动 ROS2 Humble、Gazebo 仿真或者需要大量 Linux 命令工具链时才值得把环境切到 WSL2。下面这张表可以帮你快速决策场景推荐方式原因日常对话、文件整理、脚本执行原生 Windows启动快路径直观配置简单需要稳定的本地模型服务原生 Windows OllamaOllama 有 Windows 版GPU 调用顺畅ROS2/Gazebo 机器人仿真WSL2 或 Docker工具链成熟避免编译地狱公司隔离环境、不想污染宿主机Docker Desktop环境即代码可快速重建2. 基础环境一次性装齐Node、Git 与 Ollama2.1 安装顺序和版本选择先说顺序先装 Git再装 Node.js最后装 Ollama。这个顺序不是因为有什么依赖关系而是方便验证。如果先装 Node 再装 Git后面拉取项目时还要多配一次全局用户信息。Node.js 版本建议直接选 20 或 22 的 LTS 版本不要一味追新。OpenClaw 这类 agent 框架依赖的生态包很多跨大版本 Node 偶尔会出现原生模块编译失败。安装时勾选“Add to PATH”这样后续 npm 命令不用重启电脑就能识别。Git 用默认配置一路下一步即可但有一点要注意安装完成后在 PowerShell 里执行git config --global user.name 你的名字和git config --global user.email 你的邮箱避免后面拉取私有仓库或提交 skill 时提示缺少身份信息。安装完成后打开 PowerShell 分别执行下面三条命令确认环境没问题node -v npm -v git --version正常会依次输出类似 v20.11.1、10.2.4、git version 2.43.0 这样的信息。如果提示“不是内部或外部命令”说明 PATH 没配好重新安装一遍并勾选 PATH 选项就行。提示PowerShell 建议升级到 7.x 版本。Windows 自带的 Windows PowerShell 5.1 在很多命令的解析上和老式 cmd 更接近对一些脚本语法支持不太好升级后能减少很多莫名其妙的坑。2.2 启动 Ollama 服务并准备本地模型Ollama 是本地模型运行时的核心组件。它有 Windows 安装包安装完成后默认监听 11434 端口OpenClaw 通过这个端口调用本地模型跟调用云端 API 的体验几乎一致。启动 Ollama 后在终端里拉取一个适合入门的小模型。Qwen2.5-3B 是个非常稳妥的选择体积不算大中文理解能力强对显存要求也不高。如果只有核显或者纯 CPU跑起来虽然慢一点但不至于卡死。ollama pull qwen2.5:3b等进度条走完执行ollama list能看到模型已经就绪。这里要说明一点本地模型的好处是离线可用、数据不出机器但推理速度和生成质量受硬件限制。真拿来处理复杂任务我还是建议同时配一个云端算力 API 作为备选OpenClaw 支持在配置里切换 provider这样两边的好处都能占到。2.3 几分钟验证基础环境在正式开始配置 OpenClaw 之前要用一条命令确认 Ollama 的服务状态是否可访问curl http://localhost:11434/api/tags如果返回一段包含models字段的 JSON说明服务正常。如果连接失败先确认 Ollama 的托盘图标有没有退出再执行ollama serve手动启动一次观察有没有端口冲突。如果你打算走 WSL2 路线还需要额外执行一次wsl --status确认 WSL 版本、默认发行版都正常。常见的问题是提示“WSL 正在完成升级”或“未安装内核”这时候直接执行wsl --update升级完成后重启终端再用wsl --status看一眼就应该正常了。这个步骤很多人会忽略等跑起来才发现命令执行时报错返工成本更高。3. 安装 OpenClaw 主体与模型链路配置3.1 两种取包方式npm 安装和源码拉取OpenClaw 的安装方式有两种我建议新手直接从 npm 安装发布包稳定省事npm install -g openclaw安装完成后执行openclaw --version能打印版本号就是装好了。这种方式适合只想要稳定版本的用户升级也简单一条npm update -g openclaw就完成了。如果你想要最新特性、或者打算给官方提交 skill 贡献就用源码拉取的方式git clone https://github.com/openclaw/openclaw.git cd openclaw npm install npm run build源码方式的缺点是安装时间长而且开发版可能带着未修复的 bug。实际使用中不建议把开发版直接用于生产场景。至于“node.js 官网下载 openclaw”这个搜索词其实是想从 Node 官网安装 Node.js 之后再用 npm 命令安装 openclaw并没有独立的 openclaw 安装包挂在 Node 官网上第一步装的是运行时而非项目本身。注意无论从哪个渠道下载第一次在 Windows 上双击运行或调用时系统都会弹出“无法安全验证”之类的提示。这不是项目本身有问题而是 Windows 对未知发布者的默认拦截。右键点击文件 → 属性 → 勾选“解除锁定”再重新执行即可。对于命令行方式下载的文件可以在 PowerShell 里先执行Get-Item .\文件名 | Unblock-File解除锁定。3.2 初始化目录和首份配置安装完成后先初始化一个独立的配置目录避免配置散落各处openclaw init这个命令会在C:\Users\你的用户名\.openclaw下生成默认目录结构核心内容如下.openclaw ├── config.yaml ├── data/ ├── logs/ ├── skills/ └── companion/config.yaml是全局配置data存放会话数据logs记录运行日志skills是技能目录companion是后续要和图形界面关联的数据。理解这几个目录的作用非常重要排查问题时可先看日志再改配置而不是乱猜。初始化之后执行一次openclaw doctor如果有这个子命令没有的话就手动检查安装路径、Node 版本和本地模型服务是否可视。这一步很像出门前检查钥匙虽然简单但能省掉后面大量绕路时间。3.3 接入 Qwen2.5-3b 等本地推理模型的完整示例打开config.yaml把模型服务指向本地 Ollama。下面是一份经过验证的最小配置provider: ollama model: qwen2.5:3b base_url: http://localhost:11434 temperature: 0.7 max_tokens: 2048保存后在终端里直接发起一次对话openclaw run 帮我查看当前目录下的文件列表如果一切正常你会看到 OpenClaw 先调用终端命令再把结果返回给模型最终给出一段自然语言总结。这里的核心链路是用户输入 → OpenClaw 解析意图 → 调用 Ollama 获取决策 → 执行工具 → 返回结果。如果你发现模型回复得很慢常见原因是模型正在被首次加载。后续再调用速度会明显提升。要是长期卡顿可以把max_tokens调小或者换一个更小的模型比如qwen2.5:1.5b。3.4 接云端算力 API 的配置模式本地模型适合把零散任务批量处理但复杂逻辑、长文本分析就明显吃力。此时建议配置第二套 provider用环境变量的方式注入密钥避免把密钥写进配置文件再同步到仓库里$env:OPENCLAW_API_KEY你的密钥 $env:OPENCLAW_API_BASEhttps://api.example.com/v1然后在config.yaml中把 provider 切换成apiprovider: api model: qwen-plus base_url: ${OPENCLAW_API_BASE} api_key: ${OPENCLAW_API_KEY}这种做法的好处是你不需要改代码只要切换 provider 字段就能在本地模型和云端算力之间来回更换。我平时会把简单任务交给本地模型复杂任务手动切到 API 模式成本和体验兼顾。4. Skill 机制与高级场景和 ROS2/Gazebo 联动4.1 一个技能就是一个目录OpenClaw 的灵魂不在对话而在 skill。所谓技能就是一段可以复用、可以被模型按需调用的能力封装。一个技能在磁盘上就是一个目录包含一个 manifest 描述文件和若干执行脚本。模型看到 manifest 就知道什么时候该用、参数怎么传执行时脚本负责干真正的活。新建一个技能目录的命令大致如下openclaw skill new my-skill生成的目录结构是skills/my-skill ├── manifest.json ├── run.ps1 └── README.mdmanifest.json里至少包含技能名、描述、参数定义和入口命令。描述写得越具体模型判断调用时机的准确率越高。比如“查看磁盘占用”就比“磁盘”要好因为模型能联想到用户在问磁盘空间。4.2 写一个“检查磁盘占用”技能的完整过程我拿一个工作中常用的“检查磁盘占用”技能做例子。先写manifest.json{ name: disk_usage_check, description: 检查指定目录或系统盘当前磁盘空间占用情况, parameters: { type: object, properties: { target: { type: string, description: 目标目录或盘符例如 C:\\, default: C:\\ } } }, entry: ./run.ps1 }再写run.ps1param([string]$target C:\\) Get-PSDrive -Name $target[0] | Select-Object Used,Free保存后在对话里说“看看 C 盘还有多少空间”OpenClaw 就能匹配到disk_usage_check并执行。技能的价值在于同一个动作以后不需要再重复给模型解释它看到你的诉求直接调用写好的脚本。这个过程中最容易踩的坑是 manifest 里的参数类型和实际脚本不一致。脚本期望 string配置里写成了 integer模型就会传错参数。所以写完技能一定要先手动执行一次确认脚本自身没问题再接进 OpenClaw 里测。4.3 Rosclaw 在 ROS2 Humble 场景里的配置思路如果你做机器人方向搜索热词里的 “rosclaw openclaw ros2 humble gazebo” 大概率指的就是用 OpenClaw 去驱动 ROS2 节点或读取仿真数据。这里推荐在 WSL2 里搭 ROS2 Humble因为原生 Windows 上跑 ROS2 的体验很不好网络通信节点经常因为防火墙策略时好时坏。基础思路在 WSL2 里安装好 ROS2 Humble 和 Gazebo然后在 Windows 侧通过 OpenClaw 的技能封装 ROS2 CLI。举个例子写一个技能用来检查话题列表{ name: ros2_topic_list, description: 列出当前 ROS2 环境下的所有话题, entry: ./run.sh }对应脚本内容只需要一句话source /opt/ros/humble/setup.bash ros2 topic list难点在于 Windows 侧执行 WSL 里的脚本需要把执行入口写成wsl -e bash -c。比如在技能运行脚本里写wsl -e bash -c source /opt/ros/humble/setup.bash ros2 topic echo /chatter这样就能用自然语言问 OpenClaw“看一下 /chatter 话题的最新消息”它会自动把命令透传到 WSL 里执行。要注意 WSL 里的 ROS2 环境变量跟 Windows 侧是隔离的所有依赖 ROS2 环境的命令都要在同一个 bash 进程里完整加载环境不要拆成多段执行否则会提示找不到ros2命令。5. Windows 桌面体验Companion 与 Codex 组合使用5.1 把 Companion 作为常驻操作窗口OpenClaw 的 CLI 用起来直接但长期挂任务时一个图形化界面确实更友好。Windows 下的 Companion 组件本质上是给 OpenClaw 套了一个桌面壳它负责显示会话、展示技能执行日志也提供了手动停止/重跑任务的按钮而不是替代模型和技能引擎。配置步骤不复杂确保 OpenClaw 主服务已经在本地运行然后找到companion相关命令或独立可执行文件启动后会生成一个本地访问地址。在 Windows 下使用时最关键的一点是不要在管理员权限的终端里启动 Companion否则命令行服务和图形界面之间的通信会报权限不一致的错误。启动后在界面上能看到本地模型的状态、当前会话列表和技能调用记录。这里我建议打开“自动记录日志”开关方便后面复盘模型到底做了哪些操作尤其是当它执行了删除或移动文件这类高危险操作时日志是唯一的追溯证据。5.2 和 Codex CLI 并行工作的正确姿势很多人的实际需求不是“用 OpenClaw 写代码”而是“让 OpenClaw 调度 Codex”。Codex 适合干编码的事OpenClaw 擅长做文件操作和全局协调两者不冲突。实际操作中可以在 OpenClaw 里新建一个codex_task技能把编码任务转交给 Codex CLI 处理。这样既保留 OpenClaw 的统一入口又利用 Codex 的编码能力openclaw skill run codex_task --prompt fix the test failure in src/app.ts要注意的是Codex 在 Windows 上经常出现“设置未完成”的提示。这通常不是 Codex 本体坏了而是它需要读取用户目录下的配置文件如果以管理员身份运行过配置文件权限被改坏之后的普通用户进程就无法写入。解决方法是删除 Codex 的配置缓存目录然后重新在非管理员终端里登录一次让它重新生成配置。5.3 常见桌面端配置坑为什么提示“设置未完成”还有一个高频提示是“daemon 必须在非管理员终端启动”。很多人直接右键“以管理员身份运行 PowerShell”再启动 Ollama 或 OpenClaw结果反而报错。原因是这些工具在设计上不愿意跑在提权环境里Windows 的用户态服务和文件访问在这两种模式下有完全不同的行为提权环境反而容易造成文件目录访问冲突。正确做法是普通权限打开 PowerShell不要右键管理员运行直接在命令行启动服务。如果你因为其他原因需要管理员终端建议把工具安装目录的写权限单独放开再用普通权限运行。6. 高频报错与排查实录Windows 部署 OpenClaw 的避坑清单6.1 按日志顺序排查的通用流程部署过程中百分之九十的问题都能靠“看日志”解决。不要一报错就猜先明确三个问题是命令行入口启动失败还是模型服务没起来还是技能执行报错三者对应的日志位置分别不同。通常建议按这个顺序排查先看 OpenClaw 运行日志~/.openclaw/logs/里面有最近一次操作的详细输出。再确认模型服务是否正常直接请求本地的模型 API看返回格式。最后检查 Windows 事件查看器里与网络、端口、防火墙相关的记录排除系统层面拦截。只要这三步走完绝大多数问题都能定位到具体环节。很多人一上来就改配置越改越乱最后反而不知道问题出在哪一层。6.2 六类常见错误速查表下面的速查表覆盖了我在 Windows 部署时实际遇到过的典型问题以及直接的解决办法。报错或现象根本原因解决办法下载文件提示“无法安全验证”Mark-of-the-Web 标记导致隔离右键文件属性勾选“解除锁定”或使用Unblock-File命令error: start the windows daemon from a non-elevated terminalOllama 或助手服务在管理员终端里启动关闭管理员窗口改用普通权限 PowerShell 启动服务请先运行wsl --status解决报告WSL 内核未更新或未初始化执行wsl --update并重启终端访问 localhost:11434 超时Ollama 未启动或端口被占用用netstat -ano | findstr 11434查看端口确认 Ollama 托盘图标在运行npm 安装时报错 ECONNRESET/ETIMEDOUTnpm 默认源在国内访问不稳定执行npm config set registry https://registry.npmmirror.com后重试对话回复乱码或答非所问模型上下文太长或提示词太泛缩短会话上下文把 prompt 写得任务导向更明确有些问题不是一次就能解决的。比如端口被占用你需要先查是哪个进程占用的端口再决定是关闭进程还是修改配置netstat -ano | findstr 11434找到最右侧的 PID 后在任务管理器里定位对应的进程确认是残留进程后再结束。不要一上来就重启电脑否则下次启动同样的进程又会抢端口。6.3 权限与安全防护的实战建议这里要特别强调一点不要为了让 OpenClaw 运行顺畅就关闭 Windows Defender 或手动把整个目录加入排除名单。这样做确实能减少误报但也会给安全防护留下后门尤其当 OpenClaw 被授权执行 shell 命令时风险会被放大。一种更稳妥的做法是把 OpenClaw 的安装目录、技能目录和模型缓存目录单独加入 Defender 排除项其他目录保持默认防护。同时不要将 OpenClaw 的 API 密钥或会话 token 写进桌面备忘录尽量放到 Windows 凭据管理器或环境变量里。另外如果 OpenClaw 的技能需要访问受保护目录比如C:\Program Files不要偷偷提权而是尽量修改技能脚本去访问用户目录或指定工作目录。在本地跑 agent权限边界越清晰后续出问题的概率越低。7. 个人使用收获和三个小技巧最后分享一点个人体会。我在 Windows 上跑 OpenClaw 差不多一周后最大的感受是真正花时间的不是安装而是想清楚模型和服务之间到底怎么配合。本地模型好处是私密、可控但能力天花板是硬伤云端模型能力强却没法在没有网络的环境中运行。把它们配置成两个 provider按任务复杂度切换是我目前觉得最舒服的模式。三个小技巧第一先跑通最小链路再往里面加技能。很多人一上来就想让 OpenClaw 操作 ROS、访问数据库、管理文件结果发现模型根本不知道什么场景调什么技能。先只接 Ollama 一个查看文件列表的技能跑通之后再逐步扩展排查问题的范围会小很多。第二会话上下文不要给太长。默认配置下模型会把历史对话都记在上下文里会话时间越长请求越慢也越容易跑偏。遇到复杂任务优先开一个新会话把任务描述写清楚而不是不停追问同一个会话。第三给模型配一个固定的“环境前言”。在配置文件里写清楚当前工作目录、默认编码、终端类型能大幅提高命令生成准确度。Windows 的编码问题尤其坑有些脚本输出 UTF-8有些是 GBK模型如果没有环境提示经常会把输出读乱。你把环境描述写清楚它就知道该用哪种方式解析结果。Windows 上部署这类工具本质上没有难度只有细节。只要环境、模型、技能这三条链路都通了剩下的就是如何把它用得顺手的问题了。