Proxy mạng

Documentation Index

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

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

​

Vì sao dùng proxy

• Chính sách tập trung: duy trì một chính sách lưu lượng đi ra thay vì phụ thuộc vào việc mọi điểm gọi HTTP của ứng dụng đều cấu hình đúng quy tắc mạng.
• Kiểm tra lúc kết nối: đánh giá đích sau khi phân giải DNS và ngay trước khi proxy mở kết nối upstream.
• Phòng vệ chống DNS rebinding: giảm khoảng cách giữa kiểm tra DNS ở cấp ứng dụng và kết nối đi ra thực tế.
• Phạm vi bao phủ JavaScript rộng hơn: định tuyến các client thông thường như fetch, node:http, node:https, WebSocket, axios, got, node-fetch và các client tương tự qua cùng một đường dẫn.
• Khả năng kiểm toán: ghi nhật ký các đích được cho phép và bị từ chối tại ranh giới lưu lượng đi ra.
• Kiểm soát vận hành: thực thi quy tắc đích, phân đoạn mạng, giới hạn tốc độ hoặc danh sách cho phép lưu lượng đi ra mà không cần build lại OpenClaw.

​

Cách OpenClaw định tuyến lưu lượng

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

• Định tuyến dispatcher của Undici bao phủ fetch, các client dựa trên undici và các transport cung cấp dispatcher undici riêng.
• Định tuyến global-agent bao phủ các bên gọi Node core node:http và node:https, bao gồm nhiều thư viện được xây trên http.request, https.request, http.get và https.get. Chế độ proxy được quản lý buộc dùng global agent đó để các agent HTTP Node rõ ràng không vô tình bỏ qua proxy của người vận hành.

​

Các thuật ngữ proxy liên quan

• proxy.enabled / proxy.proxyUrl: định tuyến proxy chuyển tiếp đi ra cho lưu lượng runtime của OpenClaw. Trang này ghi lại tính năng đó.
• gateway.auth.mode: "trusted-proxy": xác thực proxy ngược có nhận biết danh tính cho truy cập Gateway. Xem Xác thực proxy tin cậy.
• openclaw proxy: proxy gỡ lỗi cục bộ và trình kiểm tra capture cho phát triển và hỗ trợ. Xem openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy: tùy chọn bật cho web_fetch để cho phép proxy env HTTP(S) do người vận hành kiểm soát phân giải DNS trong khi vẫn giữ chính sách ghim DNS nghiêm ngặt mặc định và chính sách hostname. Xem Web fetch.
• Cài đặt proxy dành riêng cho kênh hoặc provider: các override thuộc sở hữu cụ thể cho một transport cụ thể. Ưu tiên proxy mạng được quản lý khi mục tiêu là kiểm soát lưu lượng đi ra tập trung trên toàn runtime.

​

Cấu hình

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

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

​

Chế độ local loopback Gateway

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

• gateway-only (mặc định): OpenClaw đăng ký authority loopback của Gateway trong bộ điều khiển NO_PROXY global-agent đang hoạt động để lưu lượng WebSocket Gateway cục bộ có thể kết nối trực tiếp. Các cổng Gateway loopback tùy chỉnh hoạt động vì host và cổng của URL Gateway đang hoạt động được đăng ký.
• proxy: OpenClaw không đăng ký authority NO_PROXY loopback Gateway, nên lưu lượng Gateway cục bộ được gửi qua proxy được quản lý. Nếu proxy ở xa, nó phải cung cấp định tuyến đặc biệt cho dịch vụ loopback của host OpenClaw, chẳng hạn ánh xạ nó tới một hostname, IP hoặc tunnel mà proxy có thể truy cập. Các proxy từ xa tiêu chuẩn phân giải 127.0.0.1 và localhost từ host proxy, không phải từ host OpenClaw.
• block: OpenClaw từ chối các kết nối control plane Gateway loopback trước khi mở socket.

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

​

Yêu cầu proxy

