ネットワークプロキシ

OpenClaw は、実行時の HTTP および WebSocket トラフィックを、運用者が管理するフォワードプロキシ経由でルーティングできます。これは任意の多層防御であり、ネットワーク境界での一元的な外向き通信制御、より強力な SSRF 防御、送信先の監査可能性を提供します。プロキシは DNS 解決後、上流接続を開く直前の接続時に送信先を評価するため、アプリケーションレベルで先に行われる DNS チェックと実際の外向き接続との間に生じ、DNS リバインディング攻撃が利用する隙も狭めます。また、単一のプロキシポリシーにより、OpenClaw を再ビルドせずに送信先ルール、ネットワークセグメンテーション、レート制限、外向き通信の許可リストを適用する場所を運用者向けに一元化できます。

OpenClaw はプロキシの同梱、ダウンロード、起動、設定、認証を行いません。環境に適したプロキシ技術をユーザーが運用し、OpenClaw は自身の HTTP および WebSocket クライアントをそのプロキシ経由でルーティングします。

設定

proxy:  enabled: true  proxyUrl: http://127.0.0.1:3128

設定で proxy.enabled: true を維持したまま、環境変数で URL を指定することもできます。

OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run

proxy.proxyUrl は OPENCLAW_PROXY_URL より優先されます。proxy.enabled が true でも有効な URL を解決できない場合、保護対象のコマンドは直接ネットワークアクセスへフォールバックせず、起動に失敗します。

管理対象の Gateway サービスでは、フォアグラウンド環境変数に依存せず再インストール後も維持されるよう、URL を設定に保存します。

openclaw config set proxy.enabled trueopenclaw config set proxy.proxyUrl http://127.0.0.1:3128openclaw gateway install --forceopenclaw gateway start

OPENCLAW_PROXY_URL 環境変数によるフォールバックは、フォアグラウンド実行に最適です。インストール済みサービスで使用するには、サービスの永続的な環境（$OPENCLAW_STATE_DIR/.env、デフォルトは ~/.openclaw/.env）に設定し、launchd、systemd、または Scheduled Tasks が読み込むように再インストールします。

プライベート CA を使用する HTTPS プロキシエンドポイント

proxy:  enabled: true  proxyUrl: https://proxy.corp.example:8443  tls:    caFile: /etc/openclaw/proxy-ca.pem

proxy.tls.caFile は、プロキシエンドポイント自体の TLS 証明書を検証します。これは、送信先に対する MITM の信頼設定、クライアント証明書、プロキシの送信先ポリシーの代替ではありません。代わりに NODE_EXTRA_CA_CERTS を使用するのは、Node プロセス全体が起動時から追加の CA を信頼する必要がある場合（たとえば、すべての HTTPS 送信先証明書を再署名する企業向け TLS 検査システム）に限ってください。この変数はプロセス全体に適用され、Node の起動前に設定する必要があるため、OpenClaw は proxy.tls.caFile のように実行途中で適用できません。HTTPS プロキシエンドポイントを信頼するには proxy.tls.caFile を推奨します。プロセス全体ではなく、管理対象のプロキシルーティングに適用範囲が限定されるためです。

openclaw config set proxy.enabled trueopenclaw config set proxy.proxyUrl https://proxy.corp.example:8443openclaw config set proxy.tls.caFile /etc/openclaw/proxy-ca.pemopenclaw gateway run

ルーティングの仕組み

proxy.enabled: true と有効な URL が設定されている場合、保護対象の実行時プロセス（openclaw gateway run、openclaw node run、openclaw agent --local）は、通常の HTTP および WebSocket の外向き通信をプロキシ経由でルーティングします。

OpenClaw プロセス  fetch、node:http、node:https、WebSocket クライアント  -> 運用者のプロキシ -> 送信先

内部では、OpenClaw はプロセスレベルのルーティングランタイムとして Proxyline を導入します。これは fetch、undici ベースのクライアント、node:http/node:https、一般的な WebSocket クライアント、ヘルパーが作成する CONNECT トンネルを対象とし、呼び出し元が指定した Node HTTP エージェントを置き換えるため、明示的なエージェントを使用するクライアント（axios、got、node-fetch、および同様の Node エージェントベースのクライアントを含む）がプロキシを暗黙にバイパスすることはできません。

プロキシ URL のスキームは、最終送信先ではなく OpenClaw からプロキシまでの接続を表します。

• http://proxy.example:3128 — プロキシへの平文 TCP 接続。OpenClaw は、HTTPS 送信先向けの CONNECT を含む HTTP プロキシリクエストを送信します。
• https://proxy.example:8443 — OpenClaw はプロキシ自体への TLS 接続を開き（プロキシの証明書を検証）、そのセッション内で HTTP プロキシリクエストを送信します。

