跳转至

Linux 应用

Gateway 在 Linux 上获得完整支持。Node 是主要、默认且推荐的运行时;带有 WAL 重置安全 node:sqlite 的 Bun 1.4+ 构建可以作为显式选择来运行 OpenClaw。依赖安装请使用 pnpm,而不是 Bun。

桌面伴侣

OpenClaw Linux 伴侣是一个用于本地和远程 Gateway 的 Tauri 桌面应用。它:

  • 引导新用户选择本地 Gateway、已发现的远程 Gateway、手动输入的 Gateway URL,或 SSH 隧道
  • 安装 OpenClaw CLI,并在捆绑的 OpenClaw Bun fork 上运行全新的本地安装,无需全局安装 CLI;发布构建会安装其对应的稳定版本,而开发构建会先询问通道
  • 在尝试更改服务之前,先附加到一个健康的 Gateway
  • 将安装、启动、停止和重启操作委托给由 CLI 管理的 systemd 用户服务
  • 发现附近的 Bonjour Gateway,并在路由作用域窗口中打开每个 Control UI,因此多个 Gateway 仪表盘可以保持连接并同时使用
  • 使用其解析后的身份验证 URL 打开由 Gateway 提供的 Control UI
  • 为未配置的本地或远程 Gateway 打开模型设置,发现可用的 AI 访问,并在选择、测试、安装或保存提供商之前等待你的明确操作
  • 在连接新模型后继续进入引导式入门;入门可以导入检测到的 Claude Code、Codex 或 Hermes 记忆到代理工作区(相同的导入之后仍可在 设置 → 导入记忆 下使用)
  • 当窗口关闭时,仍可从系统托盘访问

窗口控件与仪表盘顶行共用。拖动空白标题区域或会话标题可移动窗口,双击可最大化或还原窗口。顶部调整大小边缘下方的细条也可移动窗口。最小化、最大化/还原和关闭位于右上角;窗口边缘仍可调整大小。关闭主窗口后,OpenClaw 仍可在系统托盘中使用。当连接到不支持此布局的旧版 Gateway 时,伴侣会保留系统标题栏。更新 Gateway 以启用统一窗口控件。

本地启动、设置、恢复、Gateway 管理器和快速聊天界面共享浅色和深色样式,并在打开时跟随系统外观变化。连接草稿、凭据可见性和快速聊天回复会保持完整。已连接的仪表盘保留其自身的 Web UI 外观设置。

远程设置和连接设置使用同一个 身份验证 选项来选择令牌或密码。显示凭据 会显示已输入的值;切换类型会清除草稿并遮蔽新字段。按 Enter 或 连接到 Gateway 进行连接。在连接设置中,空白凭据会复用同一端点已保存的凭据。

Chrome 扩展设置

该应用会在启动时以及 CLI 安装后准备本地 Chrome 原生助手。发布构建会复用匹配的 CLI,或在自身的应用数据目录下安装版本匹配的浏览器运行时。此下载不会创建、检查、刷新或重启 Gateway 服务,不会替换其运行时,也不会更改所选的远程连接。它需要互联网连接。

在托盘中选择 设置 Chrome 扩展… 以重试设置,并在原生注册成功后打开官方 Chrome Web Store 列表。Linux 上的 Google Chrome 仍需要在商店中 添加到 Chrome;该应用不使用企业强制安装策略,也不会在每次启动时重新打开商店。启用后,受支持的主机本地设置会自动配对,无需复制凭据。仅远程的桌面连接仍需要此计算机上的浏览器节点,以将其标签页暴露给远程 Gateway。

开发构建使用现有的本地 CLI,而不是下载无关的稳定运行时。Windows Tauri 测试构建不提供此运行时安装程序。有关批准、断开连接和手动恢复,请参阅 Chrome 扩展。

桌面兼容性

Linux 伴侣与原生 macOS 应用和 CI 共享同一个 Bun fork 固定版本。运行时准入、SQLite 安全检查以及该 fork 禁用的隐式包自动安装仍保持启用。macOS Tauri 测试构建保留其现有运行时行为;原生 macOS 应用拥有其独立的捆绑运行时。Windows Tauri 测试构建保留其现有运行时,直到有签名的 Windows fork 可用;未签名的试运行不可发布。请参阅 Bun 兼容性。

