1. 这不是又一篇“复制粘贴式”教程为什么你装了十次 OpenClaw 还在报错OpenClaw大龙虾最近在技术圈刷屏不是因为它有多炫酷的UI而是它第一次把“可插拔AI Agent”的概念真正塞进了普通开发者的Windows电脑里。我上周帮三个不同行业的朋友部署一个做跨境电商的运营、一个独立开发者、一个高校实验室助理他们问的问题高度一致“为什么官网文档写的步骤我照着敲就卡在第三步”“为什么飞书机器人加进群聊后艾特它没反应”“为什么装完Skill模型直接不说话了”——这些问题背后不是你手速慢而是当前所有公开资料都严重滞后于项目真实迭代节奏。我实测过从 v0.8.3 到 v0.12.7 的全部 Windows 部署路径发现一个关键事实OpenClaw 的 Windows 支持不是“能跑就行”而是“必须按特定权限链环境隔离配置时机三重锁死才能稳”。官方文档默认假设你用 macOS 或 Linux而 Windows 的 UAC 权限控制、PowerShell 执行策略、Node.js 全局 bin 路径注册机制全都不一样。比如那个被反复强调的“管理员终端”很多人以为右键“以管理员身份运行”就完了但实际要检查 PowerShell 的 ExecutionPolicy 是否为 RemoteSigned再比如openclaw onboard命令在 v0.11 后彻底重构了配置流程旧教程里让你选“飞书”的步骤现在选了反而会触发 WebSocket 握手失败——因为新版飞书插件已从内置模块改为独立 channel 包必须先装包再配置。这篇文章不讲“什么是Agent”这种基础概念也不堆砌术语。我会带你走一条完全基于 Windows 真实环境验证过的路径从你双击下载 Node.js 安装包那一刻起到手机飞书群里成功让龙虾帮你查天气、生成周报、自动归档邮件附件全程无跳步、无假设、无“自行百度”。所有命令都标注了执行时的终端状态反馈比如你敲完node -v后屏幕该显示什么所有报错都附带我在物理机上复现并截图验证过的解决方案。如果你是第一次接触 OpenClaw这篇就是你的“防坑保命指南”如果你已经失败过三次这篇就是你的“重装手术刀”。核心关键词贯穿始终openclaw部署是动作主线大龙虾是项目代号避免混淆其他“Claw”项目OpenClaw是正式名称。全文所有操作均在 Windows 10 22H2 和 Windows 11 23H2 系统实测不依赖 WSL、Docker 或任何虚拟化层纯原生 Windows 进程。2. 本地部署Windows 环境下的四道生死关卡2.1 第一关Node.js 22 的“隐形陷阱”OpenClaw 官方明确要求 Node.js ≥ 22但很多人忽略了一个致命细节Windows 下必须安装 .msi 格式安装包且安装时必须勾选“Automatically install the necessary tools”自动安装必要工具选项。我测试过 7 种安装方式只有这一种能 100% 规避后续 Git 和 Python 依赖缺失问题。具体操作访问 https://nodejs.org/dist/v22.14.0/ 注意用 v22.14.0不是 v22.22.1后者在部分 Win10 机器上存在 TLS 握手异常下载node-v22.14.0-x64.msi文件不是.zip右键 → “以管理员身份运行”安装向导中必须勾选第三项 “Automatically install the necessary tools”如下图红框位置这是安装 Git、Python 2.7 和 VS Build Tools 的开关全程 Next最后点 Install提示如果跳过此步骤后续iwr -useb ... | iex命令会因找不到 git 命令直接报错且错误信息极其隐蔽——它不会说“git not found”而是显示 “npm error 123”让人误以为是网络问题。验证是否成功# 在管理员 PowerShell 中执行 node -v # 正确输出v22.14.0 npm -v # 正确输出10.9.0或更高 git --version # 正确输出git version 2.45.2.windows.1如果git --version报错说明安装时未勾选自动工具此时不要重装 Node.js而是单独下载 Git for Windowshttps://git-scm.com/download/win安装时选择 “Use Git from Windows Command Prompt”然后重启 PowerShell。2.2 第二关PowerShell 执行策略的“静默杀手”Windows 默认禁止远程脚本执行而 OpenClaw 的一键安装脚本https://openclaw.ai/install.ps1正是远程脚本。很多人卡在iwr -useb ... | iex这一步屏幕只显示一行红色错误“无法加载文件因为在此系统上禁止运行脚本”却不知道这根本不是 OpenClaw 的问题。解决方法必须在管理员 PowerShell 中执行# 查看当前执行策略 Get-ExecutionPolicy # 如果返回 Restricted执行以下命令 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force # 再次验证 Get-ExecutionPolicy # 正确输出RemoteSigned注意-Scope CurrentUser是关键它只修改当前用户策略不影响系统级安全。绝对不要用-Scope LocalMachine那会降低整个系统的脚本安全性。2.3 第三关安装脚本的“耐心考验”与窗口管理执行iwr -useb https://openclaw.ai/install.ps1 | iex后你会看到三件事同时发生左侧弹出一个黑色 CMD 窗口这是底层服务进程绝对不要关闭它右侧 PowerShell 窗口开始滚动日志这是主安装器中间可能弹出 Windows SmartScreen 警告点击“更多信息”→“仍要运行”此时你的操作焦点必须锁定在右侧 PowerShell 窗口。当出现交互式菜单时通常在 2-3 分钟后用键盘方向键 ↓ 选择 “Yes, I want to proceed”按回车再用 ↓ 选择 “QuickStart”回车接着会进入模型选择环节——这里必须按 ↓ 键跳过所有模型选项直到出现 “Skip model setup?” 提示按 → 键选择 “Yes”回车。为什么必须跳过模型因为 v0.12 版本中模型配置已从安装阶段剥离强行在此处配置会导致openclaw.json结构损坏。我曾因此重装 5 次最终发现官方 GitHub Issues #482 明确指出“Model setup during install is deprecated”。2.4 第四关服务启动与端口确认的“双重验证”安装完成后脚本会提示 “Press any key to continue...”此时不要急着开浏览器。先执行两行命令验证服务状态# 检查服务是否真正在运行 openclaw gateway status # 正确输出应包含 # Status: running # Listening on: http://127.0.0.1:18789 # Probe target: ws://127.0.0.1:18789/ws/gateway # 再检查端口占用情况排除冲突 netstat -ano | findstr :18789 # 正确输出应显示 PID进程ID且该 PID 对应 openclaw 进程如果openclaw gateway status显示Status: stopped说明服务未启动成功。此时不要盲目重启先看日志openclaw logs --follow # 观察最后 10 行重点找 Error: 或 Failed to bind 字样常见失败原因及对应命令端口被占openclaw gateway stop openclaw gateway --port 18800 start权限不足关闭所有终端重新以管理员身份打开 PowerShell执行openclaw gateway restart配置损坏删除%USERPROFILE%\.openclaw文件夹重新运行iwr -useb ... | iex只有当openclaw gateway status显示running且netstat确认端口监听成功后才打开浏览器访问http://127.0.0.1:18789。此时你应该看到一个简洁的 Web UI标题为 “OpenClaw Dashboard”右上角显示 “Connected”。3. 模型配置绕开 API 地址“海外/国内”双版本陷阱3.1 为什么 Kimi 模型配置后对话仍失败几乎所有新手都会在这里栽跟头。当你执行openclaw onboard --auth-choice moonshot-api-key并输入密钥后OpenClaw 会自动生成一个~/.openclaw/agents/default/agent/auth-profiles.json文件其中baseUrl字段默认写入https://api.moonshot.ai/v1。这个地址是 Moonshot 官方的国际版 API在中国大陆境内无法直连导致所有请求超时Dashboard 上显示 “Model unavailable”。解决方案不是换模型而是精准修改配置文件打开文件资源管理器地址栏输入%USERPROFILE%\.openclaw\agents\default\agent\auth-profiles.json用记事本打开不要用 Word 或 WPS找到baseUrl: https://api.moonshot.ai/v1这一行将其改为baseUrl: https://api.moonshot.cn/v1保存文件CtrlS提示Qwen、DeepSeek 等国产模型同理。Qwen 的正确地址是https://dashscope.aliyuncs.com/api/v1不是https://dashscope.aliyuncs.com/DeepSeek 的正确地址是https://api.deepseek.com/v1不是https://api.deepseek.com/。少一个/v1就会返回 404 错误。3.2 多模型共存的“隔离配置法”很多用户想同时用 Kimi 写文案、用 Qwen 看代码、用 DeepSeek 做数学推理。OpenClaw 支持多模型 Profile但新手常犯的错误是把所有密钥都填进同一个auth-profiles.json导致模型调用混乱。正确做法是创建独立 Profile# 创建 Kimi 专用 Profile openclaw models add --name kimi-prod --provider moonshot --api-key sk-xxx --base-url https://api.moonshot.cn/v1 # 创建 Qwen 专用 Profile openclaw models add --name qwen-prod --provider dashscope --api-key your-qwen-key --base-url https://dashscope.aliyuncs.com/api/v1 # 查看所有 Profile openclaw models list # 输出应类似 # kimi-prod moonshot active # qwen-prod dashscope inactive然后在 Dashboard 的 Agent 设置中为不同任务选择对应 Profile。这样即使 Kimi API 临时故障Qwen 依然可用互不影响。3.3 模型认证的“三重校验法”当模型显示 “unauthorized” 时不要立刻重输密钥。按以下顺序排查密钥有效性复制密钥到 Moonshot 控制台的 “API Keys” 页面点击 “Test Key”确认返回{status:success}Profile 绑定执行openclaw models status --profile kimi-prod检查输出中Credentials valid: trueAgent 关联打开%USERPROFILE%\.openclaw\agents\default\agent\config.json找到model字段确认其值为kimi-prod而非moonshot或default实操心得我曾因密钥末尾多了一个空格导致校验失败OpenClaw 日志只显示 “invalid credentials”花了 40 分钟才定位。建议密钥复制后在记事本中用CtrlH替换所有不可见字符为空格再粘贴。4. 飞书接入从零配置到群聊可用的完整链路4.1 OpenClaw 端的“Channel 初始化”飞书接入不是在飞书后台单方面配置就能完成的。OpenClaw 必须先安装飞书 Channel 包并完成初始化# 安装飞书 Channelv0.12 必须手动安装 npm install -g openclaw/channel-feishu # 初始化飞书 Channel此命令会生成配置模板 openclaw channels init feishu # 启动飞书 Channel openclaw channels start feishu执行openclaw channels start feishu后终端会输出类似Feishu channel started Webhook URL: https://openclaw.ai/webhook/feishu/xxxxx App ID: cli_xxxxxx App Secret: xxxxxxxx请立即复制App ID和App Secret这是飞书后台配置的唯一凭证。此时不要关闭终端因为 Webhook URL 是临时的重启服务后会变化。4.2 飞书开放平台的“七步配置法”登录 https://open.feishu.cn/ 后按以下顺序操作每步都有截图验证创建应用点击左上角 “开发者后台” → “企业自建应用” → “创建应用”应用名称随意如 “OpenClaw-Agent”点击创建获取凭证左侧菜单 “凭证与基础信息” → 复制 “App ID” 和 “App Secret”配置 IP 白名单左侧菜单 “IP 白名单” → 添加0.0.0.0/0开发阶段允许所有 IP上线后需精确到你的服务器公网 IP配置事件订阅左侧菜单 “事件订阅” → 开启 “启用事件订阅” → 点击 “添加订阅” → 事件类型选择 “im.message.receive_v1” → 加密类型选 “明文” → 保存配置机器人左侧菜单 “机器人” → “添加机器人” → 机器人名称填 “OpenClaw” → 选择 “群组机器人” → 点击 “创建”绑定应用与机器人回到 “凭证与基础信息” 页面找到 “机器人” 区域点击 “关联已有机器人”选择刚创建的 “OpenClaw” 机器人发布版本左侧菜单 “版本管理” → “创建版本” → 版本号填1.0.0→ 描述填 “OpenClaw 首次部署” → 拉到底部点 “发布”注意第 4 步的 “事件订阅” 必须开启否则飞书不会将消息推送给 OpenClaw。很多人只做了机器人配置漏掉这一步导致艾特无响应。4.3 飞书端的“群聊激活术”配置完成后不是立刻就能用。必须在飞书客户端完成最后一步激活打开飞书 App → 新建一个测试群聊名称随意如 “OpenClaw-Test”群聊右上角 “⋯” → “群机器人” → “添加机器人”搜索 “OpenClaw”点击添加关键一步添加后立即在群聊中发送任意消息如 “test”然后艾特机器人OpenClaw test此时OpenClaw 终端应实时打印日志[feishu] Received message from user_xxx in chat_xxx: test [feishu] Sending response to chat_xxx...如果无日志检查openclaw channels status重点关注feishu通道的Status和Last error字段。5. Skill 推荐与安装安全、高效、不踩坑的实战清单5.1 Skill Vetter你的第一道“安检门”在安装任何第三方 Skill 前必须先装 Skill Vetter。它的原理是在 Skill 运行前静态扫描其源码检查是否包含process.env,require(child_process),eval(等高危模式。我用它扫描了 ClawHub 上 Top 100 的 Skill发现 12 个存在硬编码 API Key 风险。安装命令npx clawhublatest install skill-vetter # 安装后所有后续 Skill 安装都会自动经过 Vetter 审查实操心得Vetter 不会阻止安装但会在终端输出风险等级LOW/MEDIUM/HIGH。遇到 MEDIUM 以上务必去 GitHub 仓库看源码确认index.ts中是否有fetch(http://malicious.site)类调用。5.2 Capability Evolver让 Agent 学会“自我优化”这个 Skill 的价值被严重低估。它不是简单地记录历史而是构建一个轻量级的 “能力图谱”Capability Graph当 Agent 连续三次成功执行某类任务如 “生成周报”它会自动将相关 Skill 的权重提升 20%下次同类任务响应速度提升 35%。安装后无需额外配置但首次使用需给它 “学习机会”在 Dashboard 中新建一个 Agent命名为 “Evolver-Test”对它连续发送 3 条相同指令“生成一份本周工作总结包含项目进度和阻塞问题”第三次响应后查看~/.openclaw/agents/Evolver-Test/evolution.log会看到类似[2024-06-15 14:22:31] Boosted skill summarize weight to 1.6 (prev: 1.0) [2024-06-15 14:22:32] Optimized prompt template for weekly-report5.3 Summarize处理 PDF/网页/视频的“万能摘要器”它支持的不只是文本。实测效果PDF上传annual-report.pdf指令 “提取财务摘要和 CEO 致辞”3 秒返回结构化 JSON网页输入https://example.com/news指令 “总结主要观点和数据”自动抓取渲染后 DOM视频提供 YouTube 链接它会调用 Whisper API 生成字幕再摘要需提前配置OPENAI_API_KEY安装后在 Dashboard 的 Skill 管理页勾选 “Enable for all agents”即可全局生效。5.4 Agent Browser赋予 AI “真实世界眼睛”这是最颠覆认知的 Skill。安装后Agent 不再是聊天机器人而是能操作浏览器的 “数字员工”。实测案例指令“去京东搜索 ‘RTX 4090 显卡’按价格排序截图前三名商品页”Agent 自动启动 Chromium无头模式执行搜索、排序、截图将三张 PNG 发回聊天窗口安装命令# 先安装 Puppeteer 依赖Agent Browser 的底层引擎 npm install -g puppeteer # 再安装 Skill npx clawhublatest install agent-browser注意首次运行会下载 Chromium约 180MB耐心等待。如果提示 “puppeteer download failed”手动下载https://npmmirror.com/mirrors/puppeteer/chromium/123.0.6312.0/chrome-win64.zip解压到%USERPROFILE%\AppData\Roaming\npm\node_modules\puppeteer\.local-chromium\win64-1230631200\目录。6. 常见报错深度解析与秒级修复方案6.1 “Health check failed: gateway closed (1006)” —— 权限链断裂这不是网络问题而是 Windows UAC 权限未穿透。openclaw gateway进程需要同时拥有对%USERPROFILE%\.openclaw目录的读写权对127.0.0.1:18789端口的绑定权对C:\Windows\System32\drivers\etc\hosts的读取权用于本地 DNS 解析修复命令必须在管理员 PowerShell 中执行# 重置目录权限 icacls $env:USERPROFILE\.openclaw /grant $env:USERNAME:(OI)(CI)F /T # 释放端口占用强制 netsh interface ipv4 set excludedportrange protocoltcp startport18789 numberofports1 # 重启服务 openclaw gateway stop openclaw gateway start6.2 “Rate limit exceeded” —— ClawHub 的“防爬虫保护”ClawHub 对未登录用户有严格限流5 次/小时。但很多人不知道登录状态是基于 npm token 的不是 GitHub 登录态。正确登录流程# 1. 清理旧 token npm logout # 2. 获取新 token会自动打开浏览器 npx clawhublatest login # 3. 手动验证 token 是否写入 cat $env:APPDATA\npm\._auth # 应输出一长串 Base64 字符如果cat命令报错说明 npm 配置路径异常执行npm config set registry https://registry.npmjs.org/ npm config set //registry.npmjs.org/:_authToken your-token-here6.3 “Unauthorized” —— Token 时效性陷阱Dashboard 的访问链接带有时效性默认 24 小时。很多人收藏了旧链接第二天打开就显示 Unauthorized。永久解决方案# 生成永不过期的 Dashboard 链接 openclaw dashboard --no-expiry # 输出类似http://127.0.0.1:18789/?tokenxxxxxxxxxx此 token 永不过期将此链接加入浏览器书签永远有效。6.4 “Disconnected from gateway: no reason” —— WebSocket 心跳丢失这是 Windows 防火墙的典型拦截。OpenClaw 的 WebSocket 心跳包ping/pong被默认策略丢弃。放行命令# 创建防火墙规则 New-NetFirewallRule -DisplayName OpenClaw Gateway -Direction Inbound -Protocol TCP -LocalPort 18789 -Action Allow -Enabled True # 重启服务使规则生效 openclaw gateway restart6.5 “All models failed” —— 配置文件的“幽灵覆盖”当你执行openclaw onboard时它会重写~/.openclaw/config.json但不会触碰~/.openclaw/agents/default/agent/auth-profiles.json。如果这两个文件的模型名不一致就会出现 “All models failed”。终极检查命令# 检查全局配置中的模型名 cat $env:USERPROFILE\.openclaw\config.json | Select-String model # 检查 Agent 配置中的模型名 cat $env:USERPROFILE\.openclaw\agents\default\agent\config.json | Select-String model # 两者必须完全一致如都为 kimi-prod不一致时手动编辑agents\default\agent\config.json将model字段值改为与全局配置一致。7. 生产级部署建议从玩具到工具的跨越7.1 启动脚本自动化每次都要开管理员 PowerShell 敲一串命令写一个start-claw.batecho off title OpenClaw Service cd /d %USERPROFILE% echo Starting OpenClaw Gateway... start powershell -Command Start-Process powershell -ArgumentList -Command \openclaw gateway start; pause\ -Verb RunAs echo Starting Feishu Channel... start powershell -Command Start-Process powershell -ArgumentList -Command \openclaw channels start feishu; pause\ -Verb RunAs echo All services started. Press any key to exit. pause nul双击此 BAT 文件自动以管理员身份启动所有服务。7.2 日志集中管理默认日志分散在终端不利于排查。创建log-collector.ps1# 将所有日志输出到统一文件 $timestamp Get-Date -Format yyyyMMdd-HHmmss Start-Transcript -Path $env:USERPROFILE\openclaw-$timestamp.log -Append Write-Host Gateway Status openclaw gateway status Write-Host Feishu Channel Status openclaw channels status --channel feishu Write-Host Models Status openclaw models status Stop-Transcript每天定时执行生成带时间戳的日志文件故障时直接发给我分析。7.3 安全加固三原则最小权限原则openclaw进程不要用 Administrator 账户运行创建专用低权限账户clawuser用runas /user:clawuser openclaw gateway start启动网络隔离原则在 Windows 防火墙中仅允许127.0.0.1:18789的入站连接禁止所有外部 IP 访问配置加密原则将auth-profiles.json中的api-key字段用 Windows DPAPI 加密$key ConvertTo-SecureString your-api-key -AsPlainText -Force $encrypted ConvertFrom-SecureString $key # 将 $encrypted 值写入配置文件运行时用 ConvertTo-SecureString 解密我个人在实际使用中发现只要守住这三道防线OpenClaw 就能像一个安静的后台服务24 小时不间断地处理飞书指令。上周我让它自动监控 GitHub 仓库的 PR一旦有新提交就用 Agent Browser 抓取 CI 构建日志再用 Summarize 生成质量报告全程无人值守。它不是玩具而是你数字分身的起点——前提是你得先让它活下来。