送信先の TLS はプロキシエンドポイントの TLS とは独立しています。HTTPS 送信先の場合、OpenClaw は常にプロキシに CONNECT トンネルを要求し、そのトンネル経由で送信先との TLS を開始します。

プロキシが有効な間、OpenClaw は no_proxy/NO_PROXY を消去します。これらのバイパスリストは送信先に基づくため、localhost や 127.0.0.1 を残すと、SSRF の標的がプロキシを完全に回避できてしまいます。シャットダウン時には、OpenClaw は以前のプロキシ環境を復元し、キャッシュされたルーティング状態をリセットします。

一部の Plugin は独自のトランスポートを所有しており、プロセスレベルのルーティングが有効でも個別のプロキシ設定が必要です。Telegram の Bot API クライアントは独自の HTTP/1 undici ディスパッチャーを使用し、プロセスのプロキシ環境変数と OPENCLAW_PROXY_URL フォールバックも個別に参照します。

Gateway のループバックモード

ローカルの Gateway コントロールプレーンクライアントは通常、ws://127.0.0.1:18789 などのループバック WebSocket に接続します。proxy.loopbackMode は、そのトラフィックが管理対象プロキシをバイパスするかどうかを制御します。

proxy:  enabled: true  proxyUrl: http://127.0.0.1:3128  loopbackMode: gateway-only # gateway-only、proxy、または block

Gateway コントロールプレーンのバイパスは、localhost とリテラルのループバック IP URL に限定されます。ws://127.0.0.1:18789、ws://[::1]:18789、または ws://localhost:18789 を使用してください。その他のホスト名は通常のトラフィックと同様にルーティングされます。

コンテナ

openclaw --container ... コマンドでは、OPENCLAW_PROXY_URL が設定されている場合、OpenClaw はそれをコンテナを対象とする子 CLI に転送します。URL はコンテナ内から到達可能である必要があります。コンテナ内の 127.0.0.1 はホストではなくコンテナ自体を指します。OpenClaw は、OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1 を設定して明示的にチェックを上書きしない限り、コンテナを対象とするコマンドでループバックプロキシ URL を拒否します。

関連するプロキシ用語

• proxy.enabled / proxy.proxyUrl — 実行時の外向き通信向けフォワードプロキシルーティング。このページで説明しています。
• gateway.auth.mode: "trusted-proxy" — Gateway アクセス向けの、受信側で ID を認識するリバースプロキシ認証。信頼済みプロキシ認証を参照してください。
• openclaw proxy — 開発およびサポート向けのローカルデバッグプロキシ兼キャプチャ検査ツール。openclaw proxyを参照してください。
• tools.web.fetch.useTrustedEnvProxy — 既定で厳格な DNS ピンニングとホスト名ポリシーを維持しながら、運用者が制御する HTTP(S) 環境プロキシによる DNS 解決を web_fetch に許可するオプトイン設定。Web フェッチを参照してください。
• チャネルまたはプロバイダー固有のプロキシ設定 — 1 つのトランスポート向けに所有者が定義する上書き設定。実行環境全体の外向き通信を一元管理するには、管理対象ネットワークプロキシを推奨します。

プロキシの検証

実際のセキュリティ境界はプロキシの送信先ポリシーです。OpenClaw は、プロキシが適切な標的をブロックしているか検証できません。次のように設定してください。

• OpenClaw のプロセス、ホスト、コンテナ、またはサービスアカウントからのみ到達可能な、ループバックまたは信頼済みのプライベートインターフェースだけにバインドします。
• 平文 HTTP と HTTPS の CONNECT トンネルの両方について、プロキシ自身が送信先を解決し、DNS 解決後の接続時に IP に基づいてブロックします。
• ループバック、プライベート、リンクローカル、メタデータ、マルチキャスト、予約済み、ドキュメント用の範囲に対する、送信先ベースのバイパスを拒否します。
• DNS 解決経路を完全に信頼できる場合を除き、ホスト名の許可リストは使用しないでください。
• 送信先、判定、ステータス、理由を記録します。リクエスト本文、認証ヘッダー、Cookie、その他のシークレットは決して記録しないでください。
• ポリシーをバージョン管理下に置き、変更をセキュリティ上重要なものとしてレビューします。

OpenClaw を実行するのと同じホスト、コンテナ、またはサービスアカウントから検証します。

openclaw proxy validate --proxy-url http://127.0.0.1:3128

プライベート CA を使用する HTTPS プロキシエンドポイントの場合：

openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem

