VS Code Remote SSHでリモートMacに接続できない対処法

VS Code公式では、SSH接続先に最低1GBのメモリ、推奨環境として2GB以上のメモリと2コアCPUを案内しています。つまり、ターミナルでSSHが通っても、VS Code Serverの展開や遠隔拡張機能の起動まで成功するとは限りません。今週の対応では、最初に同じホスト別名でコマンドラインSSHを実行し、Remote - SSHの出力ログを保存してください。SSHも失敗するならMacの遠隔ログイン、経路、認証を確認し、SSHは成功するのにVS Codeだけ失敗するなら、VS Code Server、プロキシ、遠隔側の権限へ進みます。公式要件はRemote Development using SSHで確認できます。 (code.visualstudio.com)

本記事は、WindowsやLinuxからmacOSの開発環境へ入る開発者、チームのリモートMacを管理するDevOps・プラットフォーム担当者向けです。VS Code Serverの導入停止、接続中のまま進まない症状、遠隔拡張機能の不具合を、再インストールに頼らず切り分けます。

「通常のターミナルではSSH接続できるが、VS Code Remote SSHは初期化中で止まる」という場合、SSH通信そのものは通っていても、遠隔Mac上のVS Code Serverの導入または起動に失敗している可能性があります。VS Code Remote SSHは接続先にVS Code Serverを導入し、遠隔側でワークスペース用の処理や拡張機能を動かします。 (code.visualstudio.com)

まず、次の3つを別々に記録します。

1. コマンドラインでのSSH接続結果
2. VS Codeの「Remote - SSH」出力
3. 遠隔Mac上でServerが起動したか、ワークスペースを開けたか

この順番を飛ばして拡張機能を削除したり、遠隔側のServerディレクトリを消したりすると、原因を示すログまで失うことがあります。

最初に、VS Codeではなく同じ接続情報を使って確認します。SSH設定の別名を使っている場合は、実際にVS Codeで選択している別名をそのまま指定してください。

ssh -v mac-dev

設定がどのホストへ展開されるかを見るには、次の確認も有効です。

ssh -G mac-dev

出力では、user、hostname、port、identityfileに意図した値が入っているかを確認します。ホスト名が解決できない、接続が時間切れになる、接続拒否になる、初回のホスト鍵確認が止まる、といった症状は、VS Code Serverより前の層で発生しています。

macOS側では「システム設定」→「一般」→「共有」→「リモートログイン」を開きます。リモートログインを有効にし、接続するアカウントが「アクセスを許可するユーザ」に含まれているかを確認します。Appleの案内では、ここでSSHまたはSFTPによる接続を許可し、必要に応じてリモートユーザへのフルディスクアクセスも設定できます。 (support.apple.com)

外部公開されたMacでは、固定のポート番号や特定の転送方式を前提にせず、契約環境の接続案内、ファイアウォール、許可元アドレスを順に確認します。

VS Code Remote SSHが別の設定ファイルを参照していると、ターミナルで成功した接続と、VS Codeが実行している接続が一致しません。IdentityFile、User、HostName、必要なポート指定を、VS Codeで使うホスト別名に対して確認します。

秘密鍵、パスワード、トークン、完全なホストアドレスは、記事、チケット、公開ログへ貼り付けません。ログを共有する場合は、ユーザ名、ホスト名、IPアドレス、鍵の指紋、プロジェクト名を必要な範囲で伏せます。

VS Code公式も、初回接続前に端末からssh user@hostnameを実行し、その後に同じ接続先をRemote - SSHで選ぶ手順を示しています。まずこの一致を作ることが、設定ミスを減らす最短経路です。 (code.visualstudio.com)

コマンドラインSSHは成功するのに、VS Codeが「ホストへ接続中」や「Serverを起動中」の表示で止まる場合は、コマンドパレットから「Remote - SSH: Show Log」を開きます。ログの最後に出ている処理が、ダウンロード、展開、起動、認証、接続のどこで止まったかを示します。

VS Codeの公式説明では、Serverの取得は遠隔Mac側から試され、失敗するとローカル側で取得してSSH経由で転送する動作に切り替わります。また、取得にはupdate.code.visualstudio.comやvscode.download.prss.microsoft.comへのHTTPS接続が関係します。プロキシや出口制限がある環境では、ローカルと遠隔Macのどちらが取得を担当しているかをログで確認してください。 (code.visualstudio.com)

Remote - SSH出力を保存
→ download failed なら取得経路・プロキシ
→ extract failed なら空き容量・権限・転送内容
→ server did not start ならShell・権限・残留プロセス
→ connection closed ならSSHセッションと遠隔側プロセス

