Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix [Bug]: raw `openclaw` CLI fails under Volta-managed Node with 'volta-shim should not be called directly' [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#68672•Fetched 2026-04-19 15:08:47
View on GitHub
Comments
0
Participants
1
Timeline
0
Reactions
0
Author
sanchezm86sanchezm86
Participants
sanchezm86sanchezm86

Running openclaw directly from a non-interactive shell (e.g. systemd unit, cron, agent exec) fails when Node.js is managed by Volta. The wrapper path /opt/openclaw/bin/openclaw-env openclaw ... works correctly.

Error Message

Volta error: 'volta-shim' should not be called directly.

Root Cause

Root Cause (suspected)

Fix Action

Workaround

Wrapping with /opt/openclaw/bin/openclaw-env openclaw ... loads the correct environment first and succeeds:

  • /opt/openclaw/bin/openclaw-env openclaw status ✅
  • /opt/openclaw/bin/openclaw-env openclaw memory status ✅
  • /opt/openclaw/bin/openclaw-env openclaw doctor --non-interactive ✅

Code Example

Volta error: 'volta-shim' should not be called directly.

---

Command not executable (permission denied)
RAW_BUFFERClick to expand / collapse

Summary

Running openclaw directly from a non-interactive shell (e.g. systemd unit, cron, agent exec) fails when Node.js is managed by Volta. The wrapper path /opt/openclaw/bin/openclaw-env openclaw ... works correctly.

Environment

  • Linux (custom server deployment)
  • Node.js managed by Volta (not system Node, not nvm)
  • Custom systemd gateway unit using SOPS-encrypted secrets
  • Systemd unit runs: /usr/bin/bash -lc 'cd /opt/openclaw && exec ./start-gateway.sh gateway'
  • start-gateway.sh decrypts .env.sops → secrets/runtime.env, loads env, then runs openclaw gateway
  • OpenClaw version: current (2026.4.x)

Steps to Reproduce

  1. Install Node.js via Volta on Linux
  2. Run openclaw status or openclaw doctor --non-interactive from a non-interactive shell context (systemd unit, raw exec, agent tool call)
  3. Observe failure

Expected Behavior

openclaw ... works in any exec context regardless of how Node.js is installed.

Actual Behavior

Fails with:

Volta error: 'volta-shim' should not be called directly.

or:

Command not executable (permission denied)

Workaround

Wrapping with /opt/openclaw/bin/openclaw-env openclaw ... loads the correct environment first and succeeds:

  • /opt/openclaw/bin/openclaw-env openclaw status ✅
  • /opt/openclaw/bin/openclaw-env openclaw memory status ✅
  • /opt/openclaw/bin/openclaw-env openclaw doctor --non-interactive ✅

Root Cause (suspected)

OpenClaw's launcher invokes node in a way that hits Volta's shim binary. Volta shims require a Volta-managed shell context to resolve the correct Node version. When called from a non-interactive systemd unit or raw exec, that context is absent and the shim errors out.

Important: Do Not Auto-Fix

openclaw doctor --fix must not auto-rewrite the gateway service unit in this deployment shape. The custom start-gateway.sh handles SOPS secret decryption before gateway start — a blind service unit rewrite would break the secrets-loading flow.

Suggested Fix Directions

  1. Patch the raw launcher to detect and handle Volta-shim environments (resolve actual Node binary path before exec)
  2. Formally support and document wrapper-based execution for env-sensitive installs as a first-class deployment pattern

Related Issues

  • #52184 — Volta shim path vs version-pinned path for macOS LaunchAgent (related but macOS/feature-request scoped)

extent analysis

TL;DR

Wrap openclaw commands with /opt/openclaw/bin/openclaw-env to ensure the correct environment is loaded when running from non-interactive shells.

Guidance

  • Verify that the issue is indeed related to Volta's shim binary by checking the error message for 'volta-shim' should not be called directly or Command not executable (permission denied).
  • Use the provided workaround by prefixing openclaw commands with /opt/openclaw/bin/openclaw-env to load the correct environment.
  • Consider patching the raw launcher to detect and handle Volta-shim environments, but be cautious of the custom start-gateway.sh script that handles SOPS secret decryption.
  • Review the start-gateway.sh script to ensure it correctly loads the environment and runs openclaw with the wrapper.

Example

# Correct usage
/opt/openclaw/bin/openclaw-env openclaw status

# Incorrect usage
openclaw status

Notes

This solution assumes that the issue is specific to the interaction between OpenClaw and Volta's shim binary. If the issue persists after applying the workaround, further investigation into the custom start-gateway.sh script and the systemd unit configuration may be necessary.

Recommendation

Apply the workaround by wrapping openclaw commands with /opt/openclaw/bin/openclaw-env to ensure the correct environment is loaded. This approach is a safe and effective solution that does not require modifying the underlying launcher or systemd unit configuration.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#memory leak#API versioning#request timeout

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix [Bug]: raw `openclaw` CLI fails under Volta-managed Node with 'volta-shim should not be called directly' [1 participants]