openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2543340e26
docs/docs/id/security/network-proxy.md
openclaw-docs-i18n[bot] 2543340e26 chore(i18n): refresh id translations
2026-05-04 18:25:46 +00:00

16 KiB
Raw Blame History

read_when summary title x-i18n
Anda menginginkan pertahanan berlapis terhadap serangan SSRF dan pengikatan ulang DNS
Mengonfigurasi proksi penerusan eksternal untuk lalu lintas waktu proses OpenClaw
Cara merutekan lalu lintas HTTP dan WebSocket runtime OpenClaw melalui proksi pemfilteran yang dikelola operator Proksi jaringan
generated_at model provider source_hash source_path workflow
2026-05-04T18:24:26Z gpt-5.5 openai eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b security/network-proxy.md 16

Proksi Jaringan

OpenClaw dapat merutekan lalu lintas HTTP dan WebSocket runtime melalui proksi penerusan yang dikelola operator. Ini adalah pertahanan berlapis opsional untuk deployment yang menginginkan kontrol egress terpusat, perlindungan SSRF yang lebih kuat, dan auditabilitas jaringan yang lebih baik.

OpenClaw tidak menyertakan, mengunduh, memulai, mengonfigurasi, atau menyertifikasi proksi. Anda menjalankan teknologi proksi yang sesuai dengan lingkungan Anda, dan OpenClaw merutekan klien HTTP dan WebSocket lokal proses yang normal melaluinya.

Mengapa Menggunakan Proksi?

Proksi memberi operator satu titik kontrol jaringan untuk lalu lintas HTTP dan WebSocket keluar. Itu dapat berguna bahkan di luar pengerasan SSRF:

  • Kebijakan terpusat: kelola satu kebijakan egress alih-alih bergantung pada setiap lokasi panggilan HTTP aplikasi untuk menerapkan aturan jaringan dengan benar.
  • Pemeriksaan saat koneksi: evaluasi tujuan setelah resolusi DNS dan tepat sebelum proksi membuka koneksi upstream.
  • Pertahanan terhadap 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.

Perutean proksi adalah guardrail tingkat proses untuk egress HTTP dan WebSocket normal. Ini memberi operator jalur gagal-tertutup untuk merutekan klien HTTP JavaScript yang didukung melalui proksi pemfilteran mereka sendiri, tetapi ini bukan sandbox jaringan tingkat OS dan tidak membuat OpenClaw menyertifikasi kebijakan tujuan proksi.

Cara OpenClaw Merutekan Lalu Lintas

Ketika proxy.enabled=true dan URL proksi dikonfigurasi, proses runtime yang dilindungi seperti openclaw gateway run, openclaw node run, dan openclaw agent --local merutekan egress HTTP dan WebSocket normal melalui proksi yang dikonfigurasi:

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

Kontrak publiknya adalah perilaku perutean, bukan hook Node internal yang digunakan untuk mengimplementasikannya. Klien WebSocket control-plane OpenClaw Gateway menggunakan jalur langsung yang sempit untuk lalu lintas RPC Gateway local loopback saat URL Gateway menggunakan localhost atau IP loopback literal seperti 127.0.0.1 atau [::1]. Jalur control-plane itu harus dapat menjangkau Gateway loopback bahkan ketika proksi operator memblokir tujuan loopback. Permintaan HTTP dan WebSocket runtime normal tetap menggunakan proksi yang dikonfigurasi.

Secara internal, OpenClaw menggunakan dua hook perutean tingkat proses untuk fitur ini:

  • Perutean dispatcher Undici mencakup fetch, klien berbasis undici, dan transport yang menyediakan dispatcher undici mereka sendiri.
  • Perutean global-agent mencakup pemanggil Node core 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 agent global itu agar agent HTTP Node eksplisit tidak secara tidak sengaja melewati proksi operator.

Beberapa Plugin memiliki transport kustom yang memerlukan penyambungan proksi eksplisit bahkan ketika perutean tingkat proses sudah ada. Misalnya, transport Bot API Telegram menggunakan dispatcher undici HTTP/1 miliknya sendiri sehingga menghormati env proksi proses plus fallback OPENCLAW_PROXY_URL terkelola di jalur transport khusus pemilik tersebut.

URL proksi itu sendiri harus menggunakan http://. Tujuan HTTPS tetap didukung melalui proksi dengan HTTP CONNECT; ini hanya berarti OpenClaw mengharapkan listener proksi penerusan HTTP biasa seperti http://127.0.0.1:3128.

