$cd ../troubleshooting/
High🤖 API / Providers
プラグインContextEngineクラッシュ — アップグレード後ファクトリ検証失敗
// OpenClaw v2026.4.14でContextEngine v2が導入され、プラグインファクトリ検証が厳格化。旧context API向けにビルドされたサードパーティプラグイン — コミュニティで人気のlossless-claw、カスタムメモリshim、実験的providerラッパー — はgateway起動時または初回エージェント実行時にクラッシュし、ContextEngine、factory validation、無効plugin manifestを示すエラーが出ます。コアOpenClawは起動できても、プラグインがcontext factoryを登録する瞬間に失敗します。本非公式ガイドではログで問題プラグインを特定、無効化・更新、メンテナー互換リリースまでOpenClaw固定、拡張を1つずつ再有効化する前のクリーンブート確認を説明します。
diagnose.sh
🔍 これがあなたの問題ですか？
?OpenClaw v2026.4.14以降へのアップグレード直後にクラッシュ開始
?ログにContextEngine、factory validation、plugin init failed
?サードパーティプラグイン実行（例lossless-claw、カスタムメモリ拡張）
?Gatewayが 'listening on' 前に終了またはControl UIが接続不能
?全プラグイン無効化（またはpluginエントリ削除）でgateway起動
boot.log
✅ 修正1 — ログでクラッシュプラグインを特定
スタックトレース直前のプラグイン名を特定
# 起動クラッシュを捕捉 openclaw gateway start 2>&1 | tee /tmp/openclaw-boot.log # plugin + ContextEngineエラーを検索 grep -iE 'contextengine|factory|plugin' /tmp/openclaw-boot.log # 設定済みプラグイン一覧 grep -A20 '"plugins"' ~/.openclaw/openclaw.json
debugログでfactory登録順序を表示
# 次回起動用debug有効 # openclaw.json: "log_level": "debug" openclaw logs --follow | grep -iE 'plugin|context' # グローバル vs ローカルプラグインパス ls -la ~/.openclaw/plugins/ npm list -g | grep -i claw
openclaw.json
✅ 修正2 — 非互換プラグインを無効化
サードパーティcontext hookなしでクリーン起動
// ~/.openclaw/openclaw.json — プラグイン一時無効
{
"plugins": {
"enabled": false
}
}
// または特定エントリ削除/コメント：
// "lossless-claw": { "enabled": false }二分探索：どのプラグインがContextEngineをクラッシュ
openclaw gateway restart openclaw gateway status # 健全性確認後、1つずつ再有効化 # openclaw.json編集 → 単一plugin enabled: true # 変更毎に再起動
pin_version.sh
✅ 修正3 — プラグイン更新またはOpenClawバージョン固定
永久pinより公式プラグイン更新を優先
# メンテナーがv2サポートを出していれば更新 cd ~/.openclaw/plugins/lossless-claw # 例 git pull && npm install && npm run build # またはopenclaw plugin CLI（バージョン依存） openclaw plugins update lossless-claw
ロールバックは妥当 — changelogでplugin SDK言及後にアップグレード
# プラグインが追いつくまでOpenClaw固定 npm i -g openclaw@2026.4.13 openclaw --version # pinを記録；毎月@latest再試行 # ウォッチ：github.com/openclaw/openclaw/releases openclaw doctor
💡 プロのヒント：プラグインは1つずつ有効化
アップグレード後はplugins: []または全disabledから始め、gateway健全性確認後、1つずつ有効化して再起動。再有効化で最初にクラッシュしたものが非互換パッケージ — スタックトレース当て推量不要。
🛡️ 予防チェックリスト
- • `npm i -g openclaw@latest` 前にリリースノート — 2026.4.xでContextEngine破壊的変更が明記
- • runbookでopenclaw.jsonのプラグインバージョンとOpenClawバージョンを両方pin
- • プラグインリポ（例lossless-claw）のContextEngine v2互換tagをウォッチ
- • 本番Mac Miniアップグレード前に~/.openclawコピーでstaging gateway
- • アップグレード週は `openclaw doctor` とdebugログを有効のまま
❓ FAQ
Q1. ContextEngine v2で何が変わった？
v2026.4.14でプラグインがcontext factory — モデル呼び出し前にprompt、メモリスライス、ツールコンテキストを組み立てる関数 — を登録する方法をリファクタ。検証は非推奨フィールド付きmanifest、initでthrowするasync factory、schemaバージョン不一致を拒否。ContextEngine v1内部フックをmonkey-patchしたプラグインは即失敗。コアチャネル（Discord、Telegram）は無影響 — ~/.openclaw/pluginsとnpmリンクコミュニティ拡張が対象。
Q2. なぜlossless-clawがクラッシュ報告に多い？
lossless-clawはcontext圧縮とtoken accountingに深くフック — ContextEngine v2が書き換えた面そのもの。旧リリースのfactory署名は新バリデータが拒否。プラグインリポでv2互換tag/branchを確認。暫定：設定でlossless-claw無効 — 更新までデフォルトcontext処理でエージェント実行。
Q3. Gatewayが全く起動しない — 必ずプラグイン？
必ずしもそうではないが、プラグインロードはgateway bootstrap早期。plugin initの同期throwはHTTP/WebSocketリスナー绑定を阻止 — total crashに見える。CLIがサポートすれば `openclaw gateway start --no-plugins`、またはopenclaw.jsonでplugins.enabled: false。その後起動すればプラグイン隔離確定。
Q4. 最後に動いたOpenClawバージョンにpinするには？
npm i -g openclaw@2026.4.13（または最後に良好だった版）。package-lockやdotfileにpin記録。プラグインが追いつくまでcronで@latest避ける。メンテナー修正後はOpenClaw先、各プラグインを1つずつ bump してテスト。公式リリース：github.com/openclaw/openclaw/releases。
Q5. プラグインをローカルpatchできる？
上級者は修正コードを~/.openclaw/plugins/nameにsymlinkまたはforkをnpm link。バージョンのOpenClaw plugin SDK文書の新factoryインターフェースに合わせる必要。破壊的リリース後数日でコミュニティfork — 上流修正があれば上流優先。pluginパス編集前にopenclaw.jsonバックアップ。
Q6. プラグイン無効化でメモリやセッションは失われる？
contextプラグイン無効化は圧縮/enrichment動作を止めるだけ — ~/.openclawメモリストアやチャネルセッションは削除しない。プラグインなしではpromptが大きくなったりtoken使用量が変わる可能性。プラグイン更新後に再有効化で以前のcontext動作を復元。