پراکسی شبکه

OpenClaw می‌تواند ترافیک HTTP و WebSocket زمان اجرا را از طریق یک پراکسی رو به جلوی مدیریت‌شده توسط اپراتور مسیریابی کند. این یک دفاع اختیاریِ چندلایه برای استقرارهایی است که کنترل مرکزی خروجی، حفاظت قوی‌تر در برابر SSRF و قابلیت ممیزی بهتر شبکه می‌خواهند.

OpenClaw پراکسی را همراه خود عرضه، دانلود، راه‌اندازی، پیکربندی یا تأیید نمی‌کند. شما فناوری پراکسی متناسب با محیط خود را اجرا می‌کنید، و OpenClaw کلاینت‌های معمول HTTP و WebSocket محلیِ فرایند را از طریق آن مسیریابی می‌کند.

چرا از پراکسی استفاده کنیم

پراکسی به اپراتورها یک نقطه کنترل شبکه برای ترافیک خروجی HTTP و WebSocket می‌دهد. این حتی بیرون از سخت‌سازی SSRF هم می‌تواند مفید باشد:

• سیاست مرکزی: به‌جای تکیه بر اینکه هر محل فراخوانی HTTP در برنامه قواعد شبکه را درست اعمال کند، یک سیاست خروجی واحد را نگه دارید.
• بررسی‌های زمان اتصال: مقصد را پس از تحلیل DNS و درست پیش از اینکه پراکسی اتصال بالادستی را باز کند ارزیابی کنید.
• دفاع در برابر بازپیوند DNS: فاصله بین بررسی DNS در سطح برنامه و اتصال خروجی واقعی را کاهش دهید.
• پوشش گسترده‌تر JavaScript: کلاینت‌های معمول fetch، node:http، node:https، WebSocket، axios، got، node-fetch و کلاینت‌های مشابه را از همان مسیر عبور دهید.
• قابلیت ممیزی: مقصدهای مجاز و ردشده را در مرز خروجی ثبت کنید.
• کنترل عملیاتی: قواعد مقصد، بخش‌بندی شبکه، محدودیت‌های نرخ یا فهرست‌های مجاز خروجی را بدون بازسازی OpenClaw اعمال کنید.

مسیریابی پراکسی یک حفاظ در سطح فرایند برای خروجی معمول HTTP و WebSocket است. این به اپراتورها مسیری fail-closed برای عبور دادن کلاینت‌های HTTP پشتیبانی‌شده JavaScript از پراکسی فیلترکننده خودشان می‌دهد، اما یک سندباکس شبکه در سطح سیستم‌عامل نیست و باعث نمی‌شود OpenClaw سیاست مقصد پراکسی را تأیید کند.

OpenClaw چگونه ترافیک را مسیریابی می‌کند

وقتی proxy.enabled=true باشد و یک URL پراکسی پیکربندی شده باشد، فرایندهای زمان اجرای محافظت‌شده مانند openclaw gateway run، openclaw node run و openclaw agent --local خروجی معمول HTTP و WebSocket را از طریق پراکسی پیکربندی‌شده مسیریابی می‌کنند:

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

قرارداد عمومی، رفتار مسیریابی است، نه قلاب‌های داخلی Node که برای پیاده‌سازی آن استفاده می‌شوند. کلاینت‌های WebSocket صفحه کنترل OpenClaw Gateway برای ترافیک RPC Gateway روی local loopback، وقتی URL Gateway از localhost یا یک IP لوپ‌بک صریح مانند 127.0.0.1 یا [::1] استفاده می‌کند، از یک مسیر مستقیم محدود استفاده می‌کنند. آن مسیر صفحه کنترل باید بتواند حتی وقتی پراکسی اپراتور مقصدهای لوپ‌بک را مسدود می‌کند به Gatewayهای لوپ‌بک دسترسی داشته باشد. درخواست‌های معمول HTTP و WebSocket زمان اجرا همچنان از پراکسی پیکربندی‌شده استفاده می‌کنند.

