openclaw - 💡(How to fix) Fix Plugin runtime deps: support layered stage dirs for preinstalled baseline deps [2 comments, 3 participants]

Summary

Support layered plugin runtime dependency stage dirs, so OpenClaw can resolve preinstalled baseline deps from one location and install new deps into another writable location.

This helps avoid repeated slow, heavy installs while keeping new plugin deps persistent.

Problem

Installing baseline plugin runtime dependencies can be very slow and heavy. On a fresh setup, OpenClaw may need to install large dependency sets before bundled plugins are ready.

This is especially painful in containerized deployments, where users often want images to start quickly and predictably. Baseline deps are known at image build time, so they should be installable once into the image. But users still need a writable persistent location for plugin deps installed later.

Today OPENCLAW_PLUGIN_STAGE_DIR appears to model this as one writable stage dir. That makes it hard to support both:

• fast startup from preinstalled baseline deps
• persistent installs for newly added plugin deps

Proposed Solution

Allow OPENCLAW_PLUGIN_STAGE_DIR to contain multiple paths:

OPENCLAW_PLUGIN_STAGE_DIR=<preinstalled-runtime-deps-dir>:<writable-runtime-deps-dir>

Example:

OPENCLAW_PLUGIN_STAGE_DIR=/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps

Behavior:

• resolve deps by checking paths left to right
• allow earlier paths to be read-only image paths
• install missing deps only into the final writable path
• keep newly installed plugin deps persistent in the user-selected writable path

Alternatives

Add a separate read-only stage dir env var, for example:

OPENCLAW_PLUGIN_STAGE_READONLY_DIR=/opt/openclaw/plugin-runtime-deps OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps

OpenClaw would resolve deps from both paths, but install new deps only into OPENCLAW_PLUGIN_STAGE_DIR.

This is more explicit, but it adds another config knob. Reusing OPENCLAW_PLUGIN_STAGE_DIR as a path list keeps the behavior compact and matches common PATH-style config.

Impact

• faster startup when baseline deps are preinstalled
• no need to reinstall heavy baseline deps at runtime
• newly added plugin deps still persist
• useful for Docker and other image-based deployments

Evidence/examples

Container example:

OPENCLAW_PLUGIN_STAGE_DIR=/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps

/opt/openclaw/plugin-runtime-deps is preinstalled in the image. /var/lib/openclaw/plugin-runtime-deps is backed by a persistent volume.

Code word: lobster-biscuit