已发布的 AMD64 AppImage 在 Ubuntu 22.04 上构建,要求 glibc 2.35 或更高版本,以及提供 GLIBCXX_3.4.30 的 libstdc++。Ubuntu 22.04 和 Debian 12 满足该 ABI 下限。RHEL 9 和 Rocky Linux 9 附带 glibc 2.34,因此无法运行已发布的 AppImage。提取 AppImage 不会绕过此要求。

.deb 安装仍由系统包管理器管理;安装下载内容不会添加 APT 软件源。AppImage 使用签名的应用内更新器。

全局快捷键在 X11 上可用。在 Wayland 上,当桌面提供托盘宿主时,请使用托盘中的 快速聊天 条目;全局快捷键不可用。托盘访问是快捷键的后备方案,而非原生 Wayland 兼容性保证。

该应用外壳不会向其嵌入的 WebKitGTK WebView 授予麦克风捕获权限,因此 getUserMedia 预计会在那里失败。对于 Talk 模式,请在常规浏览器中打开 Gateway 的 Control UI。

桌面应用以 Gateway 操作员身份连接,并使用本地 CLI 将此计算机的桌面共享给其主 Gateway。其应用拥有的节点仅暴露桌面流。其他设备命令属于 CLI 节点主机 及其 Linux Node 插件。

原生 macOS 应用 和 Windows Hub 是独立的应用,而不是此应用外壳的可选 macOS 和 Windows Tauri 测试包。请参阅其平台页面了解要求和功能。

网关选择

从原生应用或托盘菜单打开 网关 → 管理网关…,以保存直接 URL 或 SSH 连接。选择 添加网关 或 编辑 可打开连接表单;返回网关 会返回已保存列表并丢弃未保存的更改。在 身份验证 下,选择令牌或密码,并仅在需要时输入凭据。已保存的凭据保持隐藏;对于同一连接,留空该字段即可保留它们。切换身份验证类型会清除您已输入的凭据。SSH 证书固定位于 高级连接设置 下。

仪表板的个人资料菜单仅切换其当前窗口;Control 单击会打开一个额外窗口。从原生菜单中选择网关会聚焦其现有窗口,而不会重新加载它,而 在新窗口中打开… 会创建一个独立窗口。

主网关继续拥有 Quick Chat 和桌面连接。更改它需要在已保存的令牌身份验证连接上单独进行 设为主网关 确认。其他网关窗口保留其各自的目标。伴侣应用会记住成功的显式选择,当该已保存连接被移除时返回主网关,并将凭据保存在操作系统的凭据存储中。Linux 需要一个已解锁的 Secret Service,例如 GNOME Keyring 或 KWallet 的 Secret Service 支持。

不可用的凭据存储会显示可关闭的通知,而不会阻塞仪表板。已保存的连接保持完整;解决所报告的凭据存储问题后,使用 管理网关… → 重试。

当已保存的网关加载失败时,同一窗口会返回其本地连接编辑器。更正端点后,只有在新仪表板成功加载后才会更新记住的选择。

macOS Tauri 构建版本名为 OpenClaw-Tauri,其已保存的连接与原生 OpenClaw 应用分开保存。

使用捆绑运行时

在 Linux 上,全新的本地设置会通过标准 CLI 在捆绑的 OpenClaw Bun 分支上安装网关。安装保护要求服务仍然不存在。在设置期间出现的服务会阻止该安装。应用的运行时标记仅供参考,绝不会授权自动更改服务。

对于使用其他运行时的任何现有网关,请在托盘菜单中选择 使用捆绑运行时…。这包括 Node、应用更新后的旧版捆绑 Bun 以及操作员选择的运行时。确认对话框会显示当前运行时。CLI 安装会检查服务定义和运行时固定是否仍与您确认的内容一致,然后才切换到当前捆绑的 Bun。如果其中任何一项已更改,该操作将被拒绝。已暂停或已停止的网关会保持停止状态;在切换运行时之前,请选择 启动网关。

应用会在安装后检查网关健康状态。如果失败,它会显示错误以及一条用于返回之前运行时的 CLI 命令。它不会自动恢复运行时。若要返回 Node,如有需要,请安装 受支持的 Node 版本,然后运行:

openclaw gateway install --force --runtime node

若要返回某个特定的之前可执行文件,请使用 openclaw gateway install --force --runtime-path /absolute/path/to/node-or-bun。 CLI 负责服务安装。切换现有网关的运行时不会更改其 CLI 启动器。

