从一台空白电脑
到你自己的 AI 产品

用飞书 App 扫终端里的二维码，它会自动帮你建好机器人。 这个方式会把私聊锁定到你自己的账号，别人找不到这个机器人 —— 自己用的话这样最省事，也最安全。

国内版飞书 App 扫码没反应是已知情况。 遇到的话不用纠结，直接重跑一次命令改选方式 B。

去飞书开放平台 open.feishu.cn （国内直接能打开），登录后：

1. 创建一个「企业自建应用」，随便起个名字
2. 在「凭证与基础信息」页面复制 App ID 和 App Secret
3. 在「权限管理」里开通这四个权限：

im:message
im:chat
contact:user.base:readonly
contact:contact.base:readonly

4. 在「事件与回调」里，订阅方式选 「使用长连接接收事件」（千万别选 webhook， 那个要公网地址），然后添加事件 im.message.receive_v1
5. 在「版本管理与发布」里创建版本并发布， 等管理员审核通过（自己是管理员的话直接通过）
6. 回到终端，把 App ID 和 App Secret 粘进向导

已经 npm config set registry 了，安装依然卡住 / 超时 / 报错

先跑这段自检，它会一次性把所有可能出问题的地方打出来。 把输出对照下面几条看，基本能定位到具体原因。

echo "1. 当前源:      $(npm config get registry)"
echo "2. 代理残留:    $(npm config get proxy) / $(npm config get https-proxy)"
echo "3. URL改写:     $(npm config get replace-registry-host)"
echo -n "4. 元数据域名:  "; curl -s -o /dev/null -w "%{http_code}\n" -m 15 \
  https://registry.npmmirror.com/openclaw/latest
echo -n "5. 包体CDN:     "; curl -s -r 0-99 -o /dev/null -w "%{http_code}\n" -m 15 \
  https://cdn.npmmirror.com/packages/openclaw/2026.7.1-2/openclaw-2026.7.1-2.tgz
echo "6. 剩余空间:    $(df -h ~ | tail -1 | awk '{print $4}')"

echo "1. 当前源:      $(npm config get registry)"
echo "2. 代理残留:    $(npm config get proxy) / $(npm config get https-proxy)"
echo "3. URL改写:     $(npm config get replace-registry-host)"
echo -n "4. 元数据域名:  "; curl -s -o /dev/null -w "%{http_code}\n" -m 15 \
  https://registry.npmmirror.com/openclaw/latest
echo -n "5. 包体CDN:     "; curl -s -r 0-99 -o /dev/null -w "%{http_code}\n" -m 15 \
  https://cdn.npmmirror.com/packages/openclaw/2026.7.1-2/openclaw-2026.7.1-2.tgz
echo "6. 剩余空间:    $(df -h ~ | tail -1 | awk '{print $4}')"

"1. 当前源:   " + (npm config get registry)
"2. 代理残留: " + (npm config get proxy) + " / " + (npm config get https-proxy)
"3. URL改写:  " + (npm config get replace-registry-host)
try { "4. 元数据:   " + (iwr https://registry.npmmirror.com/openclaw/latest `
  -UseBasicParsing -TimeoutSec 15).StatusCode } catch { "4. 元数据:   失败" }
try { "5. 包体CDN:  " + (iwr https://cdn.npmmirror.com/packages/openclaw/2026.7.1-2/openclaw-2026.7.1-2.tgz `
  -Method Head -UseBasicParsing -TimeoutSec 15).StatusCode } catch { "5. 包体CDN:  失败" }

1. 当前源:      https://registry.npmmirror.com/
2. 代理残留:    null / null
3. URL改写:     npmjs
4. 元数据域名:  200
5. 包体CDN:     206
6. 剩余空间:    (至少 2G)

下面按出问题的概率从高到低排列：

① 第 1 行显示的还是 npmjs.org —— 源根本没生效
最隐蔽的一种情况是你用了 sudo： sudo 会切换到 root 身份，读的是 root 的配置文件， 你给自己账号配的镜像源完全不起作用。 Mac 用户遇到权限报错后改用 sudo，就会莫名其妙掉进这个坑。

# 两条输出如果不一样，就是它了
npm config get registry
sudo npm config get registry

正确做法不是给 sudo 也配一遍源，而是回到 权限那一条，把 npm 装到用户目录， 从此不再需要 sudo。另外也检查一下当前目录有没有 .npmrc 文件在覆盖你的配置。

