Gateway

• تا زمانی که gateway.mode=local در ~/.openclaw/openclaw.json تنظیم نشده باشد، از شروع خودداری می‌کند. برای اجراهای موقت/توسعه از --allow-unconfigured استفاده کنید؛ این گزینه بدون نوشتن یا ترمیم پیکربندی، کنترل محافظتی را دور می‌زند.
• وقتی هنگام راه‌اندازی یک پیکربندی نامعتبرِ قابل‌ترمیم پیدا شود، ترمینال تعاملی پیشنهاد اجرای openclaw doctor --fix را می‌دهد و پس از تأیید، راه‌اندازی را یک‌بار دیگر امتحان می‌کند. اجراهای غیرتعاملی هرگز به‌طور خودکار ترمیم نمی‌کنند؛ در عوض فرمان را نمایش می‌دهند. اگر پیکربندی ترمیم‌شده همچنان نامعتبر باشد، راه‌اندازی متوقف می‌ماند.
• openclaw onboard --mode local و openclaw setup مقدار gateway.mode=local را می‌نویسند. اگر فایل پیکربندی وجود داشته باشد اما gateway.mode موجود نباشد، این وضعیت به‌عنوان پیکربندی آسیب‌دیده/بازنویسی‌شده تلقی می‌شود و Gateway از حدس‌زدن local برای شما خودداری می‌کند — فرایند آغازین را دوباره اجرا کنید، کلید را دستی تنظیم کنید، یا --allow-unconfigured را ارسال کنید.
• اتصال به فراتر از loopback بدون احراز هویت مسدود است.
• مقادیر --bind شامل lan، tailnet و custom در حال حاضر تنها از مسیرهای IPv4 تفکیک می‌شوند؛ راه‌اندازی‌های میزبان شخصیِ فقط IPv6 به یک sidecar یا پراکسی IPv4 در جلوی Gateway نیاز دارند.
• SIGUSR1 در صورت مجازبودن، راه‌اندازی مجدد درون‌پردازه‌ای را فعال می‌کند. commands.restart (پیش‌فرض: فعال) اجرای SIGUSR1های ارسال‌شده از بیرون را کنترل می‌کند؛ برای مسدودکردن راه‌اندازی‌های مجدد دستی با سیگنال سیستم‌عامل، آن را روی false تنظیم کنید. ابزار روبه‌عاملِ gateway فقط‌خواندنی است؛ عامل‌ها از طریق ابزار واگذاری openclaw که نیازمند تأیید انسان است، درخواست راه‌اندازی مجدد می‌دهند.
• SIGINT/SIGTERM پردازه را متوقف می‌کنند، اما وضعیت سفارشی ترمینال را بازیابی نمی‌کنند — اگر CLI را درون TUI یا ورودی حالت خام قرار داده‌اید، پیش از خروج خودتان ترمینال را بازیابی کنید.

• رکوردها فراداده‌های عملیاتی را نگه می‌دارند: نام رویدادها، تعدادها، اندازه‌های بایتی، مقادیر حافظه، وضعیت صف/نشست، شناسه‌های تأیید، نام کانال‌ها/Pluginها و خلاصه‌های ویرایش‌شدهٔ نشست. آن‌ها متن گفت‌وگو، بدنه‌های Webhook، خروجی ابزارها، بدنه‌های خام درخواست/پاسخ، توکن‌ها، کوکی‌ها، مقادیر محرمانه، نام‌های میزبان و شناسه‌های خام نشست را مستثنا می‌کنند. برای غیرفعال‌کردن کامل ثبت‌کننده، diagnostics.enabled: false را تنظیم کنید.
• خروج‌های مرگبار Gateway، مهلت‌های پایان‌یافتهٔ خاموش‌سازی و شکست‌های راه‌اندازی مجدد، هنگامی که ثبت‌کننده رویدادهایی داشته باشد، همان عکس فوری تشخیصی را در ~/.openclaw/logs/stability/openclaw-stability-*.json می‌نویسند. جدیدترین بسته را با openclaw gateway stability --bundle latest بررسی کنید؛ --limit، --type و --since-seq برای خروجی بسته نیز اعمال می‌شوند.

