Ağ proxy'si

OpenClaw, çalışma zamanı HTTP ve WebSocket trafiğini operatör tarafından yönetilen bir ileri vekil sunucu üzerinden yönlendirebilir. Bu, isteğe bağlı bir derinlemesine savunma katmanıdır: merkezi çıkış trafiği denetimi, daha güçlü SSRF koruması ve ağ sınırında hedeflerin denetlenebilirliği sağlar. Vekil sunucu hedefi bağlantı kurulurken, DNS çözümlemesinden sonra ve üst akış bağlantısını açmadan hemen önce değerlendirdiği için, DNS yeniden bağlama saldırısının daha önceki uygulama düzeyindeki DNS denetimi ile gerçek giden bağlantı arasındaki zaman aralığından yararlanma olanağını da daraltır. Tek bir vekil sunucu politikası ayrıca operatörlere OpenClaw'ı yeniden derlemeden hedef kurallarını, ağ segmentasyonunu, hız sınırlarını veya giden trafik izin listelerini uygulayabilecekleri tek bir yer sağlar.

OpenClaw bir vekil sunucu sağlamaz, indirmez, başlatmaz, yapılandırmaz veya onaylamaz. Ortamınıza uygun vekil sunucu teknolojisini siz çalıştırırsınız; OpenClaw kendi HTTP ve WebSocket istemcilerini bunun üzerinden yönlendirir.

Yapılandırma

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

proxy.enabled: true yapılandırmada kalırken URL'yi ortam üzerinden de ayarlayabilirsiniz:

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

proxy.proxyUrl, OPENCLAW_PROXY_URL değerine göre önceliklidir. proxy.enabled değeri true olduğu hâlde geçerli bir URL çözümlenemezse korunan komutlar doğrudan ağ erişimine geri dönmek yerine başlangıçta başarısız olur.

Yönetilen Gateway hizmetlerinde URL'yi ön plan ortam değişkenine bağlı kalmak yerine yeniden kurulumdan sonra da korunması için yapılandırmada saklayın:

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

OPENCLAW_PROXY_URL ortam değişkeni geri dönüşü, ön plandaki çalıştırmalar için en uygundur. Bunu kurulu bir hizmetle kullanmak için hizmetin kalıcı ortamına ($OPENCLAW_STATE_DIR/.env, varsayılan ~/.openclaw/.env) ekleyin, ardından launchd/systemd/Zamanlanmış Görevler tarafından alınması için yeniden kurun.

Özel CA kullanan HTTPS vekil sunucu uç noktası

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

proxy.tls.caFile, vekil sunucu uç noktasının kendi TLS sertifikasını doğrular. Bu, hedef MITM güven ayarı, istemci sertifikası veya vekil sunucunun hedef politikasının yerine geçen bir ayar değildir. Bunun yerine NODE_EXTRA_CA_CERTS değişkenini yalnızca tüm Node işleminin başlangıçtan itibaren ek bir CA'ya güvenmesi gerektiğinde kullanın (örneğin, her HTTPS hedef sertifikasını yeniden imzalayan kurumsal bir TLS inceleme sistemi) — bu değişken işlem genelinde geçerlidir ve Node başlamadan önce ayarlanmalıdır; dolayısıyla OpenClaw bunu proxy.tls.caFile ayarını uyguladığı gibi çalışma sırasında uygulayamaz. HTTPS vekil sunucu uç noktasına güvenmek için proxy.tls.caFile kullanmayı tercih edin: tüm işlem yerine yönetilen vekil sunucu yönlendirmesiyle sınırlıdır.

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

Yönlendirme nasıl çalışır?

proxy.enabled: true ve geçerli bir URL ile korunan çalışma zamanı işlemleri (openclaw gateway run, openclaw node run, openclaw agent --local) normal HTTP ve WebSocket çıkış trafiğini vekil sunucu üzerinden yönlendirir:

OpenClaw işlemi  fetch, node:http, node:https, WebSocket istemcileri  -> operatör vekil sunucusu -> hedef

OpenClaw, işlem düzeyindeki yönlendirme çalışma zamanı olarak dahili biçimde Proxyline kurar. fetch, undici tabanlı istemciler, node:http/node:https, yaygın WebSocket istemcileri ve yardımcılar tarafından oluşturulan CONNECT tünellerini kapsar; ayrıca çağıranın sağladığı Node HTTP aracılarının yerine geçerek açıkça belirtilen aracıların (axios, got, node-fetch ve benzeri Node aracısı tabanlı istemciler dâhil) vekil sunucuyu sessizce atlayamamasını sağlar.

Vekil sunucu URL şeması, OpenClaw'dan vekil sunucuya olan bağlantı adımını tanımlar; son hedefe olan bağlantıyı değil:

• http://proxy.example:3128 — vekil sunucuya düz TCP; OpenClaw, HTTPS hedefleri için CONNECT dâhil HTTP vekil sunucu istekleri gönderir.
• https://proxy.example:8443 — OpenClaw vekil sunucunun kendisine TLS bağlantısı açar (vekil sunucunun sertifikasını doğrulayarak), ardından bu oturum içinde HTTP vekil sunucu istekleri gönderir.

