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 替换成 HTTPS：
git config --global url."https://github.com/".insteadOf "ssh://git@github.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 URL：
https://taotoken.net/api - API Key：你在 TaoToken 控制台创建的 Key
- Model ID：比如
qwen-plus或你实际要用的模型名
回车后输入 API Key。注意 Key 不要泄露，也不要提交到代码仓库里。
接下来是网关基础配置：
- Port：填 18789，这是默认端口
- Bind：选 Loopback (127.0.0.1)，仅本地访问，安全
- Auth：选 Token，会自动生成一个访问令牌
配置完成后，启动服务。打开 cmd 或 PowerShell：
openclaw 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/api，Key 在控制台统一管理，换模型只改 Model ID。这样你不需要在 OpenClaw 里为每个厂商维护一套配置。对于长期跑私人顾问的场景，这种统一通道能省很多事。
如果你后面要接 Claude Code 或做 Agent 类的长期编码任务，可以考虑 Coding Plan，它更适合高频调用和长时间运行的场景。日常验证模型是否通，用模型对话页面发一条消息最快。接入过程中遇到配置问题，查接入文档比到处搜更靠谱。
Key 的管理要注意：不要写死在代码里提交到仓库，不要截图发出去，定期轮换。OpenClaw 的配置文件里如果明文存了 Key，注意这个文件的权限，别让其他用户读到。
最后一步，确认你的服务能开机自启或手动稳定启动。openclaw onboard --install-daemon里的 daemon 选项就是干这个的。如果你没装 daemon，每次重启电脑后需要手动openclaw gateway。装了就省心。
到这里，从 Node.js 到 Git，从依赖安装到模型通道配置，整条链路就完整了。你手上现在有一个跑在本机的私人顾问，数据不出本机，模型可换，Key 自己管。后面想加功能、换模型、调参数，都在这个基础上折腾就行。