• حتی هنگامی که پیکربندی محلی CLI وجود ندارد یا نامعتبر است، برای اطلاعات تشخیصی در دسترس می‌ماند.
• خروجی پیش‌فرض، وضعیت سرویس، اتصال WebSocket و قابلیت احراز هویت قابل‌مشاهده در زمان دست‌دادن را اثبات می‌کند — نه عملیات خواندن/نوشتن/مدیریتی را.
• کاوش‌ها برای احراز هویت نخستین‌بارهٔ دستگاه، بدون تغییر هستند: در صورت وجود توکن دستگاه ذخیره‌شده، از آن دوباره استفاده می‌کنند، اما هرگز صرفاً برای بررسی وضعیت، هویت جدیدی برای دستگاه CLI یا رکورد جفت‌سازی فقط‌خواندنی ایجاد نمی‌کنند.
• در صورت امکان، SecretRefهای احراز هویت پیکربندی‌شده را برای احراز هویت کاوش برطرف می‌کند. اگر SecretRef موردنیازی برطرف نشده باشد، هنگام شکست اتصال/احراز هویت کاوش، --json مقدار rpc.authWarning را گزارش می‌کند؛ --token/--password را صریحاً ارائه کنید یا منبع راز را اصلاح کنید. پس از موفقیت کاوش، هشدارهای احراز هویت برطرف‌نشده نمایش داده نمی‌شوند.
• خروجی JSON هنگامی که Gateway در حال اجرا آن را گزارش کند، شامل gateway.version است؛ اگر کاوش دست‌دادن نتواند فرادادهٔ نسخه را فراهم کند، --require-rpc می‌تواند به بار دادهٔ RPC مربوط به status.runtimeVersion بازگردد.
• هنگامی که وجود یک سرویس در حال گوش‌دادن کافی نیست و سالم‌بودن RPC با دامنهٔ خواندن نیز لازم است، در اسکریپت‌ها/اتوماسیون از --require-rpc استفاده کنید.
• --deep نصب‌های اضافی launchd/systemd/schtasks را اسکن می‌کند؛ هنگامی که چند سرویس شبیه Gateway پیدا شود، خروجی قابل‌خواندن برای انسان نکات پاک‌سازی را چاپ می‌کند (معمولاً در هر دستگاه یک Gateway اجرا کنید) و در صورت مرتبط‌بودن، واگذاری اخیر راه‌اندازی مجدد ناظر را گزارش می‌دهد.
• --deep همچنین اعتبارسنجی پیکربندی را در حالت آگاه از Plugin ‏(pluginValidation: "full") اجرا می‌کند و هشدارهای مانیفست Plugin را نمایش می‌دهد (برای مثال نبود فرادادهٔ پیکربندی کانال). gateway status پیش‌فرض، مسیر سریع فقط‌خواندنی را حفظ می‌کند که اعتبارسنجی Plugin را نادیده می‌گیرد.
• خروجی قابل‌خواندن برای انسان، مسیر فایل گزارش برطرف‌شده را به‌همراه مسیرها/اعتبار پیکربندی CLI در مقایسه با سرویس دربر می‌گیرد تا به تشخیص انحراف پروفایل یا پوشهٔ وضعیت کمک کند.
• خروجی قابل‌خواندن برای انسان شامل Gateway heap: با محدودیت اعمال‌شده و نحوهٔ استخراج تطبیقی آن است. خروجی JSON همان گزارش را به‌شکل service.gatewayHeap ارائه می‌کند.

• بررسی‌های انحراف احراز هویت سرویس، هر دو Environment= و EnvironmentFile= را از واحد می‌خوانند (از جمله %h، مسیرهای نقل‌قول‌شده، چند فایل و فایل‌های اختیاری -).
• ‏SecretRefهای gateway.auth.token را با استفاده از محیط ادغام‌شدهٔ زمان اجرا برطرف می‌کند (ابتدا محیط فرمان سرویس، سپس محیط فرایند به‌عنوان مسیر جایگزین).
• هنگامی که احراز هویت با توکن عملاً فعال نباشد (تنظیم صریح gateway.auth.mode به password/none/trusted-proxy، یا تنظیم‌نبودن حالت در شرایطی که گذرواژه می‌تواند اولویت پیدا کند و هیچ توکن نامزدی نمی‌تواند اولویت پیدا کند)، بررسی‌های انحراف توکن از برطرف‌سازی توکن پیکربندی صرف‌نظر می‌کنند.

