$cd ../troubleshooting/
High📦 Installation
Node.jsバージョンが古い — 構文エラーとtsxクラッシュ
// OpenClawの現行リリースはNode.js 22.14以降（24 LTS可）を対象とします。Ubuntuデフォルトのnode 18/20、古いnvmエイリアス、他ツール同梱Nodeでは即失敗：optional import構文のSyntaxError、誤ABI向けネイティブアドオン、gateway起動前のtsxクラッシュ。症状は「Nodeを上げろ」とは言わないランダムなスタックトレースに見えます。本非公式ガイドではgatewayと同じコンテキスト（SSH vs systemd）で `node -v` を確認し、nvm/fnm/NodeSourceで22.14+を入れ、ネイティブモジュールを再ビルドしてMac MiniとLinux VPS両方でopenclaw doctorとgateway installを成功させる方法を説明します。
diagnose.sh
🔍 これがあなたの問題ですか？
?`node -v` がv18.x、v20.18未満、またはv22.14未満
?起動時にSyntaxErrorまたはtsxモジュールエラーでgatewayクラッシュ
?ネイティブモジュールエラーにNODE_MODULE_VERSION不一致
?ノートPCではopenclaw動作、VPSの古いディストロNodeで失敗
?`openclaw doctor` が非サポートNodeランタイムを警告
check_node.sh
✅ 修正1 — あらゆる場所でNodeバージョンを確認
シェルNodeとデーモンNodeを比較
# 対話シェル node -v which node npm -v # gatewayが見る環境 systemctl --user show-environment | grep -i path grep -E 'ExecStart|Environment' ~/.config/systemd/user/openclaw-gateway.service
終了コード1はNodeが古い
# 下限クイックチェック（bash）
NODE_MAJOR=$(node -p "process.versions.node.split('.')[0]")
NODE_MINOR=$(node -p "process.versions.node.split('.')[1]")
# 必要：major >= 22 かつ (major > 22 または minor >= 14)
node -e "const [M,m]=process.versions.node.split('.').map(Number); if(M<22||(M===22&&m<14)) process.exit(1)"install_node22.sh
✅ 修正2 — Node 22.14+をインストール（nvm / fnm / NodeSource）
nvm経由でNode 22 LTSラインをインストール
# nvm（Mac / Linuxで一般的） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash source ~/.nvm/nvm.sh nvm install 22 nvm alias default 22 nvm use 22 node -v
1つのインストール方法を選択 — サーバーはfnmまたはNodeSource
# fnm代替（高速、VPS向き） curl -fsSL https://fnm.vercel.app/install | bash fnm install 22 fnm default 22 node -v # Ubuntu NodeSource（システム全体、nvmなし） # curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - # sudo apt-get install -y nodejs
rebuild_openclaw.sh
✅ 修正3 — ネイティブモジュール再ビルドとOpenClaw再インストール
ネイティブアドオンは新Nodeバージョンと一致必須
# 新Node ABI向けグローバルopenclawを再ビルド npm rebuild -g openclaw # またはクリーン再インストール npm uninstall -g openclaw npm i -g openclaw@latest openclaw --version openclaw doctor
サービスを/usr/bin/nodeではなくNode 22バイナリに
# systemdを正しいnodeパスに更新 NODE_PATH=$(which node) # openclaw-gateway.serviceのExecStartを$NODE_PATHに systemctl --user daemon-reload systemctl --user restart openclaw-gateway openclaw gateway status
💡 プロのヒント：gatewayのNodeをシェルと一致させる
対話SSHはnvmを読み込むがsystemdはしない。サービスユニットのEnvironmentにnvm/fnm initを入れるか、ExecStartでNode 22の絶対パスを使う。アップグレード後、サービスコンテキストの `which node` はターミナルの `node -v` と一致必須。
🛡️ 予防チェックリスト
- • プロジェクトルートとgatewayホストで.nvmrcまたは.node-versionにNode 22.14+を固定
- • CI、Dockerベースイメージ、systemdで `node -v` — ノートPCだけで確認しない
- • OSアップグレード（apt upgrade nodejs）後にバージョン再確認 — ディストロパッケージは遅れがち
- • 同一ホストでHomebrew node、nvm node、/usr/bin/nodeを混在させない
- • runbookのopenclawインストール手順横に必要Nodeバージョンを記載
❓ FAQ
Q1. OpenClawの最低Nodeバージョンは？
コミュニティテストと最近のリリースノートはNode 22.14+を実質的下限と示します。Node 24 LTS可。Node 18と初期Node 20はOpenClaw内部の現代ESM/tsxパスで失敗しがち。`openclaw doctor` — 新バージョンは閾値未満で明示警告。迷ったら可能な最古ではなく最新Node 22パッチをインストール。
Q2. SSHでnode -vが22なのにgatewayがまだクラッシュ？
systemd、launchd、cronはnvm/fnmプロファイルなしの最小環境。gatewayサービスが/usr/bin/node（v18）を呼び、シェルが~/.nvm/versions/node/v22.x/bin/nodeを使う可能性。サービスファイルExecStart=を確認。Node 22フルパスを埋め込むかExecStartPreでnvmをsource。Dockerベースnode:18でローカルnode:22開発も同様。
Q3. Nodeバージョン問題を示す具体的エラーは？
よくあるパターン：`SyntaxError: Unexpected token 'with'`、組み込みパスの `Cannot find module`、ネイティブモジュール `ERR_DLOPEN_FAILED`、tsx/esbuildバージョン不一致、非常に古いランタイムの `ReferenceError: structuredClone is not defined`。dist/gateway.js行1のスタックはランタイムがバンドルをパースできない意味 — アプリロジック前にNodeアップグレード。
Q4. nvm、fnm、システムパッケージどれを使う？
nvmとfnmはホームラボとMac Miniで人気 — 複数バージョンが容易。ヘッドレスUbuntu VPSはNodeSource setup_22.xまたはグローバルデフォルト付きfnmが良好。上にnvmを使わない限りapt nodejs 18は避ける。fnmは速く絶対パスでsystemdと相性良い。1マネージャーを選び、二重openclawバイナリ問題のように3 Nodeインストールを積まない。
Q5. Nodeアップグレード後openclawを再インストール必要？
推奨。グローバルnpmパッケージは旧Node ABI向けネイティブアドオンをリンクしている可能性。新Node下で `npm rebuild -g openclaw` または `npm uninstall -g openclaw && npm i -g openclaw@latest`。その後 `openclaw doctor` とgateway再起動。rebuild省略はnode -vが正しくてもMODULE_VERSION不一致の obscure エラー。
Q6. Raspberry Pi arm64は特殊Nodeビルド必要？
Node.jsダウンロードまたはnvmの公式arm64バイナリ — Piでx64 nvmを想定しない。ネイティブモジュールビルドは遅い；初回インストールに余裕を。Pi 4/5 64bit OS向けNode 22 arm64ビルドあり。ネイティブrebuild失敗時はbuild-essential python3を確認。公式リポ：github.com/openclaw/openclaw。