跳转至

重启与监控

重启标志,用于确定宿主服务、外部监督程序和性能分析的归属安装。属于 openclaw gateway 参考文档的一部分。

重启网关

openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --safe --skip-deferral
openclaw gateway restart --force
openclaw gateway restart --wait 30s

Warning

手动重启信号现在使用 SIGUSR2。SIGUSR1 会启动 Node 的 inspector,不再重启网关。请更新发送旧信号的脚本;对于能感知服务的重启,请优先使用 openclaw gateway restart。

如果重启无法验证存在一个活跃的正在服务的属主进程,则不会触动该进程。运行 openclaw gateway status --deep,修复报告中的启动失败(例如,在配置了 Serve 时 Tailscale 后端已停止),然后运行 openclaw gateway start 等待就绪。仅凭已加载的服务或运行中的 PID 并不能证明网关正在服务。重新安装并不能解决未解决的启动依赖或未知的进程归属问题。

--safe 请求正在运行的网关对活跃工作进行预检,并在这些工作排空后安排一次合并重启。等待时间上限为 5 分钟;当预算耗尽时,重启会被强制进行。--safe 不能与 --force 或 --wait 组合使用。

--skip-deferral 仅绕过安全重启的活跃工作延迟门。即使报告存在活跃工作阻塞,它也可以将网关移入关闭状态,但在进程退出前,关闭阶段中待处理回复的排空仍然适用。它要求与 --safe 一起使用——当某个延迟被失控任务卡住,但仍可让回复投递完成时,可使用此选项。

--wait <duration> 覆盖普通(非安全)重启的排空预算。接受纯毫秒数或单位后缀 ms、s、m、h、d(例如 30s、5m、1h30m);--wait 0 表示无限期等待。不能与 --force 或 --safe 兼容。

原生服务停止期限仍然适用:对于 systemd 的 330 秒限制,网关将排空时间上限设为 315 秒;对于 launchd 的 20 秒限制,则设为 5 秒。两者都为取消和清理留有时间。这些上限同样适用于 --wait 0。更长的模型或心跳超时不会延长该期限。排空日志在可用时会报告观测到的最大模型请求超时时间,以供参考。

当关闭操作停止准入时,排队中的心跳唤醒会以 gateway-draining 状态收尾,包括等待重试的唤醒。它们无法在排空运行时中开始另一轮操作。已在运行的唤醒和待处理的最终回复写入仍保留其排空宽限期。

如果在 systemd 或 launchd 下,工作仍无视取消操作直至关闭期限,原生服务停止或监督程序所属的重启会记录剩余的工作类别和待处理属主(包括命令通道和请求来源),写入一份诊断性稳定性包,并以状态 0 退出。它不会复用那个未完成的运行时来进行进程内重启。这样可以让请求的停止干净地完成,并让服务管理器为重启启动一个新的网关。

显式的服务器关闭失败会保留退出状态 1,包括当最终提供方清理超出原生关闭期限时。

准入关闭日志会标明关闭触发器,例如 stop (SIGTERM) 或 restart (SIGUSR2: config reload: gateway.bind)。单独的信号无法识别其发送方:Node 不会暴露发送者的 PID 或命令。同一进程在五分钟内出现三次相同信号,或在进程生命周期内记录到三次普通 SIGTERM/SIGINT 停止,都会提示您检查 openclaw gateway status --deep 以查找另一个监督程序。深度本地状态会显示所选状态目录的最后一次记录的关闭原因和时间;在 Linux 上,检查原生服务时,它还会报告相互竞争的用户服务单元和系统服务单元。失败结果会保留其具体的失败原因。

降级后,如果数据库的 schema 比当前运行的构建版本所支持的更新,网关会拒绝使用这些数据库。启动错误和 openclaw gateway status --deep 会报告实际找到和受支持的 schema 版本、记录到的写入者构建版本,以及拒绝启动的构建版本。请运行一个至少与写入者同样新、且支持这些 schema 的构建,或停止服务并恢复升级前的备份。启动时保留退出状态 78,并在可能的情况下停放受管理的 LaunchAgent。被拒绝的共享状态数据库无法记录新的生命周期行;错误日志会说明拒绝原因,深度状态会报告这一情况,而不是显示不可用的关闭记录。

