OpenClaw 是一个功能强大且易于扩展的 AI 助手开发平台，旨在将操作系统打造为 AI 原生环境。近期在 Linux 环境下尝试部署 OpenClaw，过程中遇到不少网络依赖、构建错误及配置问题，现将踩坑经验与解决方案整理如下。
安装方案选择
OpenClaw 支持多种安装方式，包括 npm、pnpm 以及官方的一键脚本。对于国内用户，直接拉取 GitHub 源码往往受网络波动影响较大，容易出现 SSL 超时或 Git 连接失败。
推荐方案：使用 openclaw-cn
经过多次测试，发现直接使用 openclaw-cn 版本能更好地适配国内环境，自动处理部分依赖配置。
pnpm install -g openclaw-cn --registry=https://registry.npmmirror.com
openclaw-cn onboard --install-daemon
若坚持使用原版，建议先升级 Node.js 至较新版本（如 v24），并配置 pnpm 允许构建脚本：
pnpm setup
source /home/skywalk/.bashrc
pnpm add -g openclaw@latest pnpm approve-builds -g
一键安装脚本虽然省心，但需注意磁盘空间。曾有因根分区满导致安装中断的情况，建议预留至少 30GB 空间。
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
启动与远程访问
安装完成后，通过 openclaw onboard 进行初始化配置。默认情况下，网关仅监听本地回环地址（loopback），这意味着无法从局域网其他设备访问 Web 管理面板。
开启局域网访问
如需在局域网内访问，可修改网关绑定配置：
openclaw config set gateway.bind lan
此时服务会监听所有网卡接口。若需更安全的远程访问，推荐使用 SSH 隧道映射到本地端口：
ssh -N -L 18789:127.0.0.1:18789 user@server_ip
随后在浏览器打开 http://localhost:18789/#token=xxx 即可进入控制面板。
配对与授权
首次登录可能提示 pairing required，需在终端执行以下命令完成设备配对：
openclaw devices list
openclaw devices approve <device_id>
常见报错排查
在部署过程中，可能会遇到以下几类典型错误，可根据日志快速定位。
1. 构建失败 (Canvas A2UI)
如果编译过程中出现 ERROR Build failed with 1 error 或 Cannot resolve entry module，通常是依赖缓存问题。尝试清理缓存后重新构建：
pnpm store prune rm -rf node_modules
pnpm install
pnpm build
若仍无效，可尝试强制使用 sudo 权限全局安装：
sudo npm i -g openclaw
2. Git 依赖错误
遇到 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 时，说明某些 Git 托管包需要执行构建脚本但未在白名单中。可在 pnpm-workspace.yaml 中添加相关包名，或直接更新 pnpm 版本。
