From bc77f7a00a5c006c1d8fb301f7b4d3ffeb13581a Mon Sep 17 00:00:00 2001
From: "Ashd.LW." <281221101+wAngByg@users.noreply.github.com>
Date: Sun, 31 May 2026 01:38:35 +0800
Subject: [PATCH] fix(gateway): explain ignored restart signal

Add actionable operator guidance when an unauthorized SIGUSR1 gateway restart is ignored because unmanaged restart is disabled.

The change is log-only: restart authorization and scheduling semantics are unchanged, and the existing run-loop test now asserts both the reason warning and the recovery hint.

Refs #79577
Refs #78110
Refs #82433

Co-authored-by: wAngByg <281221101+wAngByg@users.noreply.github.com>
---
 src/cli/gateway-cli/run-loop.test.ts | 7 +++++++
 src/cli/gateway-cli/run-loop.ts      | 7 ++++++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/cli/gateway-cli/run-loop.test.ts b/src/cli/gateway-cli/run-loop.test.ts
index 7e2d5b99c77..134941ad904 100644
--- a/src/cli/gateway-cli/run-loop.test.ts
+++ b/src/cli/gateway-cli/run-loop.test.ts
@@ -1205,6 +1205,13 @@ describe("runGatewayLoop", () => {
       expect(gatewayLog.warn).toHaveBeenCalledWith(
         "SIGUSR1 restart ignored (not authorized; commands.restart=false or use gateway tool).",
       );
+      expect(gatewayLog.warn).toHaveBeenCalledTimes(2);
+      expect(gatewayLog.warn).toHaveBeenNthCalledWith(
+        2,
+        "An unauthorized SIGUSR1 restart signal was received and ignored. " +
+          "If a pending gateway restart needs to be applied, run `openclaw gateway restart` " +
+          "or restart the gateway through your service manager.",
+      );
     });
   });
 
diff --git a/src/cli/gateway-cli/run-loop.ts b/src/cli/gateway-cli/run-loop.ts
index 67b8d1b2793..532b9c85411 100644
--- a/src/cli/gateway-cli/run-loop.ts
+++ b/src/cli/gateway-cli/run-loop.ts
@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import net from "node:net";
+import { clearRuntimeConfigSnapshot } from "../../config/runtime-snapshot.js";
 import {
   captureGatewayRestartTraceHandoff,
   createGatewayRestartTraceHandoffEnv,
@@ -12,7 +13,6 @@ import { formatErrorMessage } from "../../infra/errors.js";
 import { acquireGatewayLock } from "../../infra/gateway-lock.js";
 import { createSubsystemLogger } from "../../logging/subsystem.js";
 import type { RuntimeEnv } from "../../runtime.js";
-import { clearRuntimeConfigSnapshot } from "../../config/runtime-snapshot.js";
 import { createLazyImportLoader } from "../../shared/lazy-promise.js";
 const gatewayLog = createSubsystemLogger("gateway");
 const LAUNCHD_SUPERVISED_RESTART_EXIT_DELAY_MS = 1500;
@@ -743,6 +743,11 @@ export async function runGatewayLoop(params: {
           gatewayLog.warn(
             "SIGUSR1 restart ignored (not authorized; commands.restart=false or use gateway tool).",
           );
+          gatewayLog.warn(
+            "An unauthorized SIGUSR1 restart signal was received and ignored. " +
+              "If a pending gateway restart needs to be applied, run `openclaw gateway restart` " +
+              "or restart the gateway through your service manager.",
+          );
           return;
         }
         if (shuttingDown) {