当共享状态数据库完全无法读取时(例如文件已损坏),openclaw gateway status --deep 会以退出状态 1 失败,并指出数据库路径和读取错误,而不是报告配置读取失败。请停止 OpenClaw 进程,然后从经过验证的备份中恢复该文件,openclaw doctor 也建议这样做。

前台/手动网关、由 OPENCLAW_NO_RESPAWN=1 选择的进程内重启,以及其他监督程序,在清理无法于关闭期限前完成时,会保留退出状态 1。

--force 会立即开始重启并关闭新的准入。当前 CLI 提供正常的排空预算,并以原生服务关闭期限为上限。只有在该期限仍剩余的工作会在清理前被取消。已经过了延迟预算的安全重启不会获得第二次排空预算。普通的 restart 通常会使用服务管理器的重启路径。

来自旧调用方且未提供排空预算的强制请求,最多有 45 秒的排空时间。它们的 60 秒替换窗口为清理预留 10 秒,为替换预留 5 秒。这同样适用于交互式和更新调用方。如果排空到期时仍有工作,网关会在其重启历史和日志中记录一条包含剩余工作类别的警告,然后通过正常的终止恢复取消这些工作。提供预算的调用方保留其预算,但受原生服务期限约束。

在升级期间,重启会在现有网关状态中记录其原因和排空选项,而不会在旧网关仍在运行时启动 schema 迁移。如果不存在状态数据库,它会记录一条跳过意图记录的日志,然后继续重启。

当更新器调用已安装的 gateway restart 命令时,其现有的更新标记会在观察到受管进程正在运行后启用五分钟启动看门狗。这使得较旧的更新器能够在不传递新选项的情况下完成缓慢的首跳启动。看门狗包括迁移、监听器和健康阶段;阶段变化不能延长其上限。由较新的更新调用方提供的显式就绪预算优先。普通独立重启只有在同一正在运行的 Gateway 推进启动阶段,或获取、续期或完成一个被观察到的同进程迁移时,才会在标准就绪预算之外等待,最长五分钟,然后报告 still-starting(退出码 2),并附上最后阶段以及将 openclaw gateway status --deep 作为下一步;没有进展的启动仍会在标准预算时失败(退出码 1),而一个新观察到的迁移租约在被视为停滞前会获得一个心跳间隔加上轮询宽限,其被观察到的完成会在同一上限内获得一个新的就绪窗口。参见 重启恢复。

在 Windows 上,受管的 gateway start 和 gateway restart 允许冷启动最多 90 分钟,使用三个默认的更新步骤预算,分别用于激活、加载和就绪。受管更新恢复使用相同的允许时间,除非显式的 update --timeout 提供了其每步预算。隐式 Windows 更新就绪检查使用观察到的启动时长的十倍,限制在 90 到 120 分钟之间;上限不能截断冷启动下限。这可以适应慢速存储上的大型代理数据库;退出或健康检查失败的服务仍可以更早报告失败。在截止时间仍处于启动状态的存活 Gateway 会被保留运行并报告为 still-starting;更新会保留就绪警告和恢复备份。

在 Windows 上,从 Gateway 服务进程启动的普通重启,包括代理的 shell 命令,会自动使用安全重启路径。正在运行的 Gateway 拥有延迟的 Scheduled Task 交接,因此停止其进程树不会在重新启动前杀死调用方。这需要可到达的 Gateway;该命令确认的是重启请求,而不是后继进程的健康状态。之后请使用 openclaw gateway status 验证恢复。

Windows 交接最多等待三分钟,直到旧 Gateway 退出,然后请求任务启动。只有当一个具有预期可执行文件和 Gateway 入口点的不同进程在配置的端口上监听时,它才会在 logs/gateway-restart.log 中记录 restart finished。此监听器检查使用相同的 90 分钟冷启动允许时间;它不能证明通道就绪。仅标记为 Running 的任务或成功的启动请求本身不算恢复。

