ドキュメント
Windows の WSL
Windows で WSL を使う方法は 2 つあります。ライトな方法は WSL シェルをターミナルプロファイルとして追加するもの、フルの方法は WSL 内部に vterm-server をインストールするものです。前者はシェルのみ、後者はファイル管理、Git パネル、MCP などすべてを解放します。
ライトな方法:WSL ターミナルプロファイル
Windows では WSL ターミナルプロファイルは自動的に読み込まれます。起動時にサーバーが wsl.exe を検出してインストール済みディストリビューションを列挙し、ディストロごとに 1 つのプロファイルエントリをプロファイルリストに追加します(例: Ubuntu (WSL)。一覧にない場合は汎用の WSL エントリが現れます)。
使うには、クライアントのタイトルバーのプロファイルメニューで WSL エントリを選ぶだけです。ディストロが起動し、そのターミナルに直接落ちます。ローカルのものを開くのと同じです。
制限:このようなセッションは Windows 側サーバーで実行されるため、クライアントのファイルエクスプローラー、Git パネル、環境変数などは機能しません(Windows のファイルシステムセマンティクスで動作し、WSL 内の Linux ファイルシステムは見えません)。
フルの方法:WSL 内部に vterm-server をインストール
WSL を独立した Linux マシンとみなし、ヘッドレスの vterm-server をインストールします。Web サイトがワンライナースクリプトを提供しています。WSL ターミナルに貼り付けてください:
curl -fsSL https://vterminal.dev/install.sh | bashスクリプトは自動的に:
- WSL/ヘッドレス環境を検出し、ヘッドレス vterm-server を
~/.local/vtermにダウンロードします; - systemd ユーザーサービス をインストールして即座に起動します — ログインのたび(WSL 起動を含む)に実行され、手動起動は不要です;
~/.local/vtermを PATH に追加します。
WSL で systemd が無効な場合、スクリプトは
/etc/wsl.confに[boot]systemd=trueを追加し、Windows 側でwsl --shutdownを実行し、インストーラを再実行するよう案内します。
設定ページを開く
WSL 内で:
vterm-server --openこのコマンドは Web UI アドレス(http://localhost:<config-port>/)を表示し、ブラウザの起動を試みます(WSL 内では wslview 経由で Windows のデフォルトブラウザ)。WSL2 の localhost 転送により、Windows ブラウザで同じアドレスを開くのも同様に機能します。サーバーが動いている間は、表示される URL に一回限りのログイントークン(?ticket=...、ローカルソケット経由で発行)が付き、開くだけでサインインが完了します。
(オプション)WSL サーバーをホストリレーに共有
Windows マシンも vterm-server を実行している(リレーとして動作)場合、WSL サーバーをその配下に接続でき、クライアントは 1 つのローカル接続で両方の「マシン」を見られます:
- Windows サーバーの Web UI で QR コードをクリックして共有文字列をコピー;
- WSL サーバーの Web UI(前節のアドレス)を開き、
Relay Addressフィールドの横に現れる貼り付けボタンをクリックしてアドレスとキーを自動入力し、Apply; - Windows の vterm-server が動作している間、クライアントはローカルリレー配下で WSL サーバーのターミナル・ファイル・Git を見られます。
WSL2 のデフォルト NAT ネットワークでは、WSL は WSL 側から見たホストのアドレス(デフォルトゲートウェイ —
cat /etc/resolv.confの nameserver)で Windows ホストに到達します。ミラー化ネットワークではlocalhostが使えます。リレーの詳細は Relay の章を参照してください。