پروکسی شبکه

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

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

در داخل، OpenClaw برای این قابلیت Proxyline را به‌عنوان زمان اجرای مسیریابی در سطح فرایند نصب می‌کند. Proxyline موارد fetch، کلاینت‌های مبتنی بر undici، فراخوان‌های هسته Node از نوع node:http / node:https، کلاینت‌های رایج WebSocket، و تونل‌های CONNECT ساخته‌شده توسط helperها را پوشش می‌دهد. حالت پراکسی مدیریت‌شده agentهای HTTP مربوط به Node را که توسط فراخواننده ارائه شده‌اند جایگزین می‌کند تا agentهای صریح به‌طور تصادفی پراکسی اپراتور را دور نزنند.

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

خود URL پراکسی می‌تواند از http:// یا https:// استفاده کند. این schemeها اتصال از OpenClaw به endpoint پراکسی را توصیف می‌کنند:

• http://proxy.example:3128: OpenClaw یک اتصال TCP ساده به پراکسی فوروارد باز می‌کند و درخواست‌های پراکسی HTTP، از جمله CONNECT برای مقصدهای HTTPS، را ارسال می‌کند.
• https://proxy.example:8443: OpenClaw اتصال TLS را به endpoint پراکسی باز می‌کند، گواهی پراکسی را راستی‌آزمایی می‌کند، و سپس درخواست‌های پراکسی HTTP را داخل همان نشست TLS ارسال می‌کند.

HTTPS مقصد از TLS مربوط به endpoint پراکسی جداست. برای یک مقصد HTTPS، OpenClaw همچنان از پراکسی یک تونل HTTP CONNECT می‌خواهد و سپس TLS مقصد را از طریق آن تونل شروع می‌کند.

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

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

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

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

پیکربندی

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

برای یک endpoint پراکسی HTTPS با CA خصوصی پراکسی:

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

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

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

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

حالت Loopback Gateway

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

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

• gateway-only (پیش‌فرض): OpenClaw authority مربوط به loopback Gateway را در خط‌مشی managed bypass مربوط به Proxyline ثبت می‌کند تا ترافیک WebSocket محلی Gateway بتواند مستقیم وصل شود. پورت‌های سفارشی loopback Gateway کار می‌کنند، چون host و port مربوط به URL فعال Gateway ثبت می‌شوند. Plugin مرورگرِ همراه نیز می‌تواند endpointهای دقیق WebSocket مربوط به آمادگی CDP محلی و DevTools را برای مرورگرهای مدیریت‌شده‌ای که OpenClaw اجرا کرده ثبت کند، و provider همراه Ollama برای embedding حافظه می‌تواند از مسیر مستقیمِ محافظت‌شده و محدودتر خودش برای origin دقیق embedding مربوط به host-local loopback پیکربندی‌شده استفاده کند.
• proxy: OpenClaw bypassهای loopback مربوط به Gateway یا Ollama را ثبت نمی‌کند، بنابراین آن ترافیک loopback از طریق پراکسی مدیریت‌شده ارسال می‌شود. اگر پراکسی راه‌دور باشد، باید مسیریابی ویژه‌ای برای سرویس loopback میزبان OpenClaw فراهم کند، مانند نگاشت آن به یک hostname، IP، یا تونل قابل‌دسترسی برای پراکسی. پراکسی‌های راه‌دور استاندارد 127.0.0.1 و localhost را از میزبان پراکسی تفکیک می‌کنند، نه از میزبان OpenClaw.
• block: OpenClaw اتصال‌های سطح کنترل loopback مربوط به Gateway و اتصال‌های loopback مربوط به embedding host-local محافظت‌شده Ollama را پیش از باز کردن socket رد می‌کند.

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

برای سرویس‌های 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 دروازه را با آن مقدار شروع کند.

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

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

خط‌مشی پراکسی مرز امنیتی است. OpenClaw نمی‌تواند راستی‌آزمایی کند که پراکسی هدف‌های درست را مسدود می‌کند.

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

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

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

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

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

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

اعتبارسنجی

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

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

برای یک نقطه پایانی پراکسی HTTPS که با CA خصوصی امضا شده است:

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

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

برای اتوماسیون از --json استفاده کنید. خروجی JSON شامل نتیجه کلی، منبع پیکربندی مؤثر پراکسی، هر خطای پیکربندی، و هر بررسی مقصد است. اعتبارنامه‌های URL پراکسی در خروجی متنی و 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 و فراداده باید توسط پراکسی مسدود شوند. برای openclaw proxy validate، canary داخلی loopback می‌تواند رد پراکسی را از یک مبدا قابل‌دسترسی تشخیص دهد. بررسی‌های سفارشی --denied-url آن canary را ندارند، بنابراین هم پاسخ‌های HTTP و هم شکست‌های انتقال مبهم را شکست اعتبارسنجی در نظر بگیرید، مگر اینکه پراکسی شما سیگنال رد خاص استقرار ارائه کند که بتوانید جداگانه آن را راستی‌آزمایی کنید.

اعتماد CA پراکسی