如果没有替代监听器出现,日志会记录 restart failed 以及一条感知 profile 的 openclaw gateway restart --force 命令,供从外部终端运行。交接不会结束其自身的 Scheduled Task:在具有 Job Object 包含的安装中,这样做可能会在观察者记录结果之前终止观察者。过期的运行任务仍可能需要此外部恢复。

在 macOS 上,当 openclaw gateway restart、stop、install 或 uninstall 在受管 LaunchAgent 的进程树内运行时,包括代理的 shell 命令,OpenClaw 会从 launchd 的服务环境中检测到这一点,或者,当手写 plist 省略了这些变量时,从针对 launchd 为该作业报告的 PID 的进程祖先关系中检测到。重启会交接给一个分离的辅助进程,因此 kickstart -k 无法杀死调用方。停止、安装和卸载会拒绝,并要求你从外部 shell 运行该命令。

没有 Gateway 服务标记的外部终端、外部监督的 Gateway、node 服务以及非 Windows 调用方保留其现有路由。显式的 --force、--wait、--preserve-definition 或 --skip-deferral 也保留其现有行为和验证;它们不会隐式启用 --safe。

Warning

内联 --password 可能在本地进程列表中暴露。请优先使用 --password-file、环境变量或基于 SecretRef 的 gateway.auth.password。

安装身份

服务管理(install、start、stop、restart、uninstall、Doctor 服务修复以及自更新服务处理)属于拥有主机服务的安装。即操作系统账户主目录下的规范 .openclaw 目录,或命名 profile 投射到那里的 .openclaw-<profile> 目录。命名 profile 使用不同的原生服务身份。

OPENCLAW_HOME 可以显式选择操作系统账户主目录,包括该主目录的文件系统别名。进程主目录(HOME 或 USERPROFILE)和有效的 OpenClaw 主目录都必须解析到账户主目录。指向其他位置的 OPENCLAW_HOME、OPENCLAW_STATE_DIR 或 OPENCLAW_CONFIG_PATH 会被视为隔离状态并跳过。迁移或复制的状态树不能接管并重写账户的主机服务。

Doctor 还会验证已安装服务中保存的环境。那里的规范 OPENCLAW_HOME 不会阻止 openclaw doctor --fix 进入维护并导入旧版凭据。Doctor 仍然是迁移所有者:它会验证导入的凭据,并在正常运行时读取恢复之前归档原始字节。

在 macOS 和 Windows 上,原生服务管理的 profile 名称必须为小写。仅运行时 profile 仍可使用大写,但大小写不同的名称(例如 Main 和 main)在普通大小写不敏感的文件系统上会共享路径,并且无法安全地拥有独立的原生服务。在 macOS 上,小写名称 gateway 和 node 也无法用于原生服务管理,因为它们的历史 LaunchAgent 标签与默认 Gateway 和 node-host 服务冲突。

命名 profile 还必须使用从 OPENCLAW_PROFILE 派生的原生服务身份。在服务管理之前,请取消设置 OPENCLAW_LAUNCHD_LABEL、OPENCLAW_SYSTEMD_UNIT 或 OPENCLAW_WINDOWS_TASK_NAME;自定义身份仍可用于默认 profile 或仅运行时/外部监督配置。

在 Linux 上,发现也识别旧版 openclaw-<profile> 单元名称。当自定义系统单元的 OpenClaw 启动器、服务账户、profile 和状态/配置路径标识该安装时,它可以属于默认安装。发现使用 systemd 的有效命令和环境,包括 drop-in 片段和环境文件。如果多个自定义单元匹配,或包装器使它们的身份不明确,请使用 OPENCLAW_SYSTEMD_UNIT 指定目标单元;OpenClaw 不会选择第一个携带其标记的单元。

Doctor 仅在两个管理器已加载的 Gateway 命令标识所选账户、profile、状态/配置路径以及匹配的端口选择时,才提供重复用户单元清理。它会在确认后重新检查这些单元。身份不同或无法验证时,用户单元会保留原样。清理仅移除已确认的用户单元,然后报告任何剩余匹配的单元或无法验证的发现;其他单元需要在后续 Doctor 运行中单独检查和确认。

