Proksi jaringan

​

Mengapa menggunakan proksi

• Kebijakan terpusat: pertahankan satu kebijakan egress alih-alih mengandalkan setiap call site 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 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

• http://proxy.example:3128: OpenClaw membuka koneksi TCP polos ke proksi penerusan dan mengirim permintaan proksi HTTP, termasuk CONNECT untuk tujuan HTTPS.
• https://proxy.example:8443: OpenClaw membuka TLS ke endpoint proksi, memverifikasi sertifikat proksi, lalu mengirim permintaan proksi HTTP di dalam sesi TLS tersebut.

​

Istilah proksi terkait

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

​

Konfigurasi

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

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

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 kebijakan bypass terkelola Proxyline sehingga lalu lintas WebSocket Gateway lokal dapat terhubung langsung. Port Gateway loopback kustom berfungsi karena host dan port URL Gateway aktif didaftarkan. Plugin browser bawaan juga dapat mendaftarkan endpoint kesiapan CDP lokal dan WebSocket DevTools yang persis untuk browser terkelola yang diluncurkan OpenClaw, dan provider embedding memori Ollama bawaan dapat menggunakan jalur langsung terjaga miliknya yang lebih sempit untuk origin embedding loopback host-lokal yang dikonfigurasi secara persis.
• proxy: OpenClaw tidak mendaftarkan bypass loopback Gateway atau Ollama, sehingga lalu lintas loopback tersebut dikirim melalui proksi terkelola. Jika proksi berada jarak jauh, proksi harus menyediakan perutean khusus untuk layanan loopback host OpenClaw, seperti memetakannya ke hostname, IP, atau tunnel yang dapat dijangkau proksi. Proksi jarak jauh standar menyelesaikan 127.0.0.1 dan localhost dari host proksi, bukan dari host OpenClaw.
• block: OpenClaw menolak koneksi control plane loopback Gateway dan koneksi loopback embedding host-lokal Ollama yang dijaga 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

• Mengikat hanya ke loopback atau antarmuka privat tepercaya.
• Membatasi akses sehingga hanya proses, host, kontainer, atau akun layanan OpenClaw yang dapat menggunakannya.
• Menyelesaikan tujuan sendiri dan memblokir IP tujuan setelah resolusi DNS.
• Menerapkan kebijakan saat koneksi untuk permintaan HTTP polos maupun tunnel HTTPS CONNECT.
• Menolak bypass berbasis tujuan untuk rentang loopback, privat, link-local, metadata, multicast, reserved, atau dokumentasi.
• Menghindari allowlist hostname kecuali Anda sepenuhnya memercayai jalur resolusi DNS.
• Mencatat tujuan, keputusan, status, dan alasan tanpa mencatat body permintaan, header otorisasi, cookie, atau secret lain.
• Menyimpan kebijakan proksi dalam version control dan meninjau perubahan seperti konfigurasi sensitif keamanan.

​

Tujuan yang direkomendasikan untuk diblokir

​

Validasi

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

openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem

{
  "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/

​

Kepercayaan CA proksi

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

openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl https://proxy.corp.example:8443
openclaw config set proxy.tls.caFile /etc/openclaw/proxy-ca.pem
openclaw gateway run

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

​

Batasan

• Proksi meningkatkan cakupan untuk klien HTTP JavaScript dan WebSocket lokal proses, tetapi ini bukan sandbox jaringan tingkat OS.
• Lalu lintas control-plane loopback Gateway secara default memakai bypass lokal langsung melalui proxy.loopbackMode: "gateway-only". OpenClaw menerapkan bypass itu dengan mendaftarkan otoritas loopback Gateway aktif dalam kebijakan bypass terkelola Proxyline. Operator dapat mengatur proxy.loopbackMode: "proxy" untuk mengirim lalu lintas loopback Gateway melalui proksi terkelola, atau proxy.loopbackMode: "block" untuk menolak koneksi Gateway loopback. Lihat Mode Loopback Gateway untuk catatan penting proksi jarak jauh.
• Socket mentah net, tls, dan http2, addon native, serta proses turunan non-OpenClaw dapat melewati routing proksi tingkat Node kecuali proses tersebut mewarisi dan mematuhi variabel lingkungan proksi. CLI turunan OpenClaw yang di-fork mewarisi URL proksi terkelola dan status proxy.loopbackMode.
• IRC adalah kanal TCP/TLS mentah di luar routing proksi forward yang dikelola operator. Dalam deployment yang mengharuskan semua egress melalui proksi forward tersebut, atur channels.irc.enabled=false kecuali egress IRC langsung disetujui secara eksplisit.
• Proksi debug lokal adalah tooling diagnostik dan penerusan upstream langsungnya untuk permintaan proksi serta tunnel CONNECT dinonaktifkan secara default saat mode proksi terkelola aktif; aktifkan penerusan langsung hanya untuk diagnostik lokal yang disetujui.
• WebUI lokal pengguna dan server model lokal harus dimasukkan ke allowlist dalam kebijakan proksi operator bila diperlukan; OpenClaw tidak mengekspos bypass jaringan lokal umum untuk keduanya. Penyedia embedding memori Ollama bawaan lebih sempit: penyedia ini dapat memakai jalur langsung yang dijaga hanya untuk origin embedding loopback lokal-host persis yang diturunkan dari baseUrl terkonfigurasi agar embedding lokal-host tetap berfungsi ketika proksi terkelola tidak dapat menjangkau loopback host. Host embedding Ollama LAN, tailnet, jaringan privat, dan publik tetap memakai jalur proksi terkelola. proxy.loopbackMode: "proxy" mengirim lalu lintas loopback Ollama ini melalui proksi terkelola, dan proxy.loopbackMode: "block" menolaknya sebelum membuka koneksi.
• Bypass proksi control-plane Gateway sengaja dibatasi ke localhost dan URL 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 lalu lintas berbasis hostname biasa.
• OpenClaw tidak menginspeksi, menguji, atau mensertifikasi kebijakan proksi Anda.
• Perlakukan perubahan kebijakan proksi sebagai perubahan operasional yang sensitif terhadap keamanan.