启动和应用更新绝不会更改现有网关服务或运行时固定。应用更新后,当前服务会保留其现有运行时,直到您再次选择 使用捆绑运行时…。不可变的应用运行时目录会被保留,因此更新绝不会删除服务引用的运行时。这些操作仅限 Linux;macOS Tauri 保留其现有行为,与 原生 macOS 应用 分开。

桌面共享

打开 设置 → 此电脑 → 功能 → 桌面共享 以更改该设置。macOS Tauri 构建版本将此部分标记为 此 Mac。共享默认启用;已有的 desktop.host.enabled: false 会保持关闭,直到您在应用中显式启用它。您的选择会在应用重启后保留,并且独立于 保持电脑唤醒。

共享需要本地 OpenClaw CLI(即使您的网关是远程的也是如此),以及一个经过身份验证的本地 VNC 服务器。在 macOS 上,请在系统设置中启用 屏幕共享。当被要求时,请在主网关上批准该电脑的桌面功能,然后从 系统 打开其桌面。有关身份验证、配对和升级行为,请参阅 配对节点桌面。

状态行显示应用的桌面进程正在运行还是需要关注。在桌面可以打开之前,配对批准和本地 VNC 服务器也必须就绪。缺少 CLI 或配置无效的错误会显示在此处。关闭共享、更改主网关或退出应用会停止旧的桌面连接。将窗口关闭到托盘会保持共享处于活动状态。

首次运行设置

在欢迎屏幕上选择 开始使用,然后选择您的助手应位于何处:

  • 在此电脑上 会安装任何缺失的本地先决条件,并将网关作为 systemd 用户服务启动。
  • 在另一台电脑上 连接到现有网关。选择一个已发现的网关,在 网关 URL 下输入其地址,或选择 SSH 隧道 并输入 SSH 目标,例如 user@gateway-host。网关端口默认为 18789。

如果远程网关需要身份验证,请展开 网关身份验证 并输入其令牌或密码。使用一种凭据类型,并与远程网关的配置匹配。远程设置不会安装或启动本地网关服务;远程主机拥有其模型、提供商凭据和代理状态。

对于公共直接连接,请使用 HTTPS 或 wss://。普通 HTTP 或 ws:// 应仅限于环回、受信任的私有网络和 Tailnet 主机。当已保存的配置包含 gateway.remote.tlsFingerprint 时,请选择 SSH 隧道 而不是直接连接。嵌入式浏览器无法强制实施证书固定,因此应用会在加载远程仪表板或暴露其凭据之前拒绝直接连接。已保存的远程令牌和密码值可以使用基于环境变量或文件的 SecretRefs;exec 和共享存储引用必须在其所属网关主机上解析。SSH 使用您现有的 OpenSSH 身份验证和主机密钥验证。有关安全的网关配置,请参阅 远程访问。

连接成功后,模型设置会发现所选 Gateway 可用的 AI 访问方式,并将其显示为一个选项。发现过程不会导入或复制账户。在首次访问时,除非你选择相应操作,否则伴侣应用不会选择、测试、安装或保存任何提供商。需要时会提供提供商登录或 API 密钥输入,并且在打开智能体之前必须获得一次成功的模型响应。已配置好的 Gateway 在验证后会打开其正常仪表盘;新配置的访问方式则会继续进入引导式入门流程。

如果 Gateway 确认在保存模型和凭据之前,实时模型测试失败,请关闭错误提示并重试,或选择其他连接。不确定的错误会阻止替换设置,因为设置可能已经保存。已确认的取消以及在设置开始之前被拒绝的请求可以立即重试。

在临时恢复记录有效期间,模型设置可以在 Gateway 重启或应用重新打开后恢复激活流程。恢复流程始终绑定到相同的 Gateway、智能体和身份验证。当已知的激活目标仍与所选模型匹配时,OpenClaw 会在继续引导式入门之前验证该确切模型,而不是再次激活提供商。对于未解决的结果,请使用 验证并使用所选模型 来显式验证并采用已显示的模型,或者等待该设置尝试的限定窗口结束,再选择 再次检查。 在该记录过期、浏览器存储不可用或被清除,或 Gateway、智能体或身份验证发生变化后,不保证能够恢复。

Ollama 自动发现使用已加载到内存中的可用模型,而不是磁盘上安装的所有模型。若要使用一个空闲的已安装模型,请在其 Ollama 卡片上选择 选择连接,然后选择 仅本地。参见 Ollama。

