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

解决 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 ✅

总结

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

关键知识点

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 自动生成，记录运维实战经验。