跳转至

服务

原生服务生命周期、恢复、包装器及托管服务选项参考。属于 openclaw gateway 参考文档的一部分。

管理 Gateway 服务

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

当插件配置需要 Doctor 迁移时，gateway stop 仍然可用。它仍然会验证核心配置，并拒绝由较新版本的 OpenClaw 二进制文件写入的配置。start 和 restart 继续验证插件配置。

在 Windows 上，计划任务的 stop 和 restart 操作首先要求已验证的 Gateway 排空工作并退出。较旧或无响应的 Gateway 会回退到终止已捕获的进程树；保留替换实例。确认进程退出后出现的瞬时 SQLite 共享错误会重试；如果检查仍然不可用，命令会发出警告，并在继续重启前检查 Gateway 端口是否空闲。

如果在停止时限内任务收尾检查仍然不可用，restart 仍会在确认 Gateway 已退出后尝试已捕获的任务，然后报告重启未经验证。观察到替换实例时，将保留该实例并拒绝重启。

如果 gateway start 在托管 Gateway 仍在启动时达到就绪期限，它会报告 still-starting 并以退出码 2 退出。服务会继续运行；在重启之前，请再次检查 openclaw gateway status --deep。崩溃的服务或外部监听器仍然会产生失败。仅凭端口所有权并不能证明就绪状态，也不能排除预热过程。

恢复不可读的原生服务定义

如果安装或托管更新报告 SERVICE_DEFINITION_UNKNOWN，请首先恢复对服务文件和原生服务管理器的访问权限。--force 不会绕过未知的服务事实。使用拥有该服务的账户和配置文件，通过 openclaw gateway status --deep 检查所选服务。

对于格式错误的定义或不支持的环境语法，请私下备份服务文件以及仅存储在其环境中的任何值。在重新安装之前，修正未解析或不支持的值；OpenClaw 无法推断这些值的预期含义。然后，在使用相同账户和配置文件的外部 shell 中执行：

openclaw gateway uninstall
openclaw gateway install
openclaw gateway health

卸载会移除原生注册和启动器，同时保留配置、插件安装、会话状态和工作区。重新安装会根据当前配置和安装输入重建服务环境；服务专用的值必须重新提供。如果原生服务状态本身不可用，卸载也会拒绝执行：请先恢复原生管理器的访问权限，而不是删除状态或绕过检查。

来自 Gateway 聊天的生命周期请求

由 Gateway 托管的 OpenClaw 聊天控制着为当前会话提供服务的那个确切 Gateway。已批准的启动请求会报告 Gateway 已在运行，而不会发现或启动另一个服务。Restart 保持安全的本地重启行为。

已批准的停止请求在宿主为其确切实例准备好停止后，会报告 已安排 Gateway 停止。这只是确认已安排，而非确认终止已完成。独占的前台宿主会排空工作、完成拆除并成功退出，而不会发现或更改已安装的服务。由 launchd 或 systemd 管理的宿主会验证原生所有权并准备执行器，然后在要求原生管理器停止服务之前，排空工作并完成拆除。请求操作可以在该排空期间完成其审计、历史和响应提交；但这并不保证客户端能在断开连接前收到响应。

在正常宽限期结束后，stop 会取消该 Gateway 拥有的剩余运行，并等待它们的命令和清理工作收尾。普通的 stop 不会安排重启恢复。必需的清理失败会产生非零退出码，并阻止进程内替换，包括在 Gateway 就绪之前启动失败的情况。

所有权或准备失败会使 Gateway 继续服务并返回错误。Linux 在所属的 systemd 管理器中使用独立的临时控制作用域，因此 stop 命令在服务 cgroup 终止后仍然有效。在 macOS 上，托管 stop 请求普通的 launchctl bootout，不会更改持久启用状态。如果原生管理器在最终停止交接期间发送 SIGTERM，宿主会在加入清理后完成其优雅退出，包括所属的 stop 客户端。

在 Windows 上，独占拥有 Gateway 进程的运行循环也会在任务计划程序下使用优雅进程退出。它不会按名称选择或停止任务。生成的任务监督器会等待子进程树退出，并通过启动器传播子进程的退出结果。其 RestartOnFailure 策略 不会重启成功退出的任务。自定义包装器可能具有不同的退出或重启行为；请分别检查其策略。此停止路径不会更改任务定义或其重启策略。外部监督的 Gateway 会将停止请求定向到其监督器。

