openclaw - 💡(How to fix) Fix bug: image tool fails with "Failed to optimize image" — sharp postinstall silently dropped after `npm install -g openclaw` on macOS [1 comments, 2 participants]

Bug type

Regression (worked before, now fails)

Beta release blocker

No

Summary

After upgrading OpenClaw to 2026.4.26 via npm install -g openclaw on macOS Apple Silicon, the image tool fails with "Failed to optimize image". Root cause: sharp's postinstall script was silently dropped during the global npm install, leaving node_modules/sharp/ missing entirely. Image processing was working before the upgrade.

Steps to reproduce

1. Have OpenClaw installed globally via npm install -g openclaw on macOS Apple Silicon, with image processing previously working.
2. Upgrade to 2026.4.26 (or run a fresh global install) under any condition that causes sharp's postinstall to fail silently — flaky network, prebuilt-install transient 404, etc.
3. Send any image (screenshot, JPEG, PNG) to the agent.
4. Agent reports: "Failed to optimize image".
5. Verify: ls /usr/local/lib/node_modules/openclaw/node_modules/sharp/ returns "No such file or directory".
6. Gateway logs show: [tools] image failed: Failed to optimize image and Optional dependency sharp is required for image attachment processing.

Expected behavior

The image tool should successfully process incoming images, as it did before the upgrade. At minimum, sharp's postinstall failure during a global npm install should not be silently swallowed — installs should fail loudly when a critical native dep for image processing is missed, OR openclaw doctor should detect the missing sharp module and surface a clear, actionable repair instruction.

Actual behavior

The image tool fails immediately with the generic message "Failed to optimize image". The user-facing error gives no hint that sharp is missing — the actual cause is buried in ~/.openclaw/logs/ gateway logs. There is no doctor-level warning. npm rebuild sharp reports "rebuilt dependencies successfully" while doing nothing, because node_modules/sharp/ was never created in the first place — making diagnosis genuinely confusing.

OpenClaw version

2026.4.26

Operating system

macOS, Apple Silicon

Install method

Global npm install (npm install -g openclaw)

Model

Not relevant — bug is in the install/packaging layer, reproduces independently of which model is configured. Tested with: kimi/k2.6-code-preview.

Provider / routing chain

Not applicable — this bug is in the local install/packaging layer, independent of model/provider routing. Sharp is a native image-processing dependency loaded by the local OpenClaw process.

Additional provider/model setup details

Not relevant — bug is in local install state, not in provider/routing config. The relevant local state for this bug is:

• OpenClaw install path: /usr/local/lib/node_modules/openclaw (global npm install)
• Expected sharp path: /usr/local/lib/node_modules/openclaw/node_modules/sharp/
• Sharp registered under onlyBuiltDependencies in OpenClaw's package.json
• Tested config (memorySearch / models) is unrelated to this bug — reproduces with any model/provider setup.

Logs, screenshots, and evidence

Filesystem state BEFORE fix:

    $ ls -la /usr/local/lib/node_modules/openclaw/node_modules/sharp/
    ls: ... : No such file or directory

Filesystem state AFTER fix:

    $ ls -la /usr/local/lib/node_modules/openclaw/node_modules/sharp/
    drwxr-xr-x  install/  lib/  src/  LICENSE  package.json  README.md

    $ node -e "console.log(require('.../sharp').versions)"
    sharp version: {
      sharp: '0.34.5',
      vips:  '8.17.3',
      heif: '1.20.2', webp: '1.6.0', png: '1.6.50', tiff: '4.7.1',
      cairo: '1.18.4', pango: '1.57.0', harfbuzz: '12.1.0',
      ... (28 total libvips dependencies, all present)
    }

OpenClaw gateway log (the buried error):

    2026-04-30T13:53:17.956+08:00 [tools] image failed: Failed to optimize image
    raw_params={"image":"/Users/<user>/.openclaw/media/inbound/<id>.jpg"}
    "Optional dependency sharp is required for image attachment processing"

Impact and severity

• Affected users: every macOS user who installs/upgrades OpenClaw via npm install -g. Easily reproducible under flaky network or any transient prebuild-install issue.
• Severity: HIGH — image processing capability is completely broken. The image/vision tool is a core feature for screenshot understanding, document analysis, and multimodal workflows.
• Discoverability: LOW — the user-facing error ("Failed to optimize image") is generic and gives no hint at the actual cause. Diagnosis takes hours of digging through extension source code, gateway logs, and node_modules state.
• Frequency: every npm-global install that suffers a sharp postinstall hiccup falls into this trap. Without --foreground-scripts, the failure is invisible.
• Real cost example: spent ~2 hours bisecting through "rebuild sharp" → "false success" → "still missing" → "what?" loops before discovering --foreground-scripts reveals the issue.

Additional information

Last known good version: prior to 2026.4.26 (image processing was working before the upgrade — exact previous version not recorded by the user, but workflow had been reliable for weeks). First known bad version: 2026.4.26 (verified at the time of report). Workaround: see the install command in "Additional context / steps already tried" — cd <openclaw-install-dir> && sudo npm install sharp --no-save --foreground-scripts. Confirmed working end-to-end.

Note for triage: a related CLI symptom worth flagging — npm rebuild sharp --prefix <openclaw-install-dir> reports "rebuilt dependencies successfully" while the target directory does not exist (silent no-op). This makes user-side diagnosis significantly harder than it should be, and is part of why a doctor-level probe (suggested fix #1) would be high-value.