跳转至

Linux 应用

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

桌面伴侣

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

  • 引导新用户选择本地网关、已发现的远程网关、手动输入的网关 URL 或 SSH 隧道
  • 当本地设置需要时，在私有受管运行时中安装 OpenClaw CLI 和 Node，而不是要求全局安装 CLI；发布构建会自动安装稳定通道，开发构建会先询问通道
  • 在尝试更改服务之前，先连接到健康的网关
  • 将安装、启动、停止和重启操作委托给由 CLI 管理的 systemd 用户服务
  • 发现附近的 Bonjour 网关，并在路由作用域窗口中打开每个控制界面，使多个网关仪表盘可以保持连接并同时使用
  • 使用解析后的身份验证 URL 打开由网关提供的控制界面
  • 为未配置的本地或远程网关打开模型设置，发现可用的 AI 访问，并在选择、测试、安装或保存提供商之前等待你的明确操作
  • 连接新模型后继续进入引导式入门；入门流程可以将检测到的 Claude Code、Codex 或 Hermes 记忆导入代理工作区（同一导入功能之后仍可在“设置 → 导入记忆”下使用）
  • 窗口关闭后仍可从系统托盘访问

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

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

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

Chrome 扩展设置

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

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

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

桌面兼容性

已发布的 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 预计会在那里失败。对于 对话模式，请在常规浏览器中打开网关的控制界面。

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

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

网关选择

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

仪表板的个人资料菜单只会切换其当前窗口；Control 单击会打开一个附加窗口。从原生菜单中选择某个 Gateway 会聚焦其现有窗口而不会重新加载它，而 在新窗口中打开 … 会创建一个独立窗口。

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

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

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

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

桌面共享

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

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

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

首次运行设置

在欢迎屏幕上选择 开始使用，然后选择你的助手应位于何处：

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

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

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

连接成功后，模型设置会发现所选 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 分支构建的稳定版本，会作为该标签的 GitHub 发布 资产发布 .deb 和 AppImage 捆绑包，文件名为 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

打包脚本在 Tauri 调用 linuxdeploy 之前仅暂存该媒体能力集。这可防止可选的宿主机插件将无关的系统库添加到 AppImage 依赖闭包中。

打包流程将 Tauri 的五个 AppImage 工具配置到一个干净的、按摘要固定的缓存中。在 Tauri 构建 AppImage 后，最终处理程序会重新验证该缓存，从保留的 AppDir 中移除捆绑的 Wayland 客户端库，并重新构建产物。随后 WebKitGTK 和 Mesa 使用同一套兼容的宿主机栈。

你也可以从源码检出构建相同的捆绑包：

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

Linux App 工作流使用 Rust 测试、原生构建和原生内联浏览器冒烟测试来检查受影响的拉取请求；它不会为拉取请求构建捆绑包。手动运行会构建并上传 .deb 和 AppImage，作为 openclaw-linux-companion 工作流产物；它们不会发布版本。有关 Linux 构建依赖项和开发命令，请参见仓库中的 apps/linux/README.md。

快速聊天

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

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

当原生连接不可用时，Quick Chat 会显示 网关不可达——正在重试，并在重新连接前禁用发送功能。已进入配对阶段的远程设备则会显示 在仪表盘（节点）中批准此设备，并在网关提供简短设备 ID 时一并显示。当网关需要某个缺失的共享凭据时，会显示 网关需要凭据——请在网关主机上打开仪表盘；在该状态下，没有等待审批的配对请求。当服务器提供的修复指引更具体时，会替代这些后备通知。

对于 TLS 网关，CLI 会将网关证书的 SHA-256 指纹交给应用；原生客户端会固定该证书，并将 网关 TLS 信任失败——请检查证书指纹 作为与停机状态分开的一项单独报告。通过 SecretRef 配置共享机密的网关会在 CLI 交接中省略该机密。已配对的现有安装会通过其存储的设备令牌继续工作，但在共享机密认证下，全新安装没有该引导凭据就无法创建待处理的配对请求。设置码和 bootstrapToken 的兑换需要专门的产品界面，仍属于后续工作；Quick Chat 不会尝试任一流程。

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

CLI 与 SSH 替代方案

CLI 仍然是无头服务器或 VPS 最简单直接的选择。在没有 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 服务设备能力。命令只有在相应能力已启用且所需本地工具存在时，才会向网关通告。

能力 默认 要求
桌面通知（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 },
        },
      },
    },
  },
}

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

网关会对节点的命令与能力集合进行审批，该审批独立于设备配对。在首次启动或启用了更多能力后，请批准待处理的集合：

openclaw nodes pending
openclaw nodes approve <requestId>

在该审批完成之前，节点可以保持已连接并完成设备配对，但其有效的 caps 和 commands 仍为空。

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

camera.snap 和 camera.clip 还需要通过 gateway.nodes.commands.allow 显式启用网关。有关载荷、限制和错误，请参阅相机捕获和定位命令。

已停用的 Linux Canvas

捆绑的 Linux Canvas 桥接器及其桌面 Canvas 窗口已被移除。对于 Control 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 用户 unit。有关完整服务指南，包括适用于共享或常驻主机的系统级 unit 变体，请参阅 Gateway 运维手册。

受管 unit 会自动转义字面路径。在自定义 unit 中，不要在 WorkingDirectory= 或 EnvironmentFile= 路径两侧添加 shell 引号，即使路径包含空格。每个绝对路径应使用单独的 EnvironmentFile= 指令；systemd 会忽略相对路径。如需字面百分号，请编写 %%。EnvironmentFile= 也接受 glob 模式，因此请用反斜杠转义字面 glob 字符。受管的工作目录路径不得以空格或制表符结尾：systemd 255 在启动进程时会丢失该尾部空白。OpenClaw 会拒绝这些路径，而不是冒险使用其他目录；请选择不带尾部空白的路径。

仅在自定义设置时才需要手写 unit。最小的用户级 unit 示例（~/.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

手写的 unit 不会继承 openclaw gateway install 为受管 Gateway 服务写入的自适应堆大小设置。建议优先使用受管安装器；或者在考虑原生内存余量后，在自定义监督程序中设置显式堆限制。

TimeoutStopSec=330 涵盖 Gateway 的五分钟协作式排空及拆除预留时间。若要查看当前受管 unit 的内容，运行 systemctl --user cat openclaw-gateway.service（对于指定名称的 profile，运行 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 自身的分数永远不需要改变。

受覆盖的子进程场景包括：

  • 由监督程序管理的命令子进程
  • 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 unit 的 OOMPolicy=continue 会在瞬时子进程被 OOM killer 选中时保持 Gateway 服务存活，而不是将整个 unit 标记为失败并重启所有通道；失败的子进程/会话会报告自身的错误。

这不能替代正常的内存调优。如果 VPS 或容器反复终止子进程，请提高内存限制、减少并发，或添加更强的资源控制（systemd MemoryMax=、容器内存限制）。

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