解决 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
# 发现进程存在，但环境变量中没有 DISPLAY

cat /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-reload
systemctl --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/bash
unset SESSION_MANAGER
unset DBUS_SESSION_BUS_ADDRESS

# 设置 DISPLAY
export DISPLAY=:1

# 加载 nvm（新增）
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 启动 dbus
if [ -x /usr/bin/dbus-launch ]; then
    eval $(dbus-launch --sh-syntax --exit-with-session)
fi

# 启动 XFCE
exec startxfce4

重启 VNC：

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

验证结果

1. 浏览器自动化测试

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

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

2. Node 版本验证

在 VNC 终端中运行：

node -v
# 输出：v22.22.1 ✅

总结

关键知识点

1. systemd 用户服务 vs 系统服务

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

2. DISPLAY 环境变量

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

3. nvm 加载时机

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

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