پروکسی شبکه

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

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

پیکربندی

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

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

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

proxy.proxyUrl بر OPENCLAW_PROXY_URL اولویت دارد. اگر proxy.enabled برابر true باشد اما هیچ نشانی معتبری تفکیک نشود، فرمان‌های محافظت‌شده هنگام راه‌اندازی شکست می‌خورند و به دسترسی مستقیم شبکه بازنمی‌گردند.

برای سرویس‌های Gateway مدیریت‌شده، نشانی را در پیکربندی ذخیره کنید تا پس از نصب مجدد باقی بماند، نه اینکه به متغیر محیطی اجرای پیش‌زمینه متکی باشید:

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

راهکار جایگزین متغیر محیطی OPENCLAW_PROXY_URL برای اجراهای پیش‌زمینه مناسب‌تر است. برای استفاده از آن با یک سرویس نصب‌شده، آن را در محیط پایدار سرویس ($OPENCLAW_STATE_DIR/.env، با پیش‌فرض ~/.openclaw/.env) قرار دهید، سپس سرویس را دوباره نصب کنید تا launchd/systemd/Scheduled Tasks آن را دریافت کند.

نقطه پایانی پراکسی HTTPS با CA خصوصی

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

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

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 و یک نشانی معتبر، فرایندهای محافظت‌شده زمان اجرا (openclaw gateway run، openclaw node run، openclaw agent --local) ترافیک خروجی عادی HTTP و WebSocket را از طریق پراکسی مسیریابی می‌کنند:

فرایند OpenClaw  کلاینت‌های fetch، node:http، node:https و WebSocket  -> پراکسی اپراتور -> مقصد

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

طرح نشانی پراکسی، گام ارتباطی OpenClaw تا پراکسی را توصیف می‌کند، نه تا مقصد نهایی:

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

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

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

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

حالت local loopback برای Gateway

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

proxy:  enabled: true  proxyUrl: http://127.0.0.1:3128  loopbackMode: gateway-only # gateway-only، proxy یا block

عبور صفحه کنترل Gateway فقط به نشانی‌های localhost و IP صریح local loopback محدود است — از ws://127.0.0.1:18789، ws://[::1]:18789 یا ws://localhost:18789 استفاده کنید. نام‌های میزبان دیگر مانند ترافیک عادی مسیریابی می‌شوند.

کانتینرها

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

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

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

اعتبارسنجی پراکسی

خط‌مشی مقصد پراکسی مرز امنیتی واقعی است؛ OpenClaw نمی‌تواند تأیید کند که پراکسی شما اهداف درست را مسدود می‌کند. آن را به‌گونه‌ای پیکربندی کنید که:

• فقط به local loopback یا یک رابط خصوصی مورد اعتماد متصل شود و تنها برای فرایند/میزبان/کانتینر/حساب سرویس OpenClaw قابل دسترس باشد.
• مقصدها را خودش تفکیک کند و پس از تفکیک DNS، هنگام اتصال، بر اساس IP مسدودسازی را برای HTTP ساده و تونل‌های HTTPS مبتنی بر CONNECT اعمال کند.
• عبورهای مبتنی بر مقصد را برای بازه‌های local loopback، خصوصی، پیوند-محلی، فراداده، چندپخشی، رزروشده و مستندسازی رد کند.
• از فهرست‌های مجاز نام میزبان پرهیز کند، مگر اینکه به مسیر تفکیک DNS کاملاً اعتماد داشته باشید.
• مقصد، تصمیم، وضعیت و دلیل را ثبت کند — هرگز بدنه درخواست‌ها، سرآیندهای مجوزدهی، کوکی‌ها یا سایر اسرار را ثبت نکند.
• خط‌مشی را تحت کنترل نسخه نگه دارد و تغییرات را از نظر امنیتی حساس بررسی کند.

از همان میزبان/کانتینر/حساب سرویسی که 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

اگر proxy.enabled برابر true نباشد و --proxy-url نیز ارائه نشده باشد، فرمان به‌جای اعتبارسنجی، وجود مشکل در پیکربندی را گزارش می‌کند؛ برای یک پیش‌بررسی موردی پیش از تغییر پیکربندی، --proxy-url را ارسال کنید.

