跳转至

服务

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

管理 Gateway 服务

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

gateway stop、gateway uninstall 和 gateway restart 在配置无效或需要 Doctor 迁移时仍然可用,包括由更新版本的 OpenClaw 写入的配置。它们控制已记录的服务,并将配置问题作为警告报告,同时提供 openclaw doctor --fix 指导。停止和卸载不会重写配置。当配置需要修复时,重启会保留已安装的服务定义;其健康检查仍会报告 Gateway 是否已恢复运行。gateway start 在启动 Gateway 之前仍会验证配置。

gateway status 将服务进程状态与 Gateway 就绪状态分开报告。当其连接检查失败时,即使进程正在运行,也应检查服务日志。最近的日志错误是来自有界日志尾部的匹配证据,可能属于较早的运行,并不能确定当前进程的启动阶段。常规启动和关闭消息不会作为错误报告。Doctor 和引导流程使用相同的错误筛选。

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

如果任务结算检查在停止预算内仍不可用,重启仍会在确认 Gateway 已退出后尝试已捕获的任务,然后报告重启未经验证。观察到的替换实例会被保留,并且重启会被拒绝。

gateway start 即使服务进程已在运行也会检查就绪状态。只有选定的 Gateway 通过健康和就绪检查后,它才会报告 already-running;它不会重启仍在预热中的进程。

如果 gateway start 在托管 Gateway 仍在启动时达到就绪截止时间,它会报告 still-starting 并以代码 2 退出。服务会继续运行;在重启它之前,请再次检查 openclaw gateway status --deep。已崩溃的服务或外部监听器仍会导致失败。仅凭端口占用无法证明就绪,也不能排除预热。

Linux 维护保持

在 Linux 上,openclaw gateway stop 会请求 systemd 停止该单元。显式停止会抑制其 Restart=always 策略,直到单元再次启动;它不会禁用下次登录或启动时的启动。gateway stop --disable 仅限 macOS。对于非交互式维护,请使用 openclaw gateway stop --force。

systemd 掩码也会拒绝显式启动。请将掩码保持在操作员控制之下:OpenClaw 不会自动移除它们。如果你为维护而掩码了默认用户服务,请在更新前移除该保持:

systemctl --user unmask openclaw-gateway.service
openclaw update

对于自定义 profile 或系统服务,请使用 openclaw gateway status --deep 显示的单元和作用域。在运行 openclaw update 之前取消掩码:预检会在替换文件或运行迁移之前拒绝已掩码的托管单元。Doctor 和 status 会报告掩码及取消掩码命令;Doctor 不会移除该保持,也不会提供重新安装已掩码单元的选项。

如果单元在更新期间变为已掩码,更新器会保留已激活的候选项,并报告服务定义警告。移除掩码,运行 openclaw gateway start,并检查 openclaw gateway status --deep;被拒绝的启动并不能证明候选项不健康,也不能证明 Gateway 已就绪。

恢复无法读取的原生服务定义

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

对于格式错误的定义或不受支持的环境语法,请私下备份服务文件以及仅存储在其环境中的任何值。在重新安装前修正未解析或不受支持的值;OpenClaw 无法推断其预期值。然后,从外部 shell 使用相同的账户和 profile:

openclaw gateway uninstall
openclaw gateway install
openclaw gateway health

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

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

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

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

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

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

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

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

固定服务运行时

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

配置和高级入门引导首先建议受支持的记录运行时。如果没有,其运行时选择器在无可用的受支持 Node 时建议正在运行的受支持 Bun,否则建议 Node。选择器选择是显式的:在仅 Bun 主机上选择 Node 会在替换服务之前报告 Node 不可用。Quickstart 保持自动选择,而不创建运行时固定。

使用 --runtime-path 让服务保留在操作员选择的 Node 或 Bun 可执行文件上,而不是自动运行时选择:

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

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

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

修复 LaunchAgent 环境包装器

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

在修复格式错误的定义之前,请备份 plist 和私有服务环境文件。如果其运行时参数也已更改,请如上所示使用 --runtime-path 显式选择目标可执行文件。服务定义已更改的记录运行时固定必须再次显式选择。保持仅服务的环境值可供重新安装使用;格式错误的包装器参数可能阻止 OpenClaw 读取之前的环境文件。

使用包装器安装

当托管服务必须通过另一个可执行文件启动时,请使用 --wrapper,例如密钥管理器 shim 或 run-as helper。包装器接收正常的 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 的主要且推荐的运行时,也是全新安装的默认运行时;在没有显式指定运行时、固定版本(pin)或包装器的情况下,如果在受支持的 Bun 下运行安装,则会使用该可执行文件,并且在找不到受支持的 Node 时不会创建固定版本。隐式重新安装会按上述说明保留受支持的已记录 Node 或 Bun 运行时。
  • 对于未固定版本的 service,gateway install 会检查受管服务中记录的 Node 可执行文件。如果该文件缺失、不可执行或不受支持,安装过程将刷新服务且无需 --force,并报告替换后的路径。这同样适用于安装程序或更新程序刷新服务的情况。修复操作会优先使用当前 CLI 支持的 Node,同时保留稳定的 Homebrew 路径,然后再检查受支持的系统安装。自定义包装器继续控制其自身运行时;受保护的服务定义仍需要其部署所有者进行修复。
  • Bun 1.4+ 以及具备 WAL 重置安全的 node:sqlite 可作为显式选择,通过 gateway install --runtime bun 启用。
