OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Security

ネットワークプロキシ

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

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

設定

yaml
proxy:  proxyUrl: http://127.0.0.1:3128

環境変数を使用して URL を設定することもできます。

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

proxy.proxyUrl は OPENCLAW_PROXY_URL より優先されます。URL を設定すると管理対象プロキシルーティングが有効になり、両方の URL を削除すると無効になります。

キー 型 デフォルト 注記
proxy.proxyUrl string 未設定 http:// または https:// フォワードプロキシ URL。URL に埋め込まれた認証情報は機密情報として扱われ、スナップショットやログでは秘匿されます。
proxy.tls.caFile string 未設定 プライベート CA によって署名された https:// プロキシエンドポイントを検証するための CA バンドル。
proxy.loopbackMode gateway-only | proxy | block gateway-only ループバックのバイパス動作を制御します。以下を参照してください。

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

bash
openclaw 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/スケジュールされたタスクが取得できるように再インストールします。

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

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

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

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

ルーティングの仕組み

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

text
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 は、そのトラフィックが管理対象プロキシをバイパスするかどうかを制御します。

yaml
proxy:  proxyUrl: http://127.0.0.1:3128  loopbackMode: gateway-only # gateway-only, proxy, or block

proxyUrl または OPENCLAW_PROXY_URL を設定すると、管理対象ルーティングが有効になります。URL を保存したまま有効化しない高度なオプトアウトとしてのみ、 proxy.enabled: false を設定してください。

モード 動作
gateway-only（デフォルト） OpenClaw は有効な Gateway ループバックオーソリティを直接接続の例外として登録するため、ローカル Gateway WebSocket トラフィックはプロキシを使用せずに接続します。この例外は設定された正確なホストとポートを対象とするため、カスタムループバックポートも機能します。同梱のブラウザー Plugin は、OpenClaw が起動した管理対象ブラウザーの正確なローカル CDP 準備確認 URL および DevTools WebSocket URL に対して、同じ種類の例外を登録します。同梱の Ollama メモリ埋め込みプロバイダーには、設定された正確なホストローカルのループバック埋め込みオリジンに対する、より限定的で保護された直接パスがあります。
proxy ループバックの例外は登録されません。Gateway および Ollama のループバックトラフィックはプロキシを経由します。リモートプロキシは、OpenClaw ホストのループバックサービスへ戻る経路を確保できる必要があります（たとえば、到達可能なホスト名、IP、またはトンネル経由）。標準的なリモートプロキシは、127.0.0.1/localhost を OpenClaw ホストではなく、プロキシ自身に対して解決します。
block OpenClaw は、ソケットを開く前に Gateway ループバックのコントロールプレーン接続と、保護された Ollama ループバック埋め込み接続を拒否します。

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 フェッチを参照してください。
  • チャンネルまたはプロバイダー固有のプロキシ設定 — 単一のトランスポートに対する所有者固有の上書き。ランタイム全体の外向き通信を一元管理するには、管理対象ネットワークプロキシを推奨します。

プロキシの検証

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

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

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

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

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

bash
openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem
フラグ 目的
--proxy-url <url> config/env を解決する代わりに、この URL を検証します。
--proxy-ca-file <path> HTTPS プロキシエンドポイント用の CA バンドル。
--allowed-url <url> 成功が期待される宛先（繰り返し指定可能）。
--denied-url <url> ブロックされることが期待される宛先（繰り返し指定可能）。
--apns-reachable プロキシがサンドボックス APNs への直接 HTTP/2 プローブもトンネリングできることを検証します。
--apns-authority <url> --apns-reachable でプローブする APNs オーソリティを上書きします。
--timeout-ms <ms> リクエストごとのタイムアウト。
--json 機械可読形式の出力。

config、環境、または --proxy-url の値が利用できない場合、コマンドは設定上の問題を報告します。設定を変更する前の一時的な事前チェックには --proxy-url を渡してください。

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

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

bash
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 は外部プロキシでこれらのルールをエクスポートまたは適用しません。

範囲またはホスト ブロックする理由
127.0.0.0/8, localhost, localhost.localdomain IPv4 loopback
::1/128 IPv6 loopback
0.0.0.0/8, ::/128 未指定アドレス／このネットワークのアドレス
10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 RFC 1918 プライベートネットワーク
169.254.0.0/16, fe80::/10 一般的なクラウドメタデータパスを含むリンクローカル
169.254.169.254, metadata.google.internal クラウドメタデータサービス
100.64.0.0/10 キャリアグレード NAT の共有アドレス空間
198.18.0.0/15, 2001:2::/48 ベンチマーク用の範囲
192.0.0.0/24, 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32 特殊用途および文書用の範囲
224.0.0.0/4, ff00::/8 マルチキャスト
240.0.0.0/4 予約済み IPv4
fc00::/7, fec0::/10 IPv6 ローカル／プライベート範囲
100::/64, 2001:20::/28 IPv6 破棄および ORCHIDv2 の範囲
64:ff9b::/96, 64:ff9b:1::/48 IPv4 が埋め込まれた NAT64 プレフィックス
2002::/16, 2001::/32 IPv4 が埋め込まれた 6to4 および Teredo
::/96, ::ffff:0:0/96 IPv4 互換および IPv4 マップ IPv6

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

制限

対象 マネージドプロキシの状態
fetch、node:http、node:https、一般的な WebSocket クライアント 設定されている場合、マネージドプロキシフックを通じてルーティングされます。
APNs への直接 HTTP/2 APNs のマネージド CONNECT ヘルパーを通じてルーティングされます。
Gateway コントロールプレーンの loopback 正確に設定されたローカル loopback Gateway URL に対してのみ直接接続します。
デバッグプロキシのアップストリーム転送 ローカル診断用に明示的に有効化されていない限り、マネージドプロキシモードの有効中は無効です。
IRC 生の TCP/TLS であり、マネージド HTTP プロキシモードではプロキシされません。デプロイですべての送信トラフィックをフォワードプロキシ経由にする必要がある場合は、channels.irc.enabled: false を設定してください。
その他の生の net、tls、または http2 クライアント呼び出し 導入前に生ソケットガードで分類する必要があります。
  • これは JavaScript の HTTP/WebSocket クライアントを対象とするプロセスレベルの保護であり、OS レベルのネットワークサンドボックスではありません。
  • 生の net、tls、http2 ソケット、ネイティブアドオン、および OpenClaw 以外の子プロセスは、プロキシ環境変数を継承して遵守しない限り、Node レベルのルーティングを迂回する場合があります。フォークされた OpenClaw の子 CLI は、マネージドプロキシ URL と proxy.loopbackMode の状態を継承します。
  • ユーザーのローカル WebUI とローカルモデルサーバーは、一般的なローカルネットワークのバイパス対象ではありません。必要に応じて、運用者のプロキシポリシーで許可リストに追加してください。例外は、同梱されている Ollama メモリ埋め込みプロバイダーの保護された直接パスで、設定済みの baseUrl に含まれる正確なホストローカル loopback オリジンに限定されます。LAN、tailnet、プライベートネットワーク、および公開 Ollama ホストでは、引き続きマネージドプロキシが使用されます。
  • ローカルデバッグプロキシによる直接のアップストリーム転送（プロキシリクエストおよび CONNECT トンネル用）は、マネージドプロキシモードの有効中はデフォルトで無効になります。承認済みのローカル診断にのみ有効化してください。
  • OpenClaw は、プロキシポリシーの検査、テスト、または認証を行いません。プロキシポリシーの変更は、セキュリティ上慎重な扱いを要する運用変更として扱ってください。
Was this useful?
On this page

On this page