1. OpenClaw 在 Windows 上到底能做什么为什么值得折腾OpenClaw 是一个可以在本地跑起来的 AI Agent 运行框架简单说就是让大模型不只是聊天而是能真正在你电脑上执行任务——读写文件、跑命令、调用工具、串联多步操作。它适合谁适合想在 Windows 上做本地 AI 自动化、又不想把数据全丢到云端的开发者也适合想拿它当编码助手、任务助手来用的人。Windows 环境跑 OpenClaw 有两条路一条是走 WSL2Windows Subsystem for Linux 2在 Linux 子系统里跑兼容性最好、坑最少另一条是直接在 PowerShell 里装省去子系统但偶尔会遇到路径和权限问题。这篇教程两条路都给你走一遍重点放在 WSL2 这条稳定路线上同时把 PowerShell 直装作为备选方案讲清楚。我实测下来WSL2 方案在依赖安装、脚本执行、文件权限这几块明显更省心尤其是 OpenClaw 的安装脚本本身是 shell 脚本在 Linux 环境下跑几乎不会出幺蛾子。而 PowerShell 方案虽然也能用但对 Node.js 版本、执行策略、管理员权限的要求更敏感新手容易卡在第一步。整篇教程会覆盖WSL2 的完整初始化命令、Node.js 版本检查、OpenClaw 的安装与启动、配置文件怎么写、怎么验证一次完整的本地运行。每一步都给可复制的命令和参数说明你照着敲就行。核心检索词先记住OpenClaw Windows 搭建、WSL2 安装、Node.js 环境准备、PowerShell 启动验证这四个是整篇的主线。在开始之前你需要准备的东西不多一台 Windows 10 版本 2004 以上或 Windows 11 的机器、管理员权限、稳定的网络。Node.js 版本要求 ≥ 22.19这是 OpenClaw 2026 版本的最低门槛低于这个版本启动会直接报错。另外你需要一个大模型的 API KeyOpenClaw 本身不带模型它只是个调度框架得接一个模型服务才能干活。2. 前置准备Node.js 环境与模型 API Key 怎么配2.1 Node.js 安装与版本验证Node.js 是 OpenClaw 的运行基础先把它装好。去 Node.js 官网下载 Windows 版的.msi安装包双击一路下一步即可。安装完成后打开 PowerShell 或 CMD执行版本检查node -v npm -v正常会输出类似v22.19.0和10.x.x的版本号。如果node -v输出的版本低于 22.19说明你装的是旧版需要卸载后重新下载最新 LTS 或 Current 版本。这一步别偷懒版本不够后面openclaw onboard会直接拒绝启动。如果你已经装了旧版 Node.js建议用 nvm-windows 来管理多版本切换起来方便nvm install 22.19.0 nvm use 22.19.0 node -v2.2 模型 API Key 的获取思路OpenClaw 需要对接一个大模型服务配置里要填三样东西baseUrl、apiKey、模型name。你可以选国内的大模型平台注册后一般有免费额度可以先试。以常见的兼容 OpenAI 接口的平台为例流程是注册账号、完成实名、在控制台创建 API Key、在模型广场找到你要用的模型记下它的模型 Code 和 base_url。创建 API Key 时注意很多平台的新 Key 只在创建后显示一次务必当场复制保存。另外建议打开「免费额度用完即停」这类开关避免调用超额产生费用。拿到这三样东西后先放一边等会儿写进 OpenClaw 的配置文件。如果你希望统一管理多个模型的接入、少折腾各家平台的 Key 和地址也可以用一个聚合接入层来统一 baseUrl 和 Key这样切换模型时只改一个地方。后面配置章节我会给出标准的 JSON 写法你按自己的平台替换字段即可。2.3 WSL2 与 PowerShell 两条路怎么选简单给个判断如果你追求稳定、少踩坑选 WSL2如果你机器资源紧张、不想装子系统选 PowerShell 直装。WSL2 本质是在 Windows 里跑一个轻量 Linux 虚拟机OpenClaw 的安装脚本、依赖、权限模型都是按 Linux 设计的所以在这上面跑最顺。PowerShell 直装省了子系统但你要自己处理执行策略、路径分隔符、管理员权限这些 Windows 特有的问题。两条路的安装命令不一样但装完之后的启动、配置、验证流程基本一致。下面先讲 WSL2 的完整初始化。3. 可复制配置WSL2 初始化与 OpenClaw 安装全流程3.1 启用 WSL 功能并安装 Ubuntu第一步以管理员身份打开 PowerShell执行下面两条命令启用 WSL 和虚拟机平台功能dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完重启电脑让功能生效。重启后继续在 PowerShell 里执行wsl --install这条命令会自动安装 WSL2 和默认的 Ubuntu 发行版。如果你已经装过 WSL只是想更新内核用wsl --update接着把默认版本设为 2wsl --set-default-version 2如果wsl --install没能自动拉取 Ubuntu可以手动指定wsl --install -d Ubuntu或者直接去 Microsoft Store 搜 Ubuntu 下载安装。装完后验证状态wsl --status wsl -l -vwsl -l -v会列出所有已安装的发行版和版本号看到 Ubuntu 后面标着2就对了。第一次进 Ubuntu 会让你设置用户名和密码设好之后你就有了一个 Linux 终端环境。3.2 在 WSL2 里安装 OpenClaw进入 Ubuntu 终端后先确认 Node.js 环境。WSL2 里的 Node.js 和 Windows 主机的是两套需要单独装。推荐用 NodeSource 或 nvm 安装curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs node -v确认版本 ≥ 22.19 后执行 OpenClaw 官方安装脚本curl -fsSL https://openclaw.ai/install.sh | bash这个脚本适用于 macOS、Linux 和 WSL2。安装完成后验证openclaw --version有版本号输出就说明装好了。3.3 PowerShell 直装方案备选如果你不想用 WSL2以管理员身份打开 PowerShell执行iwr -useb https://openclaw.ai/install.ps1 | iex如果遇到执行策略报错先临时放开Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass然后再跑安装命令。装完同样用openclaw --version验证。3.4 配置文件 openclaw.json 怎么写OpenClaw 的配置文件默认在C:\Users\你的用户名\.openclaw\openclaw.jsonWSL2 下在~/.openclaw/openclaw.json。下面是一份可直接参考的配置把baseUrl、apiKey、模型id换成你自己的{ agents: { defaults: { workspace: D:\\WorkSpace\\OpenClawWorkSpace, model: { primary: myprovider/qwen3.5-flash }, models: { myprovider/qwen3.5-flash: {} } } }, models: { providers: { myprovider: { baseUrl: https://your-endpoint.example.com/compatible-mode/v1, apiKey: 你的apiKey, api: openai-completions, models: [ { id: qwen3.5-plus, name: qwen3.5-plus, contextWindow: 128000, maxTokens: 8192 }, { id: qwen3.5-flash, name: qwen3.5-flash, contextWindow: 128000, maxTokens: 8192 } ] } } }, gateway: { mode: local, auth: { mode: token, token: 你的网关令牌 }, port: 18789, bind: loopback }, tools: { profile: coding } }这里三件套必须齐全baseUrl指向模型服务的兼容接口地址apiKey是你的密钥models[].id是模型 ID。api字段填openai-completions表示走 OpenAI 兼容协议。gateway.port默认 18789bind设为loopback表示只监听本机。如果你用聚合接入层统一管理把baseUrl换成对应的 API 地址、apiKey换成聚合平台的 Key 即可模型 ID 按平台文档填。这样多个模型可以在一个配置里切换不用每个平台单独维护。保存后检测配置格式openclaw config validate改完配置重启网关openclaw gateway restart4. 验证请求一次完整的本地运行与成功结果确认4.1 启动前的健康检查在启动之前先跑一遍诊断命令把潜在问题提前暴露openclaw doctor openclaw gateway status openclaw config validateopenclaw doctor会检查配置、依赖、权限等常见问题gateway status确认网关服务是否在运行config validate检查 JSON 格式。三条都通过再往下走。4.2 执行 onboard 初始化向导以管理员身份打开 PowerShellWSL2 下直接在 Ubuntu 终端执行openclaw onboard向导会依次问你几个问题按下面选是否继续选 Yes安装模式选 QuickStart是否保留当前配置按实际情况选 Keep current values模型配置如果之前配过选 Keep current没配过就手动填后续几个 Skip 选项选 Skip for now是否配置 skills选 NoGateway 已安装选 Restart首次安装选 Install最后选 Hatch later向导过程中会另开一个窗口启动 Gateway等它跑起来即可。4.3 打开 Web 端并登录OpenClaw 的 Web 控制台默认端口是 18789浏览器访问http://localhost:18789登录需要网关令牌这个令牌就在openclaw.json的gateway.auth.token字段里复制粘贴到登录框即可进入。4.4 发一条真实请求验证进入聊天界面后发一条能触发工具调用的指令比如让它列一下工作目录的文件或者读一个本地文件的内容。如果模型正常返回、并且能执行你要求的操作说明整条链路——WSL2、Node.js、OpenClaw、模型 API——全部打通。验证成功的标志有三个Web 界面能正常对话、模型返回内容不是报错、工具调用有实际执行结果。三个都满足这次本地部署就算完成了。日常排查可以用这些命令openclaw logs --follow # 实时看日志 openclaw skills list # 查看已安装技能 openclaw skills install agent-browser # 安装技能 openclaw skills reload # 刷新技能列表5. 本篇常见报错排查401、local proxy failed、reading choices 怎么解5.1 401 未授权最常见的就是 401。原因基本是apiKey填错、过期或者baseUrl和 Key 不匹配。排查顺序先确认 Key 没有多余空格再确认baseUrl指向的平台和 Key 是同一家。如果你用的是聚合接入层确认 Key 是在对应平台创建的。改完配置记得openclaw config validate再openclaw gateway restart。5.2 local proxy failed这个报错通常出现在网关启动阶段意思是本地代理或网关绑定失败。常见原因是端口 18789 被占用或者bind配置不对。先查端口占用netstat -ano | findstr 18789如果被占用要么杀掉占用进程要么在配置里把gateway.port改成别的端口。另外确认bind是loopback如果你改成了对外监听又没配好认证也会出问题。5.3 reading choices 相关报错这类报错一般出现在模型返回解析阶段说明返回的 JSON 结构不符合预期。原因可能是api字段填错——比如模型服务实际是 OpenAI 兼容接口你却填了别的协议。确认api填openai-completions并且models[].id和平台文档里的模型 Code 完全一致。模型 ID 写错也会导致返回异常。5.4 OAuth 与认证模式问题如果你在配置里用了 OAuth 模式而不是 token 模式登录时可能遇到认证失败。本地部署建议直接用token模式简单可靠。确认gateway.auth.mode是token并且token字段有值。Web 登录时粘贴的令牌要和配置文件里的一致。5.5 Node.js 版本与执行策略问题PowerShell 直装方案里如果node -v低于 22.19openclaw onboard会直接报版本不满足。升级 Node.js 即可。另外 PowerShell 默认执行策略可能阻止脚本运行用Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass临时放开。WSL2 方案基本不会遇到执行策略问题。5.6 配置改了不生效改完openclaw.json后必须重启网关否则还是旧配置。顺序是openclaw config validate确认格式没问题再openclaw gateway restart。如果重启后还不生效用openclaw logs --follow看启动日志里有没有报错。6. 后续怎么用模型接入、编码助手与长期运行部署跑通只是开始。接下来你可以把 OpenClaw 当成日常的编码助手和任务助手来用。如果你需要频繁切换模型、对比不同模型的效果可以在配置里多写几个 provider用agents.defaults.model.primary切换主模型。想验证某个模型的实际表现直接开对话界面发任务就行。对于长期编码和 Agent 场景建议把工作目录workspace固定到一个专门的项目目录避免它乱翻你的系统文件。tools.profile设为coding会启用适合编码的工具集。技能方面按需安装比如agent-browser这类装完记得openclaw skills reload刷新。如果你希望统一管理模型接入、减少在多个平台之间来回配置 Key 和地址的麻烦可以用一个聚合接入层来统一 baseUrl 和 Key这样切换模型只改配置里的一个字段。接入文档和 API Key 管理入口在这里API Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite模型对话验证https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期编码与 Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后给个实用建议把openclaw doctor和openclaw gateway status加进你的日常检查习惯每次改完配置先跑一遍再重启。日志用openclaw logs --follow挂着出问题第一时间能看到原因。WSL2 方案下Ubuntu 终端和 Windows 文件系统之间的路径映射也要留意工作目录尽量放在 WSL2 内部或者用/mnt/d/...这种挂载路径避免权限和换行符问题。