生命周期行为
  • gateway start 是幂等的:当受管服务已在运行时,它会报告正在运行的进程并保持其不变。已加载但已停止的服务会像之前一样被启动。
  • 在 Windows 上,显式执行 gateway start 会在验证所选 profile 和命令后重新启用已禁用的 Scheduled Task。它会保留已注册的启动器和触发器设置。如果启用成功但启动失败,该 Task 可能仍处于启用状态;重试前请使用 gateway status --deep 检查同一 profile。update repair 会让已停止的 Gateway 保持离线;若你希望其上线,请随后运行 gateway start。
  • 如果未安装受管服务,gateway start 会打印安装提示并以非零状态退出。gateway restart 可以首先恢复已安装但未加载的 LaunchAgent,或经过验证的非受管 Gateway;如果受管服务和恢复流程都无法处理该操作,它会打印相同的提示并以非零状态退出。停止不存在的服务仍是成功的空操作(no-op)。
  • 如果 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 entries)。daemon restart 别名也接受相同的选项。
  • 在进行可写 Linux 服务安装或刷新期间,请保持 unit 和状态目录固定不变,并避免并发的手动编辑。OpenClaw 会对其自身的写入操作进行串行化,并在检测到变更时中止,但无法协调任意的文件系统编辑。在发布过程中移动或替换父目录可能会在移动后的目录中留下临时文件;重试前请检查该文件。
  • 在 macOS 上,失败的 LaunchAgent 替换操作回滚时会恢复之前的 plist 字节和权限位,包括二进制 plist。如果无法完成恢复,命令会报告失败。
  • 请使用 gateway restart 重启受管服务。不要将 gateway stop 和 gateway start 串联起来代替重启。
  • 正在运行的 Gateway 会在共享状态中记录其进程身份、监听器模式和监督器。重启会在启动期间保留已验证的活动属主,即使其监听器尚未打开;健康检查超时不会使该属主过期。已记录的前台属主即使在已安装原生服务的情况下也会收到定向重启。Scheduled Task 清理会保留外部监督器和其他任务,并在错误中标识其属主。没有记录身份的旧版 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 的启动、停止和重启操作、安全重启请求、监督器重启以及分离式交接(detached handoffs)。
  • 生命周期命令支持 --json 以便脚本化使用。
  • 如果重启完成了原生激活或已接受的恢复,但健康检查失败,则会输出 action: "restart"、ok: false 和 result: "restart-health-failed",并保留其错误、提示、警告和退出码 1。此诊断信息并不授权再次激活。拒绝、意外异常,以及未经确认激活的定义修复不会输出此结果。计划的重启仅报告已接受,而不声明后继运行的健康状态。

```

托管网关堆大小设置
  • 对于没有现有堆设置的托管 Node 网关,gateway install 会将 --max-old-space-size 放入 Node 的启动参数中,位于入口脚本之前。它会显式清除服务环境中的 NODE_OPTIONS,以免环境中的服务管理器预加载/调试标志泄漏到网关中。普通派生的 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 参数不会保存为网关堆设置。预算在安装时选定,并在服务进程启动时生效;网关运行期间不会重新计算。仅升级 OpenClaw 不会调整正在运行的网关,前台启动也不会自我替换以应用此策略。
  • 安装程序的内存约束可能与未来服务的约束不同。Node/libuv 的报告取决于平台,并不保证检测到每个祖先 cgroup 限制;在提高预算前,请检查实际的服务或容器限制。
  • 此策略适用于托管 Node 网关启动,不适用于前台 gateway run、自定义监督程序、Docker 运行时命令、Bun 或 node-host 服务。它们保留各自的运行时配置。有关显式原生 Node 设置,请参阅 内存故障排除。
安装时的身份验证和 SecretRef
  • 当令牌身份验证需要令牌且 gateway.auth.token 由 SecretRef 管理时,gateway install 会验证该 SecretRef 可解析,但不会将解析后的令牌持久化到服务环境元数据中。
  • 重新安装和更新会保留活动 env SecretRef 的现有服务值,包括网关令牌和密码。在 Linux 和 macOS 上,旧的内联值会在重写 unit 或 LaunchAgent 之前移入生成的仅限所有者访问的 env 文件。这不会使服务凭据可用于交互式 CLI 命令。
  • 如果令牌身份验证需要令牌,且配置的令牌 SecretRef 未解析,安装会失败关闭,而不是持久化回退明文。
  • 对于 gateway run 的密码身份验证,请优先使用 OPENCLAW_GATEWAY_PASSWORD、--password-file 或由 SecretRef 支持的 gateway.auth.password,而不是内联 --password。
  • 在推断身份验证模式下,仅 shell 中的 OPENCLAW_GATEWAY_PASSWORD 不会放宽安装令牌要求;安装托管服务时,请使用持久配置(gateway.auth.password 或配置 env)。
  • 如果同时配置了 gateway.auth.token 和 gateway.auth.password,且 gateway.auth.mode 未设置,则安装会被阻止,直到显式设置模式。

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