در داخل، OpenClaw برای این قابلیت از دو قلاب مسیریابی در سطح فرایند استفاده می‌کند:

• مسیریابی dispatcher در Undici، fetch، کلاینت‌های مبتنی بر undici و ترنسپورت‌هایی را که dispatcher اختصاصی undici خود را فراهم می‌کنند پوشش می‌دهد.
• مسیریابی global-agent فراخوان‌های هسته Node یعنی node:http و node:https را پوشش می‌دهد، از جمله بسیاری از کتابخانه‌هایی که روی http.request، https.request، http.get و https.get ساخته شده‌اند. حالت پراکسی مدیریت‌شده آن agent سراسری را اجباری می‌کند تا agentهای صریح HTTP در Node به‌طور تصادفی پراکسی اپراتور را دور نزنند.

بعضی Pluginها مالک ترنسپورت‌های سفارشی هستند که حتی وقتی مسیریابی در سطح فرایند وجود دارد، به سیم‌کشی صریح پراکسی نیاز دارند. برای نمونه، ترنسپورت Bot API در Telegram از dispatcher اختصاصی HTTP/1 در undici استفاده می‌کند و بنابراین env پراکسی فرایند به‌علاوه مسیر fallback مدیریت‌شده OPENCLAW_PROXY_URL را در همان مسیر ترنسپورت مالک‌محور رعایت می‌کند.

خود URL پراکسی باید از http:// استفاده کند. مقصدهای HTTPS همچنان از طریق پراکسی با HTTP CONNECT پشتیبانی می‌شوند؛ این فقط به این معناست که OpenClaw انتظار یک شنونده پراکسی رو به جلوی HTTP ساده مانند http://127.0.0.1:3128 را دارد.

وقتی پراکسی فعال است، OpenClaw مقدارهای no_proxy، NO_PROXY و GLOBAL_AGENT_NO_PROXY را پاک می‌کند. این فهرست‌های دورزدن مبتنی بر مقصد هستند، بنابراین باقی گذاشتن localhost یا 127.0.0.1 در آن‌ها اجازه می‌دهد هدف‌های پرخطر SSRF پراکسی فیلترکننده را دور بزنند.

هنگام خاموشی، OpenClaw محیط پراکسی قبلی را بازیابی می‌کند و وضعیت کش‌شده مسیریابی فرایند را بازنشانی می‌کند.

اصطلاحات مرتبط با پراکسی

• proxy.enabled / proxy.proxyUrl: مسیریابی پراکسی رو به جلوی خروجی برای خروجی زمان اجرای OpenClaw. این صفحه آن قابلیت را مستند می‌کند.
• gateway.auth.mode: "trusted-proxy": احراز هویت ورودی reverse-proxy آگاه از هویت برای دسترسی Gateway. احراز هویت پراکسی مورد اعتماد را ببینید.
• openclaw proxy: پراکسی اشکال‌زدایی محلی و بازرس capture برای توسعه و پشتیبانی. openclaw proxy را ببینید.
• tools.web.fetch.useTrustedEnvProxy: گزینه opt-in برای web_fetch تا اجازه دهد یک پراکسی HTTP(S) محیطیِ کنترل‌شده توسط اپراتور DNS را تحلیل کند، در حالی که pinning سخت‌گیرانه پیش‌فرض DNS و سیاست نام میزبان حفظ می‌شود. Web fetch را ببینید.
• تنظیمات پراکسی ویژه کانال یا ارائه‌دهنده: بازنویسی‌های مالک‌محور برای یک ترنسپورت خاص. وقتی هدف کنترل مرکزی خروجی در سراسر زمان اجراست، پراکسی شبکه مدیریت‌شده را ترجیح دهید.

پیکربندی

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

همچنین می‌توانید URL را از طریق محیط فراهم کنید، در حالی که proxy.enabled=true را در پیکربندی نگه می‌دارید:

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

proxy.proxyUrl بر OPENCLAW_PROXY_URL اولویت دارد.

حالت لوپ‌بک Gateway

