Proksi jaringan

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.

​

Mengapa menggunakan proksi

• Kebijakan terpusat: pertahankan satu kebijakan egress alih-alih mengandalkan setiap lokasi pemanggilan HTTP aplikasi untuk menerapkan aturan jaringan dengan benar.
• Pemeriksaan saat koneksi: evaluasi tujuan setelah resolusi DNS dan tepat sebelum proksi membuka koneksi upstream.
• Pertahanan DNS rebinding: kurangi celah antara pemeriksaan DNS tingkat aplikasi dan koneksi keluar yang sebenarnya.
• Cakupan JavaScript yang lebih luas: rutekan klien biasa seperti fetch, node:http, node:https, WebSocket, axios, got, node-fetch, dan klien serupa melalui jalur yang sama.
• Auditabilitas: catat tujuan yang diizinkan dan ditolak di batas egress.
• Kontrol operasional: terapkan aturan tujuan, segmentasi jaringan, batas laju, atau allowlist keluar tanpa membangun ulang OpenClaw.

​

Cara OpenClaw merutekan lalu lintas

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

• Perutean dispatcher Undici mencakup fetch, klien berbasis undici, dan transport yang menyediakan dispatcher undici mereka sendiri.
• Perutean global-agent mencakup pemanggil inti Node node:http dan node:https, termasuk banyak pustaka yang dibangun di atas http.request, https.request, http.get, dan https.get. Mode proksi terkelola memaksa agen global tersebut agar agen HTTP Node eksplisit tidak secara tidak sengaja melewati proksi operator.

​

Istilah proksi terkait

• proxy.enabled / proxy.proxyUrl: perutean proksi forward keluar untuk egress runtime OpenClaw. Halaman ini mendokumentasikan fitur tersebut.
• gateway.auth.mode: "trusted-proxy": autentikasi proksi balik sadar identitas masuk untuk akses Gateway. Lihat Autentikasi proksi tepercaya.
• openclaw proxy: proksi debug lokal dan pemeriksa tangkapan untuk pengembangan dan dukungan. Lihat openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy: opt-in untuk web_fetch agar proksi env HTTP(S) yang dikendalikan operator dapat meresolusi DNS sambil mempertahankan penyematan DNS ketat default dan kebijakan hostname. Lihat Web fetch.
• Pengaturan proksi khusus channel atau provider: override khusus pemilik untuk transport tertentu. Utamakan proksi jaringan terkelola ketika tujuannya adalah kontrol egress terpusat di seluruh runtime.

​

Konfigurasi

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

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

​

Mode Loopback Gateway

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

• gateway-only (default): OpenClaw mendaftarkan otoritas loopback Gateway dalam pengontrol NO_PROXY global-agent yang aktif sehingga lalu lintas WebSocket Gateway lokal dapat terhubung secara langsung. Port Gateway loopback kustom berfungsi karena host dan port URL Gateway aktif didaftarkan.
• proxy: OpenClaw tidak mendaftarkan otoritas NO_PROXY loopback Gateway, sehingga lalu lintas Gateway lokal dikirim melalui proksi terkelola. Jika proksi bersifat remote, proksi harus menyediakan perutean khusus untuk layanan loopback host OpenClaw, seperti memetakannya ke hostname, IP, atau tunnel yang dapat dijangkau proksi. Proksi remote standar meresolusi 127.0.0.1 dan localhost dari host proksi, bukan dari host OpenClaw.
• block: OpenClaw menolak koneksi control plane Gateway loopback sebelum membuka 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

​

Persyaratan Proksi

• Bind hanya ke loopback atau antarmuka privat tepercaya.
• Batasi akses sehingga hanya proses, host, container, atau akun layanan OpenClaw yang dapat menggunakannya.
• Meresolusi tujuan sendiri dan memblokir IP tujuan setelah resolusi DNS.
• Menerapkan kebijakan saat koneksi untuk permintaan HTTP biasa maupun tunnel HTTPS CONNECT.
• Menolak bypass berbasis tujuan untuk rentang loopback, privat, link-local, metadata, multicast, reserved, atau dokumentasi.
• Hindari allowlist hostname kecuali Anda sepenuhnya mempercayai jalur resolusi DNS.
• Catat tujuan, keputusan, status, dan alasan tanpa mencatat body permintaan, header otorisasi, cookie, atau rahasia lainnya.
• Simpan kebijakan proksi dalam version control dan tinjau perubahan seperti konfigurasi yang sensitif terhadap keamanan.

​

Tujuan yang direkomendasikan untuk diblokir

​

Validasi

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

​

Batasan

• Proxy meningkatkan cakupan untuk klien HTTP JavaScript dan WebSocket lokal proses, tetapi bukan sandbox jaringan tingkat OS.
• Trafik control-plane loopback Gateway secara default melewati langsung lokal melalui proxy.loopbackMode: "gateway-only". OpenClaw mengimplementasikan bypass tersebut dengan mendaftarkan otoritas loopback Gateway aktif di controller NO_PROXY global-agent terkelola. Operator dapat menetapkan proxy.loopbackMode: "proxy" untuk mengirim trafik loopback Gateway melalui proxy terkelola, atau proxy.loopbackMode: "block" untuk menolak koneksi Gateway loopback. Lihat Mode Loopback Gateway untuk catatan proxy jarak jauh.
• Soket net, tls, dan http2 mentah, addon native, dan proses anak non-OpenClaw dapat melewati perutean proxy tingkat Node kecuali mewarisi dan menghormati variabel lingkungan proxy. CLI anak OpenClaw yang di-fork mewarisi URL proxy terkelola dan status proxy.loopbackMode.
• IRC adalah channel TCP/TLS mentah di luar perutean forward proxy yang dikelola operator. Dalam deployment yang mengharuskan semua egress melalui forward proxy tersebut, tetapkan channels.irc.enabled=false kecuali egress IRC langsung disetujui secara eksplisit.
• Proxy debug lokal adalah alat diagnostik dan penerusan upstream langsungnya untuk permintaan proxy dan tunnel CONNECT dinonaktifkan secara default saat mode proxy terkelola aktif; aktifkan penerusan langsung hanya untuk diagnostik lokal yang disetujui.
• WebUI lokal pengguna dan server model lokal harus dimasukkan ke allowlist dalam kebijakan proxy operator bila diperlukan; OpenClaw tidak mengekspos bypass jaringan lokal umum untuk keduanya.
• Bypass proxy control-plane Gateway sengaja dibatasi ke URL localhost dan IP loopback literal. Gunakan ws://127.0.0.1:18789, ws://[::1]:18789, atau ws://localhost:18789 untuk koneksi control-plane Gateway lokal langsung; hostname lain dirutekan seperti trafik berbasis hostname biasa.
• OpenClaw tidak memeriksa, menguji, atau mensertifikasi kebijakan proxy Anda.
• Perlakukan perubahan kebijakan proxy sebagai perubahan operasional yang sensitif terhadap keamanan.