اگر --allowed-url/--denied-url ارائه نشود، بررسی‌های پیش‌فرض چنین‌اند: دسترسی به https://example.com/ باید موفق باشد و یک سرور موقت قناری local loopback که پروکسی نباید بتواند به آن دسترسی پیدا کند، باید مسدود شود. بررسی local loopback در صورت شکست انتقال یا دریافت پاسخ غیر 2xx که فاقد توکن مختص همان اجرای قناری باشد، موفق محسوب می‌شود؛ در صورت دریافت پاسخ 2xx فاقد توکن (موفقیتی غیرمنتظره از چیزی غیر از قناری) و به‌ویژه هر پاسخی که توکن منطبق را حمل کند شکست می‌خورد، زیرا چنین پاسخی ثابت می‌کند پروکسی واقعاً مقصد local loopback را که باید رد می‌کرد، هدایت کرده است. مقصدهای سفارشی --denied-url چنین توکن قناری‌ای ندارند، بنابراین به‌صورت بسته در هنگام خطا عمل می‌کنند: هر پاسخ HTTP به‌معنای قابل دسترس بودن مقصد (شکست) است و خطای انتقال به‌جای اثبات مسدود بودن، نامشخص گزارش می‌شود، زیرا OpenClaw نمی‌تواند تأیید کند که پروکسی شما یک مبدأ قابل دسترس را رد کرده یا مشکل دیگری رخ داده است. --apns-reachable عمداً یک توکن ارائه‌دهندهٔ نامعتبر ارسال می‌کند؛ بنابراین پاسخ 403 InvalidProviderToken مدرکی محسوب می‌شود که تونل به Apple رسیده است. فرمان در صورت هرگونه شکست اعتبارسنجی با کد 1 خارج می‌شود؛ اطلاعات احراز هویت 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 (درخواست عمومی باید موفق شود؛ درخواست‌های local loopback و فراداده باید توسط خود پروکسی مسدود شوند — curl به‌تنهایی نمی‌تواند مانند قناری داخلی 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/

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

فهرست اولیهٔ منع برای هر پروکسی روبه‌جلو، دیوارهٔ آتش یا سیاست خروجی. طبقه‌بند SSRF خود OpenClaw در src/infra/net/ssrf.ts و packages/net-policy/src/ip.ts قرار دارد (BLOCKED_HOSTNAMES، BLOCKED_IPV4_SPECIAL_USE_RANGES، BLOCKED_IPV6_SPECIAL_USE_RANGES، پیشوند محک‌زنی RFC 2544 و مدیریت IPv4 تعبیه‌شده برای قالب‌های NAT64/6to4/Teredo/ISATAP/IPv4-mapped) — این‌ها مراجع مفیدی هستند، اما OpenClaw این قواعد را در پروکسی خارجی شما صادر یا اعمال نمی‌کند.

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

محدودیت‌ها

• این پوشش در سطح فرایند برای کلاینت‌های HTTP/WebSocket جاوااسکریپت است، نه یک محیط ایزولهٔ شبکه در سطح سیستم‌عامل.
• سوکت‌های خام net، tls و http2، افزونه‌های بومی و فرایندهای فرزند غیر OpenClaw ممکن است مسیریابی در سطح Node را دور بزنند، مگر اینکه متغیرهای محیطی پروکسی را به ارث ببرند و رعایت کنند. CLIهای فرزند OpenClaw که به‌صورت انشعابی اجرا می‌شوند، URL پروکسی مدیریت‌شده و وضعیت proxy.loopbackMode را به ارث می‌برند.
• رابط‌های وب محلی کاربر و سرورهای مدل محلی تحت پوشش یک دورزدن عمومی شبکهٔ محلی نیستند — در صورت نیاز، آن‌ها را در سیاست پروکسی اپراتور در فهرست مجاز قرار دهید. استثنا، مسیر مستقیم محافظت‌شدهٔ ارائه‌دهندهٔ تعبیه‌سازی حافظهٔ Ollama همراه بسته است که دامنه‌اش به مبدأ دقیق local loopback و محلی میزبان از baseUrl پیکربندی‌شدهٔ آن محدود می‌شود؛ میزبان‌های Ollama در LAN، tailnet، شبکهٔ خصوصی و عمومی همچنان از پروکسی مدیریت‌شده استفاده می‌کنند.
• هدایت مستقیم بالادستی پروکسی اشکال‌زدایی محلی (برای درخواست‌های پروکسی و تونل‌های CONNECT) هنگام فعال بودن حالت پروکسی مدیریت‌شده به‌طور پیش‌فرض غیرفعال است؛ آن را فقط برای عیب‌یابی محلی تأییدشده فعال کنید.
• OpenClaw سیاست پروکسی شما را بازرسی، آزمایش یا تأیید نمی‌کند. تغییرات سیاست پروکسی را تغییرات عملیاتی حساس از نظر امنیتی تلقی کنید.