Proksi jaringan

OpenClaw dapat merutekan lalu lintas HTTP dan WebSocket runtime melalui proksi penerusan yang dikelola operator. Ini merupakan pertahanan berlapis opsional: kontrol lalu lintas keluar terpusat, perlindungan SSRF yang lebih kuat, dan kemampuan audit tujuan pada batas jaringan. Karena proksi mengevaluasi tujuan pada saat koneksi, setelah resolusi DNS dan tepat sebelum membuka koneksi hulu, proksi juga mempersempit celah yang dimanfaatkan serangan pengikatan ulang DNS antara pemeriksaan DNS tingkat aplikasi sebelumnya dan koneksi keluar yang sebenarnya. Satu kebijakan proksi juga memberi operator satu tempat untuk menerapkan aturan tujuan, segmentasi jaringan, batas laju, atau daftar izin keluar tanpa membangun ulang OpenClaw.

OpenClaw tidak menyertakan, mengunduh, memulai, mengonfigurasi, atau menyertifikasi proksi. Anda menjalankan teknologi proksi yang sesuai dengan lingkungan Anda; OpenClaw merutekan klien HTTP dan WebSocket miliknya sendiri melalui proksi tersebut.

Konfigurasi

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

Anda juga dapat menetapkan URL melalui lingkungan selama proxy.enabled: true tetap berada dalam konfigurasi:

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

proxy.proxyUrl lebih diprioritaskan daripada OPENCLAW_PROXY_URL. Jika proxy.enabled bernilai true, tetapi tidak ada URL valid yang dapat ditentukan, perintah yang dilindungi gagal dimulai alih-alih beralih kembali ke akses jaringan langsung.

Untuk layanan Gateway terkelola, simpan URL dalam konfigurasi agar tetap tersedia setelah penginstalan ulang, alih-alih mengandalkan variabel lingkungan proses latar depan:

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

Penggunaan cadangan variabel lingkungan OPENCLAW_PROXY_URL paling sesuai untuk proses latar depan. Untuk menggunakannya dengan layanan yang telah diinstal, letakkan variabel tersebut dalam lingkungan persisten layanan ($OPENCLAW_STATE_DIR/.env, bawaan ~/.openclaw/.env), lalu instal ulang agar launchd/systemd/Scheduled Tasks mengambilnya.

Titik akhir proksi HTTPS dengan CA privat

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

proxy.tls.caFile memverifikasi sertifikat TLS milik titik akhir proksi. Ini bukan pengaturan kepercayaan MITM tujuan, sertifikat klien, atau pengganti kebijakan tujuan proksi. Gunakan NODE_EXTRA_CA_CERTS hanya ketika seluruh proses Node harus memercayai CA tambahan sejak dimulai (misalnya, sistem inspeksi TLS perusahaan yang menandatangani ulang setiap sertifikat tujuan HTTPS) — variabel tersebut berlaku untuk seluruh proses dan harus ditetapkan sebelum Node dimulai, sehingga OpenClaw tidak dapat menerapkannya saat proses berjalan seperti halnya proxy.tls.caFile. Utamakan proxy.tls.caFile untuk kepercayaan terhadap titik akhir proksi HTTPS: cakupannya terbatas pada perutean proksi terkelola, bukan seluruh proses.

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

Cara kerja perutean

Dengan proxy.enabled: true dan URL yang valid, proses runtime yang dilindungi (openclaw gateway run, openclaw node run, openclaw agent --local) merutekan lalu lintas keluar HTTP dan WebSocket biasa melalui proksi:

Proses OpenClaw  klien fetch, node:http, node:https, WebSocket  -> proksi operator -> tujuan

Secara internal, OpenClaw memasang Proxyline sebagai runtime perutean tingkat proses. Runtime ini mencakup fetch, klien berbasis undici, node:http/node:https, klien WebSocket umum, dan terowongan CONNECT yang dibuat oleh pembantu, serta mengganti agen HTTP Node yang disediakan pemanggil sehingga agen eksplisit (termasuk axios, got, node-fetch, dan klien serupa yang berbasis agen Node) tidak dapat melewati proksi secara diam-diam.

Skema URL proksi menjelaskan lintasan dari OpenClaw ke proksi, bukan ke tujuan akhir:

