1. 零基础跑通 OpenClaw 私人顾问先搞懂它到底在干什么OpenClaw 是一个可以本地部署的私人 AI 顾问框架它能让你在自己电脑上跑一个带网页控制台的智能助手支持接入不同厂商的大模型。适合谁适合想拥有一个不依赖第三方托管、数据留在本机、又能自由切换模型的开发者或技术爱好者。你不需要会写复杂代码只要跟着命令一步步敲就能把它跑起来。很多人第一次听到「本地部署 AI 顾问」会觉得门槛很高其实拆开看就三件事装运行环境、拉源码装依赖、配一个能调用模型的 Key。OpenClaw 本身是基于 Node.js 开发的所以 Node.js 是地基源码托管在代码仓库里所以需要 Git 来拉取依赖包用 npm 或 pnpm 管理最后模型调用走统一的 API 通道这里我用 TaoToken 来统一管理 Key 和请求地址省得每个模型厂商都去单独配一遍。我试过在一台干净的 Windows 机器上从零走一遍全程大概二十分钟中间卡住的地方基本都在环境变量和脚本执行权限上。这篇文章会把每一步的命令、预期输出、以及出错时怎么排查都写清楚。你照着做最后能在浏览器里打开http://127.0.0.1:18789看到控制台并且能正常和模型对话就算跑通了。先明确一下整体流程心里有个地图第一步装 Node.js版本有要求太新太旧都可能出问题第二步装 Git用来拉源码第三步把 OpenClaw 源码克隆到本地第四步配置 npm 使用 Git Bash 作为脚本执行环境第五步安装依赖并构建第六步初始化配置填入模型 API Key第七步启动网关服务并验证。这里面最容易让人放弃的是第四步和第五步因为 Windows 下 npm 默认用 PowerShell 跑脚本而 OpenClaw 的构建脚本是.sh文件需要 bash 来执行。只要把script-shell指到 Git Bash后面就顺了。还有一个点要提前说模型接入这块我推荐用 TaoToken 作为统一通道。它的作用是给你一个统一的 Base URL 和 Key你不需要在 OpenClaw 里为每个模型厂商单独填不同的地址。对于零基础用户来说少配一个东西就少一个出错点。后面第三节会给完整的配置片段。现在开始动手。先确认你的系统是 Windows 10 或 11有管理员权限磁盘留出至少 5GB 空间。Mac 和 Linux 用户命令略有不同但思路一致本文以 Windows 为主关键处会标注差异。2. 装 Node.js 和 Git把地基打牢别让版本坑了你Node.js 是 OpenClaw 的运行环境没有它后面所有命令都会报「不是内部或外部命令」。版本这块要注意官方建议的范围是 22.22.3 到 23 之间或者 24.15.0 到 25 之间25.9.0 以上也可以。简单说别用太老的 18也别用刚出的奇数版尝鲜选 LTS 长期支持版最稳。去 Node.js 官网下载 LTS 版本安装时有一个关键勾选项Add to PATH。这个一定要勾上它会把 node 和 npm 命令加到系统环境变量里否则你在命令行里敲node -v会提示找不到命令。安装完成后按 Win R输入 cmd 回车然后敲node -v npm -v正常会输出类似v22.22.3和10.9.0的版本号。如果提示「不是内部或外部命令」说明 PATH 没配好重新安装并确认勾选 Add to PATH或者手动把 Node.js 安装目录加到系统环境变量里。接下来装 Git。Git 的作用是把 OpenClaw 的源码从代码仓库克隆到本地。去 Git 官网下载 Windows 版国内如果下载慢可以用 npmmirror 的镜像地址速度会快很多。版本没有硬性要求装最新稳定版就行。安装 Git 时大部分选项保持默认即可但有一个地方建议注意在「Adjusting your PATH environment」这一步选「Git from the command line and also from 3rd-party software」这样 git 命令在 cmd 和 PowerShell 里都能用。装完后验证git --version where.exe git第一条会输出git version 2.xx.x第二条会输出 git.exe 的完整路径比如D:\Program Files\Git\cmd\git.exe。记住这个路径后面配置 npm 的 script-shell 要用到不过用的是bin\bash.exe而不是cmd\git.exe。Git 装好后会自带一个 Git Bash这是一个在 Windows 上模拟 bash 环境的工具。OpenClaw 的构建脚本是.sh文件必须用 bash 来跑所以后面我们要让 npm 知道「跑脚本的时候用 Git Bash别用 PowerShell」。验证 Git Bash 是否存在在 PowerShell 里敲Test-Path D:\Program Files\Git\bin\bash.exe如果输出 True说明路径对。如果你的 Git 装在别的盘把路径换成你自己的。这一步很关键路径错了后面 npm 跑构建会直接失败。到这里Node.js 和 Git 两个地基就打好了。你可以把这两个理解成Node.js 是发动机Git 是搬运工。发动机负责跑代码搬运工负责把代码从仓库搬到你的电脑上。两者缺一不可。顺便提一句如果你之前装过 Node.js 但版本不对建议先卸载再重装不要直接覆盖否则环境变量可能残留旧路径导致命令行调用的还是旧版本。卸载后在 cmd 里敲node -v应该提示找不到命令再装新版本就干净了。3. 克隆源码并配置 npm 使用 Git Bash这一步决定后面顺不顺环境装好后找一个你想放项目的目录。比如你想放在 D 盘先打开 PowerShell 或 cmd切到 D 盘D: mkdir openclaw-project cd openclaw-project然后克隆源码。OpenClaw 在 gitee 和 github 上都有仓库选一个就行不要重复克隆。这里用 gitee 的地址国内访问更稳定git clone https://gitee.com/OpenClaw-CN/openclaw-cn.git克隆完成后会多出一个openclaw-cn文件夹进入它cd openclaw-cn注意如果你是从 github 克隆的文件夹名可能是openclaw进目录时别搞错。接下来是 Windows 下最关键的一步配置 npm 使用 Git Bash 作为脚本执行环境。因为 OpenClaw 的构建脚本是.sh文件npm 默认在 Windows 上用 PowerShell 跑脚本会直接报错。执行npm config set script-shell D:\Program Files\Git\bin\bash.exe把路径换成你自己 Git Bash 的实际路径。配完后可以用npm config get script-shell确认一下输出应该是你刚设置的路径。这一步做完有些人会遇到 PowerShell 阻止脚本运行的问题报错类似「无法将 openclaw-cn 项识别为 cmdlet」或者「因为在此系统上禁止运行脚本」。这是因为 PowerShell 默认的执行策略比较严格。解决方法是开启当前用户的脚本执行权限Set-ExecutionPolicy RemoteSigned -Scope CurrentUser回车后会问你是否确认输入 A 回车表示全是或 Y 回车。这个设置只影响当前用户不会动系统全局策略相对安全。现在可以安装依赖了。npm 是 Node.js 自带的包管理器兼容性最强pnpm 是第三方的高性能包管理器省磁盘、装得快语法和 npm 基本一样。两者选一个就行我建议零基础先用 npm少装一个东西少一个变量。在项目根目录下执行npm install如果你用 pnpm先全局装 pnpm 再执行pnpm install。安装过程会拉取一堆依赖包时间取决于网速耐心等。如果中途报对等依赖冲突peer dependency conflict用这条命令忽略冲突按旧版行为安装npm install --legacy-peer-deps如果 npm 通过 SSH 协议拉取 GitHub 依赖时认证失败全局配置 Git 把 SSH 替换成 HTTPSgit config --global url.https://github.com/.insteadOf ssh://gitgithub.com/依赖装完后构建项目会生成 dist 目录npm run build构建成功后再做全局链接让 openclaw 命令在命令行里可用npm link验证安装openclaw --version正常会输出版本号比如2026.3.3。看到版本号说明 OpenClaw 本体已经装好了。这里插一句模型接入的配置。OpenClaw 初始化时会让你选模型提供商并填 API Key。为了统一管理我建议用 TaoToken 的通道。它的 Base URL 是https://taotoken.net/api你可以在 TaoToken 控制台创建一个 API Key然后在 OpenClaw 配置里把提供商选成兼容 OpenAI 协议的自定义项填入这个 Base URL 和 Key。这样后面换模型只需要改 Model ID不用动地址和 Key。如果你用的是 Claude Code 或类似工具配置逻辑是一样的核心三件套就是 Base URL、API Key、Model ID。OpenClaw 的配置文件在初始化后会生成路径通常在D:\.openclaw\下具体在下一节展开。4. 初始化配置并启动网关把私人顾问真正跑起来OpenClaw 装好后需要初始化配置才能启动。执行配置向导openclaw onboard --install-daemon这个命令会启动一个交互式向导按提示一步步选。第一个出现的是 Security 安全警告选 Yes表示你理解并确认。接着 Onboarding mode 选 Manual手动配置这样你能看清每一项。Setup 这一步选 Local gateway (this machine)意思是网关跑在本机。Workspace 填你的工作目录比如D:\.openclaw\workspace也可以自定义但建议路径里不要有中文和空格避免后面出奇怪的问题。然后是 Model/auth provider模型提供商。这里选 Qwen通义千问或者你购买的其他 Token Plan。如果你用 TaoToken 统一通道就选兼容 OpenAI 协议的自定义提供商然后填Base URLhttps://taotoken.net/apiAPI Key你在 TaoToken 控制台创建的 KeyModel ID比如qwen-plus或你实际要用的模型名回车后输入 API Key。注意 Key 不要泄露也不要提交到代码仓库里。接下来是网关基础配置Port填 18789这是默认端口Bind选 Loopback (127.0.0.1)仅本地访问安全Auth选 Token会自动生成一个访问令牌配置完成后启动服务。打开 cmd 或 PowerShellopenclaw gateway服务启动后在浏览器访问http://127.0.0.1:18789应该能看到 OpenClaw 的控制台界面。如果能看到界面并且能发消息得到模型回复说明整条链路通了。这里给一个配置文件的参考结构OpenClaw 的配置通常写在D:\.openclaw\下的配置文件里格式类似 JSON 或 TOML具体以你初始化生成的为准。核心字段包括{ gateway: { port: 18789, bind: 127.0.0.1, auth: token }, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: 你的TaoToken Key, modelId: qwen-plus } }注意实际字段名以 OpenClaw 生成的配置为准上面是结构示意。关键是 Base URL、API Key、Model ID 这三样要对应上。启动后如果浏览器打不开页面先确认服务是否真的在跑看命令行有没有报错。如果提示端口被占用可以换一个端口比如 18790然后重新访问对应端口。验证请求是否成功除了在网页界面发消息也可以用 curl 直接测网关curl http://127.0.0.1:18789/health如果返回类似{status:ok}的内容说明网关活着。再测模型调用可以在网页界面里发一句「你好」看是否有回复。有回复就说明模型通道也通了。到这里你的私人顾问就跑起来了。整个过程的核心就是环境装对、脚本执行环境配对、模型通道填对。三样都对基本不会出问题。5. 常见报错排查401、local proxy failed、reading choices 怎么解跑 OpenClaw 的过程中报错基本集中在几类。下面按真实遇到的错误对照着说。第一类401 未授权。这个通常是 API Key 填错、过期或者 Base URL 和 Key 不匹配。如果你用 TaoToken确认 Key 是从 TaoToken 控制台创建的Base URL 是https://taotoken.net/api两者要配套。另外检查 Key 有没有多余空格复制时容易带上换行。解决方法是重新生成一个 Key重新填入配置重启网关。第二类local proxy failed。这个报错一般出现在网关启动阶段意思是本地代理或端口绑定失败。常见原因是端口 18789 被别的程序占用了。用netstat -ano | findstr 18789查一下哪个进程占了要么结束它要么在配置里换端口。另一个原因是 Bind 地址填错如果你填了非本机 IP 但本机没有那个地址也会失败。改回127.0.0.1即可。第三类reading choices 相关报错。这个通常出现在模型返回结果解析阶段报错信息里带reading choices或类似字段。原因是模型接口返回的结构和 OpenClaw 预期的不一致多半是 Base URL 指向的接口不是 OpenAI 兼容格式或者 Model ID 填错了。确认你用的通道是 OpenAI 兼容协议Model ID 是通道支持的模型名。如果用的是 TaoToken确认 Model ID 写的是它支持的模型比如qwen-plus不要写成别的厂商的模型名。第四类OAuth 相关报错。如果你在配置里选了需要 OAuth 的提供商但没完成授权流程就会报 OAuth 失败。零基础建议直接用 API Key 方式不要走 OAuth少一层交互。在配置里把认证方式改成 API Key。第五类UI 界面缺失。服务启动了但浏览器打开是空白或报前端资源缺失。这说明网关在跑但 UI 资源包没构建好。先 Ctrl C 停掉服务然后执行openclaw doctor --repair这个命令会自动检查并修复缺失的 UI 文件。如果提示选择修复项勾选和 Control UI 或 Dashboard 相关的。如果 doctor 无效手动构建pnpm ui:build然后再openclaw gateway重启重新访问。第六类依赖版本冲突。npm install时报一堆 peer dependency 错误。用npm install --legacy-peer-deps绕过。如果还不行删掉node_modules和package-lock.json重来。第七类脚本执行被阻止。前面提过PowerShell 执行策略问题用Set-ExecutionPolicy RemoteSigned -Scope CurrentUser解决。排查的思路是先看报错关键词定位是环境问题、配置问题还是网络问题。环境问题看版本和路径配置问题看 Key、Base URL、Model ID 三件套网络问题看能不能访问到接口地址。大部分问题都能通过重启服务和重新填配置解决。6. 把 Key 和通道管好后面换模型才不折腾跑通之后建议你把模型接入这块规范化。核心就三样Base URL、API Key、Model ID。不管你后面换什么模型只要这三样对应上OpenClaw 就能调通。用 TaoToken 的好处是 Base URL 固定为https://taotoken.net/apiKey 在控制台统一管理换模型只改 Model ID。这样你不需要在 OpenClaw 里为每个厂商维护一套配置。对于长期跑私人顾问的场景这种统一通道能省很多事。如果你后面要接 Claude Code 或做 Agent 类的长期编码任务可以考虑 Coding Plan它更适合高频调用和长时间运行的场景。日常验证模型是否通用模型对话页面发一条消息最快。接入过程中遇到配置问题查接入文档比到处搜更靠谱。Key 的管理要注意不要写死在代码里提交到仓库不要截图发出去定期轮换。OpenClaw 的配置文件里如果明文存了 Key注意这个文件的权限别让其他用户读到。最后一步确认你的服务能开机自启或手动稳定启动。openclaw onboard --install-daemon里的 daemon 选项就是干这个的。如果你没装 daemon每次重启电脑后需要手动openclaw gateway。装了就省心。到这里从 Node.js 到 Git从依赖安装到模型通道配置整条链路就完整了。你手上现在有一个跑在本机的私人顾问数据不出本机模型可换Key 自己管。后面想加功能、换模型、调参数都在这个基础上折腾就行。