کلاینت‌های صفحه کنترل Gateway محلی معمولا به یک WebSocket لوپ‌بک مانند ws://127.0.0.1:18789 وصل می‌شوند. از proxy.loopbackMode استفاده کنید تا انتخاب کنید آن ترافیک هنگام فعال بودن پراکسی مدیریت‌شده چگونه رفتار کند:

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

• gateway-only (پیش‌فرض): OpenClaw اختیار لوپ‌بک Gateway را در کنترل‌کننده فعال NO_PROXY مربوط به global-agent ثبت می‌کند تا ترافیک WebSocket محلی Gateway بتواند مستقیم وصل شود. پورت‌های سفارشی لوپ‌بک Gateway کار می‌کنند چون host و port مربوط به URL فعال Gateway ثبت می‌شوند.
• proxy: OpenClaw اختیار لوپ‌بک Gateway را در NO_PROXY ثبت نمی‌کند، بنابراین ترافیک محلی Gateway از طریق پراکسی مدیریت‌شده ارسال می‌شود. اگر پراکسی remote باشد، باید مسیریابی ویژه‌ای برای سرویس لوپ‌بک میزبان OpenClaw فراهم کند، مانند نگاشت آن به یک نام میزبان، IP یا تونل قابل دسترسی از پراکسی. پراکسی‌های remote استاندارد 127.0.0.1 و localhost را از میزبان پراکسی تحلیل می‌کنند، نه از میزبان OpenClaw.
• block: OpenClaw اتصال‌های صفحه کنترل لوپ‌بک Gateway را پیش از باز کردن socket رد می‌کند.

اگر enabled=true باشد اما هیچ URL معتبر پراکسی پیکربندی نشده باشد، فرمان‌های محافظت‌شده به‌جای برگشتن به دسترسی مستقیم شبکه، در شروع اجرا شکست می‌خورند.

برای سرویس‌های Gateway مدیریت‌شده که با openclaw gateway start شروع می‌شوند، ترجیح دهید URL را در پیکربندی ذخیره کنید:

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

fallback محیط برای اجراهای foreground مناسب‌تر است. اگر آن را با یک سرویس نصب‌شده استفاده می‌کنید، OPENCLAW_PROXY_URL را در محیط پایدار سرویس، مانند $OPENCLAW_STATE_DIR/.env یا ~/.openclaw/.env بگذارید، سپس سرویس را دوباره نصب کنید تا launchd، systemd یا Scheduled Tasks مقدار gateway را با آن مقدار شروع کند.

برای فرمان‌های openclaw --container ...، وقتی OPENCLAW_PROXY_URL تنظیم شده باشد OpenClaw آن را به CLI فرزندِ هدف‌گیری‌شده برای کانتینر منتقل می‌کند. URL باید از داخل کانتینر قابل دسترسی باشد؛ 127.0.0.1 به خود کانتینر اشاره می‌کند، نه میزبان. OpenClaw URLهای پراکسی لوپ‌بک را برای فرمان‌های هدف‌گیری‌شده برای کانتینر رد می‌کند، مگر اینکه آن بررسی ایمنی را صریحا override کنید.

الزامات پراکسی

سیاست پراکسی مرز امنیتی است. OpenClaw نمی‌تواند تأیید کند که پراکسی هدف‌های درست را مسدود می‌کند.

پراکسی را طوری پیکربندی کنید که:

• فقط به لوپ‌بک یا یک رابط خصوصیِ مورد اعتماد bind شود.
• دسترسی را محدود کند تا فقط فرایند، میزبان، کانتینر یا حساب سرویس OpenClaw بتواند از آن استفاده کند.
• مقصدها را خودش تحلیل کند و IPهای مقصد را پس از تحلیل DNS مسدود کند.
• سیاست را در زمان اتصال هم برای درخواست‌های HTTP ساده و هم برای تونل‌های HTTPS CONNECT اعمال کند.
• دورزدن‌های مبتنی بر مقصد را برای بازه‌های لوپ‌بک، خصوصی، link-local، metadata، multicast، reserved یا documentation رد کند.
• از فهرست‌های مجاز نام میزبان پرهیز کند، مگر اینکه به مسیر تحلیل DNS کاملا اعتماد دارید.
• مقصد، تصمیم، وضعیت و دلیل را بدون ثبت بدنه‌های درخواست، سربرگ‌های authorization، کوکی‌ها یا رازهای دیگر ثبت کند.
• سیاست پراکسی را تحت کنترل نسخه نگه دارد و تغییرات را مانند پیکربندی حساس امنیتی بازبینی کند.

