Gateway

• به‌صورت پیش‌فرض، Gateway از شروع خودداری می‌کند مگر اینکه gateway.mode=local در ~/.openclaw/openclaw.json تنظیم شده باشد. برای اجراهای موردی/توسعه‌ای از --allow-unconfigured استفاده کنید.
• openclaw onboard --mode local و openclaw setup باید gateway.mode=local را بنویسند. اگر فایل وجود دارد اما gateway.mode موجود نیست، آن را یک پیکربندی خراب یا بازنویسی‌شده تلقی کنید و به‌جای اینکه حالت محلی را به‌طور ضمنی فرض کنید، آن را تعمیر کنید.
• اگر فایل وجود دارد و gateway.mode موجود نیست، Gateway آن را آسیب مشکوک به پیکربندی تلقی می‌کند و از حدس زدن «local» برای شما خودداری می‌کند.
• بایند شدن فراتر از loopback بدون احراز هویت مسدود است (محدودیت ایمنی).
• وقتی مجاز باشد، SIGUSR1 یک راه‌اندازی مجدد درون‌فرایندی را فعال می‌کند (commands.restart به‌صورت پیش‌فرض فعال است؛ برای مسدود کردن راه‌اندازی مجدد دستی، commands.restart: false را تنظیم کنید، در حالی که اعمال/به‌روزرسانی ابزار/پیکربندی Gateway همچنان مجاز می‌ماند).
• هندلرهای SIGINT/SIGTERM فرایند Gateway را متوقف می‌کنند، اما هیچ وضعیت سفارشی ترمینال را بازنمی‌گردانند. اگر CLI را با یک TUI یا ورودی حالت خام می‌پوشانید، پیش از خروج ترمینال را بازیابی کنید.

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

• gateway status حتی وقتی پیکربندی محلی CLI وجود ندارد یا نامعتبر است، برای عیب‌یابی در دسترس می‌ماند.
• gateway status پیش‌فرض وضعیت سرویس، اتصال WebSocket، و قابلیت احراز هویتِ قابل مشاهده در زمان handshake را اثبات می‌کند. عملیات خواندن/نوشتن/مدیریت را اثبات نمی‌کند.
• probeهای عیب‌یابی برای احراز هویت دستگاه در بار نخست غیرتغییردهنده هستند: وقتی توکن دستگاه کش‌شده‌ای وجود داشته باشد از همان استفاده می‌کنند، اما فقط برای بررسی وضعیت، هویت دستگاه CLI جدید یا رکورد pairing دستگاه فقط‌خواندنی ایجاد نمی‌کنند.
• gateway status در صورت امکان SecretRefهای احراز هویت پیکربندی‌شده را برای احراز هویت probe resolve می‌کند.
• اگر یک SecretRef احراز هویت لازم در این مسیر فرمان resolve نشود، gateway status --json هنگام شکست اتصال/احراز هویت probe مقدار rpc.authWarning را گزارش می‌کند؛ --token/--password را صریحا پاس دهید یا ابتدا منبع secret را resolve کنید.
• اگر probe موفق شود، هشدارهای auth-ref resolveنشده برای جلوگیری از مثبت‌های کاذب سرکوب می‌شوند.
• وقتی یک سرویس در حال گوش‌دادن کافی نیست و لازم دارید فراخوانی‌های RPC با محدوده خواندن هم سالم باشند، در اسکریپت‌ها و اتوماسیون از --require-rpc استفاده کنید.
• --deep یک اسکن best-effort برای نصب‌های اضافی launchd/systemd/schtasks اضافه می‌کند. وقتی چند سرویس شبیه Gateway شناسایی شوند، خروجی انسانی راهنمای پاک‌سازی چاپ می‌کند و هشدار می‌دهد که بیشتر راه‌اندازی‌ها باید برای هر ماشین یک Gateway اجرا کنند.
• --deep همچنین وقتی فرایند سرویس برای restart توسط supervisor خارجی به‌صورت تمیز خارج شده باشد، handoff اخیر restart ناظر Gateway را گزارش می‌کند.
• --deep اعتبارسنجی پیکربندی را در حالت آگاه از Plugin اجرا می‌کند (pluginValidation: "full") و هشدارهای manifest مربوط به Pluginهای پیکربندی‌شده را نمایش می‌دهد (برای مثال metadata پیکربندی channel جاافتاده) تا smoke checkهای نصب و به‌روزرسانی آن‌ها را بگیرند. gateway status پیش‌فرض مسیر سریع فقط‌خواندنی را حفظ می‌کند که اعتبارسنجی Plugin را رد می‌کند.
• خروجی انسانی مسیر resolveشده لاگ فایل را به‌همراه snapshot مسیرها/اعتبار پیکربندی CLI در برابر سرویس شامل می‌شود تا به عیب‌یابی drift در profile یا state-dir کمک کند.

