网关服务及流程

Gateway 服务未运行

当服务已安装但进程无法持续运行时使用。

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # also scan system-level services

查看以下内容：

• Runtime: stopped 并带有退出提示。
• 服务配置不匹配（Config (cli) vs Config (service)）。
• Port/listener 冲突。
• 使用 --deep 时额外的 launchd/systemd/schtasks 安装。
• Other gateway-like services detected (best effort) 的清理提示。

相关：

• 后台执行和进程工具
• 配置
• 诊断工具

macOS 网关静默停止响应，然后在你触碰控制面板时恢复

当 macOS 主机上的通道（Telegram、WhatsApp 等）一次安静几分钟到几小时，并且在您打开 Control UI、SSH 或以其他方式与主机交互时网关似乎恢复时使用。 openclaw status 通常没有明显的症状，因为当您查看时，网关再次处于活动状态。

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

查看以下内容：

• ~/.openclaw/logs/stability/ 中的一个或多个 *-uncaught_exception.json 捆绑包，其中 error.code 设置为临时网络代码，例如 ENETDOWN、ENETUNREACH、EHOSTUNREACH 或 ECONNREFUSED。
• pmset -g log 中有类似 Entering Sleep state due to 'Maintenance Sleep' 或 en0 driver is slow (msg: WillChangeState to 0) 的行，并且与崩溃时间戳对齐。Power Nap / Maintenance Sleep 会短暂将 Wi-Fi 驱动置于 state 0；在该窗口内发生的任何出站 connect() 都可能返回 ENETDOWN，即使主机其他方面具有完整的网络连接。
• launchctl print 输出显示 state = not running 以及多个最近的 runs 和退出代码，特别是当崩溃与下一次启动之间的间隔约为一小时而不是几秒时。 macOS launchd 在崩溃爆发后应用未记录的重生保护门，可以停止尊重 KeepAlive=true，直到外部触发（例如交互式登录、仪表板连接或 launchctl kickstart 重新启动）为止。

常见特征：

• 一个 error.code 为 ENETDOWN 或同类代码的稳定性包，调用栈指向 Node net 的 lookupAndConnect / Socket.connect。OpenClaw 2026.5.26 及更新版本会将这些视为良性的瞬态网络错误，因此不再将其传播到顶层未捕获处理器；如果你使用的是更早版本，请先升级。
• 漫长的静默期在你连接 Control UI 或通过 SSH 登录主机的瞬间结束：用户可见的活动是在重新为 launchd 的 respawn 门控上弦，而不是控制面板对网关做了什么。
• runs 计数在一天中递增，但 ~/Library/Logs/openclaw/gateway.log 中没有相应的 received SIG*; shutting down 行：干净关闭记录信号；短暂的崩溃则不然。

该怎么办：

1. 如果你运行的是 2026.5.26 之前的版本，请升级网关。升级后，未来的 ENETDOWN 错误会以 warning 的形式记录，而不会终止进程。

2. 降低面向始终在线服务器的 Mac mini / 桌面主机上的维护性睡眠活动：

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   这会显著降低底层驱动抖动，但不能完全消除。系统仍可能为了 TCP keepalive 和 mDNS 维护而执行某些维护性睡眠，无论这些标志如何设置。

3. 添加一个存活监控，以便在未来由 launchd 暂停的崩溃风暴能被迅速捕获：

   # Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgentstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   关键在于从外部重新为 respawn 门控上弦；仅靠 KeepAlive=true 在 macOS 崩溃风暴后并不充分。

相关：

• macOS 平台说明
• 日志
• 诊断工具

macOS launchd 监督循环，重复的 gateway/node LaunchAgents

当 macOS 安装每隔几秒就不断重启、openclaw 健康检查在 healthy 和 unavailable 之间来回波动，并且即使服务看起来正在运行，channel 分发仍然停滞时，请使用此方法。

当 ai.openclaw.gateway 和 ai.openclaw.node LaunchAgents 均处于活动状态且各自注入 OPENCLAW_LAUNCHD_LABEL 时，会发生这种情况。在该状态下，OpenClaw 可以检测到 launchd 监督，尝试手动重新启动回 launchd，并陷入快速 EADDRINUSE/respawn 循环而不是稳定的网关进程。

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

查看以下内容：

• 在 30 秒采样期间出现多个 gateway PID，而不是一个稳定的进程。
• EADDRINUSE、another gateway instance is already listening 或 gateway.log 中重复的 restart/handoff 行。
• 在一台本应只运行一个受管 gateway 服务的主机上，~/Library/LaunchAgents/ai.openclaw.gateway.plist 和 ~/Library/LaunchAgents/ai.openclaw.node.plist 两者同时被加载。