Hedef TLS, vekil sunucu uç noktası TLS'sinden bağımsızdır: OpenClaw, bir HTTPS hedefi için her zaman vekil sunucudan bir CONNECT tüneli ister ve hedef TLS bağlantısını bu tünel üzerinden başlatır.

Vekil sunucu etkinken OpenClaw, no_proxy/NO_PROXY değişkenlerini temizler. Bu atlama listeleri hedef tabanlıdır; localhost veya 127.0.0.1 değerlerini burada bırakmak, SSRF hedeflerinin vekil sunucuyu tamamen atlamasına olanak tanır. OpenClaw kapanırken önceki vekil sunucu ortamını geri yükler ve önbelleğe alınmış yönlendirme durumunu sıfırlar.

Bazı Plugin'ler, işlem düzeyinde yönlendirme etkin olsa bile kendi vekil sunucu bağlantısına ihtiyaç duyan özel bir aktarım mekanizmasına sahiptir. Telegram'ın Bot API istemcisi kendi HTTP/1 undici dağıtıcısını kullanır ve işlem vekil sunucu ortam değişkenleriyle birlikte OPENCLAW_PROXY_URL geri dönüşünü ayrıca dikkate alır.

Gateway local loopback modu

Yerel Gateway denetim düzlemi istemcileri normalde ws://127.0.0.1:18789 gibi bir local loopback WebSocket'e bağlanır. proxy.loopbackMode, bu trafiğin yönetilen vekil sunucuyu atlayıp atlamayacağını denetler:

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

Gateway denetim düzlemi atlaması localhost ve değişmez local loopback IP URL'leriyle sınırlıdır — ws://127.0.0.1:18789, ws://[::1]:18789 veya ws://localhost:18789 kullanın. Diğer ana bilgisayar adları sıradan trafik gibi yönlendirilir.

Kapsayıcılar

openclaw --container ... komutlarında OpenClaw, ayarlanmışsa OPENCLAW_PROXY_URL değerini kapsayıcıyı hedefleyen alt CLI'ye iletir. URL'ye kapsayıcının içinden erişilebilmelidir — buradaki 127.0.0.1 ana bilgisayarı değil, kapsayıcının kendisini ifade eder. Denetimi açıkça geçersiz kılmak için OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1 ayarlamadığınız sürece OpenClaw, kapsayıcıyı hedefleyen komutlarda local loopback vekil sunucu URL'lerini reddeder.

İlgili vekil sunucu terimleri

• proxy.enabled / proxy.proxyUrl — çalışma zamanı çıkış trafiği için giden ileri vekil sunucu yönlendirmesi. Bu sayfa.
• gateway.auth.mode: "trusted-proxy" — Gateway erişimi için gelen, kimlik duyarlı ters vekil sunucu kimlik doğrulaması. Bkz. Güvenilir vekil sunucu kimlik doğrulaması.
• openclaw proxy — geliştirme ve destek için yerel hata ayıklama vekil sunucusu ve yakalama inceleyicisi. Bkz. openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy — varsayılan olarak katı DNS sabitlemesini ve ana bilgisayar adı politikasını korurken web_fetch aracının, DNS'i operatör denetimindeki bir HTTP(S) ortam vekil sunucusunun çözmesine izin vermek için isteğe bağlı ayar. Bkz. Web getirme.
• Kanala veya sağlayıcıya özgü vekil sunucu ayarları — tek bir aktarım için sahip bileşene özgü geçersiz kılmalar. Çalışma zamanı genelinde merkezi çıkış trafiği denetimi için yönetilen ağ vekil sunucusunu tercih edin.

Vekil sunucuyu doğrulama

Vekil sunucunun hedef politikası gerçek güvenlik sınırıdır; OpenClaw, vekil sunucunuzun doğru hedefleri engellediğini doğrulayamaz. Şu şekilde yapılandırın:

• Yalnızca local loopback veya özel ve güvenilir bir arabirime bağlayın; yalnızca OpenClaw işlemi/ana bilgisayarı/kapsayıcısı/hizmet hesabı tarafından erişilebilir olsun.
• Hedefleri kendisi çözümlesin ve hem düz HTTP hem de HTTPS CONNECT tünelleri için bağlantı sırasında, DNS çözümlemesinden sonra IP'ye göre engellesin.
• local loopback, özel, bağlantı yerel, meta veri, çok noktaya yayın, ayrılmış ve belgeleme aralıklarına yönelik hedef tabanlı atlamaları reddetsin.
• DNS çözümleme yoluna tamamen güvenmediğiniz sürece ana bilgisayar adı izin listelerinden kaçının.
• Hedefi, kararı, durumu ve nedeni günlüğe kaydedin — istek gövdelerini, yetkilendirme üstbilgilerini, çerezleri veya diğer sırları asla kaydetmeyin.
• Politikayı sürüm denetimi altında tutun ve değişiklikleri güvenlik açısından hassas olarak inceleyin.