• Reachable: yes یعنی دست‌کم یک هدف، اتصال WebSocket را پذیرفته است.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only آنچه کاوش توانسته دربارهٔ احراز هویت اثبات کند، جدا از دسترس‌پذیری، گزارش می‌دهد.
• Read probe: ok یعنی فراخوانی‌های تفصیلی RPC با دامنهٔ خواندن (health/status/system-presence/config.get) نیز موفق بوده‌اند.
• Read probe: limited - missing scope: operator.read یعنی اتصال موفق بوده، اما RPC با دامنهٔ خواندن محدود است. این وضعیت به‌عنوان دسترس‌پذیری تنزل‌یافته گزارش می‌شود، نه شکست کامل.
• Read probe: failed پس از Connect: ok یعنی WebSocket متصل شده، اما اطلاعات تشخیصی خواندن بعدی مهلتشان پایان یافته یا ناموفق بوده‌اند — این وضعیت نیز تنزل‌یافته است، نه غیرقابل‌دسترسی.
• همانند gateway status، کاوش از احراز هویت ذخیره‌شدهٔ موجود دستگاه دوباره استفاده می‌کند، اما هویت نخستین‌بارهٔ دستگاه یا وضعیت جفت‌سازی ایجاد نمی‌کند.
• کد خروج تنها زمانی غیرصفر است که هیچ‌یک از هدف‌های کاوش‌شده در دسترس نباشند.

سطح بالا:

• ok: دست‌کم یک مقصد قابل دسترسی است.
• degraded: دست‌کم یک مقصد اتصال را پذیرفت، اما عیب‌یابی کامل RPC جزئیات را به پایان نرساند.
• capability: بهترین قابلیت مشاهده‌شده در میان مقصدهای قابل دسترسی (read_only، write_capable، admin_capable، pairing_pending، connected_no_operator_scope یا unknown).
• primaryTargetId: بهترین مقصد برای در نظر گرفتن به‌عنوان برندهٔ فعال، به‌ترتیب: URL صریح، تونل SSH، مقصد راه‌دور پیکربندی‌شده، حلقهٔ بازگشتی محلی.
• warnings[]: رکوردهای هشدار با تلاش حداکثری، شامل code، message و targetIds اختیاری.
• network: راهنمای URL حلقهٔ بازگشتی محلی/tailnet که از پیکربندی فعلی و شبکهٔ میزبان استخراج شده است.
• discovery.timeoutMs / discovery.count: بودجهٔ واقعی کشف/تعداد نتایج استفاده‌شده برای این نوبت وارسی.

برای هر مقصد (targets[].connect): ok (دسترسی‌پذیری + طبقه‌بندی تنزل‌یافته)، rpcOk (موفقیت کامل RPC جزئیات)، scopeLimited (شکست RPC جزئیات به‌دلیل نبود دامنهٔ اپراتور).

برای هر مقصد (targets[].auth): در صورت موجود بودن، role و scopes در hello-ok گزارش می‌شوند، به‌همراه طبقه‌بندی نمایش‌داده‌شدهٔ capability.

• ssh_tunnel_failed: راه‌اندازی تونل SSH ناموفق بود؛ فرمان به وارسی‌های مستقیم بازگشت.
• multiple_gateways: هویت‌های متمایز Gateway قابل دسترسی بودند، یا OpenClaw نتوانست اثبات کند که مقصدهای قابل دسترسی همان Gateway هستند. تونل SSH، ‏URL پروکسی یا URL راه‌دور پیکربندی‌شده به همان Gateway باعث فعال‌شدن این هشدار نمی‌شود.
• auth_secretref_unresolved: یک SecretRef احراز هویت پیکربندی‌شده برای مقصد ناموفق قابل حل نبود.
• probe_scope_limited: اتصال WebSocket موفق بود، اما وارسی خواندن به‌دلیل نبود operator.read محدود شد.
• local_tls_runtime_unavailable: ‏TLS محلی Gateway فعال است، اما OpenClaw نتوانست اثر انگشت گواهی محلی را بارگیری کند.

• gateway status: --url، --token، --password، --timeout، --no-probe، --require-rpc، --deep، --json
• gateway install: --port، --runtime <node> (پیش‌فرض: node)، --token، --wrapper <path>، --force، --json
• gateway restart: --safe، --skip-deferral، --force، --wait <duration>، --json
• gateway uninstall|start: --json
• gateway stop: --disable، --force، --json