如果 systemd 在拆除后明确拒绝停止，且同一原生实例仍然处于活动状态且没有待处理作业，宿主会记录失败的停止，并在同一进程中启动全新的一代 Gateway。不确定的原生结果会被记录为关闭失败，而不会声称成功或启动进程内替换。在意外断开连接后，请先从外部 shell 检查 openclaw gateway status 和原生服务日志，然后再重试。独立的 CLI 生命周期命令保留其服务管理行为。

固定服务运行时

当未提供运行时选项时，强制重新安装会保留记录在未固定且没有包装器的服务中的受支持的 Node 或 Bun 可执行文件。更新刷新也会执行相同操作，而不会创建固定项。当不需要运行时迁移时，Doctor 也默认使用记录的运行时，包括已存在但未加载的服务。如果记录的 Bun 缺失、不可执行或不受支持，则回退到自动选择 Node。显式指定 --runtime node 或 --runtime bun 会请求自动选择该运行时。

配置和高级入门引导会优先建议受支持的已记录运行时。 如果没有，它们的运行时选择器会在没有受支持的 Node 可用时建议正在运行的受支持 Bun，否则建议 Node。选择器的选择是显式的：在仅 Bun 主机上选择 Node 会报告 Node 不可用，然后才替换服务。快速入门保持自动选择，而不会创建运行时固定项。

使用 --runtime-path 让服务继续使用操作员选择的 Node 或 Bun 可执行文件，而不是自动运行时选择：

openclaw gateway install --runtime-path "/absolute/path/to/node" --force

该路径必须是绝对路径、可执行文件，并且在同时提供 --runtime 选项时必须与其匹配。运行时必须通过当前的 Node/Bun 和 SQLite 能力检查。支持包含空格的路径；请在 shell 中为其加上引号。

该固定项保存在此托管服务的机器状态元数据中。 强制重新安装、更新和定义修复会保留它。缺失或不受支持的固定项会失败并给出诊断信息，而不是静默切换运行时。 要替换它，请提供另一个 --runtime-path；要返回自动选择，请运行不带 --runtime-path 的 openclaw gateway install --runtime node --force。 显式包装器仍然控制可执行文件，并优先于固定项。 安装会启动服务，并可能重启现有 Gateway。

修复 LaunchAgent 环境包装器

在 macOS 上，生成的 LaunchAgent 会启动一个 shell 包装器，先使用生成的环境文件，然后执行 Gateway 命令。如果 gateway status 报告缺少环境文件参数，或服务日志报告 无效的 LaunchAgent 环境文件，请从拥有该服务的账户和配置文件运行 openclaw gateway install --force，然后检查 openclaw gateway status 和 openclaw health。

在修复格式错误的定义之前，请备份 plist 和私有服务环境文件。如果其运行时参数也被更改，请按照上述方式使用 --runtime-path 显式选择目标可执行文件。如果服务定义已更改，则必须再次显式选择已记录的运行时固定项。请确保仅服务使用的环境变量值在重新安装时可用；格式错误的包装器参数可能会阻止 OpenClaw 读取之前的环境文件。

使用包装器安装

当托管服务必须通过另一个可执行文件启动时，请使用 --wrapper，例如密钥管理器 shim 或 run-as 辅助程序。包装器会接收正常的 Gateway 参数，并负责最终使用这些参数 exec openclaw 或 Node。

cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart

你还可以通过环境变量设置包装器。gateway install 会验证该路径是否为可执行文件，将包装器写入服务的 ProgramArguments，并在服务环境中持久化 OPENCLAW_WRAPPER，以便后续强制重新安装、更新和 doctor 修复。

OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor

要移除已持久化的包装器，请在重新安装时清除 OPENCLAW_WRAPPER：

OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart
命令选项
  • gateway status: --url, --port, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
  • gateway install: --port, --runtime <node|bun>（全新安装默认值：node）, --runtime-path <path>, --token, --wrapper <path>, --force, --json
  • gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --preserve-definition, --json
  • gateway uninstall|start: --json
  • gateway stop: --disable, --force, --json
服务运行时
  • Node 是主要的、推荐的托管 Gateway 运行时，也是全新安装的默认值；如果没有显式运行时、固定项或包装器，则在受支持的 Bun 下运行的安装会使用该可执行文件，并且如果未找到受支持的 Node，则不会创建固定项。隐式重新安装会保留上述受支持的已记录 Node 或 Bun 运行时。
  • 对于未固定运行时的服务，gateway install 会检查托管服务中记录的 Node 可执行文件。如果它缺失、不可执行或不受支持，安装会刷新服务，而不需要 --force，并报告替换路径。当安装程序或更新刷新服务时，也适用此规则。修复会优先使用当前 CLI 支持的 Node，保留稳定的 Homebrew 路径，然后检查受支持的系统安装。自定义包装器保留对其运行时的控制；受保护的服务定义仍需要其部署所有者进行修复。
  • 带有 WAL 重置安全的 node:sqlite 的 Bun 1.4+ 可通过 gateway install --runtime bun 显式选择启用。
