目次
まずログで処理が止まった段階を確認し、二種類の失敗を混同しないでください
OpenClash の APK 更新では、インストールパッケージのダウンロード、更新前テスト、実際のインストールの順に処理が進みます。ログに「ダウンロード成功」と表示されても、/tmp/openclash.apk がルーターへ書き込まれたことを示すだけで、その後の二段階も成功するとは限りません。
OpenClash の公式 issue #5256 には、2026 年 7 月 28 日以降、二種類の現象が記録されています。一つは「更新前テスト」の段階で unrecognized option 'allow-downgrade' により停止するもの、もう一つは「更新前テスト合格」と明示された後に「ソフトウェアパッケージのインストール失敗」となるものです。
2026 年 8 月 6 日時点でも、この issue は Open のままであり、プロジェクトからすべてのデバイスに当てはまる統一的な原因は示されていません。
ログに基づいて次の手順を決める
| 末尾の重要なログ一式 | 現時点で確認できること | 次の手順 |
|---|---|---|
| 更新前テストに失敗し、unrecognized option 'allow-downgrade' が表示される | 現在の apk-tools がこの引数を受け付けず、実際のインストールにはまだ進んでいない | APK の入手元を確認し、公式 Release に記載された、この引数を含まない形式を使用する |
| 更新前テストに失敗するものの、引数のエラーは表示されない | シミュレーションしたトランザクションに別のエラーがある | apk の出力をすべて保存し、先にシステムパッケージの状態を確認する |
| 更新前テストに合格した後、パッケージのインストールに失敗する | 事前チェックは通過しており、実際のトランザクションで失敗している | 繰り返しクリックするのをやめ、SSH でインストール時の元のエラーを取得する |
| ダウンロードに失敗しているか、/tmp/openclash.apk が存在しない | 完全なインストールパッケージをまだ取得できていない | 先にダウンロード、入手元、ストレージの問題を解決する |
- インストールパッケージをダウンロードするopenclash.apk を /tmp へ書き込む
- 更新前テストapk-tools で引数とトランザクションを模擬検査する
- 実際のインストール検査を通過したパッケージをシステムへ書き込む
- サービスの検証プラグインを再起動し、設定、カーネル、ネットワークを確認する
「更新前テストの失敗」と「テスト通過後のインストール失敗」は異なる段階で発生します。まず末尾の apk エラーを読み、手動インストールが必要か判断してください。
先にバックアップを取り、このルーターが APK を使用していることを確認する
LuCI プラグインを更新する前に、OpenClash の設定管理ページから現在のバックアップをエクスポートしてください。また、OpenClash が停止しても、LAN または有線接続の SSH からルーターへ入れることを確認します。サブスクリプション、オーバーライド、カスタムルールには機密性の高いリンクが含まれる可能性があるため、バックアップは信頼できる場所にのみ保存してください。
OpenClash v0.47.133 の公式 Release では、APK システムに apk と openclash.apk を使用し、従来の OpenWrt ファームウェアには opkg と IPK を使用します。二つのパッケージマネージャーとインストールパッケージ形式には互換性がありません。本稿は、ログに apk が明示されているデバイスだけを対象とします。
command -v apk
apk --version
apk info luci-app-openclash 2>/dev/null
df -h /overlay /tmp
ls -lh /tmp/openclash.apk手動で対処する前に必要な条件
- OpenClash の設定をエクスポート済み、または復元可能なバックアップがあることを確認済み
- LAN または有線接続の SSH からルーターへログインできる
- ログと command -v の結果から、IPK や opkg ではなく APK を使用していることを確認済み
- /tmp/openclash.apk が存在し、ファイルサイズが 0 ではない
- 現在の OpenClash、ファームウェア、apk-tools のバージョンを記録済み
更新前テストに失敗する場合は、先に引数とパッケージの状態を確認する
完全なエラーが unrecognized option 'allow-downgrade' である場合、その意味は限定的です。現在の apk-tools がこのオプションを解析できないことを示すだけで、ストレージ不足やパッケージの破損、OpenWrt のダウングレードが必要であることまでは意味しません。まずローカルのヘルプを表示し、その引数が存在するか確認してください。
apk add --help 2>&1 | grep -- '--allow-downgrade' || echo '当前 apk-tools 不支持 allow-downgrade'テストに失敗しても、この引数エラーが表示されない場合は、公式 APK を使った修復チェックを一度シミュレーションできます。Alpine のドキュメントによると、--simulate ではデータベースへの変更はコミットされません。依存関係、world 制約、その他のエラーが出力された場合は、まず結果を保存してください。fix から --simulate を外して、そのまま実行しないでください。
apk fix --simulateallow-downgrade が未対応であることだけが報告される
次節へ進み、この引数を含まない公式のインストール形式を使用してください。
apk fix --simulate が OK を返す
今回のシミュレーションではシステムパッケージの状態にエラーが見つかっていません。実際のインストール出力の取得へ進みます。
breaks: world、依存関係の競合、パッケージの欠落が表示される
手動インストールを中止し、サードパーティーのパッケージソースと不適合なパッケージを確認してください。force-broken-world は使用しないでください。
容量またはファイルの検査で異常がある
先にファームウェア所定のストレージ管理方法で対処し、設定のバックアップを残してください。/overlay の内容をむやみに削除しないでください。
公式 Release と同じ手動インストールを一度だけ実行する
ログに、allow-downgrade が未対応のため停止したことが明示されている場合、OpenClash v0.47.133 の公式 Release にある APK インストールコマンドには、このオプションが含まれていません。バックアップ、管理経路、/tmp/openclash.apk の入手元を確認した後、まず同じ引数一式でインストールをシミュレーションします。シミュレーションに成功した場合だけ、--simulate を外して実際のインストールを一度実行してください。
二つ目のケースでは、ログに「更新前テスト合格」と明記されている一方、実際のインストール段階で失敗します。この場合も LuCI の更新をクリックし続けないでください。SSH で以下の実コマンドを実行し、依存関係、署名、容量、ロック、I/O などの実際のエラーを apk にすべて出力させます。issue のコメントに特定の原因が書かれているというだけで、システムを事前に変更しないでください。
apk add --simulate --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apkapk add --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apkコマンドが完了し、成功を返す
LuCI を再読み込みしてプラグインのバージョンを確認し、最後のチェックリストに沿ってサービスを検証します。
引き続き unrecognized option と表示される
実行したコマンドと出力をすべて保存し、実際に使われた apk のパスとバージョンを確認します。引数を推測し続けないでください。
UNTRUSTED signature が表示され、ファイルも公式の入手元ではない
直ちに中止し、それ以上強制引数を追加しないでください。公式 Release からインストールパッケージを取得し直します。
依存関係、world、容量、ロック、読み取り専用ファイルシステムのエラーが表示される
元の出力を保存し、そのエラーに応じて対処してください。強制引数を加えた別形式を繰り返し実行しないでください。
インストールが反映されない場合は、直前の正常な状態へ戻す
手動インストールには成功したものの、LuCI が開かない、OpenClash が起動しない、既存のオーバーライドが消えた、といった問題がある場合は、まず OpenClash を停止し、プラグインを経由しないローカル管理経路を復旧させてから、更新前にエクスポートしたバックアップで設定を復元します。プラグインパッケージ、Mihomo カーネル、サブスクリプション、オーバーライドは別々の層に属するため、ファームウェアを一度戻すだけで各層の復元を代用することはできません。
apk コマンド自体が失敗した場合は、/tmp/openclash.apk、ターミナル出力、設定のバックアップを残し、force 引数をさらに加えた形式を繰り返し実行しないでください。旧バージョンへ戻す必要がある場合は、現在のファームウェアのパッケージソースにある、システム適合済みのパッケージ、または動作確認済みの公式パッケージを優先します。検証可能なダウングレード経路がない場合は、現在の管理可能な状態を維持し、機密情報を除去したログを公式 issue へ提出してください。
実際の影響範囲に応じてロールバックする
| 結果 | 残しておくもの | ロールバック手順 |
|---|---|---|
| APK コマンドは失敗したが、以前のページは引き続き利用できる | apk の元の出力と現在の設定 | 再試行を中止し、元のサービス状態を復元する |
| インストールには成功したが、ページまたはサービスに異常がある | 更新前の OpenClash バックアップ | サービスを停止して設定を復元し、カーネルのアーキテクチャを確認する |
| 更新後、家全体のデバイスからアクセスできない | ルーターのローカル管理画面 | OpenClash を一時停止し、まず OpenWrt の直接接続が復旧することを確認する |
| LAN からもルーターを管理できない | あらかじめ用意した有線接続または failsafe の手順 | まず管理経路を復旧し、状態を観測できないまま更新を続けない |
プラグインをインストールした後、サービスと家全体のネットワークを個別に検証する
最後に、「プラグインのインストール成功」と「プロキシサービスの復旧」を分けて検証します。まず LuCI または apk info でインストール済みのバージョンを確認してから OpenClash を起動し、カーネルのアーキテクチャ、設定、サブスクリプション、オーバーライドが引き続き適合しているか確認します。サービスが安定した後に限って、一台の LAN 端末から新たな DNS 問い合わせと Web ページへのリクエストを送信してください。
プラグインのページが正常でも振り分けに異常が残る場合は、カーネル、サブスクリプション、DNS、ルーティングルールの確認へ移り、apk のインストールを繰り返さないでください。反対に、ネットワークを利用できても LuCI のバージョンが変わっていない場合は、パッケージのインストールログへ戻り、ページキャッシュだけで更新完了を判断しないでください。
更新完了後のチェックリスト
- apk info または LuCI に表示される OpenClash のバージョンが今回の対象と一致する
- OpenClash のページを開くことができ、設定、オーバーライド、サブスクリプションも表示される
- Mihomo カーネルのアーキテクチャがルーターのプラットフォームと一致し、起動ログに新たなエラーがない
- 一台の LAN 端末で新しいドメインを名前解決し、通常の Web ページを開ける
- 接続記録で、テストリクエストが想定したルールとポリシーに一致している
- OpenClash を停止しても、ルーターに明確な直接接続経路と管理用のロールバック経路が残る