你已在 Ubuntu/Debian 小内存 VPS 上跑通 OpenClaw Gateway，但一旦启用需要 Chromium 的浏览器类能力，日志里就出现「无显示」「找不到可执行文件」或沙箱相关报错。本文写给要把 无桌面 Linux 当生产 Gateway 的工程师：先用七条清单拆 DISPLAY / Xvfb / browser.executablePath 的隐性假设，再用一张对照表收敛「虚拟帧缓冲 vs 真机显示」的运维成本，最后给出 六步可复现 Runbook（安装依赖、拉起 Xvfb、导出环境、校验配置、接入 systemd/Docker、验收最小用例），并明确与站内 跨平台安装、not ready 排错、观测篇 的分工。
官方文档往往假设你有一台带显示栈的机器；而生产里更常见的是 headless VPS。下面七条把争论从「装个 Chrome 就行」收敛成可签字的风险表。
以为 Gateway 进程会自动继承 shell 里的 DISPLAY：systemd Environment= 未写时，浏览器子进程仍可能落在空显示上。
把 browser.executablePath 配成桌面发行版路径：容器或最小镜像里路径不同，症状表现为「spawn ENOENT」类错误。
忽略字体与 ICU 依赖：无头环境缺字体包时，渲染阶段可能静默失败或超时，看起来像 Gateway「卡住」。
用 root 跑浏览器沙箱：Chromium 常以降级沙箱或拒绝启动回应；应使用专用非特权用户并与 安全加固篇 的最小权限原则对齐。
Xvfb 与 Gateway 启动顺序未写死：竞态下首次工具调用失败、重试后又「自愈」，排障极难稳定复现。
把浏览器内存与模型调用内存混在一个预算里：小内存机器上先 OOM 的很可能是 Chromium，而不是 LLM。
日志只看 Gateway 不看子进程退出码：浏览器闪退会在下游表现为工具超时，需要结合 openclaw logs 与系统 journal 对齐时间线。
这些假设的共同根因，是把「浏览器」当成可选插件，而不是 带操作系统依赖链的运行时。与 MCP 握手篇 分工：MCP 解决工具发现与会话；本文解决 浏览器可执行文件 + 显示栈 的最小闭环。
若你同时跑 Docker 生产 与裸机 systemd，请把「DISPLAY 与 Xvfb 由谁拉起」写进拓扑图，避免两套编排互相抢同一显示号。
没有银弹：你要选的是可复现性与排障表面积。
| 维度 | Xvfb + DISPLAY | 真机/VNC 显示 | 仅 Chromium --headless（无 Xvfb） |
|---|---|---|---|
| 依赖面 | 需维护 Xvfb 进程、显示号、字体包 | 需维护会话、分辨率与人为介入窗口 | 依赖版本对 headless 策略，升级后行为可能漂移 |
| 可复现性 | 高：单元化 systemd 或 compose 可固定环境变量 | 中：受桌面会话与锁屏影响 | 中-高：取决于发行版与沙箱组合 |
| 排障信号 | 清晰：DISPLAY、Xvfb 日志、Chromium stderr | 复杂：GUI 状态与权限弹窗 | 偶发：GPU/ANGLE 相关路径在无 GPU 机器上更易踩坑 |
| 典型适用 | 小内存 VPS、只要截图/自动化类能力 | 强 GUI 或签名弹窗类流程 | 工具链已验证可在该版本裸跑 headless |
「可复现」在这里的含义是：同一套 systemd 单元或 compose 文件，换一台干净 VPS 仍能稳定拉起 Xvfb + Gateway + 浏览器。
与 not ready 篇 联动：若 Gateway 进程尚未稳定监听，先不要叠加浏览器层排错，否则日志会互相污染。
下列顺序强调「先显示栈，再 Gateway，再工具」；命令以 Debian/Ubuntu 系为例，其他发行版请替换包名。
安装 Chromium 与字体依赖：apt install 选择发行版提供的 chromium 或 google-chrome-stable，并补齐 fonts-noto 等常用字体包。
安装 Xvfb：确认 Xvfb :99 -screen 0 1920x1080x24 可手动启动且无端口冲突。
导出 DISPLAY：在运行 Gateway 的同一环境中设置 DISPLAY=:99；systemd 使用 Environment=DISPLAY=:99，Docker 使用 environment 块。
写入 browser.executablePath：用 which chromium 或包安装路径对齐配置，并在配置变更后跑 openclaw doctor（或等价校验）。
用 systemd 或 compose 固定启动顺序：Xvfb 先就绪再启动 Gateway；为 Xvfb 加重启策略与日志落盘。
最小验收：在 Gateway 健康后触发一次仅打开 about:blank 的浏览器工具调用，确认日志无沙箱/显示错误，再放开业务流量。
# 手动验证（维护窗）： Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 chromium --no-sandbox --disable-dev-shm-usage --headless=new --dump-dom about:blank >/tmp/blank.html # 然后以相同 DISPLAY 启动/重启 Gateway（systemd 或 docker compose）
提示：--no-sandbox 仅用于受限诊断环境；生产请回到非 root 用户、最小权限与 networkPolicy 组合收敛暴露面。
与 观测篇 对齐：把 Xvfb 与 Chromium 的 stderr 纳入同一工单时间线，避免「Gateway 绿但工具红」时被误判为模型后端问题。
把下面这张表贴在 on-call 频道，可减少无效 @。若错误已涉及 WebSocket 关闭码，请转 gateway closed(1000) 篇。
cannot open display：检查 DISPLAY 与 Xvfb 是否存活。executablePath ENOENT：检查路径与容器内是否挂载了同一二进制。zygote / sandbox：先确认非特权用户与内核参数，再考虑临时诊断开关。
注意：不要在生产长期保留宽松沙箱参数；诊断结束后应回滚配置并记录变更单，满足审计要求。
Docker 场景下还要核对 /dev/shm 与共享内存大小：过小会导致 Chromium 异常退出，表现为工具间歇性失败。
下列字段用于二线对齐；外发前请脱敏。
/etc/os-release、uname -r，以及 Chromium 主版本号。ss -lxn | grep X11 或等价监听检查结果。dmesg 是否出现 OOM killer。仅把 Gateway 绑在随时可能休眠的个人笔记本上，显示栈与网络都不稳定；纯最小 VPS 又常被浏览器与模型并发顶到 OOM。若你需要长期在线、可合同化的 macOS 或独占算力承载 OpenClaw 与周边工具链，独占远程 Mac通常比「凑合用本机」更稳。相较自建零散机器，NodeMini 的 Mac Mini 云端租赁在固定 SSH、清晰磁盘档位与可复制的节点画像上更利于平台治理；规格与价格见 租赁价格说明，接入见 帮助中心，OpenClaw 系列可从 博客分类 进入。
浏览器层稳定后，建议把本次根因标签写进变更记录，避免下次升级 Chromium 时重复踩同一坑。
DISPLAY 是否指向正在监听的 Xvfb；browser.executablePath 是否与实际二进制一致；systemd/Docker 是否把 DISPLAY 与字体依赖注入 Gateway 进程。需要算力规划见 算力订购。
not ready 聚焦端口、内存、超时与容器启动顺序；本文聚焦浏览器子系统与显示栈。若仍失败，再对照 not ready 篇 与 closed(1000) 篇。
从 博客 OpenClaw 分类进入安装、Docker、systemd、安全、观测与 MCP 篇；需要接入帮助见 帮助中心。