正确做法不是给 sudo 也配一遍源，而是按 第 01 步把 Node 装到 ~/.local/node，从此不需要 sudo。 另外检查当前目录有没有 .npmrc 在覆盖配置。

Windows 一般不涉及 sudo。检查一下当前目录有没有 .npmrc 文件在覆盖你的全局配置。

② 第 4 行是 200 但第 5 行失败 —— CDN 被单独拦了
这是很多人误判的地方：npm 取包信息走 registry.npmmirror.com， 但真正下载包体时会跳转到 cdn.npmmirror.com。 部分校园网、公司网只放行了前者。 症状就是「查得到版本、装不下来」。换腾讯云源可以绕开：

npm config set registry https://mirrors.cloud.tencent.com/npm/
npm install -g openclaw@latest

③ 第 2 行不是 null —— 有失效的代理配置残留
以前配过代理、后来代理没了，npm 还在往那个地址发请求。清掉即可：

npm config delete proxy
npm config delete https-proxy
npm cache clean --force
npm install -g openclaw@latest

④ 第 3 行不是 npmjs
OpenClaw 的包里带了一份 npm-shrinkwrap.json， 里面 308 个依赖的下载地址全部写死成 npmjs.org。 npm 默认会自动把它们改写成你配的镜像（这就是 replace-registry-host=npmjs 的作用）。 但如果这项被人改成了 never， npm 就会老老实实去 npmjs.org 拉 308 个包，在国内必然失败。改回来：

npm config set replace-registry-host npmjs

⑤ 报证书错误 —— 校园网／公司网做了 TLS 中间人
典型报错是 SELF_SIGNED_CERT_IN_CHAIN 或 UNABLE_TO_VERIFY_LEAF_SIGNATURE。 正确做法是把单位的根证书加进来，而不是关掉校验。 实在要临时应急，装完记得马上改回来：

npm config set strict-ssl false
npm install -g openclaw@latest
npm config set strict-ssl true

⑥ 网络本身就抖 —— 加大重试
OpenClaw 的包压缩后 20 MB、解压出 87 MB 共 8550 个文件， 比一般的包大不少，弱网下容易中断。让 npm 更耐心一点：

npm config set fetch-retries 5
npm config set fetch-retry-maxtimeout 120000
npm config set maxsockets 3
npm install -g openclaw@latest

maxsockets 调小反而更容易成功 —— 并发少一点，弱网下每条连接更稳。

⑦ 以上都试过还是不行 —— 换台机器打包搬过去
找一台网络正常的机器（或者手机热点），把整棵依赖树打包带走：

npm install openclaw@latest --prefix /tmp/ocbundle \
  --registry https://registry.npmmirror.com
tar -czf openclaw-bundle.tgz -C /tmp/ocbundle .

npm install openclaw@latest --prefix /tmp/ocbundle \
  --registry https://registry.npmmirror.com
tar -czf openclaw-bundle.tgz -C /tmp/ocbundle .