生命周期行为
  • gateway start 是幂等的：当托管服务已在运行时，它会报告正在运行的进程并保持其不变。已加载但已停止的服务会像以前一样启动。
  • 在 Windows 上，显式的 gateway start 会在验证其选定的配置文件和命令后，重新启用已禁用的计划任务。它会保留已注册的启动器和触发器设置。如果启用成功但启动失败，该任务可能仍处于启用状态；重试前请使用 gateway status --deep 检查同一配置文件。update repair 会保持已停止的 Gateway 处于离线状态；如果你打算将其上线，请在之后运行 gateway start。
  • 如果未安装托管服务，gateway start 会打印安装提示并以非零状态退出。gateway restart 可以先恢复已安装但未加载的 LaunchAgent 或经过验证的非托管 Gateway；如果托管服务和恢复机制都未处理该操作，它会打印相同的提示并以非零状态退出。停止不存在的服务仍然是成功的无操作。
  • 如果 gateway start 或 gateway restart 需要修复过时的服务定义，当调用 shell 解析出的状态目录、配置路径或端口与已安装服务不同时，该命令会拒绝执行。请匹配或取消设置冲突的环境变量覆盖，或使用 openclaw gateway install --force 有意重新指定服务目标。
  • 在 Linux 上，当操作员拥有的 systemd drop-in 覆盖了命令或工作目录时，gateway start 和 gateway restart 也会拒绝无效的修复。请使用 systemctl --user cat <unit>.service 检查生效的单元，然后更新或移除该 drop-in。gateway install --force 只会重写托管的基础单元，并在覆盖仍然存在时发出警告；Environment= drop-in 仍受支持。
  • gateway restart --preserve-definition 仅重启可检查的原生服务，跳过自动定义修复，并在已安装启动器的端口上检查健康状态。它不会恢复非托管监听器，也不能与 --safe 或外部监督组合使用。在 macOS 上，它可以引导未加载的可读 plist，而无需重写 plist、环境、包装器或权限；被拒绝的原生激活会失败，且不会进行文件修复。在 Windows 上，它还会保留现有的 Startup 项。daemon restart 别名接受相同选项。
  • 在可写的 Linux 服务安装或刷新期间，请保持单元目录和状态目录不变，并避免并发的手动编辑。OpenClaw 会串行化其自身的写入器，并在检测到更改时中止，但无法协调任意的文件系统编辑。在发布过程中移动或替换父目录可能会在移动后的目录中留下临时文件；重试前请检查它。
  • 在 macOS 上，失败的 LaunchAgent 替换的回滚会恢复之前的 plist 字节和权限位，包括二进制 plist。如果恢复无法完成，该命令会报告失败。
  • 使用 gateway restart 重启托管服务。不要将 gateway stop 和 gateway start 串联作为重启的替代方案。
  • 正在运行的 Gateway 会在共享状态中记录其进程身份、监听器模式和监督者。重启会在其启动期间保留经过验证的存活所有者，即使其监听器尚未打开；健康超时不会使该所有者过时。已记录的前台所有者会收到有针对性的重启，即使已安装原生服务也是如此。计划任务清理会保留外部监督者和其他任务，并在错误中识别其所有者。对于没有记录身份的旧版 Gateway，当其参数与已安装任务命令完全匹配时，仍然可以终止。如果没有该归属，被持有的协调器会保持进程运行，并要求你在启动后重试。未验证的监听器会被报告，而不是被终止。
  • 在非交互式 shell 中，gateway stop 需要 --force。交互式终端保持现有的无提示行为。对于自动化和测试，请优先使用 gateway run --dev 或带有空闲端口的隔离 --profile。
  • 在 macOS 上，gateway stop 默认使用 launchctl bootout，它会从当前启动会话中移除 LaunchAgent，而不会持久化禁用 — KeepAlive 自动恢复对未来崩溃保持有效，并且 gateway start 可以干净地重新启用，无需手动 launchctl enable。传递 --disable 以持久抑制 KeepAlive 和 RunAtLoad，使 Gateway 在下一次显式 gateway start 之前不会重新生成；当手动停止需要在重启后仍然有效时，请使用此选项。
  • Gateway 生命周期变更会尽力将键值审计记录追加到 <state-dir>/logs/gateway-restart.log，包括 CLI 启动、停止和重启操作、安全重启请求、监督者重启以及分离交接。
  • 生命周期命令接受 --json 以便脚本化。
  • 完成原生激活或已接受的恢复但健康检查失败的重启会发出 action: "restart"、ok: false 和 result: "restart-health-failed"，并保留其错误、提示、警告和退出码 1。此诊断不会授权另一次激活。拒绝、意外异常以及未确认激活的定义修复不会发出此结果。计划重启会报告接受，而不会声称继任者健康。