proxy.enabled が true ではなく、--proxy-url も指定されていない場合、このコマンドは検証を行わずに設定上の問題を報告します。設定を変更する前に一度限りの事前確認を行うには、--proxy-url を指定してください。

--allowed-url/--denied-url を指定しない場合、既定では次の検査を行います。https://example.com/ への接続は成功する必要があり、プロキシが到達してはならない一時的なループバックカナリアサーバーへの接続はブロックされる必要があります。ループバック検査は、トランスポート障害が発生した場合、またはカナリアの実行ごとのトークンを含まない 2xx 以外の応答を受け取った場合に合格します。トークンを含まない 2xx 応答（カナリア以外からの予期しない成功）では失敗し、特に一致するトークンを含む応答では、プロキシが拒否すべきループバック宛先を実際に転送したことが証明されるため失敗します。カスタムの --denied-url ターゲットにはこのようなカナリアトークンがないため、フェイルクローズ方式で判定されます。HTTP 応答があれば到達可能（失敗）と見なし、トランスポートエラーはブロック済みの証明ではなく判定不能として報告します。これは、到達可能なオリジンをプロキシが拒否したのか、それとも別の問題が発生したのかを OpenClaw が確認できないためです。--apns-reachable は意図的に無効なプロバイダートークンを送信するため、403 InvalidProviderToken 応答はトンネルが Apple に到達した証明と見なされます。検証に一つでも失敗すると、コマンドは 1 で終了します。プロキシ URL の認証情報は、テキスト出力と JSON 出力の両方で伏せ字になります。

{  "ok": true,  "config": {    "enabled": true,    "proxyUrl": "http://127.0.0.1:3128/",    "source": "override",    "errors": []  },  "checks": [    { "kind": "allowed", "url": "https://example.com/", "ok": true, "status": 200 },    { "kind": "apns", "url": "https://api.sandbox.push.apple.com", "ok": true, "status": 403 }  ]}

手動での curl 検査（公開先へのリクエストは成功し、ループバックおよびメタデータへのリクエストはプロキシ自体によってブロックされる必要があります。curl だけでは、openclaw proxy validate の組み込みカナリアのように、プロキシによる拒否と到達不能なオリジンを区別できません）：

curl -x http://127.0.0.1:3128 https://example.com/curl -x http://127.0.0.1:3128 http://127.0.0.1/curl -x http://127.0.0.1:3128 http://169.254.169.254/

ブロックを推奨する宛先

フォワードプロキシ、ファイアウォール、または送信ポリシーで使用する拒否リストの初期例です。OpenClaw 独自の SSRF 分類器は src/infra/net/ssrf.ts および packages/net-policy/src/ip.ts にあります（BLOCKED_HOSTNAMES、BLOCKED_IPV4_SPECIAL_USE_RANGES、BLOCKED_IPV6_SPECIAL_USE_RANGES、RFC 2544 ベンチマークプレフィックス、および NAT64/6to4/Teredo/ISATAP/IPv4 マップ形式向けの埋め込み IPv4 処理）。これらは有用な参考情報ですが、OpenClaw が外部プロキシでこれらのルールをエクスポートまたは適用することはありません。

クラウドプロバイダーまたはネットワークプラットフォームの文書に記載されている追加のメタデータホストや予約済み範囲も追加してください。

制限事項

• これは JavaScript の HTTP/WebSocket クライアントを対象としたプロセスレベルの適用範囲であり、OS レベルのネットワークサンドボックスではありません。
• 生の net、tls、http2 ソケット、ネイティブアドオン、および OpenClaw 以外の子プロセスは、プロキシ環境変数を継承して遵守しない限り、Node レベルのルーティングを迂回する可能性があります。フォークされた OpenClaw の子 CLI は、管理対象プロキシ URL と proxy.loopbackMode の状態を継承します。
• ユーザーのローカル WebUI およびローカルモデルサーバーは、一般的なローカルネットワーク迂回の対象にはなりません。必要に応じて、運用者のプロキシポリシーで許可リストに追加してください。例外は、同梱されている Ollama メモリ埋め込みプロバイダーの保護された直接パスで、設定済みの baseUrl に含まれる正確なホストローカルのループバックオリジンに限定されます。LAN、tailnet、プライベートネットワーク、および公開 Ollama ホストは、引き続き管理対象プロキシを使用します。
• ローカルデバッグプロキシの直接アップストリーム転送（プロキシリクエストおよび CONNECT トンネル用）は、管理対象プロキシモードが有効な間は既定で無効です。承認済みのローカル診断に限って有効化してください。
• OpenClaw はプロキシポリシーの検査、テスト、または認証を行いません。プロキシポリシーの変更は、セキュリティ上重要な運用変更として扱ってください。