「connect」は成功したのに、モデル一覧は空で、実際のリクエストだけ本機のOmniRouteへ送られている。」
今週は再インストールを始めず、①ヘルスチェック、②遠隔コンテキスト、③アクセス先と令牌、④プロキシ、⑤クライアントの実送信先の順に確認してください。認証なしの管理画面をインターネットへ公開する修復は避け、HTTPSまたは私設ネットワークで入口を保護します。
OmniRoute Remote Modeの診断順序を先に固定する
この手順は、ノートパソコンから遠隔のOmniRouteへ接続し、omniroute connectやモデル一覧取得が失敗する個人開発者向けです。複数のAI開発ツールで1つの遠隔AIゲートウェイを共有するチーム、再起動後も継続利用したいクラウドMac運用者にも適しています。
Remote Modeでは、接続できた事実と、目的のサーバーへリクエストが届いた事実を分けて確認する必要があります。公式のCLI統合仕様では、現在のコンテキスト、または明示した--remoteと--api-keyが、モデルカタログ取得やランチャーの接続先を決めます。詳しくは公式のCLI統合仕様を参照してください。
最初に、次のチェックリストを作業端末と遠隔端末の両方で残します。
- [ ] 遠隔プロセスが起動しているだけでなく、API応答を返す
- [ ] 待ち受けアドレス、ポート、ファイアウォールの許可範囲が一致している
- [ ] 上流モデル用のキーではなく、OmniRouteのアクセス令牌を使用している
- [ ] 現在のコンテキストが本機ではなく遠隔サーバーを指している
- [ ] リバースプロキシがパス、HTTPS、SSEを壊していない
- [ ] 再起動、令牌失効、長時間処理の3条件を確認している
まず遠隔インスタンスが本当に利用可能か確認する
識別信号
connectが失敗する、接続直後に401や502が返る、再起動後だけモデル一覧が消える場合は、クライアントより先に遠隔インスタンスを疑います。プロセス一覧に表示されても、ポートが閉じている、データディレクトリを読めない、起動直後に終了しているケースがあります。
取得コマンド
遠隔サーバー上で、実際の起動ログとプロセス状態を確認します。使用する起動管理方式に応じてコマンドは置き換えてください。
ps aux | grep -i '[o]mniroute'
ss -ltnp | grep ':<PORT>'
curl -i http://127.0.0.1:<PORT>/
利用中のバージョンでヘルス用のエンドポイントが案内されている場合は、そのパスを使ってください。パスや既定ポートはリリースごとに変わる可能性があるため、公式Wikiの現行コマンド説明とomniroute --helpを照合します。公式資料ではローカルの既定ポート例として20128が示されていますが、固定値として遠隔環境へコピーしないでください。
データ保存先を変更している場合は、DATA_DIRやXDG_CONFIG_HOMEの値も確認します。公式の構成説明では、保存先にデータベースが含まれ、プロバイダーの秘密情報もファイルシステム上で保護すべき対象とされています。保存先と構成の公式説明を基準に、再起動前後で同じディレクトリを参照しているか確認してください。
処理の結論
プロセスが存在しない、待ち受けがない、ローカルループバックからも応答しない場合は、Remote Modeの問題ではなくサービス起動障害です。ログ、保存先、環境変数を直してから再起動します。
修復後の確認
遠隔サーバー上の127.0.0.1から応答が返り、再起動後も同じデータディレクトリと設定が使われることを確認します。本機からの接続確認は、その後に実施します。
OmniRoute Remote Modeで接続がタイムアウトするときの分岐
識別信号
TCP接続自体が成立しない場合は、ホスト名、ポート、ファイアウォール、トンネルの問題です。TCP接続後に応答が遅れて切れる場合は、アプリケーションまたはプロキシの問題であり、同じ「タイムアウト」でも処理が異なります。
取得コマンド
nc -vz <REMOTE_HOST> <PORT>
curl -vk --connect-timeout <短い確認値> https://<REMOTE_HOST>/<PATH>
ここで使う接続確認値は、運用環境の監視基準またはプロキシの公式設定値に合わせ、根拠のない共通値を採用しません。ncが失敗するなら、アプリケーションの再インストールでは直りません。ホスト名の名前解決、セキュリティグループ、OSファイアウォール、VPNやTailnetなどの私設経路を順番に確認します。
遠隔入口は、全ポートを開けるのではなく、必要な経路だけを許可します。管理画面を認証なしで公開せず、HTTPSのリバースプロキシ、VPN、または許可済み端末だけが到達できる私設ネットワークを選びます。Vuncloudのヘルプセンターを参照する場合も、接続方式、公開範囲、認証方法を先に整理して問い合わせると切り分けが速くなります。
処理の結論
ncが失敗するならネットワーク経路、ncは成功してcurlだけ失敗するならアプリケーションまたはプロキシ、HTTP応答後に長時間処理だけ切れるならストリーム維持設定を調べます。
修復後の確認
本機から最小限のAPI確認を行い、遠隔サーバー側のアクセスログに同じ時刻の記録が出ることを確認します。画面が表示されたことだけでは、正しい経路を通った証拠になりません。
アクセス令牌の失敗は、種類と権限を分けて確認する
識別信号
401は令牌の値、送信ヘッダー、失効状態の問題が中心です。403や特定操作だけの失敗は、令牌の権限範囲が不足している可能性があります。上流モデルのAPIキーをOmniRouteの管理APIへ送っても、遠隔接続用の資格情報にはなりません。
取得コマンド
omniroute connect <REMOTE_HOST>
omniroute context
omniroute launch --remote https://<REMOTE_HOST>/<PATH> --api-key '<OMNIROUTE_TOKEN>'
実際のサブコマンド名は、利用中の版でomniroute --helpを確認してください。トークンをシェル履歴へ残したくない場合は、環境変数や安全な秘密情報管理機能を使い、記事やログへ実値を出力しません。
Claude Code向けでは、公式設定にあるANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEYの役割を混同しないことが重要です。ANTHROPIC_AUTH_TOKENが優先され、環境変数は起動時に一度読み込まれるため、値を変更した後はクライアントを再起動します。公式のClaude Code設定に記載された形式から外れて、ベースURLへ不要な/v1を追加しないでください。
処理の結論
まず読み取りだけのモデル一覧取得を行い、次に設定変更、最後にモデル呼び出しを検証します。令牌に管理者権限を無制限で与えるのではなく、必要な操作を満たす最小範囲へ絞ります。公式資料でも、MCPや管理操作に対する範囲付きキーが説明されています。権限範囲の公式説明を確認してください。
修復後の確認
- [ ] 読み取り操作が成功する
- [ ] 許可した設定変更だけ成功する
- [ ] モデル呼び出しが成功する
- [ ] 禁止した操作は拒否される
- [ ] 令牌を失効させると接続できなくなる
最後の失効確認まで行わないと、古い令牌が残ったままの誤判定を見逃します。
Remote Mode接続成功後もモデルが見えない原因を切り分ける
識別信号
接続表示は成功しているのにモデル一覧が空、本機で追加したモデルだけ表示される場合は、現在のコンテキストと生成済み設定ファイルを確認します。特に、connectは遠隔を指していても、クライアントが以前作成したローカル設定を読み続けることがあります。
取得コマンド
omniroute context
env | grep -E 'OMNIROUTE|ANTHROPIC|CLAUDE_CONFIG_DIR'
omniroute setup-claude --remote https://<REMOTE_HOST>/<PATH> --api-key '<OMNIROUTE_TOKEN>' --dry-run
公式のCLI統合では、遠隔カタログを取得し、その内容を本機側のクライアント設定へ書き出す設計です。CLI設定コマンドの一覧と、生成された設定ファイルのURL、モデル名、プロファイルを照合します。
Claude Codeのモデル選択欄に表示されないモデルがあっても、遠隔側の/v1/models相当のカタログに存在するとは限りません。公式説明では、モデル発見機能に対応するクライアント版と環境変数が必要で、表示対象にも条件があります。表示名ではなく、遠隔側のモデルカタログと呼び出しログを証拠にします。
処理の結論
遠隔カタログが取得できるのにクライアントが本機へ送っているなら、設定ファイルまたは環境変数の問題です。遠隔カタログ自体が空なら、サーバー側のモデル設定、令牌権限、保存データを確認します。
修復後の確認
モデル一覧取得時刻とモデル呼び出し時刻を記録し、遠隔サーバー側のアクセスログに一致するリクエストが出ることを確認します。omniroute launchは現在のコンテキストから接続先と令牌を注入できますが、起動済みのクライアントへ後から環境変数を反映する機能ではありません。
リバースプロキシと長いストリームを最後に確認する
識別信号
短いモデル一覧は成功するのに、生成処理だけ途中で切れる、プロキシ経由時だけ接続が閉じる場合は、URLのパス書き換え、HTTPS終端、SSEの転送、アイドル接続処理を調べます。特に、プロキシが/v1/messagesなどのパスを別の場所へ書き換えると、認証が正しくても失敗します。
取得コマンド
curl -N -v \
-H "Authorization: Bearer <OMNIROUTE_TOKEN>" \
-H "Content-Type: application/json" \
https://<REMOTE_HOST>/<PATH>
実際のリクエストパスとJSON形式は、利用中の版のAPIリファレンスに合わせます。公式APIリファレンスにないパスを推測して固定しないでください。
プロキシ設定では、HTTPSの証明書、ホスト名転送、SSEのバッファリング、読み取りタイムアウト、アイドル接続の扱いを確認します。タイムアウト値はプロキシ製品の公式資料か、対象環境の実測値から設定し、出所不明の「一般的な数値」をそのまま採用しません。
処理の結論
直接接続で長い処理が完了し、プロキシ経由だけ切断するなら、OmniRoute本体ではなく入口設定の問題です。プロキシを無効化して常用するのではなく、HTTPSとストリーム転送を維持できる設定へ修正します。
修復後の確認
短い応答、長い応答、途中で端末を切断した後の再接続をそれぞれ確認します。クライアント側のエラーだけでなく、遠隔サーバーとプロキシの両方に、開始・継続・終了の記録が残る状態が合格条件です。
修復後は遠隔運用の受け入れ試験を行う
単発の接続成功だけで運用開始にしないため、次の条件分岐で判定します。
- 遠隔サーバーのローカル確認が失敗する場合は、クライアント設定を触らず、起動ログ・保存先・待ち受けを修正します。
- TCP接続が失敗する場合は、公開範囲を広げず、HTTPS、VPN、または私設経路の許可設定を修正します。
- 401が出る場合は、上流キーとOmniRouteのアクセス令牌を分離し、令牌の有効状態を確認します。
- 403が出る場合は、管理者キーを配るのではなく、必要な操作範囲だけを付与します。
- モデル一覧だけが失敗する場合は、遠隔カタログ、現在のコンテキスト、生成済み設定ファイルを照合します。
- 長い処理だけ失敗する場合は、SSEとプロキシの転送状態を調べ、直接接続を恒久的な代替策にしません。
- 再起動後に復旧しない場合は、保存先、起動順序、令牌の読み込み、クライアントの再起動を確認します。
チーム運用では、管理者と読み取り専用メンバーで同じ手順を実施し、サーバー再起動、令牌失効、本機のネットワーク切断、長時間処理の中断を記録します。最終記録には「故障層」「修復操作」「証拠の保存場所」「再発時の担当者と接続手段」を残します。
本機を常時起動できず、家庭内ネットワークや不安定なプロキシに依存している場合、OmniRouteの設定より先に実行環境を見直す必要があります。クラウドMacを継続運用するなら、Mac miniレンタルの提供条件で接続方式と再起動後の引き渡し条件を確認し、必要なら問い合わせ窓口へ、利用地域、接続方式、必要なクライアント、長時間処理の有無を伝えると適合性を判断しやすくなります。
自宅のMacを使う方法は初期費用を抑えやすい一方、スリープ、回線断、再起動後の手動復旧、チームでの権限分離が負担になります。短期検証や一時的な遠隔AIゲートウェイなら、継続稼働するMac環境をレンタルした方が、接続経路と復旧手順を揃えやすい場合があります。ただし、物理USB機器が必要な処理や、長期間にわたり高負荷を固定運用する用途では、自前環境との費用と管理範囲を比較してから選ぶべきです。
安定したMac環境をVuncloudで始めませんか
Vuncloudなら、遠隔から実機のMac環境へ接続し、開発や検証作業をスムーズに進められます。
用途や利用期間に合わせてMac miniを選べるため、必要な環境を無駄なく整えられます。