fix: clarify gateway version mismatch warnings

src/cli/daemon-cli/status.print.test.ts

@@ -157,7 +157,7 @@ describe("printDaemonStatus", () => {
     expect(runtime.log).toHaveBeenCalledWith(expect.stringContaining("Capability: write-capable"));
   });
 
-  it("prints CLI and gateway versions with stale wrapper guidance when they differ", () => {
+  it("prints CLI and gateway versions with readable guidance when they differ", () => {
     printDaemonStatus(
       {
         cli: {
@@ -195,10 +195,12 @@ describe("printDaemonStatus", () => {
     );
     expect(runtime.log).toHaveBeenCalledWith(expect.stringContaining("Gateway version: 2026.5.6"));
     expect(runtime.error).toHaveBeenCalledWith(
-      expect.stringContaining("CLI/runtime version skew detected"),
+      expect.stringContaining("this OpenClaw command is version 2026.4.23"),
     );
     expect(runtime.error).toHaveBeenCalledWith(
-      expect.stringContaining("stale PATH/global wrappers"),
+      expect.stringContaining(
+        "if this mismatch is unexpected, update PATH so `openclaw` points to the version you want",
+      ),
     );
   });
 

src/cli/daemon-cli/status.print.ts

@@ -193,12 +193,12 @@ export function printDaemonStatus(status: DaemonStatus, opts: { json: boolean })
     if (status.cli?.version && status.cli.version !== gatewayVersion) {
       defaultRuntime.error(
         warnText(
-          `Warning: CLI/runtime version skew detected. CLI is ${status.cli.version}; gateway is ${gatewayVersion}.`,
+          `Warning: this OpenClaw command is version ${status.cli.version}, but the running Gateway is version ${gatewayVersion}.`,
         ),
       );
       defaultRuntime.error(
         warnText(
-          `Fix: check for stale PATH/global wrappers with \`command -v openclaw\`, \`readlink -f "$(command -v openclaw)"\`, and \`openclaw --version\`; reinstall the gateway service from the intended binary if needed.`,
+          "Check `openclaw --version`, `which openclaw`, and `openclaw gateway status --deep`; if this mismatch is unexpected, update PATH so `openclaw` points to the version you want, or reinstall the Gateway service from that same OpenClaw install.",
         ),
       );
     }

src/commands/doctor-gateway-health.test.ts

@@ -49,10 +49,10 @@ describe("checkGatewayHealth", () => {
       timeoutMs: 6000,
     });
     expect(runtime.error).not.toHaveBeenCalled();
-    expect(note).not.toHaveBeenCalledWith(expect.any(String), "Gateway version skew");
+    expect(note).not.toHaveBeenCalledWith(expect.any(String), "OpenClaw version mismatch");
   });
 
-  it("notes CLI and gateway version skew when the gateway reports another runtime version", async () => {
+  it("notes CLI and gateway version mismatch when the gateway reports another runtime version", async () => {
     callGateway.mockResolvedValueOnce({ runtimeVersion: "2026.4.23" }).mockResolvedValueOnce({});
     const runtime = { log: vi.fn(), error: vi.fn(), exit: vi.fn() };
 
@@ -61,12 +61,22 @@ describe("checkGatewayHealth", () => {
     ).resolves.toEqual({ healthOk: true, status: { runtimeVersion: "2026.4.23" } });
 
     expect(note).toHaveBeenCalledWith(
-      expect.stringContaining("Gateway version: 2026.4.23"),
-      "Gateway version skew",
+      expect.stringContaining("the running Gateway is OpenClaw 2026.4.23"),
+      "OpenClaw version mismatch",
     );
     expect(note).toHaveBeenCalledWith(
-      expect.stringContaining("stale global wrapper"),
-      "Gateway version skew",
+      expect.not.stringContaining("That usually means"),
+      "OpenClaw version mismatch",
+    );
+    expect(note).toHaveBeenCalledWith(
+      expect.stringContaining("Check `openclaw --version`, `which openclaw`"),
+      "OpenClaw version mismatch",
+    );
+    expect(note).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "If this mismatch is unexpected, update PATH so `openclaw` points to the version you want",
+      ),
+      "OpenClaw version mismatch",
     );
   });
 

src/commands/doctor-gateway-health.ts

@@ -33,12 +33,11 @@ function noteCliGatewayVersionSkew(status: StatusSummary | undefined): void {
   }
   note(
     [
-      `CLI version: ${VERSION}`,
-      `Gateway version: ${gatewayVersion}`,
-      "The CLI and running gateway are different versions. This can happen when PATH points at a stale global wrapper while the service runs a newer install.",
-      'Fix: run `openclaw gateway status --deep`; check `command -v openclaw`, `readlink -f "$(command -v openclaw)"`, and `openclaw --version`; reinstall the gateway service from the intended binary if needed.',
+      `This command is OpenClaw ${VERSION}; the running Gateway is OpenClaw ${gatewayVersion}.`,
+      "Check `openclaw --version`, `which openclaw`, and `openclaw gateway status --deep`.",
+      "If this mismatch is unexpected, update PATH so `openclaw` points to the version you want, or reinstall the Gateway service from that same OpenClaw install.",
     ].join("\n"),
-    "Gateway version skew",
+    "OpenClaw version mismatch",
   );
 }
 

src/config/io.compat.test.ts

@@ -109,7 +109,7 @@ describe("config io paths", () => {
     });
   });
 
-  it("hints at stale wrappers when config was written by a newer OpenClaw", async () => {
+  it("explains what to check when config was written by a newer OpenClaw", async () => {
     await withTempHome(async (home) => {
       const configPath = path.join(home, ".openclaw", "openclaw.json");
       await fs.mkdir(path.dirname(configPath), { recursive: true });
@@ -138,12 +138,19 @@ describe("config io paths", () => {
       io.loadConfig();
 
       expect(logger.warn).toHaveBeenCalledWith(
-        expect.stringContaining("stale PATH or global wrappers"),
+        expect.stringContaining(
+          "Your OpenClaw config was written by version 9999.1.1, but this command is running",
+        ),
       );
-      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("command -v openclaw"));
-      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("openclaw --version"));
       expect(logger.warn).toHaveBeenCalledWith(
-        expect.stringContaining("openclaw gateway status --deep"),
+        expect.stringContaining(
+          "Check: `openclaw --version`, `which openclaw`, and `openclaw gateway status --deep`.",
+        ),
+      );
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "If unexpected, update PATH so `openclaw` points to the version you want",
+        ),
       );
     });
   });

src/config/io.ts

@@ -908,9 +908,11 @@ function warnIfConfigFromFuture(cfg: OpenClawConfig, logger: Pick<typeof console
     }
     warnedFutureTouchedVersions.add(touched);
     logger.warn(
-      `Config was last written by a newer OpenClaw (${touched}); current version is ${VERSION}. ` +
-        `If the gateway is healthy, check for CLI/runtime skew from stale PATH or global wrappers: ` +
-        `command -v openclaw; readlink -f "$(command -v openclaw)"; openclaw --version; openclaw gateway status --deep.`,
+      [
+        `Your OpenClaw config was written by version ${touched}, but this command is running ${VERSION}.`,
+        "Check: `openclaw --version`, `which openclaw`, and `openclaw gateway status --deep`.",
+        "If unexpected, update PATH so `openclaw` points to the version you want, or reinstall the Gateway service from that same OpenClaw install.",
+      ].join("\n"),
     );
   }
 }