VS Code公式の接続方式では、接続先のMacにVS Code Serverを導入して開発処理を実行します。公式のRemote - SSH説明に基づくと、切り分けは「通常SSH」「認証」「ポート転送」「VS Code Server」の4層に分けるのが安全です。VS Code Remote SSHがリモートMacに接続できないときは、まずシステムのターミナルでSSHを検証し、その後に詳細ログを確認してください。サーバーコンポーネントが再起動後も壊れるなら、キャッシュ削除を繰り返さず、ノードの基準環境を直すか交換します。
WindowsやLinuxを主力端末にして、macOS専用ツールチェーンを使う開発者向けの記事です。共有Macを管理するDevOps担当者や、レンタルしたMacの復旧性を受け入れ試験したいプラットフォーム責任者にも適しています。
SECTION 01 最初の診断は時間順に記録する
0〜5分：通常SSHとmacOS側の状態を分ける
まず、アカウント名、ホスト名、ポート、鍵ファイルをすべてプレースホルダーに置き換えて記録します。
ssh -vvv -i ~/.ssh/<KEY_FILE> <USER>@<HOST>
ここで接続できても、VS Codeが同じ条件で動いているとは限りません。AppleのRemote Login設定ガイドに従い、Mac側でRemote Loginが有効か、対象ユーザーが許可されているかを管理経路から確認します。ネットワークに到達できることは、SSHログインが成功することを意味しません。
5〜10分：VS Codeが実際に使う設定を照合する
VS CodeのRemote - SSHログで、次の項目をターミナルの成功条件と比較します。
- 実際に呼び出されたSSHクライアント
- 使用された設定ファイル
- ユーザー名、ホスト名、ポート
IdentityFileと鍵の読み込み結果- パスフレーズ、ホスト鍵確認、対話入力の待機
ターミナルでは入れるのにエディターだけが止まる場合、設定の不一致が第一候補です。ホスト鍵検証を無効にしたり、秘密鍵を共有フォルダーへコピーしたりして回避するのは避けてください。
SECTION 02 VS Code Remote SSHがリモートMacに接続できない原因を分岐する
| 観測された現象 | まず見る証拠 | 低リスクの対応 | 次の合格条件 |
|---|---|---|---|
| 通常SSHも失敗する | ssh -vvvとMac側のRemote Login状態 |
アカウント、鍵、許可ユーザーを修正 | 通常SSHが再現可能に成功 |
| 認証後に転送で拒否される | administratively prohibited、channel作成失敗 |
SSH転送ポリシーとポート競合を確認 | 通常SSHとRemote - SSHが両方成功 |
| Installing VS Code Serverで停止する | Remote - SSH出力、ホームディレクトリ、通信結果 | ダウンロード経路とシェル出力を点検 | Server導入と起動が完了 |
| Server failed to startになる | 起動ログ、空き容量、プロセス状態 | 原因を特定してから再導入 | ワークスペースとターミナルが利用可能 |
| 接続後すぐ切れる | SSHログ、拡張ホスト、資源状況 | 原因をリンク、拡張、資源に分離 | 再接続後も編集とビルドが継続 |
認証後にポート転送が拒否される場合
ログにadministratively prohibitedや転送チャンネルの作成失敗があるなら、単なる鍵認証エラーではありません。Remote - SSHのTCP転送に関する公式手順と、OpenSSHのAllowTcpForwardingおよびAllowStreamLocalForwardingの定義を確認します。
sshd_configを変更すると、他ユーザーの接続や既存のCI経路まで影響する可能性があります。変更前にバックアップ用の管理経路を確保し、反映後は通常SSH、Remote - SSH、既存の自動化接続を同時に確認してください。ローカル側のポート競合も、転送拒否と似た見え方をするため、ログの文言を分けて記録します。
SECTION 03 VS Code Serverと遠隔Macの資源を調べる
Installingで停止する場合
遠隔Macから必要なファイルを取得できない場合、サーバー用ファイルが不完全な場合、ログインシェルの初期化スクリプトが余計な文字列を出す場合、プロセスが起動できない場合を分けます。
次の順番で確認します。
- Remote - SSHの出力から、停止した処理と対象ホストを保存します。
- 通常SSHでログインし、ホームディレクトリの空き容量とサーバー用ディレクトリを確認します。
.zshrcなどの初期化スクリプトが、非対話シェルでもバナーやコマンド出力を返していないか調べます。- Mac側でサーバープロセスの起動エラーと権限を確認します。
- 原因が通信やシェル出力ではないと確定した場合だけ、公式のサーバー削除手順で再導入します。
サーバーディレクトリの削除は、そのアカウントで動いている遠隔セッションを終了させる可能性があります。共有ノードでは、作業中のユーザーと自動化ジョブを確認してから実行してください。
接続後に切断や拡張機能の不調が起きる場合
切断を一括して遅延の問題にしないことが重要です。SSHセッション自体が切れたのか、Remote Extension Hostだけが停止したのか、MacのCPU・メモリ・ディスク圧迫でプロセスが終了したのかを分けます。
複数接続で認証が不安定なら、接続多重化や動的に割り当てられるノードの経路を確認します。VS Code公式の動的ノード接続に関する説明でも、接続ごとに別マシンへ割り当てられる構成には固有の制約があります。
ControlMaster、保活設定、プロキシ環境変数は、原因を確認した後に適用する設定です。適当に値を追加すると、切断の原因を隠したり、別の接続経路だけを壊したりします。
SECTION 04 修復後の再起動テストで判断する
修復を「接続できた」で終わらせず、同じリポジトリで次の5段階を実行します。
- 通常SSHでログインし、対象ユーザーと作業ディレクトリを確認します。
- Remote - SSHでワークスペースを開き、VS Code Serverが再起動なしで起動することを確認します。
- Remote TerminalからGit操作を行い、認証情報とシェル環境が期待どおりか確認します。
- 実際のプロジェクトをビルドし、拡張ホストと必要なネイティブ依存関係を検証します。
- クライアント側を切断し、さらにMacを再起動した後、Remote Login、通常SSH、VS Code Server、ビルドの順に再確認します。
この結果、基礎SSHは安定しているのにサーバーだけが繰り返し壊れる、ディスク不足が解消できない、またはアカウント環境を再現できない場合は、同じキャッシュを消し続ける段階ではありません。管理コンソールや別の復旧経路があるなら基準環境から再構築し、それでも復旧しなければ別の遠隔Macノードへ切り替えます。
SECTION 05 FAQ：ログの読み方と復旧判断
上の確認を行った後も、症状が同じ層にあるとは限りません。FAQでは、ターミナル接続、Server起動、インストール停止、再起動後の復旧を別々の判断材料として扱っています。
SECTION 06 現在のノードを直すか、Mac環境を替えるか
手元のWindowsやLinuxから既存のMacへ接続する構成は、初期費用を抑えられる一方、SSH設定、転送ポリシー、サーバー用ファイル、再起動後のサービス状態を自分で維持しなければなりません。管理経路が1つしかない、ノード交換の基準がない、再起動後に同じ環境を戻せないという状態では、開発者の作業時間が障害調査に流れます。
まずは現在の環境で、同じリポジトリを使った接続・編集・ビルド・再起動復旧を記録してください。そのうえで、完全な管理権限と予備のコンソール経路を持つ遠隔Macを選びたい場合は、VPSNIXのMacレンタル案内と料金ページを確認すると、単なるSSH接続だけでなく、復旧試験まで含めて比較できます。VPSNIXの利用を検討する場合も、契約前にこの検証表を使い、再起動後に開発環境が戻るかを確認してください。
SECTION 07 よくある質問 FAQ
ターミナルからは入れるのに、VS Code Remote SSHだけ失敗するのはなぜですか？
ターミナルとVS Codeが同じSSHクライアント、設定ファイル、ユーザー名、鍵を使っているとは限りません。まずRemote - SSHの詳細ログで実際の呼び出し先を確認し、IdentityFile、ホスト名、ポート、鍵のパスフレーズ待ちをターミナル側の結果と照合してください。
MacでVS Code Server failed to startが出た場合、最初に何を確認しますか？
サーバーをすぐ削除せず、Remote - SSHの出力と対象アカウントのホームディレクトリを確認します。起動スクリプトの余計な出力、空き容量不足、壊れたインストール、プロセス起動権限を分けて調べ、証拠が揃った場合だけサーバーの再導入を選びます。
Installing VS Code Serverの表示が長く続くときはどう対処しますか？
遠隔Macから配布元へ接続できない、ダウンロードが途中で欠けた、シェル初期化スクリプトが通信を妨げた、という可能性を分けます。ログとサーバー用ディレクトリを確認し、再試行を繰り返す前にネットワーク経路、ディスク状態、ログインシェルの出力を点検してください。
遠隔Macを再起動した後、VS Code Remote SSHを復旧できない場合は？
別の管理経路でmacOS Remote Loginが有効か、対象アカウントが許可されているか、同じホスト名と鍵で通常SSHが戻るかを順に確認します。通常SSHが復旧してもVS Code Serverが起動しないなら、環境の再構築または別ノードへの切り替えを検討します。