夜雨聆风无界面服务器部署 OpenClaw 浏览器功能完整指南
📌 前言：最近在自己的飞牛 NAS 服务器上部署 OpenClaw 时，遇到了浏览器功能无法使用的问题。经过一番排查和配置，终于解决了无桌面环境下浏览器运行的难题。本文将完整记录整个排查和配置过程，供后续查阅和分享学习。
📋 环境信息
🔍 问题现象
在飞书群里使用 OpenClaw 的浏览器功能时，一直报错：
抱歉，浏览器目前暂时不可用（网关超时了）查看日志发现经典错误：
[ERROR:ui/ozone/platform/x11/ozone_platform_x11.cc:256]
Missing X server or $DISPLAY问题原因：OpenClaw 尝试启动 Chrome 浏览器，但服务器没有 X11 图形界面，Chrome 无法初始化。
🛠️ 解决方案概述
核心思路：使用 Xvfb (X Virtual Framebuffer) 创建虚拟显示环境
┌─────────────────────────────────────────────────────────┐
│ 无界面服务器 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ OpenClaw │───>│ Xvfb │───>│ Chrome │ │
│ │ Gateway │ │ 虚拟显示 │ │ 无头模式 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └───────────────────┴──────────────────┘ │
│ CDP 9222 │
└─────────────────────────────────────────────────────────┘📦 前置准备
1. 安装必要软件
# 安装 Xvfb (虚拟帧缓冲)
sudo apt update
sudo apt install -y xvfb
# 验证安装
which Xvfb
# 输出：/usr/bin/Xvfb
# 安装 Google Chrome (如果未安装)
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt-get install -f -y
# 验证 Chrome
which google-chrome
# 输出：/usr/bin/google-chrome2. 测试 Xvfb + Chrome 组合
# 测试命令（可以成功启动）
xvfb-run -a google-chrome \
--no-sandbox \
--disable-dev-shm-usage \
--disable-gpu \
--remote-debugging-port=9222 \
--user-data-dir=/tmp/chrome-openclaw \
about:blank &
# 验证 CDP 端点
curl http://127.0.0.1:9222/json/version看到返回 JSON 说明 Chrome 已正常启动！
⚙️ 配置步骤
第一步：启动 Chrome 浏览器服务
# 启动 Chrome（使用 Xvfb 包装）
xvfb-run -a --server-args="-screen 0 1280x1024x24" \
google-chrome \
--no-sandbox \
--disable-dev-shm-usage \
--disable-gpu \
--remote-debugging-port=9222 \
--user-data-dir=/tmp/chrome-openclaw \
--disable-background-networking \
about:blank &
# 验证
curl -s http://127.0.0.1:9222/json/version第二步：配置 OpenClaw
编辑 ~/.openclaw/openclaw.json，添加顶层 browser 配置：
{
"browser": {
"enabled":true,
"cdpUrl": "http://127.0.0.1:9222",
"headless":false
}
}⚠️ 关键点：
• 配置必须放在顶层，不是 sandbox.browser• cdpUrl指向 Chrome 的远程调试端点• headless: false因为我们用 Xvfb 模拟有头环境
第三步：重启 OpenClaw Gateway
# 停止旧进程
pkill -f "openclaw-gateway"
# 使用正确的 Node 版本启动
source ~/.nvm/nvm.sh
nvm use 22
nohup openclaw gateway > /tmp/openclaw-gateway.log 2>&1 &
# 验证
curl http://127.0.0.1:18789/health
# 返回 {"ok":true,"status":"live"} 表示成功第四步：验证浏览器功能
# 检查浏览器服务状态
curl -s http://127.0.0.1:18791/ \
-H "Authorization: Bearer YOUR_TOKEN" | python3 -m json.tool
# 期望输出
{
"enabled": true,
"profile": "openclaw",
"running": true, # ✅ 运行中
"cdpReady": true, # ✅ CDP 就绪
"cdpHttp": true, # ✅ HTTP 可用
"cdpPort": 9222, # ✅ 正确端口
"cdpUrl": "http://127.0.0.1:9222"
}🚀 配置开机自启动
为了让服务器重启后自动恢复服务，创建两个 systemd 服务：
1. Chrome 浏览器服务
sudo tee /etc/systemd/system/openclaw-chrome.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw Chrome Browser (Xvfb)
After=network.target
[Service]
Type=simple
User=Felix
Environment=HOME=/home/Felix
Environment=DISPLAY=:99
ExecStartPre=/bin/sleep 2
ExecStart=/usr/bin/xvfb-run -a --server-args="-screen 0 1280x1024x24" /opt/google/chrome/chrome --no-sandbox --disable-dev-shm-usage --disable-gpu --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-openclaw --disable-background-networking about:blank
ExecStop=/usr/bin/pkill -f "chrome.*--remote-debugging-port=9222" || true
Restart=always
RestartSec=5
TimeoutStartSec=60
[Install]
WantedBy=multi-user.target
EOF2. OpenClaw Gateway 服务
sudo tee /etc/systemd/system/openclaw.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network.target openclaw-chrome.service
Wants=openclaw-chrome.service
[Service]
Type=simple
User=Felix
Environment=HOME=/home/Felix
Environment=DISPLAY=:99
Environment=HTTP_PROXY=http://127.0.0.1:7890
Environment=HTTPS_PROXY=http://127.0.0.1:7890
WorkingDirectory=/home/Felix
ExecStart=/home/Felix/.nvm/versions/node/v22.22.1/bin/openclaw gateway
Restart=always
RestartSec=5
LimitNOFILE=1048576
[Install]
WantedBy=multi-user.target
EOF3. 启用服务
# 重载 systemd 配置
sudo systemctl daemon-reload
# 启用开机自启
sudo systemctl enable openclaw-chrome.service
sudo systemctl enable openclaw.service
# 验证状态
systemctl list-unit-files | grep openclaw
# 应该显示 enabled🔧 常见问题排查
问题 1：Chrome 启动失败
# 查看服务日志
sudo journalctl -u openclaw-chrome.service --no-pager -n 50
# 手动测试启动
xvfb-run -a google-chrome --no-sandbox --remote-debugging-port=9222 about:blank问题 2：CDP 连接超时
# 检查 Chrome 进程
ps aux | grep chrome | grep -v grep
# 检查端口监听
ss -ltnp | grep 9222
# 测试 CDP 端点
curl http://127.0.0.1:9222/json/version问题 3：OpenClaw 配置不生效
# 检查配置文件语法
cat ~/.openclaw/openclaw.json | python3 -m json.tool
# 确认 browser 配置在顶层
cat ~/.openclaw/openclaw.json | python3 -c \
"import sys,json; d=json.load(sys.stdin); print(d.get('browser',{}))"问题 4：浏览器工具仍然超时
可能原因：
1. Chrome 未启动 → 检查服务状态 2. CDP 端口不匹配 → 确认配置是 9222 3. Gateway 未连接 → 重启 gateway
# 完整重启流程
pkill -f "chrome.*9222"
pkill -f "openclaw-gateway"
sleep 2
# 先启动 Chrome
xvfb-run -a google-chrome --no-sandbox --remote-debugging-port=9222 \
--user-data-dir=/tmp/chrome-openclaw &
sleep 5
# 再启动 Gateway
source ~/.nvm/nvm.sh && nvm use 22
nohup openclaw gateway > /tmp/openclaw-gateway.log 2>&1 &📝 配置总结
关键配置文件
~/.openclaw/openclaw.json | |
/etc/systemd/system/openclaw-chrome.service | |
/etc/systemd/system/openclaw.service |
核心参数
服务管理命令
# 启动/停止
sudo systemctl start openclaw-chrome
sudo systemctl stop openclaw-chrome
sudo systemctl start openclaw
sudo systemctl stop openclaw
# 查看状态
sudo systemctl status openclaw-chrome
sudo systemctl status openclaw
# 查看日志
sudo journalctl -u openclaw-chrome -f
sudo journalctl -u openclaw -f🎯 测试验证
在飞书群里发送测试命令：
截图 https://example.com或者：
浏览器打开 https://www.ctrip.com如果返回截图或页面信息，说明配置成功！
📚 参考资料
• OpenClaw 官方文档 • Xvfb 官方文档 • Chrome DevTools Protocol • Playwright 无头浏览器
💡 提示：本文配置同样适用于其他需要浏览器自动化的无头服务器场景，如 Puppeteer、Playwright、Selenium 等工具的部署。
祝部署顺利！ 🎉
