fix(media/image): expand sharp-install hint to cover global installs

lonexreb · lonexreb · commit bc4c1c5ddf67 · 2026-05-05T13:12:07.000-05:00
Codex review on PR #77197 noted: the previous hint suggested local install commands (pnpm add sharp / npm install sharp / bun add sharp) but the scenario operators most often hit is a global `npm install -g openclaw` where the global runtime resolves `sharp` from openclaw's own global node_modules, so a workspace install does not actually fix the failure on restart. Expand the thrown error to include both repair postures: the existing local commands plus an explicit global path (`npm install -g openclaw@latest --include=optional` or `npm install -g sharp`) so operators on either install posture get a working remediation. Update the regression test to assert both surfaces appear in the message.
diff --git a/src/media/web-media.test.ts b/src/media/web-media.test.ts
@@ -167,18 +167,28 @@ describe("loadWebMedia", () => {
   // (e.g. the `image` agent tool) on hosts that skipped the optional `sharp`
   // native dep used to see a generic "Failed to optimize image" with the raw
   // module-resolution error tail, with no install hint. The thrown error now
-  // explicitly names the missing dep and the install command.
-  it("surfaces a clear sharp-install hint when the optional optimizer is unavailable (#73148)", async () => {
+  // explicitly names the missing dep and includes both the local-checkout and
+  // global-install repair commands so operators on either install posture get
+  // a working remediation.
+  it("surfaces a clear sharp-install hint covering both local and global installs when the optional optimizer is unavailable (#73148)", async () => {
     await withUnavailableImageOptimizer(async () => {
       const { optimizeImageToJpeg: optimizeImageToJpegWithMissingOptimizer } =
         await import("./web-media.js");
       const promise = optimizeImageToJpegWithMissingOptimizer(
         Buffer.from(TINY_PNG_BASE64, "base64"),
         8,
       );
-      await expect(promise).rejects.toThrow(
-        /requires the optional `sharp` native dependency.*pnpm add sharp/i,
+      const error = await promise.then(
+        () => null,
+        (err: unknown) => err,
       );
+      expect(error).toBeInstanceOf(Error);
+      const message = (error as Error).message;
+      expect(message).toMatch(/requires the optional `sharp` native dependency/i);
+      // Local-install repair command (workspace checkout).
+      expect(message).toMatch(/pnpm add sharp/);
+      // Global-install repair command (npm -g openclaw users).
+      expect(message).toMatch(/npm install -g openclaw@latest --include=optional/);
     });
   });
 
diff --git a/src/media/web-media.ts b/src/media/web-media.ts
@@ -705,11 +705,20 @@ export async function optimizeImageToJpeg(
   // resize attempt throws "Cannot find module 'sharp'". Surface a clear,
   // actionable hint so operators know what to install instead of a generic
   // "Failed to optimize image" with the raw module-resolution error tail.
+  // The hint covers both common scenarios:
+  //   - Local repo checkout: install `sharp` in the workspace.
+  //   - Global install (e.g. `npm install -g openclaw@latest`): a workspace
+  //     `pnpm add sharp` won't help because the global runtime resolves
+  //     `sharp` from the global openclaw `node_modules`. Reinstalling the
+  //     globally installed openclaw with optional deps included rebuilds the
+  //     `sharp` prebuilt for the host platform.
   // See #73148.
   if (isOptionalImageOptimizerUnavailable(firstResizeError)) {
     throw new Error(
       "Image optimization requires the optional `sharp` native dependency, which is not installed. " +
-        "Install it with `pnpm add sharp` (or `npm install sharp` / `bun add sharp`) and restart the gateway.",
+        "Local repo install: `pnpm add sharp` (or `npm install sharp` / `bun add sharp`) and restart the gateway. " +
+        "Global install: reinstall openclaw with optional deps included, e.g. `npm install -g openclaw@latest --include=optional` " +
+        "(or `npm install -g sharp` if you cannot reinstall openclaw), then restart the gateway.",
       { cause: firstResizeError },
     );
   }
