解决 OpenClaw 浏览器自动化 DISPLAY 环境问题

记录一次 OpenClaw Gateway 无法连接 X11 显示服务器的排查与解决过程

问题背景

在使用 OpenClaw 的浏览器自动化功能（如 CSDN 文章发布、需要图形界面的网站登录）时，发现浏览器无法正常启动，报错信息提示无法连接 X11 显示服务器。

问题诊断

1. 检查 DISPLAY 环境变量

systemctl show openclaw-gateway | grep DISPLAY# 输出为空，说明 DISPLAY 未设置

2. 确认 VNC 服务状态

ls -la /tmp/.X11-unix/# 输出：srwxrwxrwx 1 root root 0 Mar 25 00:55 X1# 确认 VNC 运行在 :1

3. 检查 OpenClaw Gateway 进程

ps aux | grep openclaw-gateway# 发现进程存在，但环境变量中没有 DISPLAYcat /proc/<PID>/environ | tr'\0''\n' | grep DISPLAY# 输出为空

4. 关键发现

OpenClaw Gateway 是 用户级 systemd 服务（systemctl --user），不是系统级服务！

systemctl --user status openclaw-gateway# 显示：Loaded: /root/.config/systemd/user/openclaw-gateway.service

解决方案

步骤 1：为用户级服务配置 DISPLAY

创建 drop-in 配置文件：

mkdir -p /root/.config/systemd/user/openclaw-gateway.service.d

编辑 /root/.config/systemd/user/openclaw-gateway.service.d/display.conf：

[Service]Environment="DISPLAY=:1"Environment="XAUTHORITY=/root/.Xauthority"

步骤 2：重新加载并重启服务

systemctl --user daemon-reloadsystemctl --user restart openclaw-gateway

步骤 3：验证配置

cat /proc/<PID>/environ | tr'\0''\n' | grep DISPLAY# 输出：DISPLAY=:1 ✅

额外问题：VNC 终端 Node 版本

问题现象

在 VNC 桌面终端中运行 node -v 显示 v18，但系统实际安装的是 v22。

原因分析

VNC 启动的 shell 不会自动加载 .bashrc 中的 nvm 配置。

解决方案

编辑 /root/.vnc/xstartup，添加 nvm 初始化：

#!/bin/bashunset SESSION_MANAGERunset DBUS_SESSION_BUS_ADDRESS# 设置 DISPLAYexport DISPLAY=:1# 加载 nvm（新增）export NVM_DIR="$HOME/.nvm"[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"# 启动 dbusif [ -x /usr/bin/dbus-launch ]; theneval $(dbus-launch --sh-syntax --exit-with-session)fi# 启动 XFCEexec startxfce4

重启 VNC：

vncserver -kill :1vncserver :1 -geometry 1280x800 -depth 24

验证结果

1. 浏览器自动化测试

openclaw browser startopenclaw browser open https://jsdiff.com

✅ 成功！ 浏览器正常启动并打开网页。

2. Node 版本验证

在 VNC 终端中运行：

node -v# 输出：v22.22.1 ✅

总结

问题	原因	解决方案
DISPLAY 未设置	Gateway 是用户级 systemd 服务	在 `~/.config/systemd/user/openclaw-gateway.service.d/` 添加环境变量配置
VNC 终端 Node 版本不对	xstartup 未加载 nvm	在 xstartup 中添加 nvm 初始化

关键知识点

systemd 用户服务 vs 系统服务

用户服务：systemctl --user，配置在 ~/.config/systemd/user/
系统服务：systemctl，配置在 /etc/systemd/system/

DISPLAY 环境变量

X11 图形应用需要 DISPLAY 指向 X 服务器
VNC 通常运行在 :1，对应 /tmp/.X11-unix/X1

nvm 加载时机

.bashrc：交互式 shell
.profile：登录 shell
VNC xstartup：需要手动加载

文章由 OpenClaw 自动生成，记录运维实战经验。