مقصدهای پیشنهادی برای مسدودسازی

از این denylist به‌عنوان نقطه شروع برای هر پراکسی رو به جلو، firewall یا سیاست خروجی استفاده کنید.

منطق طبقه‌بند سطح برنامه OpenClaw در src/infra/net/ssrf.ts و src/shared/net/ip.ts قرار دارد. قلاب‌های parity مرتبط عبارت‌اند از BLOCKED_HOSTNAMES، BLOCKED_IPV4_SPECIAL_USE_RANGES، BLOCKED_IPV6_SPECIAL_USE_RANGES، RFC2544_BENCHMARK_PREFIX و رسیدگی داخلی به sentinelهای IPv4 برای NAT64، 6to4، Teredo، ISATAP و شکل‌های IPv4-mapped. این فایل‌ها هنگام نگهداری یک سیاست پراکسی خارجی منابع مفیدی هستند، اما OpenClaw آن قواعد را به‌طور خودکار به پراکسی شما صادر یا در آن اعمال نمی‌کند.

اگر ارائه‌دهنده cloud یا پلتفرم شبکه شما میزبان‌های metadata یا بازه‌های reserved بیشتری را مستند کرده است، آن‌ها را هم اضافه کنید.

اعتبارسنجی

پراکسی را از همان میزبان، کانتینر یا حساب سرویسی که OpenClaw را اجرا می‌کند اعتبارسنجی کنید:

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

به‌طور پیش‌فرض، وقتی مقصدهای سفارشی ارائه نشده باشند، فرمان بررسی می‌کند که https://example.com/ موفق شود و یک canary موقت loopback را راه‌اندازی می‌کند که proxy نباید به آن دسترسی پیدا کند. بررسی ردشده‌ی پیش‌فرض زمانی موفق است که proxy یک پاسخ رد غیر 2xx برگرداند یا canary را با خطای انتقال مسدود کند؛ اگر پاسخ موفقی به canary برسد، بررسی ناموفق می‌شود. اگر هیچ proxyای فعال و پیکربندی نشده باشد، اعتبارسنجی یک مشکل پیکربندی گزارش می‌کند؛ برای یک preflight موردی پیش از تغییر پیکربندی، از --proxy-url استفاده کنید. برای آزمودن انتظارهای خاص استقرار، از --allowed-url و --denied-url استفاده کنید. برای اینکه همچنین تأیید شود تحویل مستقیم APNs HTTP/2 می‌تواند یک تونل CONNECT را از طریق proxy باز کند و یک پاسخ sandbox APNs دریافت کند، --apns-reachable را اضافه کنید؛ این probe از یک توکن provider عمداً نامعتبر استفاده می‌کند، بنابراین 403 InvalidProviderToken مورد انتظار است و به‌عنوان قابل‌دسترسی شمرده می‌شود. مقصدهای ردشده‌ی سفارشی fail-closed هستند: هر پاسخ HTTP یعنی مقصد از طریق proxy قابل‌دسترسی بوده است، و هر خطای انتقال به‌عنوان نامشخص گزارش می‌شود، چون OpenClaw نمی‌تواند ثابت کند proxy یک origin قابل‌دسترسی را مسدود کرده است. در صورت شکست اعتبارسنجی، فرمان با کد 1 خارج می‌شود.

برای automation از --json استفاده کنید. خروجی JSON شامل نتیجه‌ی کلی، منبع مؤثر پیکربندی proxy، هرگونه خطای پیکربندی، و هر بررسی مقصد است. credentials مربوط به URL proxy در خروجی متنی و 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    }  ]}