وقتی خود نقطه پایانی پراکسی از گواهی امضاشده با CA خصوصی استفاده می‌کند، از proxy.tls.caFile مدیریت‌شده استفاده کنید:

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

آن CA برای راستی‌آزمایی TLS نقطه پایانی پراکسی استفاده می‌شود. این یک تنظیم اعتماد MITM مقصد، گواهی کلاینت، یا جایگزینی برای سیاست مقصد پراکسی نیست.

فقط زمانی از NODE_EXTRA_CA_CERTS استفاده کنید که کل فرایند Node باید از زمان شروع فرایند به یک CA اضافی اعتماد کند، مثلا وقتی یک سامانه بازرسی TLS سازمانی گواهی‌های مقصد را برای هر کلاینت HTTPS در فرایند دوباره امضا می‌کند. NODE_EXTRA_CA_CERTS در سطح کل فرایند است و باید پیش از شروع Node وجود داشته باشد. برای اعتماد به نقطه پایانی پراکسی HTTPS، proxy.tls.caFile را ترجیح دهید، چون دامنه آن به مسیریابی پراکسی مدیریت‌شده محدود است.

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

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

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

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

محدودیت‌ها

• پراکسی پوشش را برای کلاینت‌های HTTP و WebSocket جاوااسکریپتِ محلیِ فرایند بهبود می‌دهد، اما sandbox شبکه در سطح سیستم‌عامل نیست.
• ترافیک control-plane مربوط به loopback در Gateway به‌صورت پیش‌فرض از طریق proxy.loopbackMode: "gateway-only" با bypass محلی مستقیم انجام می‌شود. OpenClaw این bypass را با ثبت authority فعال loopback در Gateway در سیاست bypass مدیریت‌شده Proxyline پیاده‌سازی می‌کند. اپراتورها می‌توانند proxy.loopbackMode: "proxy" را تنظیم کنند تا ترافیک loopback در Gateway از طریق پراکسی مدیریت‌شده ارسال شود، یا proxy.loopbackMode: "block" را تنظیم کنند تا اتصال‌های loopback به Gateway رد شوند. برای نکته احتیاطی پراکسی راه‌دور، حالت loopback در Gateway را ببینید.
• سوکت‌های خام net، tls، و http2، افزونه‌های native، و فرایندهای فرزند غیر OpenClaw ممکن است مسیریابی پراکسی در سطح Node را دور بزنند، مگر اینکه متغیرهای محیطی پراکسی را به ارث ببرند و رعایت کنند. CLIهای فرزند OpenClaw که fork شده‌اند، URL پراکسی مدیریت‌شده و وضعیت proxy.loopbackMode را به ارث می‌برند.
• IRC یک کانال TCP/TLS خام خارج از مسیریابی پراکسی forward مدیریت‌شده توسط اپراتور است. در استقرارهایی که همه خروجی‌ها باید از آن پراکسی forward عبور کنند، مگر اینکه خروجی مستقیم IRC صراحتا تأیید شده باشد، channels.irc.enabled=false را تنظیم کنید.
• پراکسی محلی debug ابزار تشخیصی است و forwarding مستقیم upstream آن برای درخواست‌های پراکسی و تونل‌های CONNECT به‌صورت پیش‌فرض هنگام فعال بودن حالت پراکسی مدیریت‌شده غیرفعال است؛ forwarding مستقیم را فقط برای تشخیص‌های محلی تأییدشده فعال کنید.
• WebUIهای محلی کاربر و سرورهای مدل محلی در صورت نیاز باید در سیاست پراکسی اپراتور allowlist شوند؛ OpenClaw برای آن‌ها bypass عمومی شبکه محلی ارائه نمی‌کند. ارائه‌دهنده embedding حافظه Ollama همراه محدودتر است: فقط برای مبدا دقیق embedding روی host-local loopback که از baseUrl پیکربندی‌شده مشتق شده است می‌تواند از یک مسیر مستقیم محافظت‌شده استفاده کند تا embeddingهای host-local وقتی پراکسی مدیریت‌شده نمی‌تواند به host loopback برسد همچنان کار کنند. میزبان‌های embedding مربوط به Ollama روی LAN، tailnet، شبکه خصوصی، و عمومی همچنان از مسیر پراکسی مدیریت‌شده استفاده می‌کنند. proxy.loopbackMode: "proxy" این ترافیک loopback مربوط به Ollama را از طریق پراکسی مدیریت‌شده ارسال می‌کند، و proxy.loopbackMode: "block" پیش از باز کردن اتصال آن را رد می‌کند.
• bypass پراکسی برای control-plane در Gateway عمدا به localhost و URLهای IP صریح loopback محدود است. برای اتصال‌های control-plane محلی مستقیم Gateway از ws://127.0.0.1:18789، ws://[::1]:18789، یا ws://localhost:18789 استفاده کنید؛ نام‌های میزبان دیگر مانند ترافیک معمول مبتنی بر نام میزبان مسیریابی می‌شوند.
• OpenClaw سیاست پراکسی شما را بازرسی، آزمایش، یا تأیید نمی‌کند.
• تغییرات سیاست پراکسی را تغییرات عملیاتی حساس به امنیت در نظر بگیرید.