Saat proksi aktif, OpenClaw mengosongkan no_proxy, NO_PROXY, dan GLOBAL_AGENT_NO_PROXY. Daftar bypass tersebut berbasis tujuan, sehingga membiarkan localhost atau 127.0.0.1 di sana akan memungkinkan target SSRF berisiko tinggi melewati proksi pemfilteran.

Saat shutdown, OpenClaw memulihkan lingkungan proksi sebelumnya dan mereset status perutean proses yang di-cache.

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 proksi balik sadar identitas masuk untuk akses Gateway. Lihat Autentikasi proksi tepercaya.
  • openclaw proxy: proksi debug lokal dan pemeriksa capture untuk pengembangan dan dukungan. Lihat openclaw proxy.
  • Pengaturan proksi khusus saluran atau penyedia: override khusus pemilik untuk transport tertentu. Utamakan proksi jaringan terkelola saat tujuannya adalah kontrol egress terpusat di seluruh runtime.

Konfigurasi

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

Anda juga dapat menyediakan URL melalui lingkungan, sambil tetap mempertahankan proxy.enabled=true dalam konfigurasi:

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

proxy.proxyUrl lebih diprioritaskan daripada OPENCLAW_PROXY_URL.

Jika enabled=true tetapi tidak ada URL proksi valid yang dikonfigurasi, perintah yang dilindungi akan gagal saat startup alih-alih kembali ke akses jaringan langsung.

Untuk layanan gateway terkelola yang dimulai dengan openclaw gateway start, sebaiknya simpan URL dalam konfigurasi:

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

Fallback lingkungan paling cocok untuk proses foreground. Jika Anda menggunakannya dengan layanan terpasang, letakkan OPENCLAW_PROXY_URL di lingkungan tahan lama layanan, seperti $OPENCLAW_STATE_DIR/.env atau ~/.openclaw/.env, lalu pasang ulang layanan agar launchd, systemd, atau Scheduled Tasks memulai gateway dengan nilai tersebut.

Untuk perintah openclaw --container ..., OpenClaw meneruskan OPENCLAW_PROXY_URL ke CLI turunan yang ditargetkan ke kontainer saat nilai itu disetel. URL harus dapat dijangkau dari dalam kontainer; 127.0.0.1 merujuk ke kontainer itu sendiri, bukan host. OpenClaw menolak URL proksi loopback untuk perintah yang ditargetkan ke kontainer kecuali Anda secara eksplisit mengganti pemeriksaan keamanan tersebut.

Persyaratan Proksi

Kebijakan proksi adalah batas keamanan. OpenClaw tidak dapat memverifikasi bahwa proksi memblokir target yang tepat.

Konfigurasikan proksi untuk:

  • Hanya bind ke loopback atau antarmuka privat tepercaya.
  • Membatasi akses sehingga hanya proses, host, kontainer, atau akun layanan OpenClaw yang dapat menggunakannya.
  • Meresolusi tujuan sendiri dan memblokir IP tujuan setelah resolusi DNS.
  • Menerapkan kebijakan pada saat koneksi untuk permintaan HTTP biasa dan tunnel HTTPS CONNECT.
  • Menolak bypass berbasis tujuan untuk rentang loopback, privat, link-local, metadata, multicast, reserved, atau dokumentasi.
  • Menghindari allowlist nama host kecuali Anda sepenuhnya memercayai jalur resolusi DNS.
  • Mencatat tujuan, keputusan, status, dan alasan tanpa mencatat body permintaan, header otorisasi, cookie, atau rahasia lainnya.
  • Menyimpan kebijakan proksi di bawah kontrol versi dan meninjau perubahan seperti konfigurasi yang sensitif terhadap keamanan.

Tujuan yang Direkomendasikan untuk Diblokir

Gunakan denylist ini sebagai titik awal untuk setiap proksi penerusan, firewall, atau kebijakan egress.

Logika classifier tingkat aplikasi OpenClaw berada di src/infra/net/ssrf.ts dan src/shared/net/ip.ts. Hook paritas yang relevan adalah BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, RFC2544_BENCHMARK_PREFIX, dan penanganan sentinel IPv4 tertanam untuk bentuk NAT64, 6to4, Teredo, ISATAP, dan IPv4-mapped. File-file tersebut adalah referensi berguna saat memelihara kebijakan proksi eksternal, tetapi OpenClaw tidak otomatis mengekspor atau menerapkan aturan tersebut di proksi Anda.

