ネットワークプロキシ

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

プロキシを使う理由

• 中央ポリシー: すべてのアプリケーション HTTP 呼び出し箇所がネットワークルールを正しく扱うことに依存せず、1 つのアウトバウンドポリシーを維持できます。
• 接続時チェック: DNS 解決後、プロキシが上流接続を開く直前に宛先を評価します。
• DNS リバインディング防御: アプリケーションレベルの DNS チェックと実際のアウトバウンド接続の間の隙間を減らします。
• より広い JavaScript カバレッジ: 通常の fetch、node:http、node:https、WebSocket、axios、got、node-fetch、および類似のクライアントを同じ経路にルーティングします。
• 監査性: アウトバウンド境界で許可および拒否された宛先をログに記録します。
• 運用制御: OpenClaw を再ビルドせずに、宛先ルール、ネットワーク分離、レート制限、またはアウトバウンド許可リストを適用できます。

​

OpenClaw がトラフィックをルーティングする方法

OpenClaw process
  fetch                  -> operator-managed filtering proxy -> public internet
  node:http and https    -> operator-managed filtering proxy -> public internet
  WebSocket clients      -> operator-managed filtering proxy -> public internet

• Undici ディスパッチャールーティングは、fetch、undici ベースのクライアント、および独自の undici ディスパッチャーを提供するトランスポートを対象にします。
• global-agent ルーティングは、http.request、https.request、http.get、https.get の上に重ねられた多くのライブラリを含む、Node コアの node:http および node:https 呼び出し元を対象にします。管理プロキシモードではそのグローバルエージェントを強制するため、明示的な Node HTTP エージェントがオペレータープロキシを誤って迂回することはありません。

​

関連するプロキシ用語

• proxy.enabled / proxy.proxyUrl: OpenClaw ランタイムアウトバウンド向けのアウトバウンドフォワードプロキシルーティング。このページはその機能を説明します。
• gateway.auth.mode: "trusted-proxy": Gateway アクセス向けのインバウンド identity-aware リバースプロキシ認証。信頼済みプロキシ認証を参照してください。
• openclaw proxy: 開発およびサポート向けのローカルデバッグプロキシとキャプチャインスペクター。openclaw proxyを参照してください。
• tools.web.fetch.useTrustedEnvProxy: デフォルトの厳密な DNS ピン留めとホスト名ポリシーを維持しながら、web_fetch がオペレーター制御の HTTP(S) 環境プロキシに DNS 解決を任せられるようにするオプトイン。Web fetchを参照してください。
• チャネルまたはプロバイダー固有のプロキシ設定: 特定のトランスポート向けの所有者固有の上書き。目的がランタイム全体の中央集権的なアウトバウンド制御である場合は、管理対象ネットワークプロキシを優先してください。

​

設定

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

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

​

Gateway ループバックモード

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

• gateway-only (デフォルト): OpenClaw は Gateway ループバック authority をアクティブな global-agent NO_PROXY コントローラーに登録し、ローカル Gateway WebSocket トラフィックが直接接続できるようにします。アクティブな Gateway URL のホストとポートが登録されるため、カスタムループバック Gateway ポートも機能します。
• proxy: OpenClaw は Gateway ループバック NO_PROXY authority を登録しないため、ローカル Gateway トラフィックは管理プロキシ経由で送信されます。プロキシがリモートにある場合、OpenClaw ホストのループバックサービスへの特別なルーティングを提供する必要があります。たとえば、プロキシから到達可能なホスト名、IP、またはトンネルにマッピングします。標準的なリモートプロキシは、127.0.0.1 と localhost を OpenClaw ホストからではなくプロキシホストから解決します。
• block: OpenClaw は、ソケットを開く前にループバック Gateway コントロールプレーン接続を拒否します。

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

​

プロキシ要件

• ループバックまたはプライベートな信頼済みインターフェイスのみにバインドします。
• OpenClaw プロセス、ホスト、コンテナー、またはサービスアカウントだけが使用できるようにアクセスを制限します。
• 宛先をプロキシ自身で解決し、DNS 解決後に宛先 IP をブロックします。
• プレーン HTTP リクエストと HTTPS CONNECT トンネルの両方について、接続時にポリシーを適用します。
• ループバック、プライベート、リンクローカル、メタデータ、マルチキャスト、予約済み、またはドキュメント用範囲に対する宛先ベースの迂回を拒否します。
• DNS 解決経路を完全に信頼していない限り、ホスト名許可リストは避けます。
• リクエスト本文、認可ヘッダー、Cookie、その他のシークレットをログに記録せずに、宛先、判断、ステータス、理由をログに記録します。
• プロキシポリシーをバージョン管理下に置き、セキュリティ上重要な設定と同様に変更をレビューします。

​

推奨されるブロック対象宛先

​

検証

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

{
  "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 -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 config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run

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

​

制限

• プロキシは、プロセスローカルの JavaScript HTTP および WebSocket クライアントのカバレッジを向上させますが、OS レベルのネットワークサンドボックスではありません。
• Gateway ループバック制御プレーントラフィックは、デフォルトで proxy.loopbackMode: "gateway-only" による直接ローカルバイパスになります。OpenClaw は、アクティブな Gateway ループバック authority を管理対象の global-agent NO_PROXY コントローラーに登録することで、このバイパスを実装します。運用者は proxy.loopbackMode: "proxy" を設定して Gateway ループバックトラフィックを管理対象プロキシ経由で送信するか、proxy.loopbackMode: "block" を設定してループバック Gateway 接続を拒否できます。リモートプロキシの注意点については、Gateway ループバックモード を参照してください。
• 生の net、tls、http2 ソケット、ネイティブアドオン、および OpenClaw 以外の子プロセスは、プロキシ環境変数を継承して尊重しない限り、Node レベルのプロキシルーティングをバイパスする可能性があります。フォークされた OpenClaw 子 CLI は、管理対象プロキシ URL と proxy.loopbackMode 状態を継承します。
• IRC は、運用者が管理するフォワードプロキシルーティングの外側にある生の TCP/TLS チャンネルです。すべての外向き通信をそのフォワードプロキシ経由にする必要があるデプロイでは、直接 IRC 外向き通信が明示的に承認されていない限り、channels.irc.enabled=false を設定してください。
• ローカルデバッグプロキシは診断ツールであり、プロキシリクエストと CONNECT トンネルの直接アップストリーム転送は、管理対象プロキシモードがアクティブな間はデフォルトで無効です。承認済みのローカル診断の場合にのみ、直接転送を有効にしてください。
• ユーザーのローカル WebUI とローカルモデルサーバーは、必要に応じて運用者のプロキシポリシーで許可リストに追加する必要があります。OpenClaw はそれらに対する一般的なローカルネットワークバイパスを公開しません。
• Gateway 制御プレーンのプロキシバイパスは、意図的に localhost とリテラルのループバック IP URL に限定されています。ローカル直接 Gateway 制御プレーン接続には、ws://127.0.0.1:18789、ws://[::1]:18789、または ws://localhost:18789 を使用してください。その他のホスト名は、通常のホスト名ベースのトラフィックと同様にルーティングされます。
• OpenClaw は、プロキシポリシーを検査、テスト、または認証しません。
• プロキシポリシーの変更は、セキュリティ上重要な運用変更として扱ってください。