该怎么办：

1. 如果这台主机只应该运行 Gateway 服务，请通过 OpenClaw 移除受管的 node 服务。如果你确实依赖 node 服务提供远程 node 功能，请跳过此步骤；卸载它会停止这台主机上的这些功能：

   openclaw node uninstall

2. 安装持久性网关包装器，该包装器在启动 OpenClaw 之前清除继承的 launchd 标记。使用支持的--wrapper选项；不要编辑 ~/.openclaw/service-env/ 下生成的文件，因为服务重新安装、更新和医生修复会重新生成该文件：

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install 会在强制重装、更新和 doctor 修复之间保留 wrapper 路径。

3. 验证 Gateway 是否稳定并且正在提供 RPC，而不仅仅是在监听：

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   PID 示例应显示一个稳定的进程，而不是一组循环的 PID，并且入站通道调度应恢复。

4. 在升级到修复了底层双 LaunchAgent 循环的版本后，移除该 workaround，并重新安装正常的受管服务：

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

相关：

• macOS 上的网关
• 诊断工具
• 网关 CLI

Native 在 Linux （SIGABRT） 上中止

malloc(): invalid next->prev_inuse (unsorted) 后跟 systemd status=6/ABRT 表示检测到的本机堆损坏。它无法识别损坏的代码，并且与内核 OOM 终止不同。 JavaScript 信号处理程序或稳定性捆绑包无法可靠地捕获本机 abort()。安排OS核心在再次失败之前捕获。

启动日志包括native runtime（PID，平台，架构，Node，V8，libuv，OpenSSL和SQLite版本）和worker startup state（通过脚本跟踪的Worker计数，starts/retirements，和共享计算准入计数器）。这些是启动事实，而不是失败时刻的快照。使用崩溃时间戳、日志、精确的 OpenClaw 版本和 Node 可执行文件保留它们。

对于 systemd 系统服务，请替换下面的已安装单元名称。对于用户业务，使用systemctl --user，不使用sudo；其硬核限制不能超过用户管理器继承的限制。

sudo systemctl edit openclaw-gateway.service# Add this drop-in:# [Service]# LimitCORE=infinity sudo systemctl daemon-reloadsudo systemctl show openclaw-gateway.service -p LimitCORE -p MainPIDsysctl kernel.core_pattern

在下次运营商协调的服务重新启动时应用该限制。然后检查/proc/<gateway-pid>/limits是否有正在运行的进程的Max core file size；更改单位不会更改已运行进程的限制。

选择 kernel.core_pattern 指示的捕获后端：

• systemd-coredump： 验证分发的处理程序是否已安装并启用。检查 coredump.conf 存储和大小限制；多千兆字节的网关需要足够的磁盘空间和 ProcessSizeMax/ExternalSizeMax 来保留其核心。崩溃后，使用 sudo coredumpctl info <crashed-pid> 和 sudo coredumpctl debug <crashed-pid>。

• Appport： 检查/var/log/apport.log 和/var/crash。同一 Node executable/user 的现有报告可以抑制稍后的报告。将确切的过时 .crash 报告存档在 /var/crash 之外的仅根目录中，然后根据发行版的 Appport 过程清除任何匹配的过时 sidecar。不要删除不相关的报告。验证 Appport 已启用并确实接受下一份报告；仅 code=dumped 并不能证明核心已被保存。

• 直接核心文件： 如果安装的处理程序无法保留此崩溃，管理员可以暂时将其替换为私有绝对路径：

  # Record the old value so it can be restored after the investigation.sysctl kernel.core_patternsudo install -d -m 0700 -o <gateway-user> -g <gateway-group> /var/lib/openclaw-coressudo sysctl -w 'kernel.core_pattern=/var/lib/openclaw-cores/core.%e.%p.%t'

  core_pattern 是主机范围的：这也取代了其他进程的捕获。检查该目录是否可由网关服务用户写入并可在任何服务文件系统沙箱内访问。捕获后恢复之前的模式。此临时 sysctl 设置不会在重新启动后保留。

在同等服务限制和身份下使用一次性流程验证所选后端，而无需中止实时网关。使用 matching Node 二进制和调试符号（gdb /path/to/node /path/to/core 对于直接文件）打开捕获的内核，然后运行 ​​thread apply all bt。保留所有线程堆栈：中止线程可以检测其他地方造成的损坏。核心文件包含进程内存，包括凭证和消息内容；将其保密并仅共享经过审查和编辑的证据。

