Ubuntu虚拟机部署OpenClaw全踩坑实录｜本地访问+模型配置一站式解决

最近在VMware Ubuntu虚拟机上部署OpenClaw智能体平台，全程踩坑无数，从安装权限报错、本地无法访问WebUI、浏览器安全拦截，到模型配置失效、连接失败、端口冲突，几乎把能遇到的问题全碰了一遍。折腾许久终于全部解决，特意整理这份完整避坑指南，包含所有报错现象、原因分析和实操解决方案，照着做一步到位，少走弯路。

环境说明：主机Windows10/11、虚拟机Ubuntu 22.04（VMware）、OpenClaw最新版，目标：本地浏览器访问虚拟机OpenClaw，稳定对接大模型使用

一、安装阶段踩坑：权限报错EACCES

报错现象

执行官方安装命令：

复制代码

env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

直接报错EACCES: permission denied，提示无法创建/usr/lib/node_modules/openclaw目录，权限拒绝。

报错原因

普通用户无权限写入系统级node_modules目录，npm全局安装默认路径为系统目录，普通用户无写入权限。

解决方案

命令前加sudo提权，保留环境变量，一键解决权限问题：

复制代码

sudo env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

安装完成后，可通过openclaw -v验证是否安装成功，无报错则安装完成。

二、启动后本地访问踩坑：全是报错，无法登录

OpenClaw网关启动后，虚拟机内可访问，但本地Windows浏览器访问直接报错，核心踩坑有三个。

坑1：直接访问虚拟机IP，端口不通/连接失败

报错现象

本地浏览器输入http://虚拟机IP:18789，页面无法打开，提示连接超时或无法访问。

原因

Ubuntu未开启SSH服务，网络不通；2. 防火墙未放行18789端口；3. OpenClaw绑定地址为127.0.0.1，仅允许虚拟机本地访问。

解决步骤

Ubuntu安装并开启SSH服务（后续端口转发必备）：sudo apt update && sudo apt install openssh-server -y ``sudo systemctl start ssh ``sudo systemctl enable ssh # 开机自启
放行18789端口：sudo ufw allow 18789 ``sudo ufw reload
修改OpenClaw绑定地址为0.0.0.0，允许外网访问：openclaw config set gateway.bind 0.0.0.0 ``openclaw gateway restart

坑2：登录页报control ui requires device identity

报错现象

页面能打开，但登录后无法进入聊天页，提示：control ui requires device identity (use HTTPS or localhost secure context)。

原因

浏览器安全策略限制，HTTP协议+内网IP访问不属于安全上下文，OpenClaw前端校验拦截，强制要求HTTPS或localhost访问。

踩坑尝试

修改配置文件添加secure: false无效，重启网关也无法解决，单纯关闭安全校验不生效。

坑3：端口转发冲突，直接IP映射失败

报错现象

尝试SSH端口转发，用虚拟机IP直接映射：

复制代码

ssh -L 18789:192.168.222.128:18789 ljw@192.168.222.128

提示端口冲突，转发失败，依然无法访问。

✅ 最终完美解决方案：SSH本地隧道映射（localhost转发）

核心技巧：转发目标必须用localhost，而非虚拟机IP，绕过浏览器安全校验，无冲突、不报错。

本地Windows打开cmd或PowerShell，执行命令：

复制代码

ssh -L 18789:localhost:18789 ljw@192.168.222.128

命令说明：

18789:localhost:18789：本地18789端口映射到虚拟机localhost的18789端口
ljw：Ubuntu虚拟机用户名
192.168.222.128：Ubuntu虚拟机内网IP（通过hostname -I查看）

转发成功后，本地浏览器直接访问：http://localhost:18789，输入设置的token即可正常登录进入聊天页面。

三、模型配置踩坑：连接失败、配置不生效、模型杂乱

这是最耗时的坑，先后尝试DeepSeek、GPT模型都不通，手动改JSON配置完全无效，还出现多余模型干扰界面。

坑1：手动修改openclaw.json配置无效

报错现象

按照教程手动编辑~/.openclaw/openclaw.json，填入API Key和模型信息，重启网关后，WebUI不识别，依然提示无API Key或模型不存在。

原因

手动修改JSON文件格式容易出错，且OpenClaw对配置文件的读取优先级，低于命令行配置，部分参数无法热加载，手动修改极易不生效。

坑2：中转模型无法连接，原生接口不通

报错现象

对接部分中转/代理大模型时，一直提示连接失败、API Key无效，换原生模型也不通，还出现No API key found for provider "anthropic"报错。

原因

OpenClaw默认加载内置模型列表，未配置的模型（如Claude）会自动触发校验，且JSON配置不支持自定义中转接口参数，命令行配置才能适配中转模型。

坑3：WebUI模型列表太多，难以查找

界面展示大量内置模型，自己能用的只有一两个，挑选麻烦，还容易误选导致报错。

✅ 最终完美解决方案：命令行专属配置模型

放弃手动改JSON，用OpenClaw官方命令行配置，支持自定义模型、中转接口，只展示选中的模型，稳定生效。

核心配置命令

复制代码

openclaw configure --section models

配置步骤

执行命令后，按提示依次输入：厂商名称、API Key、接口BaseURL、模型ID
支持自定义中转模型接口，适配非原生API路径
配置到模型选择步骤时，只勾选自己能用的模型，取消其他所有内置模型
配置完成后，重启网关生效：openclaw gateway restart

实操效果

我这边换成智谱AI模型后，通过命令行配置直接连通，WebUI界面只显示自己配置的模型，干净整洁，再也没有多余报错，对话功能完全正常。

四、OpenClaw常用必备命令汇总

复制代码

# 安装（解决权限问题） sudo env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest # 启动/重启网关 openclaw gateway restart # 查看实时日志 openclaw logs --follow # 模型专属配置（推荐，避坑首选） openclaw configure --section models # SSH本地端口转发（本地访问必备） ssh -L 18789:localhost:18789 用户名@虚拟机IP # 修改绑定地址，允许外网访问 openclaw config set gateway.bind 0.0.0.0

五、全程避坑总结

安装必加sudo：普通用户npm全局安装必报权限错，sudo提权一步解决；
本地访问别直接用IP：浏览器安全拦截无解，必须用SSH隧道+localhost转发；
模型配置别手动改JSON ：命令行openclaw configure --section models才是最优解，支持中转模型，配置即生效；
精简模型列表：配置时只选自己能用的，避免内置无效模型触发报错；
Ubuntu提前开启SSH，既是端口转发前提，也方便后续远程操作。

写在最后

OpenClaw部署本身不复杂，大部分问题都是权限、网络安全策略、配置方式不对导致的。本篇全程是实操踩坑后的真实解决方案，没有多余步骤，照着做就能快速部署成功，对接大模型正常使用。如果遇到其他报错，可通过openclaw logs --follow查看实时日志，快速定位问题。

原创不易，转载请注明出处，如有其他问题欢迎评论区交流～