OpenClaw 本地部署：Web 面板调试与大模型集成

OpenClaw 本地部署实践

OpenClaw 是一个功能强大且易于扩展的 AI 助手开发平台，旨在将操作系统打造为 AI 驱动的智能终端。在本地环境部署时，虽然官方文档简洁，但实际落地过程中常遇到依赖构建、网络访问及服务启动等坑点。本文记录了从安装到配置大模型的完整流程及常见问题解决方案。

环境准备与安装

依赖配置

推荐使用 pnpm 进行包管理，相比 npm 能更好地处理构建脚本和依赖树。

1. 初始化 pnpm

   pnpm setup
   source ~/.bashrc
   

2. 全局安装 OpenClaw

   pnpm add -g openclaw@latest pnpm approve-builds -g
   

   注意： approve-builds 用于授权 node-llama-cpp、sharp 等需要编译的模块。首次安装耗时约 5-10 分钟。

3. 一键安装方案 若手动安装遇到依赖问题，可使用官方脚本，但国内网络环境下可能因 GitHub 连接超时失败。

   curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
   

   优化建议： 若遇 SSL 连接超时，可先通过镜像源克隆仓库至用户根目录，再执行安装脚本。

国内适配版本

针对国内网络环境，可直接安装 openclaw-cn 以获取更稳定的依赖源。

pnpm install -g openclaw-cn --registry=https://registry.npmmirror.com
openclaw-cn onboard --install-daemon

服务启动与配置

基础配置

初始化完成后，运行以下命令进入配置向导：

openclaw onboard

根据提示选择 Hooks（如 boot-md, command-logger 等），这将决定 AI 助手的可用能力。

网关绑定与远程访问

默认情况下，网关仅监听本地回环地址 (loopback)，导致无法从局域网其他设备访问。

1. 开启局域网监听

   openclaw config set gateway.bind lan
   

2. SSH 隧道转发 出于安全考虑，推荐通过 SSH 隧道映射到本地端口访问 Web UI：

   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. 构建错误 (Build Failed)

安装过程中若出现 canvas:a2ui:bundle 或 相关报错，通常是依赖缓存或构建工具链问题。