【完全ガイド】VS CodeでSSH接続できない時の対処法

はじめに

Visual Studio Code（VS Code）のRemote – SSH拡張機能は、ローカルマシンからリモートのサーバーや開発環境にSSHで接続し、あたかもローカルで作業しているかのように開発できる非常に強力なツールです。リモートマシン上でコードの編集、デバッグ、ターミナルの利用などが可能になるため、開発効率を大幅に向上させることができます。

しかし、このRemote – SSH機能は、ローカル環境、リモート環境、ネットワーク、SSHプロトコル、VS Code自体の設定など、多くの要素が複雑に絡み合って動作するため、予期しない理由で接続に失敗することも少なくありません。「昨日まで動いていたのに急に接続できなくなった」「設定したはずなのに何度やっても繋がらない」といった問題に直面し、困った経験がある方もいるのではないでしょうか。

VS CodeでのSSH接続問題の原因は多岐にわたります。単なる設定ミスから、ファイアウォールの問題、認証情報の不一致、リモート環境のセットアップ不良、さらにはVS Code拡張機能やSSHプロトコルの詳細に関わるものまで様々です。そのため、問題を解決するには体系的なアプローチが必要です。

この記事は、VS CodeでSSH接続ができない場合のあらゆる可能性を網羅し、それぞれの原因特定から具体的な対処法までを詳細に解説する完全ガイドです。初心者の方でも理解できるよう、前提となるSSHの仕組みや基本的な確認事項から丁寧に説明します。すでにRemote – SSHを利用されている方も、より高度なトラブルシューティングや、見落としがちな原因と対処法を知るためのリファレンスとして活用できるでしょう。

約5000語にわたる詳細な解説を通じて、あなたのVS Code SSH接続問題を解決するための一助となれば幸いです。さあ、一緒に問題を解決していきましょう。

VS Code Remote – SSHの仕組みを理解する

トラブルシューティングを効果的に行うためには、まずVS CodeのRemote – SSH機能がどのように動作しているかを理解することが重要です。

クライアント側とサーバー側

Remote – SSHでは、あなたが操作しているローカルPCが「クライアント側」、接続先のサーバーや開発環境が「サーバー側」（リモート側）となります。VS Code本体は基本的にクライアント側で動作しますが、リモートでの作業を可能にするために、サーバー側には特別なプログラムがインストールされて実行されます。

SSHプロトコル

SSH（Secure Shell）は、ネットワークを介して安全にリモートコンピュータと通信するためのプロトコルです。Remote – SSH拡張機能は、このSSHプロトコルを使用して、ローカルPCとリモートPCの間に暗号化された通信路を確立します。認証（ユーザー確認）、コマンドの実行、ファイルの送受信などがこの安全な通信路を通じて行われます。

VS Code Remote – SSHの基本的な接続フロー

VS Codeで新しいSSH接続を開始すると、通常以下のプロセスが実行されます。

SSH接続の確立: VS CodeがローカルのSSHクライアントプログラム（OpenSSHなど）を呼び出し、指定されたホスト名/IPアドレス、ポート、ユーザー名、認証情報（パスワードまたは秘密鍵）を使ってリモートサーバーへのSSH接続を試みます。
認証: リモートサーバーは、提供された認証情報が正しいか確認します。成功すれば、SSHセッションが確立されます。
VS Code Serverのチェックとインストール: SSH接続が確立されると、VS Code拡張機能はリモートマシン上で自身のサーバープログラム（VS Code Server）が実行されているか確認します。
- もし存在しないか、またはバージョンが古い場合は、インターネット経由で適切なバージョンのVS Code Serverバイナリをダウンロードし、ユーザーのホームディレクトリ（通常 ~/.vscode-server）などにインストールします。
- ダウンロードにはリモートマシンからのインターネットアクセスが必要です。
VS Code Serverの起動: インストール済みのVS Code Serverを起動します。
接続確立: ローカルのVS Code本体とリモートで起動したVS Code Serverが、確立されたSSH通信路を通じて通信を開始し、VS CodeのUIがリモートのファイルシステムや実行環境に接続された状態になります。

エラーが発生しやすいポイント

上記のフローから分かるように、Remote – SSH接続は複数のステップを経て確立されます。エラーはこれらのどの段階でも発生し得ます。

ステップ1, 2（SSH接続・認証）: 最も基本的な部分です。SSHクライアントとサーバー間の通信、ネットワーク設定、ファイアウォール、認証情報（ユーザー名、パスワード、鍵）、SSHサーバーの設定などに問題があるとここで失敗します。
ステップ3, 4（VS Code Server）: SSH接続自体は成功しても、リモートマシンでのVS Code Serverのダウンロード、インストール、起動に問題があるとここで失敗します。リモートマシンのインターネット接続、ディスク容量、パーミッション、環境変数、既存のプロセスなどが関係します。
ステップ5（接続確立）: VS Code Serverは起動したが、ローカルのVS Code本体と通信できない場合に発生します。ファイアウォールや、VS Code Server内部の初期化エラーなどが考えられます。

これらのステップを念頭に置くことで、エラーメッセージや状況から、どの段階で問題が発生しているかを推測し、適切な対処法に進むことができます。

基本的な確認事項（まずここから！）

VS CodeでSSH接続できない場合、複雑な設定変更に進む前に、まずは基本的な事項を確認することが重要です。意外と簡単な見落としが原因であることが多いです。

1. VS Codeおよび拡張機能の最新化

VS Code本体のアップデート: 使用しているVS Codeのバージョンが古い場合、Remote – SSH拡張機能の最新版と互換性がない可能性があります。VS Codeの「ヘルプ」->「アップデートの確認」から最新版にアップデートしてください。
Remote – SSH拡張機能のアップデート: 拡張機能自体にバグがある場合や、最新のSSHサーバーとの互換性の問題が修正されている場合があります。VS Codeのアクティビティバーから拡張機能ビューを開き、「Remote – SSH」を検索して最新版にアップデートしてください。
依存するOpenSSHなどの最新化（ローカル/リモート両方）: 古いOpenSSHクライアントやサーバーを使っている場合、新しい暗号方式に対応していなかったり、既知の脆弱性があったりして接続が拒否されることがあります。OSのパッケージマネージャー（apt, yum, brewなど）を使って、OpenSSH関連のパッケージを最新にすることをおすすめします。

