OpenClaw本地部署失败主因是安全软件拦截、路径含中文或Node版本错位；需关闭所有安全防护、使用纯英文无空格路径、确保Node≥v22、准确复制API Key、排查并切换占用端口。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw本地部署报错时，终端反复刷出红色错误信息、程序启动失败、技能安装卡住85%、飞书机器人不响应——这些问题不是配置不到位，而是安全软件拦截、路径含中文、Node版本错位等具体环节出了偏差。
先停掉所有安全软件
打开任务管理器（Ctrl+Shift+Esc），在“启动”和“进程”两个标签页里，彻底关闭360安全卫士、腾讯电脑管家、火绒、Windows Defender实时防护的全部后台进程。Mac用户需在“访达→前往→前往文件夹”中输入/Library/Application Support/com.microsoft.security/，手动停用微软防护模块。
这一步不可跳过。【安全软件会把OpenClaw的键鼠模拟、本地文件读写行为识别为高危操作，直接删除核心exe或拦截dll加载，导致后续所有步骤全盘失效】。项目开源可查，临时关闭仅规避误判，不是放任风险。
检查安装路径是否合规
解压后的OpenClaw文件夹路径必须满足三个硬性条件：纯英文、无空格、不带中文标点。例如：D:\OpenClaw ✅，D:\办公工具\OpenClaw ❌，C:\My OpenClaw! ❌。
Windows用户若已误装在中文路径，不要尝试修改文件夹名——系统注册表和内部配置仍指向旧路径，会导致启动后闪退或技能加载失败。正确做法是：删掉整个文件夹 → 重新解压到E:\AI\OpenClaw这类干净路径 → 再双击启动。
验证Node.js版本是否达标
第一步：打开命令行（Windows用CMD，Mac用终端），输入node -v回车，确认输出为v22.x.x或更高版本。
第二步：如果显示v20.11.1或更低，说明系统正在调用旧版Node。即使你刚装了v22，也可能因nvm或多版本共存导致路径错乱。
第三步：执行where node（Windows）或which node（Mac），查看实际调用路径。若指向C:\Program Files\nodejs\node.exe以外的位置（如nvm缓存目录），需手动删除旧版Node安装目录，并清空环境变量PATH中所有含nodejs的条目，再重装v22官方安装包。
复制API Key必须抓准那一秒
方法一：在飞书/DeepSeek等平台新建API Key时，弹窗内显示的完整密钥字符串只出现一次。必须在弹窗未关闭前，用鼠标拖选整段字符（开头sk-、结尾=都要包含），Ctrl+C复制，立即粘贴到OpenClaw配置界面。页面列表中显示的带省略号的Key不能用。
方法二：若已关掉弹窗，不要试图拼接或猜测隐藏部分——【密钥不可逆推，拼错一个字符就会触发风控拒绝连接】。直接回到API管理页删除该Key，重新生成一条全新的。
端口冲突快速定位与切换
① 打开命令行，输入netstat -ano | findstr :3000（Windows）或lsof -i :3000（Mac），查找占用3000端口的PID。
② 根据PID在任务管理器（Windows）或活动监视器（Mac）中结束对应进程。
③ 若无法终止或不想动其他程序，进入OpenClaw安装目录下的config.yaml文件，将port: 3000改为port: 3001，保存后重启程序即可。