• gateway start ایدمپوتنت است: وقتی سرویس مدیریت‌شده از قبل در حال اجرا باشد، فرایند در حال اجرا را گزارش می‌کند و آن را دست‌نخورده باقی می‌گذارد. سرویس بارگیری‌شده اما متوقف، مانند قبل آغاز می‌شود.
• برای راه‌اندازی مجدد سرویس مدیریت‌شده از gateway restart استفاده کنید. gateway stop و gateway start را به‌عنوان جایگزین راه‌اندازی مجدد زنجیره نکنید.
• در پوستهٔ غیرتعاملی، gateway stop به --force نیاز دارد. پایانه‌های تعاملی رفتار فعلی بدون اعلان را حفظ می‌کنند. برای خودکارسازی و آزمون‌ها، gateway run --dev یا یک --profile ایزوله با پورتی آزاد را ترجیح دهید.
• در macOS، ‏gateway stop به‌طور پیش‌فرض از launchctl bootout استفاده می‌کند که LaunchAgent را بدون پایدارسازی غیرفعال‌سازی از نشست راه‌اندازی فعلی حذف می‌کند — بازیابی خودکار KeepAlive برای خرابی‌های آینده فعال می‌ماند و gateway start بدون نیاز به launchctl enable دستی، دوباره به‌درستی فعال می‌شود. برای سرکوب پایدار KeepAlive و RunAtLoad، ‏--disable را ارسال کنید تا Gateway تا gateway start صریح بعدی دوباره ایجاد نشود؛ وقتی توقف دستی باید پس از راه‌اندازی مجدد سیستم نیز باقی بماند، از این گزینه استفاده کنید.
• تغییرات چرخهٔ عمر Gateway رکوردهای ممیزی کلید-مقدار را با تلاش حداکثری به <state-dir>/logs/gateway-restart.log می‌افزایند، از جمله عملیات آغاز، توقف و راه‌اندازی مجدد CLI، درخواست‌های راه‌اندازی مجدد ایمن، راه‌اندازی‌های مجدد ناظر و واگذاری‌های جداشده.
• فرمان‌های چرخهٔ عمر برای اسکریپت‌نویسی --json را می‌پذیرند.

• gateway install یک مقدار NODE_OPTIONS مختص heap برای سرویس Gateway مدیریت‌شده می‌نویسد. وقتی Node محدودیت کانتینر یا سرویس را گزارش کند، 50% حافظهٔ محدودشده و در غیر این صورت 50% حافظهٔ فیزیکی را هدف قرار می‌دهد.
• بازهٔ هدف اسمی 2048–8192 MiB است، با سقف اضافی 75% برای فضای آزاد حافظهٔ بومی. در میزبان‌های کوچک، این سقف فضای آزاد می‌تواند حد اعمال‌شده را به کمتر از کف اسمی 2048 MiB برساند.
• یک --max-old-space-size صریح و معتبر که از قبل در سرویس نصب‌شده ذخیره شده باشد، در نصب‌های مجدد اجباری و تعمیرات doctor حفظ می‌شود. دیگر پرچم‌های NODE_OPTIONS به سرویس مدیریت‌شده منتقل نمی‌شوند.
• NODE_OPTIONS محیطی پوسته این خط‌مشی را بازنویسی نمی‌کند. برای بررسی مقدار نصب‌شده از gateway status یا doctor استفاده کنید؛ برای بازتولید فرادادهٔ سرویس‌های قدیمی که تنظیم heap مدیریت‌شده ندارند، openclaw gateway install --force را اجرا کنید.
• این خط‌مشی فقط برای سرویس Gateway مدیریت‌شده اعمال می‌شود. gateway run پیش‌زمینه، سرویس‌های Node و واحدهای ناظر دست‌نویس، پیکربندی زمان اجرای خود را حفظ می‌کنند.

• وقتی احراز هویت توکنی به توکن نیاز دارد و gateway.auth.token توسط SecretRef مدیریت می‌شود، gateway install قابل حل بودن SecretRef را اعتبارسنجی می‌کند، اما توکن حل‌شده را در فرادادهٔ محیط سرویس پایدار نمی‌کند.
• اگر احراز هویت توکنی به توکن نیاز داشته باشد و SecretRef توکن پیکربندی‌شده حل‌نشده باشد، نصب به‌صورت بسته شکست می‌خورد و متن سادهٔ جایگزین را پایدار نمی‌کند.
• برای احراز هویت با گذرواژه روی gateway run، ‏OPENCLAW_GATEWAY_PASSWORD، ‏--password-file یا gateway.auth.password مبتنی بر SecretRef را به --password درون‌خطی ترجیح دهید.
• در حالت احراز هویت استنباط‌شده، OPENCLAW_GATEWAY_PASSWORD مختص پوسته الزامات توکن نصب را تسهیل نمی‌کند؛ هنگام نصب سرویس مدیریت‌شده از پیکربندی پایدار (gateway.auth.password یا env پیکربندی) استفاده کنید.
• اگر هم gateway.auth.token و هم gateway.auth.password پیکربندی شده باشند و gateway.auth.mode تنظیم نشده باشد، نصب تا زمانی که حالت به‌صراحت تنظیم شود مسدود می‌ماند.