对于 OpenAI,请选择 ChatGPT 登录 以使用 ChatGPT 或 Codex 订阅,或选择 OpenAI API 密钥 以使用 API 计费。浏览器登录会在 Gateway 主机上完成。如果该主机是远程的,或其 localhost 回调无法访问,请改为从其他登录选项中选择 ChatGPT 设备配对;设备配对无需 localhost 回调即可工作。参见 OpenAI 和 OAuth。

当桌面应用启动时,如果其环境中包含受支持的提供商 API 密钥,Gateway 服务会将该专用推理凭据保存在一个仅限所有者访问的环境文件中。提供商管理员密钥、GitHub 令牌以及无关的环境变量不会被复制到服务中。

主机休眠

在原生托盘菜单中选择 保持电脑唤醒,以防止桌面伴侣应用运行时进入空闲休眠,包括其窗口关闭时。该设置默认关闭,并会在应用重启后记住你的选择。关闭该设置或退出 OpenClaw 会释放保持唤醒请求。它不会更改你的永久电源设置,也不会解锁电脑。如果操作系统无法执行已保存的请求,菜单会将已勾选的偏好标记为 未激活 并报告错误。你仍然可以取消勾选以关闭已保存的偏好。

Linux 使用 GNOME 的会话管理器或支持空闲抑制的 xdg-desktop-portal 后端。根据桌面环境的不同,这还可能防止显示器变暗和自动锁定;手动锁定仍然可用。可选的 macOS 和 Windows Tauri 构建会阻止系统空闲休眠,而不会要求显示器保持开启。

在具有 systemd-logind 的系统上,伴侣应用会在主机休眠前为其本地 Gateway 准备一个挂起租约。唤醒后,它会重新连接并恢复 Gateway;远程 Gateway 路由保持不变。如果 logind 或系统总线不可用,休眠钩子会自行禁用,应用继续正常运行。

从 main 或其对应的 release/YYYY.M.PATCH 分支构建的稳定版本,会将 .deb 和 AppImage 包作为该标签的 GitHub 发布 资产发布,文件名为 OpenClaw-<version>-amd64.deb 和 OpenClaw-<version>-amd64.AppImage,旁边还有一个 SHA256SUMS.linux-app.txt 校验和文件。下载 .deb 并使用 sudo apt install ./OpenClaw-<version>-amd64.deb 安装,或将 AppImage 标记为可执行文件并直接运行。AppImage 运行时依赖 FUSE 2(sudo apt install libfuse2,或在 Ubuntu 24.04+ 上使用 libfuse2t64);如果没有它,请使用 APPIMAGE_EXTRACT_AND_RUN=1 运行 AppImage。

常规稳定版发布流程会在 Gateway 版本可见后自动请求 Linux 包。Linux 构建、签名和发布独立完成。在这些包待处理期间,应用更新器会继续通过其原始签名下载提供先前已发布的 Linux 版本。

仅下载包含上述 Linux 包和校验和文件的版本;仅有新的 Gateway 版本并不能证明已有新的 Linux 应用可用。随附的更新器仍使用 releases/latest/download/latest.json。独立的 linux-stable 发布工具不是客户端端点或下载链接迁移。启用该功能需要单独的发布批准和已签名的已安装客户端证明;参见 Linux 伴侣应用发布。

媒体编解码器

伴侣应用使用 GStreamer 插件进行音频和视频播放。 WebM/VP9、Opus、Vorbis 和 WAV 通常通过 plugins-good 正常工作。 H.264/MP4、AAC 和 MP3 需要 libav 和/或 plugins-bad 包。 .deb 使用宿主机的插件,并将所有三个包声明为依赖项。AppImage 捆绑了 GStreamer 媒体框架以及这些格式所需的插件。对于源码构建,或重新构建任一 Linux 包时,请显式安装这些包和检查工具:

sudo apt update && sudo apt install gstreamer1.0-libav gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad gstreamer1.0-tools patchelf xdg-utils unzip

The packaging script stages only that media capability set before Tauri invokes linuxdeploy. This prevents optional host plugins from adding unrelated system libraries to the AppImage dependency closure.

