2026 OpenClaw 无图形 Linux Docker：onboard 挂起、pending.json 与 dashboard --no-open 的 headless 验证 Runbook

约 16 分钟阅读 · MACCOME

如果你在无桌面、无浏览器的 Linux 云主机 / VPS 上只用 Docker 跑 OpenClaw，却被向导或 onboard 卡在 pending、日志提示要打开本地浏览器、或 dashboard 在无 DISPLAY 环境下直接失败，本文给你一套可写进变更单的 headless 验收阶梯：先冻结「单轨 compose + 单一 TOKEN 真源」，再用 dashboard --no-open、gateway status/probe、结构化日志替代「肉眼看 Control UI」。与站内三平台安装总览、Windows Docker 排错、Linux systemd+Tunnel 非 Docker、Compose 配对 1006/1008分工；生产常驻可并联SSH 转发六国独占 Gateway。

无图形 Linux Docker 上 OpenClaw 最常见的六类「假故障」

  1. 把「必须弹浏览器」写进验收标准：headless 主机上失败的不是 Gateway，而是验收脚本；应改用 CLI 与日志契约。
  2. onboard 与 compose 双轨并行：两个入口各写一半 pending.json / 环境变量，表现为随机 pending 或 TOKEN 漂移（与 Compose 配对文 的症状同源）。
  3. 未设置 silent 或等价 headless 开关：向导等待交互，进程并不退出，监控却显示「healthy」。
  4. cgroup / 存储驱动与 ulimit 默认值：小规格 VPS 上 Gateway 子进程 OOM 或 fd 耗尽，被误报为 WebSocket 1006。
  5. 公司出口 MITM 或透明代理：镜像层拉取成功但 WebSocket 握手被改写，需对照官方 TLS 要求与内网根证书信任链。
  6. 把 Linux 当 Windows 抄作业：WSL2、Docker Desktop 与 Linux engine 的前置条件完全不同；应回到 doctor 分诊 的「先引擎后业务」顺序。

无图形的价值是攻击面更小、可自动化更强；若验收仍依赖人工点浏览器，只是把图形桌面的混乱换成 SSH 里的混乱。与Docker 生产 Runbook同读时，请把「镜像版本、compose 哈希、TOKEN 注入方式」写进同一工单，否则 headless 只会放大配置漂移。

若团队同时维护 systemd 裸跑 与 Docker 两套拓扑，必须在 README 标明默认真源：哪套用于 CI 镜像集成测试，哪套用于生产；混用主机是最难排障的一类。

维度 无图形 Docker（本稿） Linux systemd + Tunnel（非容器）
复现与升级 镜像 tag + compose 文件可版本化，回滚快 依赖发行版包与单元文件，定制深但镜像化弱
headless 验收 天然适合 --no-open 与容器日志驱动 journald + curl 探针为主，路径与 Docker 不同
网络命名空间 1006/1008 多与 bridge / publish 组合相关 主机网络栈，问题常落在 Tunnel 与本地 bind
与远程常驻 Mac 可把 Gateway 迁到独占机，本机只跑 agent 侧 CLI 同样可迁；差异在运维习惯而非结论
典型误用 在 CI 与生产 compose 分叉却不打标签 把 Tunnel 与 Docker 网关混在同一主机双启
info

提示：社区中常见「将 pending.json 中 silent 设为 true 以跳过阻塞式向导」的做法，在写入流水线前必须与当前 OpenClaw 版本文档核对字段名与语义；版本升级后应做一次回归，避免 silent 失效导致 silent hang。

六步 headless Runbook：从「能 pull 镜像」到「gateway probe 绿」

  1. 冻结单轨入口：选定只通过 compose 或只通过官方 docker-setup 脚本之一完成安装；另一路径仅作只读对照。
  2. 校验引擎与磁盘：docker info、数据根分区空闲、ulimit -n；小规格 VPS 先加 swap 或限并发再谈功能。
  3. 处理 onboard / pending：按文档设置 headless 相关开关；变更后打印 pending 文件哈希进 CI 日志以便审计。
  4. 拉起 Gateway 并只走 CLI 验证：openclaw gateway status → openclaw gateway probe（若版本提供）→ openclaw dashboard --no-open；禁止以「我浏览器里看见了」作为唯一通过条件。
  5. 跑 doctor 并登记豁免：与 安装后 doctor 分诊 对齐字段；豁免项必须带到期日与负责人。
  6. 写回归用例：容器重建后 10 分钟内应重复通过同一脚本；失败则自动打开 incident 并附上 compose 哈希与镜像 digest。
bash
# 示例：仅验证 CLI 与 Gateway（占位符按你们 compose 服务名调整）
docker compose ps
docker compose logs -f --tail=200 openclaw-gateway

openclaw gateway status || true
openclaw dashboard --no-open || true
openclaw doctor --yes || true

三条应写进 SLO 或值班手册的量化口径（阈值按机型替换）

  • 冷启动到首次 probe 成功（G2P）：从 compose up -d 到首次 gateway probe 成功的中位数分钟数；若周环比上升 >40% 且镜像 tag 未变，优先查磁盘与 fd，而不是先升级模型。
  • 无图形主机上「浏览器依赖」步骤计数：目标为 0；任何新增步骤若要求 DISPLAY，应退回产品化改造或拆到仅用于开发档的 compose profile。
  • 双 Gateway 事件：统计同一主机 18789 上双监听或 TOKEN 双源告警次数；连续两周 >0 即应触发架构复盘（与 TOKEN 双源文 对齐）。

为什么「强行给服务器装轻量桌面 + VNC」或「无限重试 onboard 直到运气变好」在 2026 年不划算

轻量桌面增加补丁面与登录会话审计成本；VNC 若暴露到公网更是典型高风险配置。无限重试 onboard 只会把「字段漂移」藏进人肉操作里，无法写进自动化。

当你需要7×24、可审计、与团队 CI 节奏一致的 Gateway，而 headless Linux 更适合做边缘试跑或短期 PoC时，把权威 Gateway 落在独占 Apple Silicon 远程 Mac、用文档化 SSH 转发或尾网收口，往往比在小内存 VPS 上与 cgroup 搏斗更省总拥有成本——MACCOME在六国提供 Mac mini（M4 / M4 Pro）与弹性租期，可与本站多篇 OpenClaw 与远程 Mac Runbook 串联设计；公开档位请先对照节点与租期指南再定拓扑。

收束：headless 验收清单应成为 DOCKER_GATEWAY.md 的一节，而不是口头传说

交付物建议包含：compose 文件版本、镜像 digest、silent/pending 策略、CLI 验证命令输出样例、禁止浏览器依赖的声明。任何不能在第二台无图形机上复现的步骤，都应视为文档未完成。

与 Windows Docker 排错 对照时，记住：验证阶梯一致，宿主与引擎不同；不要混用 Docker Desktop 与 Linux engine 的日志路径假设。

常见问题

无图形服务器上 onboard 一直 pending，一定要装桌面吗？

多数不需要：用 headless 开关与 CLI 验收替代浏览器；并与官方文档核对 pending.json 字段。若计划上生产常驻 Gateway，可先阅读租赁价格说明与帮助中心了解独占节点选项。

Linux Docker 与 systemd+Tunnel 能混在同一台机吗？

技术上可并存，但极易出现双 Gateway / 双 TOKEN 真源；除非分环境档位并写清默认真源，否则不建议。详见 Tunnel Runbook 与 Compose 配对文的分工说明。