一、系统环境类

1.1 VMware 虚拟机双向剪贴板失效

关键词：复制粘贴失效、open-vm-tools、vmtoolsd 异常问题现象：

• 宿主机与虚拟机无法互相复制文字和文件
• 长期运行后剪贴功能突然失效

根本原因：

• 虚拟化工具未完整安装
• vmtoolsd 服务异常终止

解决步骤：

sudo apt install open-vm-tools open-vm-tools-desktop -ysudo systemctl restart vmtoolsd

1.2 虚拟机内存不足、进程 OOM 被杀

关键词：memory limit exceeded、系统卡顿、OOM、killed问题现象：

• OpenClaw 闪退，后台进程莫名消失
• 虚拟机终端卡顿，多软件运行卡死

根本原因：

• VMware 硬件资源分配过低
• 未配置 swap 分区
• 内存溢出直接杀死进程

解决步骤：

# 创建 4GB 的 Swap 交换文件并启用它，缓解物理内存不足sudo fallocate -l 4G /swapfilesudo chmod 600 /swapfilesudo mkswap /swapfilesudo swapon /swapfile

1.3 Snap 后台高占用

关键词：snapd、高 CPU、后台静默更新、磁盘冗余问题现象：

• 系统后台占用过高，磁盘空间减少
• 隐性拖慢 OpenClaw 运行流畅度

根本原因：Ubuntu 22 默认预装 Snap，自动更新服务常驻后台，会消耗资源

解决步骤：

# 移除并屏蔽 snapdsudo apt remove --purge snapd -ysudo systemctl mask snapd# 以上操作默认会删除 firefox，若需要，可通过以下方式安装sudo apt install firefox

1.4 DNS 解析失败，插件联网异常

关键词：dns resolve failed、域名解析失败、getaddrinfo问题现象：

• 联网插件，其 API 请求无法访问外网
• 虚拟机环境下域名打不开，网络请求报错

根本原因：系统默认的 DNS 不稳定，NAT 网络模式导致解析转发异常

解决步骤：

# 临时修改系统 DNS（重启电脑会失效）echo "nameserver 223.5.5.5" | sudo tee /etc/resolv.conf

二、依赖类

2.1 Node 版本不兼容

关键词：node: command not found、requires node ≥ 22、unsupported node version问题现象：

• 执行 OpenClaw 命令，提示 node: command not found
• 启动或安装时提示 Node 版本不满足要求

根本原因：

• Ubuntu 22 默认 Node 版本过低
• 没有安装 OpenClaw 要求的版本

解决步骤：

# 安装 nvm 版本管理工具curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bashsource ~/.bashrc# 安装并切换到 Node 22 版本nvm install 22nvm use 22# 验证版本node --version

2.2 npm 下载依赖超时

关键词：network timeout、registry error、fetch failed问题现象：

• npm install 长时间卡住，无法下载依赖包
• 下载中断，提示网络超时，fetch 失败

根本原因：npm 默认使用官方源，国内访问速度慢，不稳定，导致依赖下载超时

解决步骤：

# 切换到国内源，并彻底清理、重装项目依赖npm config set registry https://registry.npmmirror.com/npm cache clean --forcerm -rf node_modules package-lock.json && npm install

2.3 npm EACCES 权限不足

关键词：EACCES、permission denied、mkdir permission问题现象：

• 全局安装 npm 包时，提示权限不足
• 无法写入 npm 全局目录，安装进程中断

根本原因：npm 默认全局目录归属 root 用户，普通用户无写入权限，误用 sudo npm 会导致权限混乱

解决步骤：

# 配置属于当前用户的、无权限困扰的 npm 全局包环境mkdir -p ~/.global-npmnpm config set prefix '~/.global-npm'echo 'export PATH=~/.global-npm/bin:(date +%Y-%m-%d)# 临时清空 openclaw 当天的日志文件truncate -s 0 "/tmp/openclaw/openclaw-(date +%Y%m%d)# 4. 运行官方升级脚本curl -fsSL https://openclaw.ai/install.sh | bash# 5. 升级后，运行 doctor 自动修复配置openclaw doctor --fix# 6. 重启网关openclaw gateway restart# 7. 验证功能openclaw health

8.2 卸载不彻底，导致重装冲突

关键词：conflict file exists、residual config、残留文件、重装失败问题现象：

• 执行 openclaw uninstall 卸载后，重装时提示文件冲突
• 残留的配置文件、缓存文件导致重装失败

根本原因：

• 仅卸载 OpenClaw 的 npm 包，未清理用户目录下隐藏的配置文件和全局缓存
• 残留文件与新安装文件产生冲突

解决步骤：

# 1. 方法一：一键彻底卸载，自动处理所有残留openclaw uninstall --all --yes# 2. 方法二：手动卸载openclaw gateway stopopenclaw gateway uninstallnpm uninstall -g openclawrm -rf ~/.openclaw ~/.cache/openclawnpm cache clean --forcerm -rf ~/lib/node_modules/openclaw# 3. 确认是否卸载干净openclaw --versionls -la ~/.openclaw# 4. 重装npm install -g openclaw

九、其它

9.1 NodeSource 脚本无法识别，文件类型报错

关键词：setup_22.x、不支持该文件类型、文件无法识别问题现象：

• 执行 NodeSource 安装脚本时，提示“当前不支持该文件类型，请尝试其他文件”
• 脚本无法执行，无法通过该方式安装 Node 22

根本原因：

• 脚本文件下载不完整，文件格式错误
• 系统缺少 curl / wget 工具，导致无法识别脚本类型

解决步骤：

# 1. 安装 curl 工具（若未安装）sudo apt update && sudo apt install curl -y# 2. 重新执行 NodeSource 安装脚本curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -# 3. 安装 Node.jssudo apt install -y nodejs# 4. 验证安装node -v   # 应显示 v22.x.x

本文为原创技术实操记录，部分内容由 AI 辅助生成，已由作者深度校验与优化。文中操作仅用于技术学习交流，使用前请做好数据备份，谨慎部署，相关风险由使用者自行承担。

⚠️ 风险提示：OpenClaw 具有完整的系统访问权限，能够读写文件、执行命令。建议安装来源可信的 Skills，并定期审查已安装的技能