在 Linux 上,openclaw gateway install --force 在更改配置、身份验证令牌或服务文件之前,会拒绝已密封的 systemd 服务定义,或无法验证其写入权限的定义。错误会保留其 SERVICE_DEFINITION_SEALED 或 SERVICE_DEFINITION_UNKNOWN 前缀,并添加原因标签和下一步操作,而不打印私有路径、配置、环境值或底层检查错误。

对于 [unsafe-permissions],请在本地检查指定的工件类别。服务目录是 ~/.config/systemd/user;在新安装中,其最近的已存在父目录可能是 ~/.config。服务状态目录属于所选 profile。请检查目录元数据,而不是文件内容:

ls -ld ~/.config ~/.config/systemd ~/.config/systemd/user

在新安装中,缺少目录是正常的。在确认受影响的路径属于您且并非有意共享后,请使用 chmod go-w <path> 移除组/其他用户的写入权限,然后重试同一命令。模式 0700 适用于私有目录。不要递归执行 chmod、接管系统路径的所有权,或使用 sudo/--force 绕过检查。外部拥有的文件和已密封的挂载需要部署所有者;检查失败需要先恢复文件系统或原生服务管理器访问权限。

类型范围的 service.d 默认值作为共享只读输入进行检查,不需要写入权限。root 拥有的所选单元和单元特定的 drop-in 片段仍受保护。

外部监督程序

仅当另一个进程管理器拥有 Gateway 生命周期时,才设置 OPENCLAW_SUPERVISOR_MODE=external。在此模式下:

  • openclaw gateway restart 会保留现有的安全、强制和有界等待行为,同时针对已验证正在运行的 Gateway,而不是 launchd、systemd 或 Task Scheduler。精确锁重启投递在该 Gateway 内部运行,因此替换 CLI 不会在旧进程交接之前迁移共享状态。
  • 原生服务安装、启动、停止和卸载操作会被拒绝,并提示使用外部监督程序。
  • OpenClaw 自更新会被拒绝,以便监督程序可以停止 Gateway、替换并固化运行时,然后安全地重启它。
  • 新进程重启会在干净退出前写入有界的 SQLite 交接。如果持久化失败,Gateway 会回退到进程内重启,而不是在没有可用交接的情况下退出。

外部监督程序还可以声明对共享状态写入的持久所有权:

OPENCLAW_SUPERVISOR_MODE=external \
  openclaw database ownership claim --manager gateway-supervisor --json

