从0到1：OpenClaw避坑实录，这些坑我都踩过了分享关于OpenClaw完整的部署步骤、配置细节。一篇文章讲清楚十个

说是5分钟安装，但我第一次部署OpenClaw，前前后后花了两小时。

不是因为难，而是因为——坑太多。

有些坑是文档没写清楚，有些坑是我自己操作失误，还有些坑是环境配置问题。

总之，踩完一圈坑之后，我决定把这些经验整理出来，帮后来者省点时间。

踩过的这些坑，其实有本手册里都有解决方案。完整的部署步骤、配置细节，可以看《2026OpenClaw完全使用手册》。

坑1：Node.js版本太老

现象

安装依赖时报错：

error: The engine "node" is incompatible with this module.

原因

我的电脑上装的是Node.js 10.x，而OpenClaw要求12.x以上。

解决方案

卸载旧版Node.js
去官网下载最新的LTS版本（18.x）
安装后验证：

node -v  # 应该显示 v18.x.x

教训

安装前先检查Node.js版本。要求是12.x以上，但建议直接用18.x LTS。

坑2：npm镜像源没配置

现象

npm install卡在某个包上，等了半小时都没动静。

原因

国内访问npm官方源速度很慢，有些包还会超时。

解决方案

配置国内镜像源：

npm config set registry https://registry.npmmirror.com

验证配置：

npm config get registry
# 应该显示 https://registry.npmmirror.com

教训

国内用户第一步就该配置镜像源，能省很多时间。

坑3：依赖安装失败

现象

npm install报错：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

原因

依赖冲突，或者缓存损坏。

解决方案

方案1：清除缓存重试

npm cache clean --force
npm install

方案2：使用--legacy-peer-deps

npm install --legacy-peer-deps

方案3：删除node_modules重装

rm -rf node_modules package-lock.json
npm install

教训

遇到依赖问题，先清缓存，再试--legacy-peer-deps，最后删了重装。

坑4：端口被占用

现象

启动项目时报错：

Error: listen EADDRINUSE: address already in use :::3000

原因

3000端口被其他程序占用了。

解决方案

Windows查看端口占用：

netstat -ano | findstr :3000

macOS/Linux查看端口占用：

lsof -i :3000

解决方案：

方案1：关掉占用端口的程序
方案2：修改OpenClaw的启动端口

修改端口方法：

PORT=3001 npm run start

教训

启动前检查端口是否被占用，或者直接换个端口启动。

坑5：DeepSeek API Key配置错误

现象

发送消息后，提示"API调用失败"。

原因

API Key填错了位置。

我的错误是把Key填在了api_key字段，但配置文件里应该是providers.deepseek.api_key。

解决方案

正确的配置结构：

{
    "agents": {
        "defaults": {
            "model": "deepseek-chat"
        }
    },
    "models": {
        "providers": {
            "deepseek": {
                "api_key": "sk-xxxxxxxx",  // 注意这里是正确的位置
                "base_url": "https://api.deepseek.com"
            }
        }
    }
}

教训

配置文件是JSON格式，层级关系很重要。一定要看清楚Key填在哪一层。

坑6：企业微信机器人选错模式

现象

配置完之后，企业微信机器人毫无反应。

原因

创建企业微信机器人的时候，有两种模式：

API模式：给OpenClaw等第三方应用使用
Webhook模式：给自动化工具使用

我选成了Webhook模式，所以OpenClaw接不到消息。

解决方案

重新创建机器人，选择API模式。

教训

企业微信机器人有两种模式，选API模式才能接OpenClaw。

坑7：配置改完忘了保存

现象

明明改了配置，重启后发现配置又变回去了。

原因

改完配置没点保存，直接关了编辑器。

解决方案

改完配置，记得保存文件！

如果是通过界面配置的，记得点"保存"按钮。

教训

配置改完，养成随手保存的习惯。

坑8：API Key泄露

现象

DeepSeek账户突然多了很多异常调用，余额被扣光了。

原因

把配置文件上传到了公开的GitHub仓库，API Key被别人盗用了。

解决方案

立即操作：

登录DeepSeek平台，删除旧Key
生成新Key
更新OpenClaw配置

预防措施：

配置文件不要上传到公开仓库
在.gitignore中添加配置文件路径：

.openclaw/config/

教训

API Key绝对不能泄露！配置文件不要提交到公开仓库。

坑9：权限模式没设置

现象

让OpenClaw帮忙操作文件，结果提示"权限不足"。

原因

默认权限模式是chat，只能对话，不能访问文件。

解决方案

修改权限模式：

{
    "agents": {
        "defaults": {
            "permission": "full"  // 改为full权限
        }
    }
}

权限模式说明：

模式	能力
Full	完全访问权限
Coding	可执行代码，不可访问敏感文件
Chat	仅对话，不可访问文件系统
Minimal	最小权限

教训

如果需要OpenClaw操作文件，要把权限模式改成full或coding。

坑10：忘记重启服务

现象

改了配置，但OpenClaw的行为没有变化。

原因

改了配置文件，但没有重启服务，新配置没生效。

解决方案

改完配置后，重启OpenClaw服务：

# 停止当前服务（Ctrl+C）
# 重新启动
npm run start

教训

配置改动后，必须重启服务才能生效。

总结：避坑指南

坑	症状	解决方案
Node.js版本太老	依赖安装失败	升级到18.x LTS
npm镜像源没配置	安装超时	配置国内镜像源
依赖冲突	安装报错	清缓存或--legacy-peer-deps
端口被占用	启动失败	换端口或关掉占用程序
API Key配置错误	调用失败	检查配置层级
机器人模式选错	企微无响应	选API模式
配置没保存	重启后配置丢失	养成保存习惯
API Key泄露	异常扣费	删除旧Key，新Key保密
权限不足	文件操作失败	改为full权限
没重启服务	配置不生效	改完配置重启

最后

踩完这10个坑，OpenClaw终于跑起来了。

回头看，其实每个坑都不大，但凑在一起就够折腾半天。

把这些坑整理出来，希望后来者能少走弯路。

踩过的这些坑，其实有本手册里都有解决方案。完整的部署步骤、配置细节，可以看《2026OpenClaw完全使用手册》。 另外，我们也推出了免费封装版微盛·企微管家Claw，也欢迎大家领手册时可以顺便测评一波，等大家实测反馈~