• http://proxy.example:3128 — TCP biasa ke proksi; OpenClaw mengirim permintaan proksi HTTP, termasuk CONNECT untuk tujuan HTTPS.
• https://proxy.example:8443 — OpenClaw membuka TLS ke proksi itu sendiri (dengan memverifikasi sertifikat proksi), lalu mengirim permintaan proksi HTTP di dalam sesi tersebut.

TLS tujuan tidak bergantung pada TLS titik akhir proksi: untuk tujuan HTTPS, OpenClaw selalu meminta terowongan CONNECT kepada proksi dan memulai TLS tujuan melalui terowongan tersebut.

Saat proksi aktif, OpenClaw menghapus no_proxy/NO_PROXY. Daftar pengabaian tersebut berbasis tujuan; membiarkan localhost atau 127.0.0.1 di dalamnya akan memungkinkan target SSRF melewati proksi sepenuhnya. Saat dimatikan, OpenClaw memulihkan lingkungan proksi sebelumnya dan mengatur ulang status perutean yang disimpan dalam cache.

Beberapa Plugin memiliki transportasi khusus yang memerlukan pengaturan proksi tersendiri meskipun perutean tingkat proses aktif. Klien Bot API Telegram menggunakan dispatcher undici HTTP/1 miliknya sendiri dan secara terpisah mematuhi variabel lingkungan proksi proses serta penggunaan cadangan OPENCLAW_PROXY_URL.

Mode loopback Gateway

Klien bidang kontrol Gateway lokal biasanya terhubung ke WebSocket loopback seperti ws://127.0.0.1:18789. proxy.loopbackMode mengontrol apakah lalu lintas tersebut melewati proksi terkelola:

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

Pengabaian bidang kontrol Gateway dibatasi pada localhost dan URL IP loopback literal — gunakan ws://127.0.0.1:18789, ws://[::1]:18789, atau ws://localhost:18789. Nama host lainnya dirutekan seperti lalu lintas biasa.

Kontainer

Untuk perintah openclaw --container ..., OpenClaw meneruskan OPENCLAW_PROXY_URL ke CLI anak yang ditargetkan ke kontainer ketika variabel tersebut ditetapkan. URL harus dapat dijangkau dari dalam kontainer — 127.0.0.1 di sana merujuk ke kontainer itu sendiri, bukan host. OpenClaw menolak URL proksi loopback untuk perintah yang ditargetkan ke kontainer kecuali Anda menetapkan OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1 untuk secara eksplisit mengesampingkan pemeriksaan tersebut.

Istilah proksi terkait

• proxy.enabled / proxy.proxyUrl — perutean proksi penerusan keluar untuk lalu lintas keluar runtime. Halaman ini.
• gateway.auth.mode: "trusted-proxy" — autentikasi proksi balik masuk yang sadar identitas 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 — keikutsertaan opsional bagi web_fetch untuk mengizinkan proksi lingkungan HTTP(S) yang dikontrol operator menentukan DNS sambil tetap mempertahankan penyematan DNS ketat dan kebijakan nama host secara bawaan. Lihat Pengambilan web.
• Pengaturan proksi khusus saluran atau penyedia — pengesampingan khusus pemilik untuk satu transportasi. Utamakan proksi jaringan terkelola untuk kontrol lalu lintas keluar terpusat di seluruh runtime.

Memvalidasi proksi

Kebijakan tujuan proksi merupakan batas keamanan yang sebenarnya; OpenClaw tidak dapat memverifikasi bahwa proksi Anda memblokir target yang tepat. Konfigurasikan proksi untuk:

• Mengikat hanya ke loopback atau antarmuka privat tepercaya yang hanya dapat dijangkau oleh proses/host/kontainer/akun layanan OpenClaw.
• Menentukan tujuan sendiri dan memblokir berdasarkan IP setelah resolusi DNS, pada saat koneksi, baik untuk HTTP biasa maupun terowongan CONNECT HTTPS.
• Menolak pengabaian berbasis tujuan untuk rentang loopback, privat, link-local, metadata, multicast, khusus, dan dokumentasi.
• Menghindari daftar izin nama host kecuali Anda sepenuhnya memercayai jalur resolusi DNS.
• Mencatat tujuan, keputusan, status, dan alasan — jangan pernah mencatat isi permintaan, header otorisasi, kuki, atau rahasia lainnya.
• Menyimpan kebijakan dalam kontrol versi dan meninjau perubahan sebagai hal yang sensitif terhadap keamanan.

Validasi dari host/kontainer/akun layanan yang sama dengan yang menjalankan OpenClaw:

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