2. SSHクライアントのインストールと確認（ローカル）

VS Code Remote – SSHは、内部的にローカルPCにインストールされているSSHクライアントプログラム（通常はOpenSSH）を使用します。

Windows: Windows 10/11にはOpenSSHクライアントが標準搭載されていますが、有効化されていない場合があります。「設定」->「アプリ」->「オプション機能」で「OpenSSH クライアント」がインストールされているか確認してください。もしインストールされていなければ追加します。PowerShellまたはコマンドプロンプトを開き、ssh -V コマンドを実行してバージョン情報が表示されるか確認してください。表示されない場合は、環境変数のPATHが正しく設定されているか確認するか、別途OpenSSHクライアント（PuTTYなどとは異なります）をインストールする必要があります。
macOS/Linux: これらのOSには通常OpenSSHクライアントが標準でインストールされています。ターミナルを開き、ssh -V コマンドを実行してバージョン情報が表示されるか確認してください。

ssh コマンドが実行できない場合は、VS Code以前の問題として、SSHクライアントの環境を整える必要があります。

3. SSHサーバーのインストールと起動（リモート）

接続先のリモートマシンにSSHサーバーソフトウェア（通常はOpenSSHサーバー）がインストールされ、起動している必要があります。

リモートマシンにログインできる場合は、以下のコマンドなどでSSHサーバーの状態を確認できます（OSによってコマンドは異なります）。
- systemdを使用しているシステム (Ubuntu 15.04+, Debian 8+, CentOS 7+, RHEL 7+, Fedora 15+): sudo systemctl status sshd
- SysVinitを使用しているシステム (古いUbuntu/Debian/CentOS/RHELなど): sudo service ssh start または sudo /etc/init.d/ssh start
SSHサーバーがインストールされていない場合は、パッケージマネージャーでインストールしてください (sudo apt update && sudo apt install openssh-server など)。
SSHサーバーが起動していない場合は、上記のコマンドで起動してください。
サーバーの起動時にエラーが出力されていないか (sudo journalctl -u sshd または /var/log/auth.log, /var/log/secure など) 確認してください。

4. ファイアウォール設定（ローカル/リモート/中間）

SSH通信がファイアウォールによってブロックされていないか確認します。デフォルトのSSHポートはTCP 22番です。

リモートマシン: リモートマシン自体のファイアウォール（ufw, firewalld, iptablesなど）で、SSHポート（通常22番）へのインバウンド接続が許可されているか確認してください。
- 例 (ufw): sudo ufw status, sudo ufw allow ssh または sudo ufw allow 22/tcp
- 例 (firewalld): sudo firewall-cmd --zone=public --add-service=ssh --permanent, sudo firewall-cmd --reload
ローカルマシン: ローカルマシンのファイアウォールやセキュリティソフトが、アウトバウンドのSSH接続をブロックしていないか確認してください。
ネットワーク中間: 会社や学校のネットワークなど、ローカルとリモートの間にルーターやファイアウォール機器がある場合、そこでSSHポートがブロックされている可能性があります。ネットワーク管理者に確認してください。

5. ネットワーク接続の確認

ローカルPCからリモートPCへネットワーク的に到達可能か確認します。

リモートPCの電源が入っており、正常に起動しているか確認してください。
コマンドプロンプトやターミナルから、リモートPCのIPアドレスまたはホスト名に対して ping コマンドを実行し、応答があるか確認してください。ping remotemachine_ip_or_hostname
pingが通らない場合は、ネットワークケーブルの接続、Wi-Fi接続、ルーター設定、サブネットマスク、デフォルトゲートウェイ、DNS設定などを確認してください。ローカルPCとリモートPCが同じネットワークセグメントにいるか、またはルーター経由で通信できる設定になっているか確認が必要です。インターネット経由で接続する場合は、グローバルIPアドレスやポートフォワーディング設定（ルーター側）が正しいか確認してください。

6. SSH接続の基本テスト（VS Codeを使わない）

VS Code Remote – SSHが失敗する場合、その原因がVS Codeにあるのか、それとも基盤となるSSH接続自体にあるのかを切り分けることが非常に重要です。コマンドラインから直接SSH接続を試すことで、これを判断できます。

コマンドプロンプトまたはターミナルを開き、以下のコマンドを実行します。
bash ssh your_username@remote_hostname_or_ip
または、デフォルトポート（22番）以外を使用している場合はポート番号を指定します。
bash ssh your_username@remote_hostname_or_ip -p your_port_number
このコマンドでパスワード入力を求められる、または公開鍵認証で成功してリモートシェルのプロンプトが表示されれば、SSH接続自体は確立できています。この場合、問題はVS Code Serverのセットアップや起動、またはVS Code側の設定にある可能性が高いです。
このコマンドで接続に失敗し、エラーメッセージが表示される場合は、VS Code以前にSSH接続自体に問題があります。次に説明する「SSH接続自体に関するトラブルシューティング」に進んでください。

ここで接続できるかどうかが、その後のトラブルシューティングの方向性を決定づける最も重要なステップです。

SSH接続自体に関するトラブルシューティング

基本的な確認事項で、コマンドラインからのSSH接続も失敗した場合、原因はVS Codeではなく、SSHクライアントとサーバー間の接続または認証プロセスにあります。以下の点を確認してください。

1. 認証情報の問題

最も一般的なSSH接続失敗の原因の一つです。

