遇到问题？按错误消息搜索本页，或按场景分类查找解决方案。
你会看到：运行安装脚本后长时间没有反应，或 npm install 进度条不动。
原因：npm 默认从国外源下载，中国大陆网络访问慢。
解决方案：
# 方法1：使用淘宝镜像源安装（推荐）
npm install -g @qingchencloud/openclaw-zh@latest --registry=https://registry.npmmirror.com
# 方法2：先切换全局镜像源，再安装
npm config set registry https://registry.npmmirror.com
npm install -g @qingchencloud/openclaw-zh@latest如果是 Docker 镜像拉取慢，参考 Docker 部署指南中的镜像加速方案。
你会看到：终端输出类似：
Control UI assets not found. Build them with `pnpm ui:build` (auto-installs UI deps), or run `pnpm ui:dev` during development.原因：你可能安装了原版 openclaw 而不是汉化版，或者安装过程中断导致文件不完整。
解决方案：
# 第1步：卸载所有版本
npm uninstall -g openclaw
npm uninstall -g @qingchencloud/openclaw-zh
# 第2步：清除 npm 缓存
npm cache clean --force
# 第3步：重新安装汉化版
npm install -g @qingchencloud/openclaw-zh@latest
# 第4步：验证安装
openclaw --version如果仍然报错，检查你的 Node.js 版本是否 >= 22：node -v
你会看到：
npm error code 128
npm error An unknown git error occurred
npm error command git --no-replace-objects ls-remote ssh://[email protected]/whiskeysockets/libsignal-node.git
npm error [email protected]: Permission denied (publickey).
npm error fatal: 无法读取远程仓库。原因：OpenClaw 的某个依赖（WhatsApp 连接器）引用了一个 GitHub SSH 地址的子依赖。你的机器上没有配置 GitHub SSH 密钥，npm 无法通过 SSH 协议拉取代码。
解决方案：
# 让 git 自动把 SSH 地址转成 HTTPS（一行命令，永久生效）
git config --global url."https://github.com/".insteadOf ssh://[email protected]/
# 然后重新安装
npm install -g @qingchencloud/openclaw-zh@latest这个配置只影响 ssh://[email protected]/ 开头的地址，不会影响你自己的 SSH 使用。
你会看到：启动时终端输出：
Missing config. Run `openclaw setup` or set gateway.mode=local (or pass --allow-unconfigured).原因：首次运行没有执行初始化，或配置文件被删除。
解决方案：
# 运行初始化向导
openclaw onboard# 在容器内执行初始化
docker exec -it openclaw openclaw setup
# 设置网关模式
docker exec openclaw openclaw config set gateway.mode local
# 重启容器
docker restart openclaw如果遇到 Dashboard 连接问题，请检查以下几点：
关于内网和远程访问的详细配置，请参考远程访问指南。
如果遇到模型配置或对话相关问题，请参考国产模型配置指南。