npm install openclaw@latest --prefix C:\ocbundle `
  --registry https://registry.npmmirror.com
Compress-Archive -Path C:\ocbundle\* -DestinationPath openclaw-bundle.zip

注意打包的机器要和目标机器同系统同架构 （Mac 打的包不能给 Windows 用，x86 打的不能给 ARM 用）， 因为里面含有预编译的原生模块。

command not found: node ／ 'node' 不是内部或外部命令

九成是终端没重启。终端只在打开的那一刻读取一次系统路径， 你装 Node.js 之前开的窗口是不知道有新命令的。 完全关掉终端窗口，重新打开一个，再试一次。

Windows 上如果重开还是不行，注销一次账户再登录，或者直接重启电脑。

Mac 上如果重开还是不行，确认安装包真的装完了（有没有中途要密码没输）。

Linux 上原因通常不一样 —— 多半是 PATH 那行没写进去，或者写进了错的文件。 先确认文件本身在不在：ls ~/.local/node/bin/node。 文件在但命令找不到，就是 PATH 的问题。

# 先看自己用的是哪个 shell
echo $SHELL

# bash 用户写这个
echo 'export PATH=$HOME/.local/node/bin:$PATH' >> ~/.bashrc && source ~/.bashrc

# zsh 用户写这个
echo 'export PATH=$HOME/.local/node/bin:$PATH' >> ~/.zshrc && source ~/.zshrc

EACCES: permission denied

Mac 上 Node.js 装在系统目录，普通用户没有写入权限。 推荐的做法不是加 sudo，而是把 npm 的安装位置改到你自己的目录下， 一次设置永久生效，以后装什么包都不会再有权限问题。依次执行这三行：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

然后关掉终端重新打开，再跑一次第 04 步的安装命令。

Windows 上这个报错比较少见。如果遇到， 右键点 PowerShell 图标选「以管理员身份运行」，再执行安装命令。

按第 01 步那样装到 ~/.local/node 的话， 不应该遇到这个报错，因为那个目录本来就属于你。 如果还是报权限错，说明你的 node 其实是系统里另一个（比如 apt 装的）在起作用 —— 跑 which node 看一眼路径， 如果不是 ~/.local/node/bin/node， 回第 01 步重新把 PATH 配好。不要用 sudo npm 硬来。

EBADENGINE / Unsupported engine

你的电脑上原本就有一个旧版 Node.js，而且它的版本落在了 OpenClaw 不支持的区间。 注意这个区间很反直觉 —— Node 23 整个大版本、24.0 到 24.14、25.0 到 25.8 都是不支持的， 不是「版本越新越好」那么简单。

解决办法：回到第 01 步重新下载安装包装一遍， 新版会直接覆盖旧版。装完关掉终端重开，用第 02 步的检查器确认一下。

解决办法：回到第 01 步重新下载安装包装一遍， 新版会直接覆盖旧版。装完关掉终端重开，用第 02 步的检查器确认一下。

解决办法：回到第 01 步把那组命令重新跑一遍。 因为装在 ~/.local/node 并且 PATH 里排在前面， 它会盖过系统里原有的旧版 Node，不用先卸载旧的。 跑完用第 02 步的检查器确认一下。

ETIMEDOUT / ECONNRESET / 进度条长时间静止

先确认第 03 步真的做了 —— 跑 npm config get registry， 必须输出 https://registry.npmmirror.com/。 如果输出的是 registry.npmjs.org，说明换源没生效，重做第 03 步。

源没问题还是慢，清一下缓存重试：

npm cache clean --force
npm install -g openclaw@latest

检查更新时长时间无响应或超时

这是国内环境下唯一一个换源解决不了的地方。 OpenClaw 的「检查新版本」功能把 registry.npmjs.org 写死在了代码里，不读你的镜像配置，所以在国内会卡住。

不影响使用 —— 装插件、装依赖都是走你配的国内源， 只有这个版本检查会卡。想升级 OpenClaw 的话别用它自带的更新命令， 直接用 npm 装一遍就行：

npm install -g openclaw@latest
openclaw gateway restart

DEEPSEEK_API_KEY is not set / 模型不可用

典型症状是刚配好能用，重启电脑或重启服务后就不行了。 原因是 Key 只存在于你当时那个终端窗口的环境变量里， 后台守护进程读不到。写进配置文件就永久生效：

echo 'DEEPSEEK_API_KEY=sk-你的key' >> ~/.openclaw/.env
openclaw gateway restart

在飞书里发消息，机器人毫无反应

按顺序排查这五条，绝大多数问题出在第 1、2 条：

1. 应用在飞书开放平台发布了吗、审核通过了吗？ 只创建不发布是不会生效的
2. 事件订阅方式选的是「长连接」吗？ 选成 webhook 的话需要公网地址，家用电脑收不到
3. 事件里加了 im.message.receive_v1 吗
4. 四个权限都开通了吗
5. 网关在跑吗：openclaw gateway status

openclaw logs --follow

群里不回复是另一回事：默认必须 @ 机器人， 而且群要在白名单里。先确认机器人已被拉进群，并且你 @ 了它。

plugins list 显示已安装，但 channels status 不通

先确认插件真的被启用了（安装和启用是两件事）：

openclaw plugins list
openclaw channels status --probe

openclaw config set plugins.entries.openclaw-weixin.enabled true
openclaw gateway restart

如果启用微信后网关开始反复重启， 把 OpenClaw 和插件都更新到最新再试：

npm install -g openclaw@latest
openclaw plugins install "@tencent-weixin/openclaw-weixin" --force
openclaw gateway restart

No matching version found for openclaw@…

国内镜像是按需同步的，官方刚发布的版本可能要等一会儿才会出现。 你可以手动催它同步，把下面这行粘进终端：

curl -X PUT https://registry.npmmirror.com/-/package/openclaw/syncs

会返回一段 {"ok":true,...}， 等十几秒再重新执行安装命令即可。