OpenClaw'ı çalıştıran aynı ana bilgisayardan/kapsayıcıdan/hizmet hesabından doğrulayın:

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

Özel CA kullanan bir HTTPS vekil sunucu uç noktasıyla:

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

proxy.enabled, true değilse ve --proxy-url verilmemişse komut doğrulama yapmak yerine bir yapılandırma sorunu bildirir; yapılandırmayı değiştirmeden önce tek seferlik bir ön kontrol için --proxy-url iletin.

--allowed-url/--denied-url olmadan varsayılan kontroller şunlardır: https://example.com/ başarılı olmalı ve proxy'nin erişmemesi gereken geçici bir local loopback kanarya sunucusu engellenmelidir. local loopback kontrolü bir aktarım hatasında veya kanaryanın her çalıştırmaya özgü belirtecini içermeyen 2xx dışı bir yanıtta başarılı olur; belirtecin bulunmadığı bir 2xx yanıtında (kanarya dışındaki bir kaynaktan gelen beklenmedik başarı) ve özellikle eşleşen belirteci taşıyan herhangi bir yanıtta başarısız olur; çünkü bu, proxy'nin reddetmesi gereken bir local loopback hedefini gerçekten ilettiğini kanıtlar. Özel --denied-url hedeflerinde böyle bir kanarya belirteci yoktur; bu nedenle kapalı durumda başarısız olurlar: herhangi bir HTTP yanıtı erişilebilir sayılır (başarısızlık) ve bir aktarım hatası, engellendiği kanıtlanmış kabul edilmek yerine sonuçsuz olarak bildirilir; çünkü OpenClaw, proxy'nizin erişilebilir bir kaynağı reddettiğini mi yoksa başka bir şeyin mi ters gittiğini doğrulayamaz. --apns-reachable kasıtlı olarak geçersiz bir sağlayıcı belirteci gönderir; dolayısıyla 403 InvalidProviderToken yanıtı, tünelin Apple'a ulaştığının kanıtı sayılır. Komut, herhangi bir doğrulama hatasında 1 koduyla çıkar; proxy URL kimlik bilgileri hem metin hem de JSON çıktısında gizlenir.

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

Manuel curl kontrolü (genel istek başarılı olmalı; local loopback ve meta veri istekleri proxy'nin kendisi tarafından engellenmelidir — tek başına curl, openclaw proxy validate komutunun yerleşik kanaryasının yapabildiği gibi bir proxy reddini erişilemeyen bir kaynaktan ayırt edemez):

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/

Engellenmesi önerilen hedefler

Herhangi bir ileri proxy, güvenlik duvarı veya dışarı çıkış ilkesi için başlangıç engelleme listesi. OpenClaw'ın kendi SSRF sınıflandırıcısı src/infra/net/ssrf.ts ve packages/net-policy/src/ip.ts dosyalarında bulunur (BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, RFC 2544 kıyaslama ön eki ve NAT64/6to4/Teredo/ISATAP/IPv4 eşlemeli biçimler için gömülü IPv4 işleme) — bunlar yararlı referanslardır ancak OpenClaw, harici proxy'nizde bu kuralları dışa aktarmaz veya uygulamaz.

Bulut sağlayıcınızın veya ağ platformunuzun belgelediği diğer meta veri ana makinelerini ya da ayrılmış aralıkları ekleyin.

Sınırlar

• Bu, JavaScript HTTP/WebSocket istemcileri için süreç düzeyinde kapsama sağlar; işletim sistemi düzeyinde bir ağ sandbox'ı değildir.
• Ham net, tls, http2 soketleri, yerel eklentiler ve OpenClaw dışı alt süreçler, proxy ortam değişkenlerini devralıp bunlara uymadıkları sürece Node düzeyindeki yönlendirmeyi atlayabilir. Çatallanmış OpenClaw alt CLI'ları, yönetilen proxy URL'sini ve proxy.loopbackMode durumunu devralır.
• Kullanıcıya ait yerel WebUI'lar ve yerel model sunucuları, genel bir yerel ağ atlaması kapsamında değildir — gerekirse bunları operatör proxy ilkesindeki izin listesine ekleyin. Bunun istisnası, paketle gelen Ollama bellek gömme sağlayıcısının korumalı doğrudan yoludur; bu yol, yapılandırılmış baseUrl değerindeki tam ana makine yerel local loopback kaynağıyla sınırlıdır; LAN, tailnet, özel ağ ve genel Ollama ana makineleri yönetilen proxy'yi kullanmaya devam eder.
• Yerel hata ayıklama proxy'sinin doğrudan yukarı akış iletimi (proxy istekleri ve CONNECT tünelleri için), yönetilen proxy modu etkinken varsayılan olarak devre dışıdır; bunu yalnızca onaylanmış yerel tanılamalar için etkinleştirin.
• OpenClaw, proxy ilkenizi incelemez, test etmez veya onaylamaz. Proxy ilkesi değişikliklerini güvenlik açısından hassas operasyonel değişiklikler olarak değerlendirin.