1. Windows 11 上 OpenClaw 到底是什么为什么值得装如果你最近在折腾本地 AI 智能体大概率刷到过 OpenClaw 这个名字。它是一款开源 AI 智能体执行框架社区里因为图标是只龙虾习惯叫它「小龙虾」。它跟 ChatGPT 这类聊天机器人最大的区别在于聊天机器人只负责「说」OpenClaw 负责「做」——它能理解你的自然语言指令然后真的去操作你的电脑整理文件、填表单、跑工作流、在多个消息平台之间转发消息。我第一次接触它的时候最直观的感受是这东西不是大模型本身而是给大模型装上了手脚。你本地跑一个 Gateway 服务它把 Telegram、Discord、飞书、企微这些渠道统一接进来再通过你配置的模型通道去调用大模型做决策最后落到真实动作上。整个过程数据留在你自己的设备里隐私可控。那为什么要在 Windows 11 上装因为大部分开发者的主力机就是 Windows 11而 OpenClaw 官方文档对 Windows 的支持描述相对简略很多依赖项Node.js 版本、C 编译工具链、sharp 模块在 Windows 上踩坑概率比 Linux 高不少。这篇教程就是把我自己在 Windows 11 上从零部署 OpenClaw 的完整过程拆开包括环境检查、依赖安装、配置初始化以及最后怎么通过 TaoToken 统一 Key 和 API 通道完成模型接入并用一次真实对话请求验证安装成功。适合谁看第一次在 Windows 11 上部署 OpenClaw 的开发者已经装过但卡在依赖或模型接入环节的人想用统一 API 通道管理多个模型 Key 的人。如果你只是想随便体验一下也可以跟着走命令都是可复制的。先说结论整个流程分四块——系统环境检查、依赖软件安装、OpenClaw 本体安装与初始化、模型通道接入与验证。其中最容易出问题的是依赖版本和编译工具链我会在对应章节把报错和解决办法写清楚。2. 装 OpenClaw 前Windows 11 环境与依赖怎么准备这一章是整篇教程的地基。很多人装 OpenClaw 失败不是 OpenClaw 本身的问题而是前置依赖没到位。我按「系统要求 → 依赖清单 → 逐个安装」的顺序来。2.1 Windows 11 系统要求核对先确认你的机器达标。OpenClaw 本身不重但它要编译原生模块、跑本地服务内存和磁盘要给够。配置项最低要求推荐配置操作系统Windows 11 64 位Windows 11 22H2 64 位处理器双核 2GHz 以上四核 3GHz 以上内存8GB RAM16GB RAM 以上磁盘空间20GB 可用50GB SSD网络稳定互联网连接宽带Windows 10 也能装但本教程针对 Windows 11 优化命令和路径都以 Win11 为准。检查系统版本可以在 PowerShell 里跑winver会弹出一个窗口显示版本号。确认是 64 位系统内存建议 16GB 起步因为编译阶段 Node.js 比较吃内存。2.2 必要依赖软件清单OpenClaw 在 Windows 上依赖这几个东西缺一不可软件最低版本推荐版本Node.jsv22.16.0v24.x LTSGit2.30最新版Visual Studio Build Tools20222022Python3.103.11pnpm8.0随 Node.js 安装Node.js 版本要求特别严格v22.16 以下直接会导致安装失败这点后面会反复强调。2.3 逐个安装依赖Node.js 安装Node.js 是 OpenClaw 运行的核心环境。去 Node.js 官网下载 Windows Installer.msi64 位版本选 v24.x LTS。双击运行安装向导里务必勾选「Automatically install the necessary tools」这个选项它会顺带装一些编译辅助工具。装完重启电脑然后验证node --version npm --version正常应该显示 v24.x.x 和 10.x.x。如果显示 v20 或更低说明你系统里还有旧版本需要先卸载再装。Git 安装去 Git 官网下载 64-bit Git for Windows Setup运行安装程序全部默认设置即可。验证git --versionVisual Studio Build Tools 安装这是最容易被忽略但最关键的一步用于编译原生 C 模块。去 Visual Studio 官网下载「Build Tools for Visual Studio 2022」运行安装程序勾选「使用 C 的桌面开发」工作负载右侧详细组件里确保勾选MSVC v143 - VS 2022 C x64/x86 生成工具Windows 11 SDKC CMake 工具也可以用 winget 快速装管理员 PowerShellwinget install Microsoft.VisualStudio.2022.BuildTools装完大约 5-10 分钟耐心等。Python 安装去 Python 官网下载 3.11.x3.12 也行。安装时务必勾选「Add Python to PATH」然后选「Install Now」。验证python --versionpnpm 安装pnpm 比 npm 更快、更省磁盘。用管理员 PowerShell 装npm install -g pnpm配置国内镜像加速下载pnpm config set registry https://registry.npmmirror.com npm config set registry https://registry.npmmirror.com验证pnpm --version到这里前置依赖就齐了。我建议每装完一个就验证一次别攒到最后一起查不然出问题不好定位。3. OpenClaw 安装与 TaoToken 接入的可复制配置这一章是核心操作。OpenClaw 有两种安装方式一键脚本和源码编译。新手用一键脚本开发者用源码编译。我两种都写你按需选。3.1 方式一一键脚本安装推荐新手先以管理员身份打开 PowerShell开始菜单搜索「PowerShell」右键「Windows PowerShell」选「以管理员身份运行」。配置执行策略允许运行脚本Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned提示时输入 Y 确认。然后运行一键安装脚本iwr -useb https://openclaw.ai/install.ps1 | iex等待 2-5 分钟脚本会自动检测并配置环境。3.2 方式二源码编译安装推荐开发者适合需要自定义修改或二次开发的用户。# 创建安装目录 mkdir C:\openclaw cd C:\openclaw # 克隆官方仓库 git clone https://github.com/openclaw/openclaw.git . # 安装依赖 pnpm install # 构建前端 UI pnpm ui:build # 构建核心服务 pnpm build # 创建全局命令链接 npm linkpnpm install大约 3-8 分钟取决于网络。如果卡住先确认镜像配好了。3.3 验证安装与初始化# 检查版本 openclaw --version # 运行系统诊断最重要的验证步骤 openclaw doctoropenclaw doctor会逐项检查环境成功标志是所有检查项显示绿色通过。如果有红色项按提示修复。接着启动引导式配置openclaw onboard向导会引导你选择 AI 模型提供商、输入 API Key、选择消息渠道、设置助手名称。这里先跳过模型 Key 的细节下一节专门讲怎么用 TaoToken 统一接入。3.4 通过 TaoToken 统一 Key 与 API 通道接入模型OpenClaw 支持多种模型提供商但如果你手上有多个模型的 Key一个个配很麻烦。TaoToken 提供统一的 Key 和 API 通道把模型接入收敛到一个入口配置一次就能切换模型。先到 TaoToken 官网注册并创建 API Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content然后在控制台生成 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Key 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 后OpenClaw 的模型配置可以写进配置文件。OpenClaw 的配置目录默认在%USERPROFILE%\.openclaw配置文件是config.json部分版本是settings.json以openclaw doctor提示为准。下面是一个可复制的配置片段把 Base URL、Key、Model ID 三件套都写全{ models: { default: claude-sonnet-4-20250514, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, models: [ claude-sonnet-4-20250514, gpt-4o, qwen-max ] } } } }注意 Base URL 是https://taotoken.net/api不要加多余路径。Key 填你在控制台生成的那串。Model ID 按你实际要用的填上面只是示例。如果你用的是 Claude Code 类的接入方式配置结构类似核心还是 Base URL Key Model ID 三件套。TaoToken 的接入文档里有各客户端的详细配置https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content配置写完后重启 OpenClaw 服务让配置生效openclaw gateway restart3.5 启动服务与访问控制面板# 启动 Gateway 服务 openclaw gateway start # 查看服务状态 openclaw gateway status # 查看运行日志 openclaw logs服务启动后浏览器访问http://localhost:8787就能打开 OpenClaw 的 Web 管理界面。如果 8787 被占用可以改端口$env:OPENCLAW_PORT 8888 openclaw gateway start到这里安装和接入就完成了。下一章验证是否真的能用。4. 验证请求用一次完整对话确认安装成功装完不验证等于没装。这一章用几个递进的测试从命令行对话到实际任务确认 OpenClaw 和 TaoToken 通道都通了。4.1 命令行对话测试最直接的验证方式openclaw chat进入对话模式后输入你好请介绍一下你自己如果 AI 助手正常回复说明模型通道通了。如果报错大概率是 Key 或 Base URL 配错回到上一章检查配置。4.2 系统命令执行测试openclaw exec echo Hello OpenClaw!预期输出Hello OpenClaw!。这一步验证的是 OpenClaw 的执行能力不只是对话。4.3 健康检查openclaw doctor完整系统诊断所有项绿色通过才算真正健康。4.4 实际任务测试在 Web UI 或聊天里发一个真实任务帮我整理下载文件夹按文件类型分类创建文档、图片、视频三个子文件夹然后把对应文件移动进去预期结果是 OpenClaw 自动执行文件整理操作。这一步能跑通说明从模型决策到本地执行的链路完整。再试一个简单计算计算 256 × 1024 等于多少预期返回 262144。4.5 技能测试与服务管理# 查看已安装的技能 openclaw skill list # 运行内置技能示例 openclaw skill run system-info # 安装新技能 openclaw skill install weather常用服务管理命令openclaw gateway start openclaw gateway stop openclaw gateway restart openclaw gateway status openclaw logs -f openclaw update如果以上测试都通过恭喜你OpenClaw 在 Windows 11 上已经完整跑起来了。接下来是排障环节把常见报错和处理方式列清楚。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth这一章按真实报错来。我在部署过程中踩过的坑基本都在这里你对照着查。5.1 401 未授权报错长这样Error: 401 Unauthorized原因通常是 API Key 无效、过期或者 Base URL 写错。检查三件套Base URL 是否为https://taotoken.net/apiKey 是否完整复制有没有多余空格Key 是否在 TaoToken 控制台被禁用或额度耗尽重新生成 Key 后更新配置文件重启服务openclaw gateway restart5.2 local proxy failed报错local proxy failed: connection refused这通常是本地代理或网络配置问题。检查系统代理设置是否干扰了 OpenClaw 的出站请求。如果你之前配过全局代理先关掉再试。另外确认防火墙没有拦截 OpenClaw 进程。5.3 reading choices 报错报错TypeError: Cannot read properties of undefined (reading choices)这是模型返回格式不符合预期。常见原因是 Base URL 指向了错误的端点或者 Model ID 填了一个该通道不支持的模型。确认你用的 Model ID 在 TaoToken 支持的模型列表里Base URL 不要多加/v1之类的路径。5.4 OAuth 相关报错报错OAuth token exchange failed如果你用的是需要 OAuth 的模型提供商检查回调地址和客户端配置。用 TaoToken 统一通道的话一般走 API Key 模式不涉及 OAuth可以绕过这类问题。5.5 Node.js 版本过低报错OpenClaw requires Node.js 22.16.0卸载旧版 Node.js装 v24.x LTS重启电脑后验证。5.6 pnpm install 网络超时pnpm config set registry https://registry.npmmirror.com pnpm store prune pnpm install5.7 sharp 模块编译失败报错node-gyp build failed设置环境变量跳过 libvips 编译$env:SHARP_IGNORE_GLOBAL_LIBVIPS 1 pnpm install永久设置[Environment]::SetEnvironmentVariable(SHARP_IGNORE_GLOBAL_LIBVIPS, 1, User)5.8 缺少 C 编译工具报错MSBUILD : error MSB3428: 未能加载 Visual C 组件 VCBuild.exe确保 Visual Studio Build Tools 装好勾选「使用 C 的桌面开发」工作负载重启 PowerShell 后重试。5.9 权限被拒绝报错EACCES: permission denied以管理员身份运行 PowerShell临时关闭杀毒软件防护检查文件夹权限。5.10 端口 8787 被占用netstat -ano | findstr :8787 taskkill /PID 进程ID /F或者换端口$env:OPENCLAW_PORT 8888 openclaw gateway start5.11 内存溢出报错JavaScript heap out of memory增加 Node.js 内存限制$env:NODE_OPTIONS --max-old-space-size4096 pnpm build排障的核心思路是先跑openclaw doctor它能自动检测大部分环境问题并给出修复建议。模型通道类报错优先查三件套Base URL、Key、Model ID编译类报错优先查工具链和版本。6. 后续怎么用从验证到长期编码与 Agent 场景安装只是起点。OpenClaw 真正的价值在于长期跑起来帮你处理重复性任务。这里给几个实用建议。第一先把模型通道稳定下来。用 TaoToken 统一 Key 的好处是你换模型不用改代码只改配置里的 Model ID。日常对话和轻量任务可以用性价比高的模型复杂编码或 Agent 任务再切到能力更强的模型。如果你打算长期做编码类工作可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content第二数据备份。OpenClaw 的数据默认在%USERPROFILE%\.openclaw定期备份这个目录尤其是你配好的技能和记忆数据。第三关注更新。OpenClaw 迭代很快定期跑openclaw update第四从简单任务开始。别一上来就让它操作生产环境或重要文件。先在下载文件夹、临时目录里试熟悉它的行为模式。第五遇到问题先自诊断openclaw doctor大部分环境问题它能自动检测并给出修复建议。如果你在验证模型连通性时想快速试不同模型的效果可以直接用模型对话页面测https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档在这里各客户端的配置示例都有https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后说个我自己的习惯每次改完配置先跑openclaw gateway restart再跑一次openclaw chat发个「你好」确认通道通了再去做别的。这个动作花不了十秒但能省掉很多「以为配好了其实没生效」的排查时间。