いきなり~/.vscode-server相当のディレクトリを削除するのではなく、まずログに対象のServer版や失敗した操作が出ているかを確認します。公式のトラブルシューティングでは「Remote-SSH: Kill VS Code Server on Host」が案内されていますが、これはServerプロセスと導入状態に影響するため、作業中の遠隔セッションが閉じる可能性を説明したうえで実施します。 (code.visualstudio.com)

接続状態が緑になっても、開発作業が完了したとは判断しません。Remote SSHでは、画面側で動く拡張機能と、SSH接続先で動くワークスペース拡張機能が分かれます。拡張機能一覧で「ローカル」と「接続先のMac」のどちらにインストールされているかを確認します。 (code.visualstudio.com)

遠隔ターミナルで次を実行し、通常のSSHログイン時との差を調べます。

printf '%s\n' "$SHELL"
printf '%s\n' "$PATH"
which git
which node
pwd

シェル初期化ファイルが対話的な出力や端末制御文字を返すと、VS Code Serverの起動処理を妨げることがあります。ログイン時に表示されるメッセージ、PATHの追加、プロキシ環境変数、Homebrewや言語ランタイムの場所を確認し、非対話シェルでも必要なコマンドが見える状態にします。

Apple SiliconのMacでは、拡張機能に含まれるネイティブ依存関係がCPUアーキテクチャに対応していない場合があります。接続できないと決めつける前に、拡張機能を一つずつ無効化し、遠隔ターミナルでプロジェクトのビルド、テスト、Git操作を個別に実行します。

遠隔Macを再起動した後に再接続できない場合、まず端末から同じホスト別名でSSHを試します。SSHが失敗するなら、Macが起動済みか、リモートログインが再び有効か、アカウントの許可設定が維持されているかを確認します。Appleの共有設定では、リモートログインの許可対象を全ユーザまたは指定ユーザから選べます。 (support.apple.com)

SSHが成功する場合は、VS Code側の古い接続状態やServerの残留を疑います。ログを保存した後にServer停止操作を行い、再接続します。再起動後だけ失敗するなら、ログインシェルの設定、マウントされる作業ディレクトリ、起動時に変化するプロキシや権限も確認対象です。

復旧方法の選択

• SSHも失敗する場合は、VS Codeの拡張機能を触らず、遠隔ログイン、名前解決、経路、ユーザ許可を修復します。
• SSHは成功し、Serverの取得で止まる場合は、Remote - SSHログ、HTTPS出口、プロキシ、空き容量を確認します。
• Server起動後に拡張機能だけ失敗する場合は、遠隔側インストール、ShellのPATH、Apple Silicon対応状況を確認します。
• 再起動後だけ再現する場合は、起動前後のSSH設定、ユーザ環境、作業ディレクトリを比較します。
• ログが不足している場合は、削除や再インストールを延期し、同じ操作を再実行して証拠を取ります。

この分岐で原因層を特定できない場合、接続成功を「開発環境が使える」と判定しないことが重要です。リポジトリを開き、遠隔ターミナルでプロジェクトコマンドを実行し、必要なデバッグまで終えて初めて復旧とします。

既存のMacを使い続ける場合は、先にリモートMac開発環境の導入手順と接続情報を照合し、チームで同じSSH設定と検証項目を共有します。Apple Silicon向けの依存関係を確認する案件では、利用するMac環境の構成とツール対応状況も事前に整理しておくと、拡張機能の個別障害を切り分けやすくなります。

現在の環境で問題が繰り返す理由が、端末側ではなくMacノードの運用にある場合もあります。たとえば、Macが必要な時間に起動していない、管理者権限がなくSSH設定を変更できない、再起動後の復旧を毎回手作業で行う、といった状態では、VS Codeの再インストールだけでは解決しません。

短期の検証、チームの一時的な開発ノード、WindowsやLinuxからApple Silicon環境へ接続する用途なら、SSHの完全な操作権限を持つMacを期間単位で確保する方が、実機購入や不安定な共有環境より判断しやすい場合があります。JEXCLOUDの日本向けMacレンタル環境を検討する際も、契約前にSSH接続、遠隔ログイン、再起動後の接続、必要な開発ツールの動作を本文の検証項目で確認してください。

一方、長期間にわたる高負荷ビルド、物理USB機器への常時アクセス、組織固有のネットワークへ直接接続する運用では、自社管理のMacや専用設備が適しています。必要なのが一時的な開発環境や再現用のMacであれば、現在の構成で発生している「起動待ち」「権限不足」「復旧手順の属人化」を減らせるかという基準で、レンタルを比較すると判断を誤りにくくなります。