OpenClaw 的安装步骤本身不复杂，但第一次配置总会在某个地方卡住。

翻了一遍中文版社区的 Issue 记录，90% 的新手卡在的地方高度集中。本文把这 6 个最常见的问题整理出来，每个都给出了具体的排查步骤，按图索骥，基本能解决。

问题一：openclaw 命令找不到

安装完之后执行 openclaw --version，终端提示：

bash: openclaw: command not found
# 或者
'openclaw' 不是内部或外部命令

原因：npm 全局包的安装目录没有加入系统的 PATH 环境变量，终端找不到这个命令。

解决步骤：

先查一下全局包装在哪里：

npm bin -g

会输出一个路径，比如 /usr/local/bin 或 C:\Users\你的用户名\AppData\Roaming\npm。

macOS / Linux：把这个路径加入 PATH。打开终端，执行：

echo 'export PATH="$PATH:$(npm bin -g)"' >> ~/.zshrc
source ~/.zshrc

如果你用的是 bash 而不是 zsh，把 .zshrc 换成 .bashrc。

Windows：右键”此电脑”→ 属性 → 高级系统设置 → 环境变量 → 在”Path”里添加上面查到的路径 → 确定。关闭终端重新打开，再执行命令。

问题二：npm 安装卡住或超时

执行安装命令后，进度条一动不动，或者出现：

npm ERR! network timeout
npm ERR! code ECONNRESET

原因：npm 默认连接的是境外服务器，国内网络访问不稳定。

解决步骤：切换到淘宝镜像源，重新安装：

npm config set registry https://registry.npmmirror.com
npm install -g openclaw-cn

设置一次之后长期生效，之后所有 npm 安装都会走国内镜像。

如果还是慢，可以改用 cnpm：

npm install -g cnpm --registry https://registry.npmmirror.com
cnpm install -g openclaw-cn

问题三：API Key 验证失败

执行 openclaw start 之后，终端显示：

✗ DeepSeek API 连接失败：Invalid API Key
# 或者
✗ API 验证失败，请检查你的 API Key

这个报错看起来明确，但实际触发原因有好几种：

1. Key 复制不完整

最常见。DeepSeek 的 Key 以 sk- 开头，后面跟一长串字符。复制时漏掉开头或结尾，或者前后多了空格，都会导致验证失败。

解决方法：回到 DeepSeek 控制台，重新复制 Key，粘贴到 config.yml 时注意不要有多余空格，引号也不要遗漏：

model:
  provider: deepseek
  api_key: "sk-你的完整Key"    # 注意引号

2. 账号余额不足

新注册的 DeepSeek 账号有免费额度，但如果额度用完又没有充值，API 调用会失败。登录 DeepSeek 控制台，查看余额状态。

3. 网络无法访问 DeepSeek API

少数网络环境会屏蔽 DeepSeek 的 API 域名。可以测试一下：

curl https://api.deepseek.com/v1/models

如果返回超时或连接拒绝，说明是网络问题，考虑换网络环境或配置代理。

问题四：钉钉机器人没有响应

OpenClaw 启动正常，但在钉钉群 @ 机器人之后，没有任何回复。

排查顺序如下：

第一步，确认服务正在运行：

openclaw status

输出 running 才算正常。如果显示 stopped，执行 openclaw start 重启。

第二步，检查 Webhook 地址：

打开 config.yml，确认 webhook 字段的值是完整的 URL，以 https://oapi.dingtalk.com/robot/send?access_token= 开头，后面跟着你的 token。常见错误是复制时漏掉了 URL 的最后一段，或者多了换行符。

第三步，检查加签密钥：

如果你在钉钉里选择了”加签”安全验证（推荐），config.yml 里必须填写对应的 secret，而且要包含开头的 SEC：

platforms:
  dingtalk:
    webhook: https://oapi.dingtalk.com/robot/send?access_token=xxx
    secret: SEC你的加签密钥    # 不要漏掉 SEC

第四步，查看日志：

openclaw logs --tail 50

日志里通常会有具体的报错信息，比如”签名验证失败”或”token 无效”，根据提示处理。

问题五：权限报错（EACCES）

安装时出现：

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules

原因：当前用户没有向系统目录写入文件的权限。

macOS / Linux 解决方法：

方案一，命令前加 sudo（临时提权）：

sudo npm install -g openclaw-cn

方案二，修改 npm 全局目录到用户目录（更推荐，一劳永逸）：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw-cn

Windows 解决方法：

右键 PowerShell 或命令提示符，选”以管理员身份运行”，再执行安装命令。

问题六：启动后端口被占用

执行 openclaw start 时报错：

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

原因：OpenClaw 默认使用 3000 端口，但这个端口已经被其他程序占用。

解决方法一：修改 OpenClaw 使用的端口号，打开 config.yml：

server:
  port: 3001    # 改成任意未被占用的端口

解决方法二：找出占用 3000 端口的程序并关闭。

macOS / Linux：

lsof -i :3000
kill -9 对应的PID

Windows：

netstat -ano | findstr :3000
taskkill /PID 对应的PID /F

以上 6 个问题覆盖了绝大多数新手遇到的情况。如果按步骤操作之后还是解决不了，可以执行 openclaw logs 把完整日志复制下来，到中文版 GitHub 提 Issue，把日志贴上去，通常半天内会有回复。