• Chỉ bind vào loopback hoặc một giao diện riêng tư đáng tin cậy.
• Hạn chế truy cập để chỉ tiến trình, host, container hoặc tài khoản dịch vụ OpenClaw có thể dùng nó.
• Tự phân giải các đích và chặn IP đích sau khi phân giải DNS.
• Áp dụng chính sách tại thời điểm kết nối cho cả yêu cầu HTTP thuần và tunnel HTTPS CONNECT.
• Từ chối các bypass dựa trên đích cho loopback, private, link-local, metadata, multicast, reserved hoặc các dải tài liệu.
• Tránh danh sách cho phép hostname trừ khi bạn hoàn toàn tin tưởng đường dẫn phân giải DNS.
• Ghi nhật ký đích, quyết định, trạng thái và lý do mà không ghi body yêu cầu, header ủy quyền, cookie hoặc các bí mật khác.
• Đặt chính sách proxy dưới kiểm soát phiên bản và review các thay đổi như cấu hình nhạy cảm về bảo mật.

​

Các đích bị chặn được khuyến nghị

​

Xác thực

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

​

Giới hạn

• Proxy cải thiện phạm vi bao phủ cho các máy khách HTTP và WebSocket JavaScript cục bộ trong tiến trình, nhưng nó không phải là sandbox mạng cấp hệ điều hành.
• Lưu lượng mặt phẳng điều khiển loopback Gateway mặc định đi trực tiếp qua bypass cục bộ bằng proxy.loopbackMode: "gateway-only". OpenClaw triển khai bypass đó bằng cách đăng ký authority loopback Gateway đang hoạt động trong bộ điều khiển NO_PROXY của global-agent được quản lý. Người vận hành có thể đặt proxy.loopbackMode: "proxy" để gửi lưu lượng loopback Gateway qua proxy được quản lý, hoặc proxy.loopbackMode: "block" để từ chối kết nối Gateway loopback. Xem Chế độ Loopback Gateway để biết lưu ý về proxy từ xa.
• Các socket net, tls, và http2 thô, addon native, và tiến trình con không thuộc OpenClaw có thể bypass định tuyến proxy cấp Node trừ khi chúng kế thừa và tôn trọng các biến môi trường proxy. Các CLI con OpenClaw được fork kế thừa URL proxy được quản lý và trạng thái proxy.loopbackMode.
• IRC là kênh TCP/TLS thô nằm ngoài định tuyến forward proxy do người vận hành quản lý. Trong các triển khai yêu cầu toàn bộ lưu lượng đi ra phải đi qua forward proxy đó, đặt channels.irc.enabled=false trừ khi lưu lượng IRC đi ra trực tiếp được phê duyệt rõ ràng.
• Proxy gỡ lỗi cục bộ là công cụ chẩn đoán và tính năng chuyển tiếp upstream trực tiếp của nó cho các yêu cầu proxy và đường hầm CONNECT bị tắt theo mặc định khi chế độ proxy được quản lý đang hoạt động; chỉ bật chuyển tiếp trực tiếp cho chẩn đoán cục bộ đã được phê duyệt.
• WebUI cục bộ của người dùng và máy chủ mô hình cục bộ nên được đưa vào allowlist trong chính sách proxy của người vận hành khi cần; OpenClaw không cung cấp bypass mạng cục bộ chung cho chúng.
• Bypass proxy mặt phẳng điều khiển Gateway được cố ý giới hạn ở localhost và các URL IP loopback dạng literal. Dùng ws://127.0.0.1:18789, ws://[::1]:18789, hoặc ws://localhost:18789 cho các kết nối mặt phẳng điều khiển Gateway trực tiếp cục bộ; các hostname khác định tuyến như lưu lượng dựa trên hostname thông thường.
• OpenClaw không kiểm tra, kiểm thử, hoặc chứng nhận chính sách proxy của bạn.
• Hãy xem thay đổi chính sách proxy là thay đổi vận hành nhạy cảm về bảo mật.