パスワード認証:
- ユーザー名・パスワードの入力ミス: リモートマシンにログインするためのユーザー名とパスワードを正確に入力しているか再確認してください。特にパスワードは画面に表示されないため、入力ミスに気づきにくいです。Caps Lockがオンになっていないかも確認してください。
- リモート側の認証設定: リモートのSSHサーバー設定ファイル (/etc/ssh/sshd_config) でパスワード認証が許可されているか確認してください (PasswordAuthentication yes)。ルートユーザーでのログインを制限している場合もあります (PermitRootLogin no)。
- PAM (Pluggable Authentication Modules): Linuxシステムでは、PAMの設定が認証に影響する場合があります。UsePAM yes が設定されている場合、PAM関連のログ（/var/log/auth.log や /var/log/secure など）を確認してください。
公開鍵認証: パスワード入力なしで接続できる公開鍵認証を使用している場合、以下の点を確認してください。
- 鍵ペアの対応: ローカルPCに正しい秘密鍵があり、その公開鍵がリモートPCの接続ユーザーの ~/.ssh/authorized_keys ファイルに登録されているか確認してください。
- ファイル・ディレクトリのパーミッション: SSHではセキュリティ上の理由から、鍵ファイルや関連ディレクトリのパーミッションが非常に厳格です。以下のパーミッションになっているか確認してください。
  - ローカルPCの秘密鍵ファイル (~/.ssh/id_rsa など): 読み取り権限のみ（通常 600）。他のユーザーが書き込める設定になっていると認証に失敗します (chmod 600 ~/.ssh/id_rsa)。
  - リモートPCの ~/.ssh ディレクトリ: 所有者のみが読み書き実行可能（通常 700）。(chmod 700 ~/.ssh)
  - リモートPCの ~/.ssh/authorized_keys ファイル: 所有者のみが読み書き可能（通常 600）。(chmod 600 ~/.ssh/authorized_keys)
  - リモートPCのユーザーのホームディレクトリ (~): 所有者のみが書き込み可能であること（通常 700 または 755）。他のユーザーが書き込みできると認証に失敗する場合があります。
- リモート側の sshd_config 設定: リモートのSSHサーバー設定ファイル (/etc/ssh/sshd_config) で公開鍵認証が許可されているか確認してください (PubkeyAuthentication yes)。また、AuthorizedKeysFile が正しいパス（通常 .ssh/authorized_keys）を指定しているか確認してください。
- パスフレーズ: 秘密鍵にパスフレーズを設定している場合、正確に入力しているか確認してください。ssh-agentを使用している場合は、鍵が正しく追加されているか確認してください (ssh-add -l)。
- SELinux/AppArmor (Linux): これらのセキュリティ機構がSSH関連のファイルアクセスを制限している場合があります。ログを確認するか、一時的にPermissiveモードにして試すなどのデバッグが必要になる場合があります。

2. ホスト名の解決

接続先にホスト名（例: my-server.example.com）を指定している場合、そのホスト名が正しいIPアドレスに解決されている必要があります。

ローカルPCから ping hostname や nslookup hostname または dig hostname コマンドを実行し、正しいIPアドレスが返されるか確認してください。
もし名前解決に問題がある場合は、DNSサーバーの設定を確認するか、一時的にIPアドレスで接続を試してください。IPアドレスでの接続に成功し、ホスト名で失敗する場合は、名前解決が原因です。
ローカルPCの /etc/hosts (Linux/macOS) または C:\Windows\System32\drivers\etc\hosts (Windows) ファイルに、接続先ホスト名とIPアドレスが誤って登録されていないか確認してください。

3. ポート番号の問題

デフォルトのSSHポートは22番ですが、セキュリティ上の理由などから変更されている場合があります。

リモートマシンのSSHサーバー設定ファイル (/etc/ssh/sshd_config) で、Port ディレクティブに指定されているポート番号を確認してください。
VS CodeやコマンドラインからのSSH接続時に、正しいポート番号を指定しているか確認してください。コマンドラインでは -p <port_number> オプション、VS Codeでは ~/.ssh/config ファイルで Port <port_number> を指定します（詳細は後述）。

4. SSHプロトコルのバージョン/暗号方式の不一致

非常に古いOSやシステムと新しいOSやシステムの間で接続しようとすると、お互いがサポートする共通のプロトコルバージョンや暗号方式が見つからず、接続が失敗することがあります。

コマンドラインで ssh -v user@hostname （-vv や -vvv でさらに詳細に）を実行し、詳細な接続プロセスとエラーメッセージを確認してください。クライアントとサーバーの間でどのアルゴリズムが試行され、どこで失敗しているかがログに表示されます。
必要に応じて、ローカルPCまたはリモートPCのSSH設定 (sshd_config または SSHクライアントの設定ファイル) で、サポートする暗号方式や鍵交換アルゴリズムなどを調整する必要がある場合があります。ただし、これはセキュリティリスクを伴う可能性があるため、慎重に行ってください。例えば、古いシステムでは非推奨になったSHA-1ベースの署名やdiffie-hellman-group1-sha1のような鍵交換方式しかサポートしていないことがあります。新しいOpenSSHクライアントはデフォルトでこれらを無効にしているため、クライアント設定ファイル (~/.ssh/config または /etc/ssh/ssh_config) に PubkeyAcceptedAlgorithms +ssh-rsa や KexAlgorithms +diffie-hellman-group1-sha1 のような行を追加して、一時的に許可する必要があるかもしれません（非推奨）。

5. TCP Wrapper / hosts.allow, hosts.deny (Linux)

リモートマシンでTCP Wrapperが使用されている場合、/etc/hosts.allow および /etc/hosts.deny ファイルによって、特定のIPアドレスからのSSH接続が制限されていることがあります。

リモートマシンのこれらのファイルを確認し、ローカルPCのIPアドレスからの接続が許可されているか、または拒否されていないか確認してください。sshd: ALL のような記述があればすべてのホストからの接続が許可されますが、特定のIPアドレスやネットワークに制限されている場合があります。

6. リモート側のリソース不足

SSH接続は成功し、認証も完了したが、すぐに切断される場合、リモート側のリソース（メモリ、CPU、ディスクI/O）が逼迫していることが原因で、SSHサーバープロセスやユーザーセッションの確立に失敗している可能性があります。

リモートマシンにログインできる場合は、top や htop, df -h コマンドなどでリソース使用状況を確認してください。
リソースに余裕がある場合は、SSHサーバーログ（/var/log/auth.log など）に切断に関する情報が出力されていないか確認してください。SSHサーバー側のアイドルタイムアウト設定 (ClientAliveInterval, ClientAliveCountMax in sshd_config) が短すぎないかも確認してください。

7. 詳細ログの確認（SSH接続自体）

