1. 为什么非编程 PC 装 OpenClaw 总卡在第一步OpenClaw 是一个可以跑在本地 Windows 上的 AI 助手框架能接大模型、能挂技能插件、还能开一个 Web UI 在浏览器里直接对话。它适合谁适合不想折腾 Linux、不想买 Mac、手头只有一台 Win10 或 Win11 普通电脑但又想体验本地 Agent 的人。我自己那台老笔记本就是 Win11 家庭版没装过任何开发工具全程照着下面这套流程走通了。很多人第一次装 OpenClaw卡住的地方其实不是 OpenClaw 本身而是它依赖的两个基础工具Node.js 和 Git。Node.js 是运行环境OpenClaw 是用 JavaScript 生态写的没有 Node.js 它根本跑不起来Git 是拉取依赖用的OpenClaw 有些包会从 Git 仓库直接拉源码没有 Git 就会报npm error code 128这类错误。这两个装好之后剩下的就是一条命令的事。但现实情况是非编程用户最容易在这几个地方翻车一是 Node.js 装完没重启终端node -v提示找不到命令二是 Git 没装npm 拉包时报An unknown git error occurred三是 npm 全局安装权限不够报EACCES或者路径不存在四是配置文件里的模型地址和 Key 没填对启动后 Web UI 能打开但一发消息就报错。这篇教程就是把这些坑一个个填平让你在 Win10/11 上一次跑通。我试过在一台完全干净的 Win11 上从零开始整个过程大概二十分钟其中大部分时间是在等安装程序下载和依赖拉取。下面按顺序来每一步都有可复制的命令和验证动作你跟着做就行。2. 装 OpenClaw 前先把 Node.js 和 Git 这两个地基打好OpenClaw 手动安装的第一步不是装 OpenClaw而是把 Node.js 和 Git 装好。这一步在 Win10 和 Win11 上操作几乎一样我下面以 Win11 为例Win10 的菜单名字可能略有不同但路径一致。2.1 安装 Node.js 并验证版本打开浏览器访问 Node.js 官网下载页选择 Windows 64 位安装程序.msi 文件。下载完成后双击运行安装流程如下欢迎界面点 Next勾选接受协议点 Next安装目录保持默认一般是C:\Program Files\nodejs\点 NextCustom Setup 页面保持默认点 Next这里有一个关键选项勾选「Automatically install the necessary tools」它会帮你装一些编译工具点 Next然后点 Install 开始安装。安装完成后点 Finish这时会自动弹出一个命令提示符窗口提示你按任意键开始安装必要工具。你按一下回车它会用 PowerShell 跑一段脚本耐心等它跑完最后提示按 ENTER 退出。这一步不要跳过否则后面某些依赖编译会失败。装完之后重启一下电脑。重启是为了让环境变量生效很多人省了这一步结果在终端里敲node -v提示「不是内部或外部命令」就是因为 PATH 还没刷新。重启后点 Windows 图标右键选「Windows PowerShell」选择「以管理员身份运行」。依次执行下面三条命令npm -v node -v git -v如果 Node.js 装好了node -v会回显类似v22.14.0的版本号npm -v回显10.9.2之类。但这时候git -v大概率会报错因为 Git 还没装这就是下一步。2.2 安装 Git 并确认三件套齐全去 Git 官网下载 Windows 版安装程序双击运行。安装流程基本一路 Next 就行欢迎界面 Next安装目录保持默认后续的组件选择、默认编辑器、PATH 环境、换行符处理等页面全部保持默认依次点 Next最后点 Install完成后点 Finish。Git 装完不需要重启但建议关掉当前 PowerShell 窗口重新以管理员身份开一个这样 PATH 才会包含 Git。然后再次执行npm -v node -v git -v这次三条都应该有版本号回显。git -v会显示git version 2.47.1.windows.1这样的内容。三件套齐全地基就算打好了。这里有个细节如果你之前装过 Node.js 但版本太老比如 v14 以下OpenClaw 可能跑不起来建议用node -v确认版本在 v18 以上最好 v20 或 v22。版本不够就去官网下最新的覆盖安装。3. 用 npm 或 pnpm 安装 OpenClaw 并写入配置文件地基打好后进入正题。OpenClaw 的安装有两种方式npm 全局安装和官方脚本安装。Windows 上我推荐先用 npm如果报错再用 pnpm 兜底。3.1 npm 安装与 code 128 报错的兜底方案在管理员 PowerShell 里执行npm install -g openclawlatest如果你网络环境正常这条命令会顺利拉取依赖并安装。但很多人会在这里遇到npm error code 128完整报错类似npm error code 128 npm error An unknown git error occurred npm error command git --no-replace-objects clone ssh://gitgithub.com/whiskeysockets/libsignal-node.git ... npm error fatal: destination path ... already exists and is not an empty directory.这个错误的本质是 npm 缓存目录里有一个残留的临时克隆目录Git 拉取时发现目标路径已存在且非空就中断了。解决办法有两个一是清掉 npm 缓存再重试二是换 pnpm 来装。我实测下来pnpm 兜底最稳因为它对依赖的解析和缓存管理跟 npm 不一样能绕开这个残留问题。先装 pnpmnpm install -g pnpm pnpm setuppnpm setup会配置环境变量执行完后关掉当前窗口重新开一个管理员 PowerShell。然后用 pnpm 安装 OpenClawpnpm add -g openclawlatest装完后执行初始化向导openclaw onboard --install-daemon这个向导会问你几个问题用键盘左右方向键选择回车确认。流程大致是选择 Yes 安装守护进程选择 QuickStart 快速开始保持默认回车选择 Skip for now 跳过某些可选配置保持默认保持默认选择 Skip for now选择 No然后用方向键移动光标按空格键依次选中boot-md、bootstrap-extra-files、command-logger、session-memory这四个技能回车确认最后选择Open the Web UI回车。如果一切顺利浏览器会自动打开 OpenClaw 的 Web UI 页面说明安装成功。3.2 配置文件 openclaw.json 的写入与参数说明安装完成后配置文件在C:\Users\你的用户名\.openclaw\openclaw.json。注意如果你是用 Administrator 账户登录的路径就是C:\Users\Administrator\.openclaw\openclaw.json。用记事本打开它你会看到向导生成的默认配置。接下来要把模型接入部分改成你自己的。这里我用 TaoToken 统一 Key 来接入因为它一个 Key 能调多个模型省得你到处申请。配置文件里需要改的核心是models.providers这一段。下面是一个可复制的 JSON 片段你把它替换进去注意路径和原文一致{ models: { mode: merge, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: your_taotoken_key, api: openai-completions, models: [ { id: model_name, name: model_name, reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 200000, maxTokens: 8192, compat: { supportsDeveloperRole: false } } ] } } }, agents: { defaults: { model: { primary: taotoken/model_name }, models: { taotoken/model_name: {} }, workspace: C:\\Users\\Administrator\\.openclaw\\workspace, compaction: { mode: safeguard }, maxConcurrent: 4, subagents: { maxConcurrent: 8 } } } }这里有几个参数必须说清楚。baseUrl填https://taotoken.net/api这是接口地址不要加多余的路径。apiKey填你在 TaoToken 控制台创建的 Key获取地址是https://taotoken.net/api-keys。model_name填你要用的模型 ID比如claude-sonnet-4-5或gpt-4o这类具体以你账号里可用的为准。agents.defaults.model.primary里的taotoken/model_name要和上面 provider 名字对应否则 OpenClaw 找不到模型。另外workspace路径在 Windows 上要用双反斜杠\\或者用正斜杠/单反斜杠会被 JSON 解析成转义字符导致报错。这是非编程用户最容易忽略的一点。改完保存回到 PowerShell执行重启openclaw gateway restart回显显示 gateway 已启动就说明配置生效了。注意使用期间不要关掉 openclaw-gateway 这个窗口关了的话在新窗口重新执行openclaw gateway restart就行。4. 验证 OpenClaw 是否真的跑通版本、日志与接口连通性装完不代表跑通得验证。验证分三层环境层、进程层、接口层。每一层都有对应的命令和预期结果。4.1 环境层验证三件套版本检查开一个管理员 PowerShell执行node -v npm -v git -v openclaw --version前三条前面已经验证过。openclaw --version会回显类似2026.2.6-3的版本号说明 OpenClaw CLI 已经装好。如果提示「不是内部或外部命令」说明全局安装路径没进 PATH可以执行pnpm setup后重开窗口或者手动把 pnpm 的全局 bin 目录加到系统环境变量里。4.2 进程层验证启动日志与 gateway 状态执行openclaw gateway status如果 gateway 正在运行会显示 running 状态和监听端口默认是 18789。如果显示 stopped就执行openclaw gateway restart。启动过程中窗口里会打印日志你重点看有没有listening on和provider loaded这类字样。如果日志里出现provider taotoken not found说明配置文件里 provider 名字和 agents 里引用的名字不一致回去检查。4.3 接口层验证Web UI 对话与连通性测试浏览器打开http://127.0.0.1:18789应该能看到 OpenClaw 的 Web UI。在对话框里发一句「你好介绍一下你自己」如果模型正常返回内容说明接口连通。如果报错常见的是401 Unauthorized那是 Key 不对或者model not found那是模型 ID 填错。你也可以用命令行直接测接口连通性在 PowerShell 里执行curl -X POST https://taotoken.net/api/chat/completions -H Authorization: Bearer your_taotoken_key -H Content-Type: application/json -d {\model\:\model_name\,\messages\:[{\role\:\user\,\content\:\hi\}]}如果返回一段 JSON 且包含choices字段说明 Key 和模型都没问题问题就出在 OpenClaw 配置上。如果这里就报 401那先去 TaoToken 控制台确认 Key 是否有效、余额是否充足。三层都过了OpenClaw 就算真正跑通了。你可以回到 Web UI 里正常对话也可以继续挂飞书等 IM 集成。5. 安装 OpenClaw 常见报错排查401、code 128 与 OAuth 问题这一节把前面提到的和没提到的报错集中处理一下你遇到问题时直接对号入座。5.1 npm error code 128 与 git clone 失败完整报错前面贴过核心是destination path already exists and is not an empty directory。解决办法先清 npm 缓存执行npm cache clean --force然后删掉报错里那个临时目录路径在报错信息里能看到再重试。如果还不行直接用 pnpm 兜底命令是npm install -g pnpm然后pnpm add -g openclawlatest。pnpm 的缓存机制不同基本不会撞上这个残留问题。5.2 401 Unauthorized 与 local proxy failed401基本就是 Key 的问题。检查三处TaoToken 控制台里 Key 是否启用、配置文件里apiKey有没有多余空格、请求头是不是Bearer开头。如果你用的是环境变量方式传 Key确认变量名和配置文件里引用的一致。local proxy failed通常出现在你配置了本地代理但代理没启动或者代理地址写错。OpenClaw 默认走直连如果你没特殊需求把配置文件里跟 proxy 相关的字段删掉或留空即可。注意这里说的代理是本地网络代理配置不是让你去搞什么网络工具普通家庭网络直连就行。5.3 reading choices 报错与 OAuth 相关提示reading choices这个报错一般出现在接口返回的 JSON 结构不符合预期时比如返回了一个错误对象而不是正常的choices数组。你按 4.3 的 curl 命令单独测一下接口看返回的原始 JSON 是什么。如果是{error: {...}}那就是 Key 或模型的问题如果返回正常但 OpenClaw 还报这个错检查配置文件里api字段是不是openai-completions这个字段决定了 OpenClaw 怎么解析返回。OAuth 相关提示通常出现在你用了需要 OAuth 授权的 provider但没走完授权流程。如果你用 TaoToken 的 Key 方式接入不涉及 OAuth可以忽略。如果配置里残留了其他 provider 的 OAuth 字段删掉即可。5.4 配置文件路径与权限问题Windows 上配置文件路径是C:\Users\用户名\.openclaw\openclaw.json。如果你用管理员账户装但用普通账户跑可能读不到配置。解决办法是统一用同一个账户操作或者把.openclaw目录权限放开。另外如果你之前在 Mac 或 Linux 上跑过把配置直接拷到 Windows注意路径分隔符要改/root/.openclaw/workspace这种要改成C:\\Users\\...。还有一个坑用记事本编辑 JSON 后如果保存成了 UTF-8 带 BOM 格式OpenClaw 解析会失败。建议用 VS Code 或者 Notepad 编辑保存为无 BOM 的 UTF-8。6. 跑通之后怎么用模型对话、Coding Plan 与接入文档OpenClaw 跑通后你可以在 Web UI 里直接跟模型对话也可以把它当成一个本地 Agent 来用挂技能、接 IM、跑自动化任务。如果你主要用来写代码或者做长期项目建议看一下 TaoToken 的 Coding Plan包月方式对高频调用更划算地址是https://taotoken.net/coding-plan。如果你只是想先试试模型效果可以直接用模型对话页面地址是https://taotoken.net/chat。接入过程中如果遇到配置问题接入文档在https://taotoken.net/doc里面有各个客户端的配置示例。Key 的管理在https://taotoken.net/api-keys控制台在https://taotoken.net/console。如果你用的是 Claude Code 这类工具Anthropic 兼容接入的说明在https://taotoken.net/claudecode-anthropic。最后说一个实用技巧OpenClaw 的 gateway 窗口不要关但你可以把它最小化。如果你想让它在后台跑可以用openclaw gateway start配合 Windows 的任务计划程序开机自启。不过对非编程用户来说每次手动openclaw gateway restart也不麻烦关键是别在对话中途关窗口否则当前会话会断。整套流程走下来最花时间的其实是 Node.js 和 Git 的安装OpenClaw 本身反而很快。你把这两个地基打牢后面就是改改配置、重启、验证的事。遇到报错别慌按第 5 节对号入座基本都能解决。