托管 Gateway 堆大小设置
  • 对于没有现有堆设置的托管 Node Gateway，gateway install 会将 --max-old-space-size 放入 Node 的启动参数中，位于入口脚本之前。它会显式清除服务环境中的 NODE_OPTIONS，使环境中的服务管理器预加载/调试标志无法泄漏到 Gateway。普通派生的 Node 进程不会通过 NODE_OPTIONS 继承新的自动预算；Node 的 fork 和 Worker 继承规则保持不变。
  • 容量是有效物理内存与 Node 报告的有效约束中的较小者，绝不是波动的可用内存。如果没有可用的容量读数，Node 会保持其原生默认值。安装程序以容量的 50% 为目标，标称下限为 2048 MiB，上限为 8192 MiB 或容量 25% 中的较大者。最终的 75% 容量上限会为原生内存保留余量，并可能使小型主机的预算低于标称下限。
  • 示例：32 GiB 容量选择 8 GiB 旧空间；64 GiB 选择 16 GiB；128 GiB 选择 32 GiB。旧空间只是 V8 总堆的一部分，二者都不是总进程内存（RSS）的限制。提高上限不会预分配该内存。
  • 现有托管服务堆控制在强制重新安装和 doctor 修复过程中会保留，包括绝对旧空间、百分比旧空间和总堆标志。只有堆标志能在托管 NODE_OPTIONS 清理中保留；任意预加载/调试标志则不能。将有意设置的预加载/调试配置放在操作员拥有的 systemd Environment= drop-in 中，或在已安装的包装器内、其启动 Node 之前设置。不要为这些设置编辑生成的服务环境。即使现有存储的数值类似于旧的自动默认值或超过新建议值，也会被保留。
  • 当操作员拥有的服务覆盖控制 NODE_OPTIONS（包括空值或重置）时，重新生成不会添加新的自动堆参数。操作员值和 drop-in 文件与托管基础保持分离。现有托管 argv 控制仍然有效：对于同一选项，Node 的 argv 优先于 NODE_OPTIONS，且百分比旧空间大小优先于绝对旧空间大小。更改上限前，请检查这两个层面。
  • 安装程序环境中的 NODE_OPTIONS 和安装程序自身的 Node 参数不会保存为 Gateway 堆设置。预算在安装时选定，并在服务进程启动时生效；在 Gateway 运行期间不会重新计算。仅升级 OpenClaw 不会调整正在运行的 Gateway 大小，前台启动也不会自我替换以应用此策略。
  • 安装程序的内存约束可能与未来服务的约束不同。Node/libuv 的报告因平台而异，并且不保证检测到每个祖先 cgroup 限制；在增加预算前，请检查实际服务或容器限制。
  • 此策略适用于托管 Node Gateway 启动，不适用于前台 gateway run、自定义 supervisor、Docker 运行时命令、Bun 或 node-host 服务。它们保留自己的运行时配置。有关显式原生 Node 设置，请参阅内存故障排查。
安装时的身份验证与 SecretRefs
  • 当 token 身份验证需要 token，且 gateway.auth.token 由 SecretRef 管理时，gateway install 会验证 SecretRef 可解析，但不会将解析后的 token 持久化到服务环境元数据中。
  • 重新安装和更新会保留活动 env SecretRefs 的现有服务值，包括 Gateway token 和密码。在 Linux 和 macOS 上，旧的内联值会在重写 unit 或 LaunchAgent 之前移动到生成的仅所有者可访问的 env 文件中。这不会使服务凭据可用于交互式 CLI 命令。
  • 如果 token 身份验证需要 token，且配置的 token SecretRef 未解析，安装会失败关闭，而不是持久化回退明文。
  • 对于 gateway run 的密码身份验证，请优先使用 OPENCLAW_GATEWAY_PASSWORD、--password-file 或由 SecretRef 支持的 gateway.auth.password，而不是内联 --password。
  • 在推断身份验证模式下，仅 shell 中的 OPENCLAW_GATEWAY_PASSWORD 不会放宽安装 token 要求；安装托管服务时，请使用持久配置（gateway.auth.password 或配置 env）。
  • 如果同时配置了 gateway.auth.token 和 gateway.auth.password，且 gateway.auth.mode 未设置，安装将被阻止，直到显式设置 mode。

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