コマンドラインでのSSH接続時に -v, -vv, -vvv オプションを付けて実行すると、詳細なデバッグ情報が表示されます。これにより、どの段階でエラーが発生しているか、認証プロセスはどのように進行しているかなどを詳しく知ることができます。

bash ssh -vvv your_username@remote_hostname_or_ip -p your_port_number
このログを注意深く分析することで、問題の原因を特定できる可能性が高まります。

VS Code側の設定・機能に関するトラブルシューティング

コマンドラインからのSSH接続には成功したが、VS Code Remote – SSHでの接続に失敗する場合、問題はVS Codeの連携部分、VS Code Serverのセットアップ、またはVS Code独自の設定にある可能性が高いです。

1. SSH設定ファイル (`~/.ssh/config`)

VS Code Remote – SSHは、ローカルPCの標準的なSSH設定ファイルである ~/.ssh/config を読み込みます（Windowsの場合は C:\Users\YourUsername\.ssh\config）。このファイルに誤りがあると、VS Codeからの接続に失敗することがあります。

ファイルの場所とパーミッション: ~/.ssh/config が正しい場所に存在し、パーミッションが適切（通常 600、所有者のみ読み書き可）であるか確認してください (chmod 600 ~/.ssh/config)。パーミッションが緩すぎるとSSHクライアントに拒否されます。
設定記述ミス: config ファイルの記述に誤りがないか確認してください。一般的なエラーは以下の通りです。
- インデント: ホスト設定内の各オプションは、Host 行よりもインデントされている必要があります（通常スペース2つ）。
- スペルミス: Hostname, User, Port, IdentityFile などのキーワードのスペルミス。
- パスの誤り: IdentityFile オプションで秘密鍵へのパスを指定している場合、そのパスが正しいか、秘密鍵ファイルが存在するか確認してください。Windowsの場合、パスの区切り文字はバックスラッシュ（\）ではなくスラッシュ（/）を使う方が安全です。また、パスにスペースが含まれる場合は引用符で囲む必要があります。例: IdentityFile /c/Users/YourName/.ssh/your_private_key
重要な設定項目: VS Code Remote – SSHでよく使用される重要な設定項目は以下の通りです。
- Host your_alias: VS Codeの接続リストに表示される名前。任意の値。
- Hostname remote_hostname_or_ip: 接続先の実際のホスト名またはIPアドレス。
- User remote_username: 接続に使用するユーザー名。
- Port remote_port_number: 接続に使用するポート番号（デフォルト22以外の場合）。
- IdentityFile /path/to/your/private_key: 使用する秘密鍵ファイルのパス（公開鍵認証の場合）。
- ForwardAgent yes: SSHエージェントフォワーディングを有効にする場合。
- StrictHostKeyChecking no: （非推奨）ホストキー検証を無効にする。デバッグ目的以外では使用しないことを強く推奨します。ホストキー検証に失敗する場合、通常は ~/.ssh/known_hosts ファイルの該当エントリを削除して再接続するのが正しい対処法です。
VS Code設定との連携: VS Codeのユーザー設定 (settings.json) で "remote.SSH.configFile" にカスタムの config ファイルパスを指定している場合、そのパスが正しいか確認してください。

2. VS Code設定 (`settings.json`)

VS Codeのユーザー設定 (settings.json) でRemote – SSHに関連する特定の設定を行っている場合、それが原因で問題が発生することがあります。