Gateway 在高内存使用期间退出

当网关在负载下消失、主管报告 OOM- 式重启或日志显示 memory pressure: level=critical 时使用。

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

查看以下内容：

• memory pressure: level=critical 与 reason=rss_threshold、heap_threshold 或 rss_growth。
• RSS、该日志行中的堆、阈值和增长值。
• 现有的稳定性捆绑包可防止致命退出、关闭超时或重新启动启动失败（如果可用）。

常见特征：

• memory pressure: level=critical 出现在 gateway 日志中 → OpenClaw 检测到严重内存压力，并记录了进程内可用的内存信息。
• reason=heap_threshold → 先降低prompt/session压力或减少并发工作。对于托管服务，将 Gateway heap: 和 openclaw gateway status 中配置的控件和安装时间建议与运行时测量进行比较。重新安装会保留现有的存储堆设置；它不会自动用当前建议替换旧值。
• reason=rss_growth → RSS 下限在连续的采样窗口中不断上升。检查最新日志以了解大量导入、失控的工具输出、重复重试或一批排队的代理工作。
• 日志中出现严重内存压力，但不存在捆绑包→在事件发生后捕获openclaw gateway diagnostics export以获取可用的操作证据。压力事件不会自动写入包。

管理员还可以在 Node 或 OpenClaw 的 Bun 运行时上使用 openclaw gateway call diagnostics.heapProfile --timeout 30000 进行 样本分配 。这捕获当前的分配活动，而不是过去的峰值或所有本机内存。较旧的捆绑包仍然可以通过 openclaw gateway stability --bundle latest 读取。

在将其附加到错误报告之前检查已清理的诊断导出；避免复制原始日志。

Node的自动堆上限在大型主机上大约可以是4个GiB。这是默认的大小决定，而不是一般的 64 位地址空间上限。 --max-old-space-size控制V8旧空间；测量的总 V8 堆上限还包括其他堆空间。 RSS还包括本机分配、缓冲区和其他进程内存。较高的堆上限不会预先分配上限，但在持续负载下仍然需要足够的实际容量和净空。

对于前台 Node 网关，请在 Node 启动之前设置本机堆标志，例如在具有足够容量的主机上：

NODE_OPTIONS="--max-old-space-size=16384" openclaw gateway run

对于自定义管理程序或 Docker 运行时命令，请将 --max-old-space-size=16384 紧接在 node 之后、OpenClaw 入口脚本之前，或者在该进程或容器的启动环境中设置 NODE_OPTIONS。 Docker 映像构建时堆选项不配置运行时网关。 Node 启动后加载的 OpenClaw 配置或 dotenv 值无法调整其堆大小。 NODE_OPTIONS 也可以到达生成的 Node 子级，因此当只有网关应该接收预算时，更喜欢直接 Node 参数。

对于托管 Node 服务，请使用 托管网关堆策略 并在更改托管启动参数和操作员拥有的环境覆盖之前检查它们。 Native argv 覆盖 NODE_OPTIONS 中的相同选项；百分比旧空间大小优先于绝对旧空间大小。当操作员覆盖拥有 NODE_OPTIONS 时，重新生成会保留存储的 argv，但不会添加自动堆标志。安装程序 shell NODE_OPTIONS 不会成为服务覆盖。运行时压力诊断使用有效的 V8 堆上限和 physical/reported 约束余量；过大的显式堆设置不会将 RSS 警报阈值提高到物理容量之上。压力警告是诊断证据，而不是堆限制或自动重启触发器。

RSS 增长检测比较完整的五分钟窗口中的最小 RSS 值，需要两次连续增加。当这些楼层不断上升时，增长就会不断积累；平坦或下降的底部、超过十分钟的采样间隙或时钟回滚都会重置趋势。这会过滤普通的 GC 峰值，同时检测较小的持续增加。记录的 rssGrowth 和 windowMs 描述了累积楼层增量以及这些最小值之间经过的时间（可能超过十分钟）。

在 Node 上，增长警告和关键事件使用测得的 V8 堆上限和可用进程容量中较小者的 4% 和 8%，最小阈值为 512 MiB 和 1 GiB。流程容量使用由物理 RAM 限制的报告约束，或者在未报告约束时使用物理 RAM。如果有 16 个 GiB 堆和足够的 RAM，这些阈值约为 655 MiB 和 1.28 GiB。未知的堆限制和Bun保留512 MiB/1 GiB增长阈值； Bun 现有的绝对内存上限保持不变。绝对 RSS 和堆压检查仍在每个样品上运行。

相关：

• 网关健康状态
• 诊断导出
• 会话