• در نصب‌های Linux systemd، بررسی‌های drift احراز هویت هر دو مقدار Environment= و EnvironmentFile= را از unit می‌خوانند (شامل %h، مسیرهای quoted، چند فایل، و فایل‌های اختیاری -).
• بررسی‌های drift، SecretRefهای gateway.auth.token را با env زمان اجرای ادغام‌شده resolve می‌کنند (ابتدا env فرمان سرویس، سپس fallback به env فرایند).
• اگر احراز هویت توکنی عملا فعال نباشد (gateway.auth.mode صریح برابر password/none/trusted-proxy، یا mode تنظیم نشده باشد در وضعیتی که password می‌تواند برنده شود و هیچ token candidate نمی‌تواند برنده شود)، بررسی‌های token-drift از resolve کردن توکن پیکربندی صرف‌نظر می‌کنند.

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

سطح بالا:

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

برای هر هدف (targets[].connect):

• ok: دسترسی‌پذیری پس از connect + طبقه‌بندی degraded.
• rpcOk: موفقیت کامل RPC جزئیات.
• scopeLimited: RPC جزئیات به‌دلیل نبود scope اپراتور شکست خورده است.

برای هر هدف (targets[].auth):

• role: نقش احراز هویت گزارش‌شده در hello-ok وقتی موجود باشد.
• scopes: scopeهای اعطاشده گزارش‌شده در hello-ok وقتی موجود باشند.
• capability: طبقه‌بندی قابلیت احراز هویت نمایش‌داده‌شده برای آن هدف.

• ssh_tunnel_failed: راه‌اندازی SSH tunnel شکست خورد؛ فرمان به probeهای مستقیم fallback کرد.
• multiple_gateways: بیش از یک هدف قابل دسترسی بود؛ این غیرمعمول است مگر اینکه عمدا profileهای ایزوله اجرا کنید، مانند یک rescue bot.
• auth_secretref_unresolved: یک SecretRef احراز هویت پیکربندی‌شده برای یک هدف شکست‌خورده resolve نشد.
• probe_scope_limited: اتصال WebSocket موفق شد، اما probe خواندن به‌دلیل نبود operator.read محدود شد.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• از gateway restart برای راه‌اندازی دوباره یک سرویس مدیریت‌شده استفاده کنید. gateway stop و gateway start را به‌عنوان جایگزین راه‌اندازی دوباره پشت‌سرهم اجرا نکنید.
• در macOS، gateway stop به‌طور پیش‌فرض از launchctl bootout استفاده می‌کند، که LaunchAgent را از جلسه بوت فعلی حذف می‌کند بدون اینکه غیرفعال‌سازی را پایدار کند — بازیابی خودکار KeepAlive برای خرابی‌های آینده فعال می‌ماند و gateway start بدون نیاز به launchctl enable دستی، دوباره به‌صورت تمیز فعال می‌شود. برای سرکوب پایدار KeepAlive و RunAtLoad، گزینه --disable را بدهید تا gateway تا gateway start صریح بعدی دوباره اجرا نشود؛ وقتی توقف دستی باید پس از راه‌اندازی‌های دوباره سیستم یا ریبوت‌ها باقی بماند، از این استفاده کنید.
• gateway restart --safe از Gateway در حال اجرا می‌خواهد کار فعال OpenClaw را پیش‌بررسی کند و راه‌اندازی دوباره را تا تخلیه تحویل پاسخ، اجراهای جاسازی‌شده، و اجرای وظیفه‌ها به تعویق بیندازد. --safe را نمی‌توان با --force یا --wait ترکیب کرد.
• gateway restart --wait 30s بودجه تخلیه راه‌اندازی دوباره پیکربندی‌شده را برای همان راه‌اندازی دوباره بازنویسی می‌کند. عددهای بدون واحد برحسب میلی‌ثانیه هستند؛ واحدهایی مانند s، m، و h پذیرفته می‌شوند. --wait 0 به‌صورت نامحدود منتظر می‌ماند.
• gateway restart --safe --skip-deferral راه‌اندازی دوباره امنِ آگاه از OpenClaw را اجرا می‌کند اما gate تعویق را دور می‌زند تا Gateway حتی وقتی مسدودکننده‌ها گزارش شده‌اند، راه‌اندازی دوباره را فوراً صادر کند. راه خروج اپراتور برای تعویق‌های گیرکرده اجرای وظیفه؛ به --safe نیاز دارد.
• gateway restart --force تخلیه کار فعال را رد می‌کند و فوراً راه‌اندازی دوباره انجام می‌دهد. وقتی اپراتور مسدودکننده‌های وظیفه فهرست‌شده را از قبل بررسی کرده و اکنون می‌خواهد gateway برگردد، از آن استفاده کنید.
• فرمان‌های چرخه عمر برای اسکریپت‌نویسی --json را می‌پذیرند.

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