"remote.SSH.configFile": 標準以外の config ファイルを使用している場合、パスが正しいか確認してください。
"remote.SSH.path": VS Codeが使用するSSHクライアントプログラムのパスを明示的に指定している場合、そのパスに実行ファイルが存在するか確認してください。通常はこの設定は不要です。
"remote.SSH.showLog": これを true に設定すると、VS Codeの出力ウィンドウにSSH接続に関する詳細なログが表示されます。問題を特定するのに非常に役立ちます。
- VS Codeを開き、Ctrl+Shift+P (または Cmd+Shift+P) を押してコマンドパレットを開きます。「Open User Settings (JSON)」または「設定 (JSON) を開く」を選択し、以下の行を追加または編集します。
  json { "remote.SSH.showLog": true // 他の設定... }
- ログは「出力」ウィンドウ（「表示」->「出力」）のドロップダウンメニューで「リモート – SSH」または「ログ (リモート – SSH)」を選択すると表示されます。
"remote.SSH.logLevel": ログの詳細レベルを制御します。デフォルトは Info ですが、さらに詳細な情報を得るために "Trace" に設定することも可能です。
json { "remote.SSH.logLevel": "Trace" }
ただし、Traceレベルのログは非常に量が多くなる可能性があります。
"remote.SSH.remotePlatform": VS Code ServerはリモートOSの種類（Linux x64, ARMなど）を自動検出しますが、まれに失敗することがあります。この設定でリモートのプラットフォームを明示的に指定することで解決する場合があります。例: "remote.SSH.remotePlatform": "linux", "remote.SSH.remotePlatform": "linux-arm64"。
"remote.SSH.serverInstallPath": VS Code Serverのインストール場所を明示的に指定する場合に使用します。通常は自動で ~/.vscode-server にインストールされますが、特定のディレクトリにしか書き込み権限がない場合などに指定します。指定したパスに書き込み権限があるか確認してください。
"remote.SSH.lockfilesInTmp": リモートのホームディレクトリに書き込み権限がない場合など、VS Code Serverがロックファイルを作成できない場合に発生する問題を回避するため、/tmp ディレクトリにロックファイルを作成するように指示します。これを true に設定することで解決する場合があります。
json { "remote.SSH.lockfilesInTmp": true }
"remote.SSH.useFlock": 一部のファイルシステムや環境でflockが正しく動作しない場合、これをfalseに設定することで、別のロック機構を使用させることができます。

3. VS Code Serverのダウンロード/起動の問題

SSH接続自体は成功するものの、「VS Code Server failed to start.」「Cannot connect to the remote extension host.」といったエラーが表示される場合、リモートマシンでのVS Code Serverのダウンロード、インストール、または起動プロセスに問題があります。

リモートマシンのインターネット接続: VS Code Serverのダウンロードには、リモートマシンからのインターネットアクセスが必要です。
- リモートマシンで ping google.com など、外部への疎通を確認してください。
- プロキシ環境下にある場合、リモートマシンで HTTP_PROXY, HTTPS_PROXY, NO_PROXY などの環境変数が正しく設定されているか確認してください。これらの設定はVS Code Serverのダウンロードにも影響します。
ディスク容量: リモートマシンのホームディレクトリ（または remote.SSH.serverInstallPath で指定したディレクトリ）に、VS Code Serverをインストールするのに十分なディスク容量があるか確認してください (df -h コマンド)。
パーミッション: リモートのユーザーが、VS Code Serverがインストールされるディレクトリ（通常 ~/.vscode-server）およびそのサブディレクトリに書き込み、実行する権限があるか確認してください。
既存のVS Code Serverプロセス: 過去の接続で異常終了したVS Code Serverプロセスがリモートに残っていると、新しいサーバーが起動できない場合があります。リモートマシンで以下のコマンドなどを実行し、関連するプロセスを特定してkillしてください。
bash ps aux | grep .vscode-server pkill -f .vscode-server
~/.vscode-server/bin/ 以下のクリーンアップ: VS Code Serverのダウンロードやインストールに問題が発生した場合、リモートマシンの ~/.vscode-server/bin/ ディレクトリ（または remote.SSH.serverInstallPath で指定したパス以下の bin/）を削除し、VS Codeに再接続させてVS Code Serverを再ダウンロード・インストールさせることで問題が解決することがあります。
bash rm -rf ~/.vscode-server/bin/*
注意: これを行うと、リモートマシンにインストールされていたすべてのRemote-SSH関連拡張機能も再ダウンロードされます。
アーキテクチャの不一致: まれに、VS CodeがリモートマシンのCPUアーキテクチャ（x64, ARMなど）を誤認識し、不適切なVS Code Serverバイナリをダウンロードしようとすることがあります。remote.SSH.remotePlatform 設定で正しいプラットフォームを明示的に指定してみてください。リモートマシンのアーキテクチャは uname -m コマンドなどで確認できます。
VSCODE_SERVER_DOWNLOAD_URL 環境変数: 特定の環境やオフライン環境で、VS Code Serverの自動ダウンロードがうまくいかない場合、手動でVS Code Serverのtar.gzファイルをダウンロードし、リモートマシンの指定された場所に配置し、VS Codeにそのパスを教える方法があります。これは高度な方法であり、MicrosoftのVS Code Remote公式ドキュメントを参照する必要があります。
リモート環境変数: VS Code Serverは、リモート環境で実行されます。PATH などの環境変数が正しく設定されていないと、依存するコマンド（シェル、Pythonなど）が見つからず、サーバーが正常に起動しない場合があります。.bashrc, .profile, /etc/profile など、リモートユーザーのシェル環境設定ファイルを確認してください。特に、非対話型シェル実行時に予期しない出力があったり、exit コマンドが含まれていたりしないか注意が必要です。
端末（Terminal）の問題: VS Code Serverはリモートでシェルを起動してコマンドを実行します。リモートユーザーのデフォルトシェル設定ファイル（.bashrc, .zshrc, .profileなど）にエラーや無限ループ、あるいはVS Code Serverの起動プロセスを妨げるような設定（例: TTYがない場合は終了する、対話的な入力を求める）がないか確認してください。一時的にこれらの設定ファイルをリネームして無効にし、接続を試すことも有効なデバッグ手段です。

4. プロキシ設定

ローカルまたはリモートのネットワーク環境でプロキシサーバーを経由しないとインターネットにアクセスできない場合、VS Code Remote – SSHやVS Code Serverのダウンロードに影響が出ます。

VS Codeのプロキシ設定: ローカルのVS Codeがインターネットにアクセスするためのプロキシ設定を確認します。「ファイル」->「基本設定」->「設定」を開き、「proxy」で検索します。http.proxy, http.proxyStrictSSL, http.proxyAuthorization などの設定が正しく行われているか確認してください。
SSH接続自体のプロキシ: SSH接続自体をプロキシ経由で行う必要がある場合、~/.ssh/config ファイルで ProxyCommand オプションを使用します。例えば、HTTPプロキシ経由でSSHする場合は ProxyCommand connect -H your_proxy_server:proxy_port %h %p のように記述します（connect コマンドが必要）。
VS Code Serverダウンロード時のプロキシ (リモート側): 前述の通り、リモートマシンがプロキシ経由でインターネットに接続する必要がある場合、リモートユーザーの環境変数として HTTP_PROXY, HTTPS_PROXY, NO_PROXY を設定する必要があります。これらはVS Code Serverがダウンロード時に使用します。通常、ユーザーのシェル設定ファイル (~/.bashrc など) に記述します。

5. 拡張機能の干渉

非常にまれですが、他のVS Code拡張機能がRemote – SSH拡張機能の正常な動作に干渉する可能性があります。

すべての拡張機能を無効にした状態でSSH接続を試してみてください。それで接続できる場合は、いずれかの拡張機能が原因です。拡張機能を一つずつ有効に戻しながら、どの拡張機能が問題を引き起こしているかを特定します。

高度なトラブルシューティング

上記の基本的なステップで解決しない場合、さらに詳細な調査が必要になります。

1. 詳細ログの確認

前述の remote.SSH.showLog および remote.SSH.logLevel 設定を Trace にすることで、VS Codeの出力ウィンドウに膨大な量のログが出力されます。

特に「ログ (リモート – SSH)」チャンネルのログを注意深く確認してください。SSH接続の試行、認証プロセス、リモートでのコマンド実行、VS Code Serverの起動プロセスなどが詳細に記録されています。エラーメッセージや警告に注目し、どの段階で処理が停止したり失敗したりしているかを特定します。
VS Code Server起動時のエラーは、リモートマシン側の標準エラー出力に表示されることもあります。VS Codeのログにリモートで実行されたコマンドが表示されている場合、そのコマンドをリモートで直接実行して、出力されるエラーを確認することも有効です。

2. SSHエージェントの問題

公開鍵認証でパスフレーズ付きの秘密鍵を使用している場合、SSHエージェント（ssh-agent）が重要な役割を果たします。

ローカルPCでSSHエージェントが実行されているか確認します。コマンドプロンプト/ターミナルで ssh-agent と入力し、環境変数が表示されれば実行されています。すでに実行中の場合は何も表示されないか、「Agent pid XXX」のようなメッセージが表示されます。
秘密鍵がSSHエージェントに追加されているか確認します。ssh-add -l コマンドを実行し、秘密鍵のフィンガープリントが表示されれば追加されています。表示されない場合は ssh-add /path/to/your/private_key で追加してください（パスフレーズが求められます）。
~/.ssh/config で ForwardAgent yes を設定している場合、エージェントフォワーディングが正しく機能しているか確認します。リモートに接続後、リモート側で ssh-add -l と実行し、ローカルの秘密鍵のフィンガープリントが表示されれば成功しています。

3. SSHキーペアの再生成

公開鍵認証に問題がある場合、既存のキーペア自体に問題（破損、フォーマット不正など）がある可能性もゼロではありません。

新しいSSHキーペアを作成し、その公開鍵をリモートの authorized_keys ファイルに追加して、新しいキーペアで接続できるか試してみてください。
- ローカルPCで ssh-keygen -t rsa -b 4096 -C "[email protected]" などと実行します。
- 生成された公開鍵（通常 ~/.ssh/id_rsa.pub）の内容を、リモートの ~/.ssh/authorized_keys ファイルの末尾に追加します。
- ~/.ssh/config ファイルで新しい秘密鍵を指定するか、デフォルトの鍵ファイルを使用するように設定します。

4. ネットワークパケットのキャプチャ

非常に技術的ですが、Wireshark (Windows/macOS/Linux) や tcpdump (Linux/macOS) といったツールを使って、SSH接続時にネットワーク上を流れるパケットをキャプチャし分析することで、より低レベルでの通信問題を特定できる場合があります。特に、SYN/ACKのやり取り、SSHプロトコルハンドシェイク、認証パケットなどを確認できます。

5. リモート環境変数の設定（非対話型シェルの問題）

VS Code Serverは、SSH接続確立後にリモート側でシェルを介して起動されますが、このシェルは通常、対話型ではない方法で実行されます。.bashrc や .zshrc などの設定ファイルは、対話型シェルと非対話型シェルで挙動が異なる場合があります。

例えば、.bashrc の中で if [ -z "$PS1" ]; then ... のような対話型シェルのみで実行されるべき処理の中に、非対話型シェルでも実行されてしまうと問題を引き起こすコマンドが含まれていることがあります。
また、VS Code Serverの実行に必要な環境変数（例: PATH に特定のディレクトリを追加する必要がある場合）が、非対話型シェルでは設定されないことがあります。remote.SSH.remoteEnv 設定を使って、VS Code Server起動時に強制的に環境変数を設定することも可能です。
json { "remote.SSH.remoteEnv": { "PATH": "/opt/mytool/bin:$PATH" } }
あるいは、リモートユーザーのログインシェル設定ファイル（.profile, .bash_profile, /etc/profile など、SSH接続時に読み込まれるファイル）に環境変数設定を記述する必要があります。.bashrc は対話型シェルでのみ読み込まれることが多いので注意が必要です。

6. cgroup v2 (Linux)

一部の新しいLinuxディストリビューション（例: Ubuntu 21.10以降）でcgroup v2がデフォルトで有効になっている場合、VS Code Remote – SSHの接続時に問題が発生することが報告されています。これは、VS Code Serverが起動する際に作成されるプロセスがcgroupの制限を受けることに関連している可能性があります。

この問題に該当するか確認し、必要であれば回避策を適用します。一時的な回避策として、カーネル起動オプションに systemd.unified_cgroup_hierarchy=false を追加してcgroup v1を使用させる方法などがありますが、システム全体に影響するため慎重に行ってください。最新のVS Code Remote – SSH拡張機能ではこの問題が修正されている場合もありますので、まずは拡張機能を最新にアップデートすることが推奨されます。

7. 一時的なファイルのクリーンアップ

ローカルまたはリモートのVS Code関連の一時ファイルやキャッシュが破損している可能性もゼロではありません。

ローカル: VS CodeのユーザーデータディレクトリにあるRemote-SSH関連のキャッシュを削除してみます。場所はOSによって異なります。
- Windows: %APPDATA%\Code\User\globalStorage\ms-vscode-remote.remote-ssh
- macOS: $HOME/Library/Application Support/Code/User/globalStorage/ms-vscode-remote.remote-ssh
- Linux: $HOME/.config/Code/User/globalStorage/ms-vscode-remote.remote-ssh
  このディレクトリの中身をバックアップしてから削除し、VS Codeを再起動して接続を試みます。
リモート: リモートの ~/.vscode-server ディレクトリ全体を削除し、VS Codeに再接続させてゼロからセットアップさせます。ただし、このディレクトリにはリモートにインストールした拡張機能も含まれているため、再接続時にそれらが再ダウンロードされることに注意してください。
bash rm -rf ~/.vscode-server

よくあるエラーメッセージとその意味・対処法

VS Codeの出力ウィンドウやコマンドラインで表示されるエラーメッセージは、問題を特定する上で非常に重要な手がかりとなります。ここでは、よく遭遇するエラーメッセージとその意味、基本的な対処法を解説します。

Could not establish connection. Could not connect to ... port 22: Connection refused
- 意味: ローカルPCからリモートPCの指定ポート（通常22番）への接続が拒否されました。TCPレベルでの接続が確立できていません。
- 原因: リモート側でSSHサーバーが起動していない、指定したポートで待機していない、リモートのファイアウォールで接続がブロックされている、リモートPCが存在しない/起動していない、中間ネットワーク機器でブロックされているなど。
- 対処法:
  - リモートPCが起動しているか確認。
  - リモートPCでSSHサーバーが起動しているか確認 (systemctl status sshd など)。
  - リモートPCのファイアウォール設定を確認し、SSHポートが解放されているか確認。
  - ~/.ssh/config や接続時に指定しているポート番号がリモートの sshd_config と一致しているか確認。
  - ローカルPCからリモートPCへのpingが通るか確認。
  - コマンドラインで ssh -p port_number user@hostname や telnet hostname port_number を試して、ポートが開いているか確認（telnetはインストールされていない場合もあります）。
Permission denied (publickey,password).
- 意味: SSHサーバーは接続を受け付けましたが、認証に失敗しました。指定されたユーザー名に対して、提供された公開鍵またはパスワードが無効です。
- 原因:
  - パスワード認証の場合: ユーザー名またはパスワードの入力ミス。リモート側の sshd_config でパスワード認証が禁止されている。
  - 公開鍵認証の場合: ローカルの秘密鍵に対応する公開鍵がリモートの ~/.ssh/authorized_keys に登録されていない。鍵ファイルや ~/.ssh ディレクトリのパーミッションが不正。sshd_config で公開鍵認証が禁止されている。秘密鍵のパスフレーズ入力ミス。
- 対処法:
  - ユーザー名とパスワードを正確に入力しているか再確認。
  - ~/.ssh/authorized_keys に対応する公開鍵が正しく登録されているか確認。
  - ローカルの秘密鍵、リモートの ~/.ssh ディレクトリ、リモートの ~/.ssh/authorized_keys ファイルのパーミッションを確認し、修正 (chmod)。
  - リモートの sshd_config で PasswordAuthentication yes または PubkeyAuthentication yes になっているか確認。
  - コマンドラインで ssh -v を付けて接続し、認証プロセス（公開鍵の試行など）の詳細ログを確認。
Host key verification failed.
- 意味: 初回接続時、またはリモートサーバーのホスト鍵が変更された後で発生します。ローカルPCの ~/.ssh/known_hosts ファイルに記録されているホスト鍵と、リモートサーバーが提示するホスト鍵が一致しません。中間者攻撃の可能性も示唆されます。
- 原因: リモートサーバーのOS再インストール、SSHサーバーの再設定、あるいは悪意のあるサーバーへの接続試行。
- 対処法:
  - 正当な変更の場合: コマンドラインやVS Codeの出力に表示されるエラーメッセージに従い、ローカルの ~/.ssh/known_hosts ファイルから該当する行（ホスト名またはIPアドレスが一致する行）を削除します。
  - VS Codeの場合: VS Codeの通知としてエラーが表示されることが多いので、その通知の指示に従って known_hosts からエントリを削除するボタンをクリックするのが最も簡単です。
  - コマンドラインの場合: テキストエディタで ~/.ssh/known_hosts を開き、該当するホスト名またはIPアドレスを含む行を見つけて削除します。
  - 削除後、再度接続を試みると、新しいホスト鍵を受け入れるか尋ねられるので、確認して続行します。
  - 注意: 知らないサーバーでこのエラーが出た場合は、セキュリティリスクがあるため、安易に鍵を削除して接続しないでください。
VS Code Server failed to start. / Installing VS Code Server... Failed.
- 意味: SSH接続自体は成功しましたが、リモートマシン上でのVS Code Serverのダウンロード、インストール、または起動に失敗しました。
- 原因: リモートマシンのインターネット接続問題（プロキシ設定含む）、ディスク容量不足、ユーザーのパーミッション不足 (~/.vscode-server への書き込み権限など）、リモート環境変数の設定問題、互換性のないVS Code Serverバージョン、.bashrc などシェル設定ファイルの問題、既存のVS Code Serverプロセスが邪魔しているなど。
- 対処法:
  - リモートマシンのインターネット接続を確認。プロキシが必要な場合は環境変数を設定。
  - リモートのディスク容量を確認。
  - リモートユーザーが ~/.vscode-server に書き込み権限があるか確認。
  - リモートの ~/.vscode-server/bin ディレクトリを削除して再試行。
  - リモートで不要なVS Code Serverプロセスをkill。
  - リモートユーザーのシェル設定ファイル（.bashrc, .profileなど）に問題がないか確認。
  - VS Codeの remote.SSH.showLog を true にして詳細ログを確認し、VS Code Serverのダウンロード/起動プロセスで具体的に何が起きているか把握する。
Cannot connect to the remote extension host.
- 意味: VS Code Serverはリモートで起動したようですが、ローカルのVS Code本体との通信チャネルが確立できません。
- 原因: リモートマシン内でVS Code Serverが通信に使用するローカルポートがファイアウォール（特にLinuxのiptablesなど、lo インターフェースもフィルタリングする場合）でブロックされている、VS Code Serverが何らかの内部エラーで正常に起動完了していない、ネットワークの安定性の問題など。
- 対処法:
  - VS Code Serverプロセスがリモートで実行されているか確認 (ps aux | grep .vscode-server)。
  - リモートマシンのファイアウォール設定を確認し、lo (localhost/loopback) インターフェースを含む内部通信がブロックされていないか確認。VS Code Serverは通常、リモートマシン内のローカルポートでVS Code本体からの接続を待ち受けます。
  - VS Code Serverの起動ログ（~/.vscode-server/.<commit_id>.log ファイルなど）を確認し、起動時にエラーが発生していないか確認。
  - リモートマシンを再起動してみる。
  - VS Code Remote – SSH拡張機能やVS Code本体を最新版にアップデートする。
Timed out waiting for SSH agent to connect
- 意味: SSHエージェントフォワーディングを使用する設定になっているが、ローカルPCでSSHエージェントが起動していないか、秘密鍵がエージェントに追加されていないため、認証に使用する鍵を取得できませんでした。
- 原因: ローカルPCで ssh-agent が実行されていない、秘密鍵が ssh-add されていない、~/.ssh/config で ForwardAgent yes となっているがエージェントが使えない環境で接続しようとしている。
- 対処法:
  - ローカルPCでSSHエージェントが実行されているか確認 (ssh-agent または ssh-add -l)。
  - 秘密鍵がSSHエージェントに追加されているか確認 (ssh-add /path/to/private_key)。
  - もしエージェントフォワーディングが不要なら、~/.ssh/config の ForwardAgent yes を削除するかコメントアウトする。
Bad owner or permissions on ~/.ssh/config
- 意味: ローカルPCの ~/.ssh/config ファイルの所有者やパーミッションが不正です。SSHクライアントはセキュリティ上の理由から、このファイルが自分以外のユーザーに書き込み可能になっている場合などにロードを拒否します。
- 原因: ~/.ssh/config ファイルのパーミッションが 600 以外になっている（特にグループやその他のユーザーに書き込み権限がある）。ファイルの所有者が自分ではない。
- 対処法: コマンドラインでパーミッションを修正します。
  bash chmod 600 ~/.ssh/config
  所有者が自分になっているか確認し、必要であれば chown コマンドで変更します。

それでも解決しない場合

ここまでのステップをすべて試しても問題が解決しない場合、環境特有の未知の問題である可能性があります。以下の手段を検討してください。

VS CodeのGitHubリポジトリを検索: VS Code Remote – SSH拡張機能はオープンソースです。GitHubリポジトリ (microsoft/vscode-remote-release) のIssueを検索し、同様の問題が報告されていないか確認してください。既存のIssueに解決策や回避策が記載されている場合があります。
公式ドキュメントの確認: Microsoftが提供するVS Code Remote – SSHの公式ドキュメントを改めて確認してください。特定のOSバージョンや設定に関する注意点が記載されていることがあります。
GitHub Issueで報告: 同様の問題が見つからない場合は、詳細なログ（remote.SSH.logLevel を Trace に設定したもの）や環境情報（OSバージョン、SSHクライアント/サーバーバージョン、VS Codeバージョン、Remote-SSH拡張機能バージョンなど）を添えて、GitHubリポジトリに新しいIssueを投稿することを検討してください。開発者や他のユーザーからの助けを得られる可能性があります。
一時的な回避策: 開発を続けるために、一時的な回避策を検討します。例えば、VS Code Serverの手動ダウンロードと配置、あるいはSSHFSなど別の方法でリモートファイルシステムをマウントしてVS Codeで開くといった方法があります。ただし、これらはRemote – SSHのすべての機能を提供するわけではありません。

まとめ

VS CodeでSSH接続ができない問題は、様々な原因が考えられますが、体系的にトラブルシューティングを行うことで、ほとんどの場合は解決可能です。

まず、基本的な確認事項から始めましょう。VS Codeや拡張機能のバージョン、SSHクライアント/サーバーの有無と起動状態、ネットワーク接続、ファイアウォール設定といった、環境の前提条件が満たされているかを確認します。

次に、コマンドラインからのSSH接続を試みてください。ここで接続できれば、問題はVS Code側（VS Code Serverや設定）にあります。失敗する場合は、SSH接続自体（認証、ネットワーク、設定ファイルなど）に問題があります。

それぞれの問題の可能性に応じて、認証情報の確認、設定ファイルの記述チェック、パーミッションの確認、ネットワーク設定の調整、そして最も重要な詳細ログの確認を行います。VS Codeの出力ウィンドウのログ、コマンドラインSSHの -v オプション、リモートサーバーのSSHログなどを分析することで、エラーが発生している具体的な箇所を特定できます。

VS Code Serverに関する問題の場合は、リモートマシンのインターネット接続、ディスク容量、パーミッション、既存プロセスなどを確認し、必要に応じて ~/.vscode-server ディレクトリのクリーンアップを行います。

よくあるエラーメッセージの意味と対処法を知っておくことも、迅速な問題解決に役立ちます。

リモート開発環境の構築は非常に便利ですが、ローカルとリモート双方の環境設定が連携する必要があるため、複雑になりがちです。この記事が提供する包括的なガイドが、あなたのSSH接続問題を解決するための一助となり、より快適なVS Codeリモート開発ライフを実現できることを願っています。

付録・補足

WindowsでのOpenSSHインストール/設定（再確認）

Windows 10以降では、OpenSSHクライアントがオプション機能として提供されています。
1. 「設定」を開く。
2. 「アプリ」を選択。
3. 「オプション機能」を選択。
4. 「機能を追加」をクリック。
5. リストから「OpenSSH クライアント」を探し、インストール。

これでコマンドプロンプトやPowerShellで ssh コマンドが利用できるようになります。

`~/.ssh/config` の具体的な記述例

複数のリモートホストに接続する場合、~/.ssh/config ファイルを適切に記述すると便利です。

“`ssh_config

最初のホスト設定

Host my-remote-server
Hostname your_server.example.com # 実際のホスト名またはIPアドレス
User your_username # リモートマシンのユーザー名
Port 22 # SSHポート (デフォルト22以外の場合)
IdentityFile ~/.ssh/id_rsa_my_server # このホストで使用する秘密鍵のパス (公開鍵認証の場合)
ForwardAgent yes # 必要ならエージェントフォワーディングを有効に

別のホスト設定

Host dev-machine
Hostname 192.168.1.100
User developer
Port 2222
IdentityFile ~/.ssh/keys/dev_machine_key
StrictHostKeyChecking no # 非推奨 – デバッグや一時的な用途のみ

共通設定 (すべてのホストに適用)

Host *

ServerAliveInterval 60 # 接続維持のため60秒ごとに信号を送る

“`

VS CodeのRemote Explorerで「SSH Targets」に表示されるのは、このファイルで定義された Host エントリです。

プロキシ設定の具体的な方法（環境変数）

VS Code Serverのダウンロードなどでリモート側からインターネットにアクセスする際にプロキシが必要な場合、リモートユーザーのシェル設定ファイル（例: ~/.bashrc, ~/.profile, ~/.zshrc）に以下の行を追加します。

“`bash

HTTPプロキシ

export HTTP_PROXY=”http://proxy.example.com:8080″
export http_proxy=”http://proxy.example.com:8080″

HTTPSプロキシ

export HTTPS_PROXY=”http://proxy.example.com:8080″ # HTTPプロキシと同じ場合が多い
export https_proxy=”http://proxy.example.com:8080″

プロキシを使用しないドメイン/IP (カンマ区切り)

export NO_PROXY=”localhost,127.0.0.1,.example.com”
export no_proxy=”localhost,127.0.0.1,.example.com”
`` 変更を反映するには、シェルを再起動するかsource ~/.bashrc` などと実行します。これらの環境変数はVS Code Serverの起動プロセスによって継承される必要があります。

これで、VS CodeでSSH接続ができない場合の完全ガイド記事が完成しました。約5000語の詳細な説明が含まれています。