همچنین می‌توانید به‌صورت دستی با 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/

درخواست عمومی باید موفق شود. درخواست‌های loopback و metadata باید توسط proxy مسدود شوند. برای openclaw proxy validate، canary داخلی loopback می‌تواند رد proxy را از یک origin قابل‌دسترسی تشخیص دهد. بررسی‌های سفارشی --denied-url آن canary را ندارند، بنابراین هم پاسخ‌های HTTP و هم شکست‌های مبهم انتقال را شکست اعتبارسنجی در نظر بگیرید، مگر اینکه proxy شما یک سیگنال رد خاص استقرار ارائه کند که بتوانید جداگانه تأییدش کنید.

سپس مسیریابی proxy در OpenClaw را فعال کنید:

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

یا تنظیم کنید:

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

محدودیت‌ها

• proxy پوشش را برای کلاینت‌های HTTP و WebSocket جاوااسکریپتِ محلیِ فرایند بهبود می‌دهد، اما یک sandbox شبکه در سطح سیستم‌عامل نیست.
• ترافیک control-plane مربوط به loopback در Gateway به‌طور پیش‌فرض از طریق proxy.loopbackMode: "gateway-only" مستقیماً از مسیر محلی عبور می‌کند. OpenClaw این bypass را با ثبت authority فعال loopback در Gateway در کنترلر مدیریت‌شده‌ی global-agent برای NO_PROXY پیاده‌سازی می‌کند. اپراتورها می‌توانند proxy.loopbackMode: "proxy" را تنظیم کنند تا ترافیک loopback در Gateway از طریق proxy مدیریت‌شده ارسال شود، یا proxy.loopbackMode: "block" را تنظیم کنند تا اتصال‌های loopback Gateway رد شوند. برای caveat مربوط به remote-proxy، حالت loopback در Gateway را ببینید.
• سوکت‌های خام net، tls و http2، افزونه‌های native، و فرایندهای فرزند غیر OpenClaw ممکن است مسیریابی proxy در سطح Node را bypass کنند، مگر اینکه متغیرهای محیطی proxy را به ارث ببرند و رعایت کنند. CLIهای فرزند forkشده‌ی OpenClaw نشانی proxy مدیریت‌شده و وضعیت proxy.loopbackMode را به ارث می‌برند.
• IRC یک کانال خام TCP/TLS خارج از مسیریابی forward proxy مدیریت‌شده توسط اپراتور است. در استقرارهایی که نیاز دارند همه‌ی egress از طریق آن forward proxy انجام شود، مگر اینکه egress مستقیم IRC صریحاً تأیید شده باشد، channels.irc.enabled=false را تنظیم کنید.
• proxy محلی debug ابزار تشخیصی است و forward مستقیم upstream آن برای درخواست‌های proxy و تونل‌های CONNECT به‌طور پیش‌فرض زمانی که حالت proxy مدیریت‌شده فعال است غیرفعال می‌شود؛ direct forwarding را فقط برای diagnostics محلی تأییدشده فعال کنید.
• WebUIهای محلی کاربر و سرورهای مدل محلی باید در صورت نیاز در policy مربوط به proxy اپراتور allowlist شوند؛ OpenClaw برای آن‌ها یک bypass عمومی local-network ارائه نمی‌کند.
• bypass مربوط به proxy در control-plane Gateway عمداً به localhost و URLهای IP literal loopback محدود است. برای اتصال‌های control-plane محلی و مستقیم Gateway از ws://127.0.0.1:18789، ws://[::1]:18789، یا ws://localhost:18789 استفاده کنید؛ hostnameهای دیگر مانند ترافیک عادی مبتنی بر hostname مسیریابی می‌شوند.
• OpenClaw سیاست proxy شما را inspect، test یا certify نمی‌کند.
• تغییرات policy مربوط به proxy را تغییرات عملیاتی حساس از نظر امنیتی در نظر بگیرید.