The packaging flow provisions Tauri's five AppImage tools into a clean, digest-pinned cache. After Tauri builds the AppImage, the finalizer re-verifies that cache, removes bundled Wayland client libraries from the retained AppDir, and rebuilds the artifact. WebKitGTK and Mesa then use one compatible host stack.

You can also build the same bundles from a source checkout:

plugins=$(mktemp -d)
cache=$(mktemp -d)
trap 'rm -rf "$plugins" "$cache"' EXIT
export XDG_CACHE_HOME="$cache"
apps/linux/scripts/stage-appimage-gstreamer.sh "$plugins"
apps/linux/scripts/tauri-appimage-tools.sh prepare
apps/linux/scripts/tauri-appimage-tools.sh verify pre-build
export LDAI_RUNTIME_FILE="$(apps/linux/scripts/tauri-appimage-tools.sh runtime-path)"
(
  cd apps/linux/src-tauri
  GSTREAMER_PLUGINS_DIR="$plugins" \
    pnpm dlx @tauri-apps/cli@2.11.4 build --bundles deb,appimage \
      --config '{"bundle":{"createUpdaterArtifacts":false,"useLocalToolsDir":false}}'
)
apps/linux/scripts/finalize-appimage.sh \
  apps/linux/src-tauri/target/release/bundle/appimage

The Linux App workflow checks affected pull requests with Rust tests, native builds, and the native inline-browser smoke; it does not build bundles for pull requests. Manual runs build and upload the .deb and AppImage as the openclaw-linux-companion workflow artifact; they do not publish a release. See apps/linux/README.md in the repository for Linux build dependencies and development commands.

快速聊天

Ctrl+Shift+O 仅在获得焦点的仪表板中打开新会话。伴侣应用不会全局保留此组合键,因此其他前台应用会保留各自的快捷键行为。

使用 Ctrl+Shift+Space 或 快速聊天 托盘项打开快速聊天。代理标签会显示已配置的头像、表情符号或首字母缩写;选择它可切换代理。消息会使用所选代理的主会话,并遵循全局会话范围。原生 Rust 客户端拥有一个持久的 Ed25519 设备身份。它仅使用 CLI 交接的共享令牌或密码来启动配对,之后会存储并在后续连接中优先使用 Gateway 签发的设备令牌。身份和设备令牌以权限为 0600 的文件保存在应用配置目录中;快速聊天的 WebView 既不会接收凭据,也不会接收 WebSocket。

当原生连接不可用时,快速聊天会显示 Gateway 无法访问 — 正在重试,并在重新连接前禁用发送。已达到配对阶段的远程设备会改为显示 请在仪表板中批准此设备(节点);如果 Gateway 提供了简短设备 ID,则会显示该 ID。如果 Gateway 要求提供缺失的共享凭据,会显示 Gateway 需要凭据 — 请在 Gateway 主机上打开仪表板;在该状态下,没有等待批准的配对请求。当服务器提供的修复指引更具体时,它会替换这些回退通知。 对于 TLS Gateway,CLI 会将 Gateway 证书的 SHA-256 指纹传递给应用;原生客户端会固定该证书,并单独报告 Gateway TLS 信任失败 — 请检查证书指纹,与停机状态区分开。 通过 SecretRef 配置共享密钥的 Gateway 会从 CLI 交接中省略该密钥。已配对的现有安装会继续通过其存储的设备令牌正常工作,但全新安装在没有该引导凭据的情况下,无法在共享密钥认证下创建待处理的配对请求。 设置码和 bootstrapToken 兑换需要专门的产品 UI,并仍属于后续工作;快速聊天不会尝试这两种流程。

在 X11 上,使用快速聊天中的齿轮图标来录制或重置自定义快捷键。快速聊天快捷键 托盘开关可启用或禁用它,而不会禁用普通的 快速聊天 托盘项。Wayland 上不可用全局快捷键,因此快捷键设置会被隐藏,托盘项仍作为入口。 在发送被接受后,快速聊天会保持打开,并在底部一个输入框上方流式显示所选代理的纯文本回复,你提交的消息会显示在回复旁边。折叠回复可保持紧凑的输入框;展开它会恢复实时文本和任何组件内容。你可以在回复流式显示时准备下一条草稿,并在回合结束时发送它。回车发送,Shift+回车添加换行,Ctrl+Enter 发送并打开仪表板。打开仪表板 也可在输入框控件旁边使用。按 Esc 可关闭该栏及其回复。

CLI 和 SSH 替代方案