Rentang atau host Alasan untuk memblokir
127.0.0.0/8, localhost, localhost.localdomain Loopback IPv4
::1/128 Loopback IPv6
0.0.0.0/8, ::/128 Alamat tidak ditentukan dan jaringan-ini
10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 Jaringan privat RFC1918
169.254.0.0/16, fe80::/10 Alamat link-local dan jalur metadata cloud umum
169.254.169.254, metadata.google.internal Layanan metadata cloud
100.64.0.0/10 Ruang alamat bersama NAT carrier-grade
198.18.0.0/15, 2001:2::/48 Rentang benchmarking
192.0.0.0/24, 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32 Rentang penggunaan khusus dan dokumentasi
224.0.0.0/4, ff00::/8 Multicast
240.0.0.0/4 IPv4 reserved
fc00::/7, fec0::/10 Rentang lokal/privat IPv6
100::/64, 2001:20::/28 Rentang discard IPv6 dan ORCHIDv2
64:ff9b::/96, 64:ff9b:1::/48 Prefiks NAT64 dengan IPv4 tertanam
2002::/16, 2001::/32 6to4 dan Teredo dengan IPv4 tertanam
::/96, ::ffff:0:0/96 IPv6 kompatibel IPv4 dan IPv6 IPv4-mapped

Jika penyedia cloud atau platform jaringan Anda mendokumentasikan host metadata atau rentang reserved tambahan, tambahkan juga.

Validasi

Validasikan proksi dari host, kontainer, atau akun layanan yang sama yang menjalankan OpenClaw:

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

Secara default, ketika tidak ada tujuan kustom yang disediakan, perintah memeriksa bahwa https://example.com/ berhasil dan memulai canary loopback sementara yang tidak boleh dijangkau proksi. Pemeriksaan ditolak default lulus ketika proksi mengembalikan respons penolakan non-2xx atau memblokir canary dengan kegagalan transport; pemeriksaan gagal jika respons berhasil mencapai canary. Jika tidak ada proksi yang diaktifkan dan dikonfigurasi, validasi melaporkan masalah konfigurasi; gunakan --proxy-url untuk preflight sekali jalan sebelum mengubah konfigurasi. Gunakan --allowed-url dan --denied-url untuk menguji ekspektasi khusus deployment. Tambahkan --apns-reachable untuk juga memverifikasi bahwa pengiriman HTTP/2 APNs langsung dapat membuka tunnel CONNECT melalui proksi dan menerima respons APNs sandbox; probe menggunakan token penyedia yang sengaja tidak valid, sehingga 403 InvalidProviderToken diharapkan dan dihitung sebagai dapat dijangkau. Tujuan ditolak kustom bersifat gagal-tertutup: respons HTTP apa pun berarti tujuan dapat dijangkau melalui proksi, dan setiap error transport dilaporkan sebagai tidak meyakinkan karena OpenClaw tidak dapat membuktikan proksi memblokir origin yang dapat dijangkau. Pada kegagalan validasi, perintah keluar dengan kode 1.

Gunakan --json untuk otomatisasi. Output JSON berisi hasil keseluruhan, sumber konfigurasi proksi efektif, setiap error konfigurasi, dan setiap pemeriksaan tujuan. Kredensial URL proksi disensor dalam output teks dan JSON:

{
  "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
    }
  ]
}

Anda juga dapat memvalidasi secara manual dengan curl:

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/

Permintaan publik seharusnya berhasil. Permintaan loopback dan metadata seharusnya diblokir oleh proxy. Untuk openclaw proxy validate, canary loopback bawaan dapat membedakan penolakan proxy dari origin yang dapat dijangkau. Pemeriksaan --denied-url khusus tidak memiliki canary tersebut, jadi perlakukan baik respons HTTP maupun kegagalan transport yang ambigu sebagai kegagalan validasi kecuali proxy Anda mengekspos sinyal penolakan khusus penerapan yang dapat Anda verifikasi secara terpisah.

Lalu aktifkan perutean proxy OpenClaw:

openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run

atau atur:

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

Batasan

  • Proxy meningkatkan cakupan untuk klien HTTP JavaScript dan WebSocket lokal proses, tetapi ini bukan sandbox jaringan tingkat OS.
  • Soket mentah net, tls, dan http2, addon native, serta proses anak dapat melewati perutean proxy tingkat Node kecuali mereka mewarisi dan mematuhi variabel lingkungan proxy.
  • IRC adalah kanal TCP/TLS mentah di luar perutean proxy maju yang dikelola operator. Dalam deployment yang mengharuskan semua egress melalui proxy maju tersebut, atur 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 sebaiknya dimasukkan ke daftar izin dalam kebijakan proxy operator saat 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 langsung lokal; nama host lain dirutekan seperti lalu lintas berbasis nama host biasa.
  • OpenClaw tidak memeriksa, menguji, atau mensertifikasi kebijakan proxy Anda.
  • Perlakukan perubahan kebijakan proxy sebagai perubahan operasional yang sensitif terhadap keamanan.