# Proxyman の WebSocket キャプチャ

> Web ブラウザ、iOS の実機とシミュレータ、Android、NodeJS や Python のサーバーから、Proxyman で WebSocket（WS/WSS）通信をキャプチャして復号できます。

## 1. 概要 {#1-whats-it}

Proxyman では、WebSocket（WS）と Secure WebSocket（WSS）の通信をキャプチャして、簡単にプレビューできます。

* iOS の実機と iOS シミュレータから WS/WSS をキャプチャ（[Atlantis framework](https://github.com/ProxymanApp/atlantis) が必要）
* Web ブラウザと Mac アプリから WS/WSS をキャプチャ
* Android の実機と Android エミュレータから WS/WSS をキャプチャ
* WebSocket メッセージを整形して表示
* All / Sent / Received でメッセージをフィルタ
* JSON / Tree Preview / HEX 形式で内容を表示
* カラムをカスタマイズ：Frame、Length、Data、Time など
* 可能な場合、バイナリメッセージを JSON に自動でデコード
* Sublime や VS Code などの外部エディタで WebSocket メッセージを開く
* [Scripting](#7-modify-websocket-messages-with-scripting) で WebSocket メッセージを編集、ドロップ、送信（macOS 版 Proxyman 26.2.0 以降、Windows/Linux 版 Proxyman 26.1.0 以降）

## 2. Web ブラウザから WS/WSS をキャプチャ {#2-capture-wswss-from-web-browsers}

### localhost の WebSocket {#localhost-websocket}

Proxyman は、[Automatic Setup](https://proxyman.com/docs/ja/automatic-setup/automatic-setup) を使えば、Google Chrome から ws://localhost:3000 などの localhost WebSocket をキャプチャできます。

1. **Setup** メニュー → **Automatic Setup…** を開きます
2. Google Chrome を選択します（New Profile または Current Profile）。新しい Google Chrome のウィンドウが開きます
3. このウィンドウで localhost の WebSocket ページを開きます。Proxyman がキャプチャします

### 本番環境の WebSocket {#production-websocket}

Proxyman は、設定なしで Google Chrome からの WS/WSS 通信を自動的にキャプチャします。

1. Proxyman と Google Chrome を開きます
2. WS/WSS の通信を発生させます。たとえば [https://echo.websocket.org/.ws](https://echo.websocket.org/.ws) を開きます
3. Proxyman で WS/WSS のデータを確認します

### Protobuf ペイロードを含む WebSocket {#websocket-with-protobuf-payload}

Proxyman macOS 6.5.0 以降では、WebSocket メッセージ内の Protobuf をデコードできます。

1. まず、Proxyman で WebSocket 通信をキャプチャできる状態にします
2. WebSocket の Protobuf メッセージを右クリック → **Protobuf** → **Decode Raw Text…** または **Decode with Message Type…** を選択します

* **Raw mode**：Protobuf の desc ファイルがない場合に便利です。
* **Message Type**：Protobuf の desc ファイルにある Message Type を使用します。

![バイナリの WebSocket メッセージを右クリックした Proxyman のメニューで、Protobuf、Decode Raw Text、Decode with Message Type が表示されている画面](https://proxyman.com/docs/assets/Screenshot%202026-01-30%20at%2015.11.30.jpg)

_Protobuf で WebSocket のペイロードをデコード_

## 3. iOS から WS/WSS をキャプチャ {#3-capture-wswss-from-ios}

アプリが **URLSessionWebSocketTask** や、Starscream、SocketRocket などの iOS 向け WebSocket ライブラリを使っている場合、Proxyman では WS/WSS 通信をキャプチャできないことがあります。

* **理由**：これは Apple の設計によるものです。**URLSessionWebSocketTask** はシステムの HTTP プロキシを使用しません。WS/WSS の通信はすべてインターネットに直接送られるため、Proxyman や Charles Proxy ではキャプチャできません。
* サンプルアプリ：[https://github.com/ProxymanApp/websocket-example-ios-app](https://github.com/ProxymanApp/websocket-example-ios-app)

### ✅ 解決策 1（iOS 17 以降向け、推奨）{#-solution-1-recommended-for-ios-17-or-later}

1. [iOS デバイス](https://proxyman.com/docs/ja/debug-devices/ios-device)または [iOS シミュレータ](https://proxyman.com/docs/ja/debug-devices/ios-simulator) のセットアップガイドに従ってください。証明書がデバイスにインストールされ、信頼されていることを確認します。
2. Proxyman で **Tools** → **Proxy Settings** → **SOCKS Proxy Settings…** を開き、有効にします。ポート番号を控えておきます。
3. Proxyman のメインウィンドウのツールバーで、現在の IP アドレスを確認します。

![IP 192.168.64.4、Proxy Port 9090、Recording、macOS proxy と Network Extension のトグルが表示されている Proxyman のステータスポップオーバー](https://proxyman.com/docs/assets/proxyman-status-popover.jpg)

_Proxyman の現在の IP を確認_

4. アプリで SOCKS プロキシを設定します。スイッチなどで切り替えられるようにし、デバッグビルドでのみ有効にしてください。リリースビルドにはこの設定を含めないでください。

* NWConnection の場合

```swift
let parameters = webSocketURL.scheme == "wss" ? NWParameters.tls : NWParameters.tcp

let options = NWProtocolWebSocket.Options()
options.autoReplyPing = true

parameters.defaultProtocolStack.applicationProtocols.insert(options, at: 0)

if #available(iOS 17.0, *) {
    let socksv5Proxy = NWEndpoint.hostPort(host: "x.x.x.x", port: 8889) //  Please replace x.x.x.x with a real Proxyman IP
    let config = ProxyConfiguration.init(socksv5Proxy: socksv5Proxy)
    let context = NWParameters.PrivacyContext(description: "my socksv5Proxy")
    context.proxyConfigurations = [config]

    parameters.setPrivacyContext(context)
}

let connection = NWConnection(to: .url(webSocketURL), using: parameters)
connection.start(queue: .main)
```

* URLSession と URLSessionWebSocketTask の場合

```swift
private lazy var urlSession: URLSession = {
    let config = URLSessionConfiguration.default
    if #available(iOS 17.0, *) {
        let socksv5Proxy = NWEndpoint.hostPort(host: "x.x.x.x", port: 8889) //  Please replace x.x.x.x with a real Proxyman IP
        let proxyConfig = ProxyConfiguration.init(socksv5Proxy: socksv5Proxy)
        config.proxyConfigurations = [proxyConfig]
    }

    return URLSession(configuration: config, delegate: nil, delegateQueue: nil)
}()
```

5. 完了です ✅

![iOS シミュレータで URLSessionWebSocketTask を使うアプリの wss://echo.websocket.org の WebSocket メッセージを、Proxyman がキャプチャしている画面](https://proxyman.com/docs/assets/Screenshot%202024-11-29%20at%201.17.23%E2%80%AFPM.jpg)

_Proxyman で iOS の WebSocket をキャプチャ_

* クレジット：[**FranklinSamboni**](https://github.com/FranklinSamboni) **→** [https://github.com/ProxymanApp/Proxyman/issues/586#issuecomment-2125082129](https://github.com/ProxymanApp/Proxyman/issues/586#issuecomment-2125082129)
* チュートリアル：[iOS シミュレータや実機から WebSocket をインターセプトしてデバッグする方法](https://proxyman.com/posts/2019-10-18-WebSocket-Debugging)

### ✅ 解決策 2 {#-solution-2}

[Atlantis Framework](https://github.com/ProxymanApp/atlantis#features)（Proxyman 開発）を使うと、iOS の **URLSessionWebSocketTask** による WS/WSS 通信をキャプチャできます。

詳しくは [Atlantis の WS/WSS 通信ガイド](https://github.com/ProxymanApp/atlantis#wswss-traffic) をご覧ください。

## 4. Web ブラウザ（Chrome、Safari など）から WebSocket をキャプチャ {#4-capture-websockets-from-your-web-browser-chrome-safari-etc}

* Proxyman は、設定なしで Web ブラウザからの WS/WSS 通信をキャプチャできます。
* 使い方：Google Chrome を開く → WS/WSS 接続を行う Web サイトにアクセスする → Proxyman を開き、WebSocket のドメインを探す → Response パネルで、これらのドメインの **Enable SSL Proxying** をクリックする。ブラウザで Web サイトを再読み込みします。Proxyman が WS/WSS をキャプチャして復号します ✅

## 5. NodeJS、Golang、Python サーバーから WebSocket をキャプチャ {#5-capture-websocket-from-nodejs-golang-python-server}

* Proxyman は、NodeJS、Golang、Python、Ruby のサーバーからの WS/WSS 通信をキャプチャできます。
* 使い方：[automatic-setup.md](https://proxyman.com/docs/ja/automatic-setup/automatic-setup) に従い、Proxyman が開くターミナルでサーバーを起動 → WS/WSS 接続を行う → Proxyman が自動的にキャプチャして復号します ✅

## 6. localhost と本番環境の間で WebSocket をマップ {#6-map-websocket-from-localhost---production}

localhost と本番環境の間の WebSocket 通信もマップできます。詳しくは [Map Remote ツール](https://proxyman.com/docs/ja/advanced-features/map-remote#74-map-websocket-from-localhost-to-production) をご覧ください。

## 7. Scripting で WebSocket メッセージを変更 {#7-modify-websocket-messages-with-scripting}

macOS 版 Proxyman 26.2.0 以降、および Windows/Linux 版 Proxyman 26.1.0 以降では、数行の JavaScript で WebSocket メッセージをその場で変更できます。Scripting のルールで **Modify WebSocket Messages** にチェックを入れ、`onWebsocket()` を使って次のことができます：

* テキストまたはバイナリのメッセージを、両方向で編集する
* メッセージをドロップし、相手に届かないようにする
* クライアントまたはサーバーに新しいメッセージを送信する
* WebSocket を閉じて、アプリの再接続の動作をテストする

```javascript
function onWebsocket(context, url, request, response, message) {
  if (message.from === "server" && message.type === "text") {
    message.data = message.data.replace("staging.example.com", "api.example.com");
  }
  return message;
}
```

- [WebSocket メッセージを変更する](https://proxyman.com/docs/ja/scripting/modify-websocket-messages)

## 関連情報 {#learn-more}

* [Scripting で WebSocket メッセージを変更する方法](https://proxyman.com/posts/2026-10-23-modify-websocket-messages-with-scripting)
* [WebSocket をキャプチャして Protobuf メッセージをデコードする方法](https://proxyman.com/posts/how-to-capture-websocket-with-protobuf-message)
* [Proxyman と mitmproxy の比較：Protobuf の WebSocket メッセージをデコードする](https://proxyman.com/posts/2026-07-21-Proxyman-vs-mitmproxy-Protobuf-WebSocket)