对于无头服务器或 VPS,CLI 仍然是最简单的选择。在没有 Linux 桌面伴侣应用的情况下连接时,请使用手动 SSH 隧道:

  1. 安装 Node 26(推荐),或其他受支持的版本:Node 24.16+ 或 Node 26.1+。
  2. 在 npm 12 或 npm 11.16+ 上,运行 npm i -g openclaw@latest --allow-scripts=openclaw。在 npm 11.15 及更早版本中,省略 --allow-scripts=openclaw。
  3. openclaw onboard --install-daemon
  4. 从你的笔记本电脑:ssh -N -L 18789:127.0.0.1:18789 <user>@<host>
  5. 打开 http://127.0.0.1:18789/,并使用已配置的共享密钥进行身份验证(默认为令牌;如果 gateway.auth.mode 为 "password",则为密码)。

完整服务器指南:Linux 服务器。逐步 VPS 示例: exe.dev。

Node 功能

捆绑的 Linux Node 插件可为 CLI 的 openclaw node 服务提供设备功能,而无需桌面应用。只有当相应功能已启用且所需的本地工具存在时,命令才会向 Gateway 通告。

功能 默认 要求
桌面通知(system.notify) 开启 libnotify 的 notify-send 以及桌面通知会话
功能 默认值 要求
相机照片和片段(camera.*) 关闭 FFmpeg、V4L2 相机访问权限,以及用于片段音频的 PulseAudio 或 PipeWire
位置(location.get) 关闭 GeoClue2 及其 where-am-i 演示

在 openclaw.json 中配置插件:

{
  plugins: {
    entries: {
      "linux-node": {
        config: {
          notify: { enabled: true },
          camera: { enabled: true },
          location: { enabled: true },
        },
      },
    },
  },
}

更改这些设置后,请重启节点服务。可用性在每个进程中确定一次,节点通告会在重启时重建。

Gateway 会独立于设备配对来批准节点的命令与能力面。首次启动或启用更多能力后,请批准待处理的能力面:

openclaw nodes pending
openclaw nodes approve <requestId>

在此批准完成之前,节点可以已连接并完成设备配对,但其有效 caps 和 commands 仍可能为空。

相机设备必须可被服务用户读取,通常通过 video 组实现。当 includeAudio 为 true 时,相机片段使用默认 PulseAudio 或 PipeWire 源;麦克风音频仅作为该片段音轨存在,而不是独立命令。位置功能要求节点服务用户获得主机 GeoClue 策略的许可。

camera.snap 和 camera.clip 还要求通过 gateway.nodes.commands.allow 显式启用 Gateway。有关负载、限制和错误,请参阅 相机捕获 和 位置命令。

已弃用的 Linux Canvas

内置 Linux Canvas 桥接及其桌面 Canvas 窗口已被移除。 对于控制 UI 中的内联组件,请使用 show_widget。 独立的 macOS 组件面板 需要已连接的 Mac,并且仅用于渲染。这些组件界面不会恢复以前的 Linux Canvas 桥接或其 A2UI 推送命令。

安装

Gateway 服务(systemd)

在没有受支持的服务管理器的 Linux 主机上,请在前台运行 Gateway,或通过你自己的监督程序(例如 rc.d)运行。openclaw gateway status --deep 会报告 未检测到受支持的服务管理器,并将残留的服务单元识别为过期。该已记录的单元不会选择状态检查的配置或端口。更新会继续进行,并带有服务警告;更新后请重启你手动启动的 Gateway。在 systemd 主机上,不可用的用户会话总线仍是一项独立的服务访问诊断。

使用以下任一方式安装:

openclaw onboard --install-daemon
openclaw gateway install
openclaw configure   # select "Gateway service" when prompted

修复或迁移现有安装:

openclaw doctor

openclaw gateway install 默认渲染 systemd 用户 单元。完整的服务指南(包括用于共享或始终在线主机的 system 级单元变体)位于 Gateway 运行手册。

托管单元会自动转义字面路径。在自定义单元中,请勿在 WorkingDirectory= 或 EnvironmentFile= 路径周围添加 shell 引号,即使它们包含空格。为每个绝对路径使用单独的 EnvironmentFile= 指令;systemd 会忽略相对路径。使用 %% 表示字面百分号。EnvironmentFile= 也接受 glob 模式,因此请使用反斜杠转义字面 glob 字符。托管的工作目录路径不得以空格或制表符结尾:systemd 255 在启动进程时会丢失该尾随空白。OpenClaw 会拒绝这些路径,以避免冒险使用不同目录;请选择没有尾随空白的路径。

