资料核对日期:2026-11-13。本文适用于在 Ubuntu 上部署 OpenClaw Gateway,未做本地安装实测。当前官方内容确认 Gateway 支持 Linux,但没有把所有 Ubuntu 版本视为同一安装基线;选择安装包前,应在 https://docs.openclaw.ai/ 核对当前稳定版本、处理器架构和运行时要求。主分支代码不能替代稳定版本判断。

准备条件

准备一台可进入桌面用户会话的 Ubuntu 主机,并确定要运行本地 Gateway,而不是连接其他计算机上的现有 Gateway。Node 是主要、默认且推荐的运行时;Bun 仅是明确选择后使用的替代运行时,依赖安装应使用 pnpm。

如果选择 AMD64 AppImage,官方说明其构建基线为 Ubuntu 22.04,并要求 glibc 2.35 或更新版本以及提供 GLIBCXX_3.4.30 的 libstdc++。其他架构、Ubuntu 版本及安装包要求应以当前下载页面为准。本文不使用未经当前版本文档确认的 APT 源、npm 全局包名或第三方安装脚本。

安装并启动 Gateway

获取当前稳定版 Linux 桌面应用后启动它。全新环境在没有已保存配置或 Gateway profile 时,会自动进入本地设置;若进入手动设置,选择“On this computer”。该流程会安装缺少的本地前置项,并把 Gateway 作为 systemd 用户服务启动。桌面应用还会安装与发行版匹配的 CLI,不要求预先完成全局 CLI 安装。

如果界面发现已有 Gateway 服务,不要反复执行全新安装。应用会先连接健康的 Gateway,再处理服务操作;安装、启动、停止和重启均委托给 CLI 管理的 systemd 用户服务。服务已停止时,可从托盘选择“Start Gateway”。

预期结果是本地设置完成后打开 Gateway 提供的 Control UI,且界面能够保持连接。随后在 Gateway 主机终端执行:

openclaw gateway status --deep

该命令用于核对当前健康状态。不要把某个未经官方确认的固定字段值、端口或本地网址作为唯一成功标准。

定位日志与诊断信息

出现失败时,先保留桌面应用或 Control UI 显示的原始错误。更新相关故障可进入“Control UI → Settings → Updates”,查看时间、更新前后标识、原因代码、失败步骤和受限的诊断详情;需要更多上下文时再查看 Gateway logs。

当前流程不固定写入某个日志目录,也不假定 systemd unit 名称。应从当前版本的官方故障页面确认日志入口,避免直接套用未经确认的 ~/.openclaw/logs/、固定端口或服务名。Gateway 或代理不可用时,在 Gateway 主机执行:

openclaw triage

诊断只帮助保留和分析故障信息,不会把失败结果变成成功结果,也不会自行证明服务已经恢复。

失败场景:安装后 Gateway 未能启动

如果本地设置结束后 Control UI 无法连接,先记录界面中的失败步骤,不要立即重复安装。执行 openclaw gateway status --deep,确认服务当前健康状况;若 Gateway 仍不可用,再执行 openclaw triage 收集诊断。交互终端会在启动诊断代理前征求明确同意;未同意时仍会保留诊断信息和手动恢复入口。

预期结果是获得可定位到失败阶段的状态或诊断信息。若结果涉及运行时版本、服务所有权或安装目标不一致,应按输出指向的官方恢复步骤处理,再重新检查状态,而不是删除锁文件、修改未知目录权限或重复覆盖安装。

官方参考资料

继续阅读