Dengan titik akhir proksi HTTPS ber-CA privat:

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

Jika proxy.enabled bukan true dan tidak ada --proxy-url yang diberikan, perintah akan melaporkan masalah konfigurasi alih-alih melakukan validasi; berikan --proxy-url untuk pemeriksaan awal satu kali sebelum mengubah konfigurasi.

Tanpa --allowed-url/--denied-url, pemeriksaan bawaannya adalah: https://example.com/ harus berhasil, dan server kanari local loopback sementara yang tidak boleh dijangkau proxy harus diblokir. Pemeriksaan local loopback dinyatakan berhasil jika terjadi kegagalan transportasi, atau jika respons non-2xx tidak memiliki token per-eksekusi milik kanari; pemeriksaan dinyatakan gagal pada respons 2xx tanpa token tersebut (keberhasilan tak terduga dari sesuatu selain kanari) dan, terutama, pada respons apa pun yang membawa token yang cocok, karena hal itu membuktikan bahwa proxy benar-benar meneruskan tujuan local loopback yang seharusnya ditolak. Target --denied-url khusus tidak memiliki token kanari seperti itu, sehingga target tersebut bersifat gagal-tertutup: respons HTTP apa pun dianggap dapat dijangkau (gagal), dan kesalahan transportasi dilaporkan sebagai tidak meyakinkan, bukan terbukti diblokir, karena OpenClaw tidak dapat memastikan apakah proxy Anda menolak asal yang dapat dijangkau atau ada hal lain yang bermasalah. --apns-reachable mengirim token penyedia yang sengaja dibuat tidak valid, sehingga respons 403 InvalidProviderToken dianggap sebagai bukti bahwa terowongan mencapai Apple. Perintah keluar dengan kode 1 jika ada kegagalan validasi; kredensial URL proxy disamarkan dari keluaran teks maupun 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 }  ]}

Pemeriksaan curl manual (permintaan publik harus berhasil; permintaan local loopback dan metadata harus diblokir oleh proxy itu sendiri — curl saja tidak dapat membedakan penolakan proxy dari asal yang tidak dapat dijangkau seperti yang dapat dilakukan kanari bawaan openclaw proxy validate):

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/

Tujuan yang disarankan untuk diblokir

Daftar penolakan awal untuk setiap proxy penerusan, firewall, atau kebijakan lalu lintas keluar. Pengklasifikasi SSRF milik OpenClaw berada di src/infra/net/ssrf.ts dan packages/net-policy/src/ip.ts (BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, prefiks tolok ukur RFC 2544, serta penanganan IPv4 tertanam untuk bentuk NAT64/6to4/Teredo/ISATAP/IPv4-terpetakan) — referensi yang berguna, tetapi OpenClaw tidak mengekspor atau memberlakukan aturan ini pada proxy eksternal Anda.

Tambahkan host metadata atau rentang cadangan lain yang didokumentasikan oleh penyedia cloud atau platform jaringan Anda.

Batasan

• Ini adalah cakupan tingkat proses untuk klien HTTP/WebSocket JavaScript, bukan sandbox jaringan tingkat OS.
• Soket net, tls, http2 mentah, pengaya native, dan proses anak non-OpenClaw dapat melewati perutean tingkat Node kecuali proses tersebut mewarisi dan mematuhi variabel lingkungan proxy. CLI anak OpenClaw hasil fork mewarisi URL proxy terkelola dan status proxy.loopbackMode.
• WebUI lokal pengguna dan server model lokal tidak tercakup oleh pengabaian jaringan lokal umum — masukkan ke daftar izin dalam kebijakan proxy operator jika diperlukan. Pengecualiannya adalah jalur langsung terlindungi milik penyedia penyematan memori Ollama bawaan, yang dibatasi pada asal local loopback host-lokal yang sama persis dari baseUrl terkonfigurasinya; host Ollama di LAN, tailnet, jaringan privat, dan publik tetap menggunakan proxy terkelola.
• Penerusan hulu langsung milik proxy debug lokal (untuk permintaan proxy dan terowongan CONNECT) dinonaktifkan secara bawaan saat mode proxy terkelola aktif; aktifkan hanya untuk diagnostik lokal yang disetujui.
• OpenClaw tidak memeriksa, menguji, atau menyertifikasi kebijakan proxy Anda. Perlakukan perubahan kebijakan proxy sebagai perubahan operasional yang sensitif terhadap keamanan.