پروکسی شبکه

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

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

پیکربندی

proxy:  proxyUrl: http://127.0.0.1:3128

همچنین می‌توانید URL را از طریق محیط تنظیم کنید:

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

proxy.proxyUrl بر OPENCLAW_PROXY_URL اولویت دارد. URL پیکربندی‌شده، مسیریابی پراکسی مدیریت‌شده را فعال می‌کند؛ حذف هر دو URL آن را غیرفعال می‌کند.

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

openclaw 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:  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.proxyUrl https://proxy.corp.example:8443openclaw config set proxy.tls.caFile /etc/openclaw/proxy-ca.pemopenclaw gateway run

نحوه عملکرد مسیریابی

با یک URL معتبر پراکسی، فرایندهای محافظت‌شده زمان اجرا (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) نتوانند بی‌سروصدا پراکسی را دور بزنند.

طرح URL پراکسی، گام میان 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 را رعایت می‌کند.

حالت لوپ‌بک Gateway

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

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

یک proxyUrl یا OPENCLAW_PROXY_URL پیکربندی‌شده، مسیریابی مدیریت‌شده را فعال می‌کند. فقط به‌عنوان انصراف پیشرفته‌ای که URL را بدون فعال‌کردن آن ذخیره نگه می‌دارد، مقدار proxy.enabled: false را تنظیم کنید.

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

کانتینرها

برای فرمان‌های openclaw --container ...، هنگامی که OPENCLAW_PROXY_URL تنظیم شده باشد، OpenClaw آن را به CLI فرزندِ هدف‌گیری‌شده برای کانتینر ارسال می‌کند. URL باید از داخل کانتینر قابل‌دسترسی باشد — 127.0.0.1 در آنجا به خود کانتینر اشاره می‌کند، نه میزبان. OpenClaw URLهای پراکسی لوپ‌بک را برای فرمان‌های هدف‌گیری‌شده برای کانتینر رد می‌کند، مگر اینکه برای لغو صریح این بررسی، 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 نمی‌تواند تأیید کند که پراکسی شما اهداف درست را مسدود می‌کند. آن را طوری پیکربندی کنید که:

• فقط به لوپ‌بک یا یک رابط خصوصی مورد اعتماد متصل شود که تنها برای فرایند/میزبان/کانتینر/حساب سرویس OpenClaw قابل‌دسترسی باشد.
• مقصدها را خودش تفکیک کند و پس از تفکیک DNS، هنگام اتصال و بر اساس IP، هم برای HTTP ساده و هم تونل‌های CONNECT مربوط به HTTPS مسدودسازی کند.
• دورزدن‌های مبتنی بر مقصد را برای محدوده‌های لوپ‌بک، خصوصی، محلیِ پیوند، فراداده، چندپخشی، رزروشده و مستندسازی رد کند.
• از فهرست‌های مجاز نام میزبان اجتناب کند، مگر اینکه کاملاً به مسیر تفکیک 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-url در دسترس نباشد، فرمان یک مشکل پیکربندی را گزارش می‌کند؛ برای یک پیش‌بررسی یک‌باره پیش از تغییر پیکربندی، --proxy-url را ارسال کنید.

بدون --allowed-url/--denied-url، بررسی‌های پیش‌فرض چنین‌اند: https://example.com/ باید موفق شود و یک سرور موقت قناری روی لوپ‌بک که پروکسی نباید بتواند به آن دسترسی پیدا کند، باید مسدود شود. بررسی لوپ‌بک در صورت شکست انتقال، یا پاسخ غیر 2xx که فاقد توکن مختص همان اجرای قناری باشد، موفق محسوب می‌شود؛ در صورت پاسخ 2xx فاقد توکن (موفقیتی غیرمنتظره از چیزی غیر از قناری) و به‌ویژه هر پاسخی که توکن منطبق را داشته باشد، ناموفق است، زیرا این ثابت می‌کند پروکسی واقعاً مقصد لوپ‌بکی را که باید رد می‌کرد، هدایت کرده است. مقصدهای سفارشی --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 (درخواست عمومی باید موفق شود؛ درخواست‌های لوپ‌بک و فراداده باید توسط خود پروکسی مسدود شوند — 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 را به ارث می‌برند.
• WebUIهای محلی کاربر و سرورهای مدل محلی تحت پوشش یک گذر عمومی از شبکهٔ محلی نیستند — در صورت نیاز، آن‌ها را در سیاست پروکسی اپراتور در فهرست مجاز قرار دهید. استثنا، مسیر مستقیم محافظت‌شدهٔ ارائه‌دهندهٔ تعبیه‌سازی حافظهٔ Ollama همراه محصول است که به مبدأ دقیق لوپ‌بک محلی میزبان از baseUrl پیکربندی‌شدهٔ آن محدود می‌شود؛ میزبان‌های Ollama در LAN، tailnet، شبکهٔ خصوصی و عمومی همچنان از پروکسی مدیریت‌شده استفاده می‌کنند.
• هدایت مستقیم بالادستی پروکسی اشکال‌زدایی محلی (برای درخواست‌های پروکسی و تونل‌های CONNECT) هنگامی که حالت پروکسی مدیریت‌شده فعال است، به‌طور پیش‌فرض غیرفعال است؛ آن را فقط برای عیب‌یابی محلی تأییدشده فعال کنید.
• OpenClaw سیاست پروکسی شما را بازرسی، آزمایش یا تأیید نمی‌کند. تغییرات سیاست پروکسی را تغییرات عملیاتی حساس از نظر امنیتی در نظر بگیرید.