仅在自定义设置中手动编写单元。最小用户单元示例(~/.config/systemd/user/openclaw-gateway[-<profile>].service):

[Unit]
Description=OpenClaw Gateway (profile: <profile>)
After=network-online.target
Wants=network-online.target
StartLimitBurst=10
StartLimitIntervalSec=300

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
RestartPreventExitStatus=78
TimeoutStopSec=330
TimeoutStartSec=30
SuccessExitStatus=0 143
OOMPolicy=continue
KillMode=mixed

[Install]
WantedBy=default.target

手写单元不会继承 openclaw gateway install 为托管 Gateway 服务写入的自适应堆大小设置。请优先使用托管安装程序,或在自定义监督程序中设置显式堆限制,并考虑原生内存余量。

TimeoutStopSec=330 覆盖 Gateway 的五分钟协作式排空以及拆除预留时间。要检查当前托管单元主体,请运行 systemctl --user cat openclaw-gateway.service(对于命名配置文件,请运行 systemctl --user cat openclaw-gateway-<profile>.service)。

启用它:

systemctl --user enable --now openclaw-gateway[-<profile>].service

内存压力与 OOM 终止

在 Linux 上,当主机、虚拟机或容器 cgroup 内存耗尽时,内核会选择 OOM 受害者。Gateway 不是理想的受害者,因为它拥有长生命周期会话和通道连接,因此 OpenClaw 会尽可能偏向先终止临时子进程。

对于符合条件的 Linux 子进程生成,OpenClaw 会将命令包装在一个简短的 /bin/sh 垫片中,尝试将子进程自身的 oom_score_adj 提高到 1000,然后 exec 真实命令。这是非特权操作:进程始终可以提高自身的 OOM 分数。

小型生成代理和服务子进程锚点会避免这次额外的 shell exec:它们会在原生生成前后临时提高自身分数,然后恢复。子进程在能够执行或 fork 后代之前会继承 1000。如果辅助程序无法调整其分数,则使用垫片。直接启动和 PTY 保留垫片,因此 Gateway 自身的分数无需更改。

受保护的子进程范围:

  • 由 Supervisor 管理的命令子进程
  • PTY shell 子进程
  • MCP stdio 服务器子进程
  • 受管理的本地模型和嵌入服务子进程
  • 由 OpenClaw 启动的浏览器/Chrome 进程(通过插件 SDK 进程运行时)

沙箱后端传输保留其准备好的环境和继承的 OOM 分数,而不是接收此包装器。工作负载资源策略属于沙箱后端;普通主机命令和 PTY 保留子进程优先偏向。

该包装器仅适用于 Linux,并在 /bin/sh 不可用时跳过,或者当子进程环境变量将 OPENCLAW_CHILD_OOM_SCORE_ADJ 设置为 0、false、no 或 off 时跳过。 仅将此退出选项用于受控诊断:它会移除子进程优先的 OOM 保护,并增加 Gateway 在真实内存压力下被选为受害者的可能性。

当受管理的本地模型和嵌入服务的有效环境定义了 SHELLOPTS、BASHOPTS、某个 BASH_FUNC_* 键或保留的 OC_INTERNAL_OOM_EXEC_{BASH_ENV,ENV,CDPATH,PS4} 载体时,它们会回退到直接派生。在这些情况下,精确的环境一致性和 shell 启动安全性优先,因此 OpenClaw 不会尝试更改 oom_score_adj;使用以下验证来检查子进程的有效值。

验证子进程:

cat /proc/<child-pid>/oom_score_adj

当写入成功时,受保护子进程的预期值为 1000。 如果 /proc 不可用或不可写,子进程仍会在没有 OOM 偏向的情况下运行。Gateway 进程本身保持其正常分数(通常为 0)。

systemd 单元的 OOMPolicy=continue 会在瞬态子进程被 OOM killer 选中时保持 Gateway 服务存活,而不是将整个单元标记为失败并重启所有通道;失败的子进程/会话会报告其自身的错误。

这不会替代正常的内存调优。如果 VPS 或容器反复终止子进程,请提高内存限制、降低并发,或添加更强的资源控制(systemd MemoryMax=、容器内存限制)。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw