1. Windows 本地部署 OpenClaw 到底难在哪Node.js 与 Git 环境准备全流程OpenClaw 是一个能在本地跑起来的开源 AI 助手它和普通聊天机器人的区别在于它能读写文件、执行命令、控制浏览器、整理日程相当于给大模型装上了手脚。适合想在 Windows 上折腾本地 AI Agent、又不想把数据传到云端的开发者。但很多人卡在第一步——环境没配好后面全白搭。我自己在 Windows 11 上从零走了一遍踩过的坑主要集中在 Node.js 版本、Git 缺失、npm 源太慢这三件事上。下面把每一步拆开讲你照着做基本能一次跑通。1.1 为什么必须 Node.js ≥ 22.16 或 24 LTSOpenClaw 的运行时依赖 Node.js官方要求版本 ≥ v24或者 22.16 的 LTS 版本。低于这个版本会在安装依赖时报engine not supported之类的错。我选的是 24.14.0 LTS兼容性目前最稳。去 Node.js 官网下载 Windows Installer.msi双击一路下一步。安装时注意勾选“Add to PATH”否则命令行里找不到 node。装完打开 PowerShell 验证node -v npm -v正常会输出类似v24.14.0和11.x.x。如果提示“不是内部或外部命令”说明 PATH 没配好重新装一遍并确认勾选。1.2 Git 安装与全局配置OpenClaw 的很多技能插件和源码是通过 Git 拉取的没有 Git 会在安装 skills 阶段直接失败。去 Git 官网下载 Windows 版安装时保持默认选项即可重点是“Git from the command line”那一项要选上。装完验证git --version然后配置全局用户名和邮箱不配的话某些仓库克隆会报错git config --global user.name your name git config --global user.email your email1.3 npm 换源加速依赖下载默认 npm 源在国内下载依赖经常超时。换成国内镜像npm config set registry https://registry.npmmirror.com验证是否生效npm config get registry输出https://registry.npmmirror.com就对了。这一步能让你后面装 OpenClaw 的时间从十几分钟缩到两三分钟。1.4 用官方脚本一键安装 OpenClaw官方提供了一键安装脚本会自动检测环境并安装。以管理员身份打开 PowerShell先放开执行策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后清缓存并执行安装npm cache clean --force iwr -useb https://openclaw.ai/install.ps1 | iex安装过程会拉取依赖耐心等。如果卡在某个包不动多半是网络问题可以重跑一次脚本npm 会断点续传。安装完成后你会看到一段健康检查输出里面有 Web UI 地址通常是http://127.0.0.1:18790/和 Gateway WS 地址。把这些记下来后面验证要用。到这里Windows 上的基础环境就算搭好了。下一节讲怎么把 TaoToken 的统一 Key 接进去让 OpenClaw 真正能调用模型。2. TaoToken 统一 Key 接入 OpenClaw配置文件修改与 API 通道设置OpenClaw 本身只是个调度框架真正干活的是背后的大模型。默认它可能让你选某个厂商的模型并填对应 Key但如果你手上有多个模型想切换一个个配 Key 很麻烦。TaoToken 提供统一 Key 和 API 通道一个 Key 就能走多个模型配置也集中在一处。2.1 先拿到 TaoToken 的 API Key打开 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册登录后进入控制台。在 API Keys 页面创建一个新 Key复制保存好后面配置文件里要用。如果你还没想好用什么模型可以先在模型对话页面试几个确认哪个响应速度和效果符合预期再去配 OpenClaw。2.2 找到 OpenClaw 的配置文件OpenClaw 的配置文件默认在C:\Users\你的用户名\.openclaw\openclaw.json如果这个文件不存在先跑一次新手引导openclaw onboard --install-daemon引导过程中会让你选模型、选通讯软件、选搜索引擎等。模型那一步可以先随便选一个后面我们直接改配置文件覆盖。2.3 修改 openclaw.json 接入 TaoToken用记事本或 VS Code 打开openclaw.json找到模型相关的配置段。不同版本字段名可能略有差异核心是三个东西Base URL、API Key、Model ID。下面是一个可复制的配置片段把sk-你的TaoToken密钥替换成你实际的 Key{ models: { default: claude-sonnet-4-20250514, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, models: [ claude-sonnet-4-20250514, gpt-4o, deepseek-chat ] } } } }注意 Base URL 填https://taotoken.net/api不要加多余的路径。Model ID 要和你实际想用的模型名一致写错了会在请求时报model not found。如果你更习惯用环境变量管理 Key也可以在 PowerShell 里设置$env:TAOTOKEN_API_KEYsk-你的TaoToken密钥然后在配置文件里用apiKey: ${TAOTOKEN_API_KEY}引用。这样 Key 不会明文写在文件里相对安全一些。2.4 配置项对照表配置项填写内容说明baseUrlhttps://taotoken.net/apiTaoToken API 通道地址apiKeysk-开头的一串字符控制台创建的 Keydefault模型 ID默认调用的模型models模型 ID 数组可切换的模型列表改完保存配置文件就绪。下一节讲怎么启动并验证请求是否正常返回。3. 启动 OpenClaw 并验证 TaoToken 请求连通性配置改完不代表就能用得实际发一次请求确认链路通了。这一节给你完整的启动命令和验证动作。3.1 重启 Gateway 让配置生效OpenClaw 的 Gateway 是核心进程配置改动后必须重启openclaw gateway restart然后检查状态openclaw status正常会显示 Gateway 运行中以及当前使用的模型和 provider。如果显示gateway timeout说明进程没起来看下一节的排障。3.2 用 doctor 检查配置问题OpenClaw 自带一个诊断命令openclaw doctor它会逐项检查 Node.js 版本、Git、配置文件格式、API Key 是否可读、模型是否可达。如果 TaoToken 的 Key 或 Base URL 有问题这里会直接报出来比盲猜快得多。3.3 发一条测试请求打开 Web UIhttp://127.0.0.1:18790/在对话框里输入一句简单的话比如“你好帮我列一下当前目录的文件”。如果模型正常返回说明 TaoToken 通道打通了。也可以直接用命令行测试openclaw chat 用一句话介绍你自己正常会流式输出模型的回复。如果卡住不动多半是网络或 Key 的问题。3.4 确认请求真的走了 TaoToken想确认请求确实经过 TaoToken可以看 OpenClaw 的日志。日志里会记录每次请求的 provider 和 model。如果看到provider: taotoken就说明配置生效了。另外TaoToken 控制台的用量页面也会显示请求记录。发完测试请求后刷新一下能看到调用次数增加就说明链路完全通了。到这里Windows 本地部署 OpenClaw TaoToken 统一 Key 接入的完整流程就走完了。下面把常见的报错整理一下方便你对照排查。4. OpenClaw 常见报错排查401、local proxy failed、reading choices部署过程中最容易遇到的几个报错我按出现频率排一下每个都给出原因和解决办法。4.1 401 Unauthorized这是最常见的意思是 Key 无效或没传对。检查三件事第一配置文件里的apiKey是不是完整的sk-开头字符串有没有多余空格或换行。第二Key 有没有过期或被删除去 TaoToken 控制台确认。第三如果你用了环境变量引用确认 PowerShell 里$env:TAOTOKEN_API_KEY确实有值echo $env:TAOTOKEN_API_KEY如果输出为空说明环境变量没设上重新设一遍并且要重启 Gateway 才能读到。4.2 local proxy failed这个报错通常出现在 OpenClaw 尝试通过本地代理转发请求时。原因可能是端口被占用或者代理配置指向了一个不存在的地址。先检查 18790 和 18789 端口有没有被别的程序占用netstat -ano | findstr 18790如果有输出记下 PID去任务管理器结束对应进程然后重启 Gateway。另外确认配置文件里没有残留的 proxy 设置有的话删掉。4.3 reading choices 报错这个报错说明 OpenClaw 收到了响应但响应格式里没有choices字段通常是 Base URL 配错了。比如把https://taotoken.net/api写成了https://taotoken.net/api/v1多了一层路径导致返回的不是标准格式。解决办法把 baseUrl 改回https://taotoken.net/api重启 Gateway 再试。4.4 OAuth 相关报错如果你在配置过程中选了需要 OAuth 登录的模型 provider可能会遇到 token 过期或回调失败。最简单的办法是改用 API Key 方式也就是我们上面配的 TaoToken 统一 Key不依赖 OAuth 流程。如果已经配了 OAuth 想切回来把配置文件里对应 provider 的authType改成apiKey填上 TaoToken 的 Key 即可。4.5 模型返回空或超时有时候请求发出去了但模型半天不返回。先确认网络能通curl https://taotoken.net/api如果这个都超时说明网络层有问题。如果 curl 正常但 OpenClaw 超时检查配置文件里的超时设置适当调大{ requestTimeout: 60000 }单位是毫秒60000 就是 60 秒。5. 长期使用建议与 Coding Plan 接入跑通之后如果你打算长期用 OpenClaw 做编码或 Agent 任务可以考虑 TaoToken 的 Coding Plan它在调用频率和模型选择上更灵活适合持续性的开发场景。配置方式和上面一样只是 Key 换成 Coding Plan 对应的 KeyBase URL 不变。在控制台的 Coding Plan 页面可以查看当前套餐和用量。对于需要频繁切换模型的场景建议在openclaw.json的models数组里多列几个模型 ID然后在对话时用命令切换不用每次改配置文件。最后提醒一点OpenClaw 会在本地执行命令和读写文件安全设置别跳过。官方文档里的 security 章节值得花十分钟读一下把不必要的权限关掉避免 Agent 误操作。如果你在配置过程中遇到上面没覆盖的报错可以去 TaoToken 的接入文档页面查对应说明或者在模型对话页面直接问通常能快速定位问题。
1. Windows 本地部署 OpenClaw 到底难在哪Node.js 与 Git 环境准备全流程OpenClaw 是一个能在本地跑起来的开源 AI 助手它和普通聊天机器人的区别在于它能读写文件、执行命令、控制浏览器、整理日程相当于给大模型装上了手脚。适合想在 Windows 上折腾本地 AI Agent、又不想把数据传到云端的开发者。但很多人卡在第一步——环境没配好后面全白搭。我自己在 Windows 11 上从零走了一遍踩过的坑主要集中在 Node.js 版本、Git 缺失、npm 源太慢这三件事上。下面把每一步拆开讲你照着做基本能一次跑通。1.1 为什么必须 Node.js ≥ 22.16 或 24 LTSOpenClaw 的运行时依赖 Node.js官方要求版本 ≥ v24或者 22.16 的 LTS 版本。低于这个版本会在安装依赖时报engine not supported之类的错。我选的是 24.14.0 LTS兼容性目前最稳。去 Node.js 官网下载 Windows Installer.msi双击一路下一步。安装时注意勾选“Add to PATH”否则命令行里找不到 node。装完打开 PowerShell 验证node -v npm -v正常会输出类似v24.14.0和11.x.x。如果提示“不是内部或外部命令”说明 PATH 没配好重新装一遍并确认勾选。1.2 Git 安装与全局配置OpenClaw 的很多技能插件和源码是通过 Git 拉取的没有 Git 会在安装 skills 阶段直接失败。去 Git 官网下载 Windows 版安装时保持默认选项即可重点是“Git from the command line”那一项要选上。装完验证git --version然后配置全局用户名和邮箱不配的话某些仓库克隆会报错git config --global user.name your name git config --global user.email your email1.3 npm 换源加速依赖下载默认 npm 源在国内下载依赖经常超时。换成国内镜像npm config set registry https://registry.npmmirror.com验证是否生效npm config get registry输出https://registry.npmmirror.com就对了。这一步能让你后面装 OpenClaw 的时间从十几分钟缩到两三分钟。1.4 用官方脚本一键安装 OpenClaw官方提供了一键安装脚本会自动检测环境并安装。以管理员身份打开 PowerShell先放开执行策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后清缓存并执行安装npm cache clean --force iwr -useb https://openclaw.ai/install.ps1 | iex安装过程会拉取依赖耐心等。如果卡在某个包不动多半是网络问题可以重跑一次脚本npm 会断点续传。安装完成后你会看到一段健康检查输出里面有 Web UI 地址通常是http://127.0.0.1:18790/和 Gateway WS 地址。把这些记下来后面验证要用。到这里Windows 上的基础环境就算搭好了。下一节讲怎么把 TaoToken 的统一 Key 接进去让 OpenClaw 真正能调用模型。2. TaoToken 统一 Key 接入 OpenClaw配置文件修改与 API 通道设置OpenClaw 本身只是个调度框架真正干活的是背后的大模型。默认它可能让你选某个厂商的模型并填对应 Key但如果你手上有多个模型想切换一个个配 Key 很麻烦。TaoToken 提供统一 Key 和 API 通道一个 Key 就能走多个模型配置也集中在一处。2.1 先拿到 TaoToken 的 API Key打开 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册登录后进入控制台。在 API Keys 页面创建一个新 Key复制保存好后面配置文件里要用。如果你还没想好用什么模型可以先在模型对话页面试几个确认哪个响应速度和效果符合预期再去配 OpenClaw。2.2 找到 OpenClaw 的配置文件OpenClaw 的配置文件默认在C:\Users\你的用户名\.openclaw\openclaw.json如果这个文件不存在先跑一次新手引导openclaw onboard --install-daemon引导过程中会让你选模型、选通讯软件、选搜索引擎等。模型那一步可以先随便选一个后面我们直接改配置文件覆盖。2.3 修改 openclaw.json 接入 TaoToken用记事本或 VS Code 打开openclaw.json找到模型相关的配置段。不同版本字段名可能略有差异核心是三个东西Base URL、API Key、Model ID。下面是一个可复制的配置片段把sk-你的TaoToken密钥替换成你实际的 Key{ models: { default: claude-sonnet-4-20250514, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, models: [ claude-sonnet-4-20250514, gpt-4o, deepseek-chat ] } } } }注意 Base URL 填https://taotoken.net/api不要加多余的路径。Model ID 要和你实际想用的模型名一致写错了会在请求时报model not found。如果你更习惯用环境变量管理 Key也可以在 PowerShell 里设置$env:TAOTOKEN_API_KEYsk-你的TaoToken密钥然后在配置文件里用apiKey: ${TAOTOKEN_API_KEY}引用。这样 Key 不会明文写在文件里相对安全一些。2.4 配置项对照表配置项填写内容说明baseUrlhttps://taotoken.net/apiTaoToken API 通道地址apiKeysk-开头的一串字符控制台创建的 Keydefault模型 ID默认调用的模型models模型 ID 数组可切换的模型列表改完保存配置文件就绪。下一节讲怎么启动并验证请求是否正常返回。3. 启动 OpenClaw 并验证 TaoToken 请求连通性配置改完不代表就能用得实际发一次请求确认链路通了。这一节给你完整的启动命令和验证动作。3.1 重启 Gateway 让配置生效OpenClaw 的 Gateway 是核心进程配置改动后必须重启openclaw gateway restart然后检查状态openclaw status正常会显示 Gateway 运行中以及当前使用的模型和 provider。如果显示gateway timeout说明进程没起来看下一节的排障。3.2 用 doctor 检查配置问题OpenClaw 自带一个诊断命令openclaw doctor它会逐项检查 Node.js 版本、Git、配置文件格式、API Key 是否可读、模型是否可达。如果 TaoToken 的 Key 或 Base URL 有问题这里会直接报出来比盲猜快得多。3.3 发一条测试请求打开 Web UIhttp://127.0.0.1:18790/在对话框里输入一句简单的话比如“你好帮我列一下当前目录的文件”。如果模型正常返回说明 TaoToken 通道打通了。也可以直接用命令行测试openclaw chat 用一句话介绍你自己正常会流式输出模型的回复。如果卡住不动多半是网络或 Key 的问题。3.4 确认请求真的走了 TaoToken想确认请求确实经过 TaoToken可以看 OpenClaw 的日志。日志里会记录每次请求的 provider 和 model。如果看到provider: taotoken就说明配置生效了。另外TaoToken 控制台的用量页面也会显示请求记录。发完测试请求后刷新一下能看到调用次数增加就说明链路完全通了。到这里Windows 本地部署 OpenClaw TaoToken 统一 Key 接入的完整流程就走完了。下面把常见的报错整理一下方便你对照排查。4. OpenClaw 常见报错排查401、local proxy failed、reading choices部署过程中最容易遇到的几个报错我按出现频率排一下每个都给出原因和解决办法。4.1 401 Unauthorized这是最常见的意思是 Key 无效或没传对。检查三件事第一配置文件里的apiKey是不是完整的sk-开头字符串有没有多余空格或换行。第二Key 有没有过期或被删除去 TaoToken 控制台确认。第三如果你用了环境变量引用确认 PowerShell 里$env:TAOTOKEN_API_KEY确实有值echo $env:TAOTOKEN_API_KEY如果输出为空说明环境变量没设上重新设一遍并且要重启 Gateway 才能读到。4.2 local proxy failed这个报错通常出现在 OpenClaw 尝试通过本地代理转发请求时。原因可能是端口被占用或者代理配置指向了一个不存在的地址。先检查 18790 和 18789 端口有没有被别的程序占用netstat -ano | findstr 18790如果有输出记下 PID去任务管理器结束对应进程然后重启 Gateway。另外确认配置文件里没有残留的 proxy 设置有的话删掉。4.3 reading choices 报错这个报错说明 OpenClaw 收到了响应但响应格式里没有choices字段通常是 Base URL 配错了。比如把https://taotoken.net/api写成了https://taotoken.net/api/v1多了一层路径导致返回的不是标准格式。解决办法把 baseUrl 改回https://taotoken.net/api重启 Gateway 再试。4.4 OAuth 相关报错如果你在配置过程中选了需要 OAuth 登录的模型 provider可能会遇到 token 过期或回调失败。最简单的办法是改用 API Key 方式也就是我们上面配的 TaoToken 统一 Key不依赖 OAuth 流程。如果已经配了 OAuth 想切回来把配置文件里对应 provider 的authType改成apiKey填上 TaoToken 的 Key 即可。4.5 模型返回空或超时有时候请求发出去了但模型半天不返回。先确认网络能通curl https://taotoken.net/api如果这个都超时说明网络层有问题。如果 curl 正常但 OpenClaw 超时检查配置文件里的超时设置适当调大{ requestTimeout: 60000 }单位是毫秒60000 就是 60 秒。5. 长期使用建议与 Coding Plan 接入跑通之后如果你打算长期用 OpenClaw 做编码或 Agent 任务可以考虑 TaoToken 的 Coding Plan它在调用频率和模型选择上更灵活适合持续性的开发场景。配置方式和上面一样只是 Key 换成 Coding Plan 对应的 KeyBase URL 不变。在控制台的 Coding Plan 页面可以查看当前套餐和用量。对于需要频繁切换模型的场景建议在openclaw.json的models数组里多列几个模型 ID然后在对话时用命令切换不用每次改配置文件。最后提醒一点OpenClaw 会在本地执行命令和读写文件安全设置别跳过。官方文档里的 security 章节值得花十分钟读一下把不必要的权限关掉避免 Agent 误操作。如果你在配置过程中遇到上面没覆盖的报错可以去 TaoToken 的接入文档页面查对应说明或者在模型对话页面直接问通常能快速定位问题。
