網路代理

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 呼叫點都正確套用網路規則。
• 連線時檢查：在 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 dispatcher 路由涵蓋 fetch、以 undici 為基礎的用戶端，以及提供自身 undici dispatcher 的傳輸。
• global-agent 路由涵蓋 Node 核心 node:http 和 node:https 呼叫端，包括許多建構在 http.request、https.request、http.get 和 https.get 上的函式庫。受管理代理模式會強制使用該全域代理，因此明確的 Node HTTP agents 不會意外繞過操作員代理。

​

相關代理術語

• proxy.enabled / proxy.proxyUrl：OpenClaw 執行階段輸出的對外正向代理路由。本頁說明此功能。
• gateway.auth.mode: "trusted-proxy"：用於 Gateway 存取的輸入身分感知反向代理驗證。請參閱受信任代理驗證。
• openclaw proxy：用於開發與支援的本機除錯代理與擷取檢查器。請參閱 openclaw proxy。
• tools.web.fetch.useTrustedEnvProxy：選擇加入 web_fetch，讓操作員控制的 HTTP(S) env 代理解析 DNS，同時保留預設嚴格 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 Loopback 模式

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

• gateway-only（預設）：OpenClaw 會在作用中的 global-agent NO_PROXY 控制器中註冊 Gateway loopback authority，讓本機 Gateway WebSocket 流量可以直接連線。自訂 loopback Gateway 連接埠可以運作，因為作用中 Gateway URL 的主機與連接埠會被註冊。
• proxy：OpenClaw 不會註冊 Gateway loopback NO_PROXY authority，因此本機 Gateway 流量會透過受管理代理傳送。如果代理是遠端代理，它必須為 OpenClaw 主機的 loopback 服務提供特殊路由，例如將其對應到代理可連線的主機名稱、IP 或通道。標準遠端代理會從代理主機解析 127.0.0.1 和 localhost，而不是從 OpenClaw 主機解析。
• block：OpenClaw 會在開啟 socket 之前拒絕 loopback 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

​

代理需求

• 僅綁定到 loopback 或受信任的私人介面。
• 限制存取，讓只有 OpenClaw 程序、主機、容器或服務帳戶可以使用它。
• 自行解析目的地，並在 DNS 解析後封鎖目的地 IP。
• 在連線時同時對純 HTTP 請求與 HTTPS CONNECT 通道套用政策。
• 拒絕針對 loopback、私人、link-local、中繼資料、多播、保留或文件範圍的目的地繞過。
• 避免使用主機名稱允許清單，除非你完全信任 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 用戶端的涵蓋範圍，但它不是作業系統層級的網路沙盒。
• Gateway 回環控制平面流量預設會透過 proxy.loopbackMode: "gateway-only" 直接本機旁路。OpenClaw 會在受管理的 global-agent NO_PROXY 控制器中註冊作用中的 Gateway 回環 authority，以實作該旁路。操作員可以設定 proxy.loopbackMode: "proxy"，將 Gateway 回環流量透過受管理代理傳送，或設定 proxy.loopbackMode: "block"，拒絕回環 Gateway 連線。請參閱 Gateway 回環模式 了解遠端代理注意事項。
• 原始 net、tls 和 http2 socket、原生附加元件，以及非 OpenClaw 子程序，除非繼承並遵循代理環境變數，否則可能會繞過 Node 層級的代理路由。Fork 出來的 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 不會檢查、測試或認證你的代理政策。
• 請將代理政策變更視為安全敏感的營運變更。