在声明之前,请通过外部监督程序停止 Gateway,并停止任何嵌入式代理。CLI 会强制此流程:它会拒绝存活的 Gateway 或嵌入式代理所有者,并在提交声明时保持独占的离线所有权。同时停止并验证所有早于 2026.8.1 且可写入共享状态数据库的 CLI、Doctor、更新器和原生应用进程。所有权契约(#121069)之前的进程不理解所有权行,也无法追溯地隔离。仅在所有剩余写入者都使用所有权感知代码并携带 OPENCLAW_SUPERVISOR_MODE=external 后再声明。

对于相同的稳定管理器标识符,声明是幂等的,并拒绝不同的管理器。没有自动声明或取消声明的路径。一旦声明,未标记的可写共享状态打开会在权限、架构迁移、增量修复、压缩或其他变更之前失败。只读访问仍然可用。这是针对意外未标记的同用户写入者的保护,而不是身份验证或租约协议。

对于升级和回滚,请让监督程序创建一个合并的、WAL 一致的复制快照,且没有 SQLite 附属文件,然后在激活前运行目标版本自身的 openclaw database preflight <copied-state.sqlite> --json。仅凭数字架构版本无法证明同版本的增量形状兼容。参见 数据库架构。

OPENCLAW_SERVICE_REPAIR_POLICY=external 仍是一项独立的 Doctor 修复策略。它不声明运行时所有权;需要这两种行为的监督程序应同时设置这两个变量。

外部监督程序可以通过隐藏机器契约协商和消费重启交接:

openclaw gateway restart-handoff capabilities --json
openclaw gateway restart-handoff consume --expected-pid <pid> --json

协议版本 1 支持 consume 操作。消费会在一个即时 SQLite 事务中验证预期 PID 和有界交接字段。已接受的交接会在返回成功之前被删除,因此并发或重放的消费者不能同时接受它。PID 不匹配会保留给匹配的所有者;缺失、过期和无效的行不会授权重启。

有效的机器请求返回 JSON,退出码为 0,包括非重启结果。无效参数返回 reason: "invalid-expected-pid",退出码为 2;状态存储失败返回 reason: "store-unavailable",退出码为 1。监督程序应检查其将使用的确切运行时或启动器的 capabilities,而不是从 OpenClaw 版本字符串推断支持,或直接读取私有 SQLite 架构。

外部 supervisor 实现也应应用这些验收规则:

  • 为能力检查设置超时,该超时需考虑已部署的运行时和存储上完整的 CLI 冷启动延迟,而不是假设热启动时序。
  • 如果能力协商或交接消费拒绝替换,请立即以非零状态退出,以便进程管理器的恢复策略能够运行。不要在没有 Gateway 子进程或监听器的情况下保持存活。
  • 应将 supervisor 进程存活与替换启动和通道就绪区分开来。只有在新 Gateway 拥有其监听器且 /startupz 返回 status: "started" 之后,才报告成功;单独监控 /readyz 以检查已配置通道的健康状况,而 /healthz 仅证明存活。

Gateway profiling

  • OPENCLAW_GATEWAY_STARTUP_TRACE=1 会在启动期间记录各阶段计时,包括每个阶段的 eventLoopMax 延迟以及插件查找表计时(installed-index、manifest registry、startup planning、owner-map work)。process.bootstrap 细分包括更早的 CLI 导入、配置、数据库准入、会话清单和工作区就绪。每个 bootstrap 步骤记录其相对于进程的 start、持续时间、调用次数和可用 fleet 数量;重复调用会聚合到一个名称下。ready trace 会重复 bootstrapSteps 中的步骤名称和总计。嵌套步骤会重叠,因此不应将它们的持续时间相加。
  • OPENCLAW_GATEWAY_RESTART_TRACE=1 会记录 restart trace: 行,用于重启信号处理、active-work drain、关闭阶段、下次启动、就绪计时和内存指标。普通停止也会启动一条新的 trace,包含 stop.signal.received 和 stop.drain 计时。命名的关闭步骤和粗粒度关闭阶段会在等待前发出 .begin,然后在稳定时发出持续时间;未匹配的 begin 标识一个已进入但尚未稳定的阶段。这些阶段不会单独计时每个嵌套清理操作。
  • OPENCLAW_DIAGNOSTICS=timeline 配合 OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path> 会为外部 QA harness 写入尽力而为的 JSONL 启动诊断时间线(等效于配置 diagnostics.flags: ["timeline"];路径仍仅限环境变量)。添加 OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 以包含事件循环采样。
  • pnpm build 然后 pnpm test:startup:gateway -- --runs 5 --warmup 1 会针对已构建的 CLI 入口对 Gateway 启动进行基准测试:首个进程输出、/healthz、/readyz、启动 trace 计时、事件循环延迟和插件查找表计时。
  • pnpm build 然后 pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5 会在 macOS 或 Linux 上对进程内重启进行基准测试(Windows 不支持;重启需要 SIGUSR2)。它使用 SIGUSR2,在子进程中启用两种 trace,并记录下一个 /healthz、下一个 /readyz、停机时间、就绪计时、CPU、RSS 和重启 trace 指标。
  • /healthz 是存活;/readyz 是可用的就绪状态。应将 trace 行和基准测试输出视为 owner 归属信号,而不是基于单个 span 或样本得出的完整性能结论。

在没有 tracing 的情况下,停止和重启会在首次 drain 快照时报告非零 active-work 类别计数,并在仍待处理时最多每 30 秒报告一次。 这些报告会省略任务标识和请求来源;类别可能重叠。 普通停止会在拆除前记录 active-work drain settled; beginning server close,包括在 drain 超时或失败之后。诊断不会更改 drain 预算或服务管理器的停止截止时间。

客户端断开连接后,交互式设置仍可用于重连。Gateway 停止或重启会在排空工作之前关闭设置提示。已在进行中的设置写入可能完成,但设置不会在关闭期间等待另一个答案。 Gateway 再次启动后,重新打开设置并检查已保存的设置。

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