Gateway

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

• رکوردها metadata عملیاتی را نگه می‌دارند: نام رویدادها، شمارش‌ها، اندازه‌های byte، خوانش‌های حافظه، وضعیت queue/session، idهای تأیید، نام‌های channel/Plugin، و خلاصه‌های نشست redacted. آن‌ها متن chat، بدنه‌های webhook، خروجی‌های ابزار، بدنه‌های خام request یا response، توکن‌ها، cookieها، مقادیر secret، hostnameها، یا idهای خام نشست را نگه نمی‌دارند. برای غیرفعال کردن کامل ضبط‌کننده، diagnostics.enabled: false را تنظیم کنید.
• هنگام خروج‌های fatal از Gateway، timeoutهای خاموشی، و شکست‌های شروع پس از بازراه‌اندازی، OpenClaw وقتی ضبط‌کننده رویداد دارد همان snapshot تشخیصی را در ~/.openclaw/logs/stability/openclaw-stability-*.json می‌نویسد. جدیدترین bundle را با openclaw gateway stability --bundle latest بررسی کنید؛ --limit، --type و --since-seq نیز روی خروجی bundle اعمال می‌شوند.

• gateway status حتی وقتی پیکربندی CLI محلی موجود نیست یا نامعتبر است، برای diagnostics در دسترس می‌ماند.
• gateway status پیش‌فرض وضعیت سرویس، اتصال WebSocket، و قابلیت احراز هویت قابل مشاهده در زمان handshake را اثبات می‌کند. عملیات خواندن/نوشتن/admin را اثبات نمی‌کند.
• probeهای diagnostic برای احراز هویت دستگاه در اولین استفاده، غیرتغییردهنده هستند: وقتی توکن دستگاه cacheشدهٔ موجودی وجود داشته باشد، از آن دوباره استفاده می‌کنند، اما فقط برای بررسی وضعیت، هویت دستگاه CLI جدید یا رکورد pairing دستگاه فقط‌خواندنی ایجاد نمی‌کنند.
• gateway status در صورت امکان SecretRefs احراز هویت پیکربندی‌شده را برای احراز هویت probe resolve می‌کند.
• اگر یک SecretRef احراز هویت الزامی در این مسیر فرمان resolve نشده باشد، وقتی اتصال/احراز هویت probe شکست بخورد، gateway status --json مقدار rpc.authWarning را گزارش می‌کند؛ --token/--password را صریحاً بدهید یا ابتدا منبع secret را resolve کنید.
• اگر probe موفق شود، هشدارهای auth-ref resolveنشده برای جلوگیری از مثبت کاذب سرکوب می‌شوند.
• وقتی probing فعال باشد، خروجی JSON شامل gateway.version است، اگر Gateway در حال اجرا آن را گزارش کند؛ اگر probe handshake بعدی نتواند metadata نسخه را فراهم کند، --require-rpc می‌تواند به payload RPC مربوط به status.runtimeVersion بازگردد.
• وقتی یک سرویس در حال گوش‌دادن کافی نیست و لازم است فراخوانی‌های RPC با دامنهٔ خواندن هم سالم باشند، از --require-rpc در scriptها و automation استفاده کنید.
• --deep یک اسکن best-effort برای نصب‌های اضافی launchd/systemd/schtasks اضافه می‌کند. وقتی چند سرویس شبیه gateway شناسایی شوند، خروجی انسانی راهنمای پاک‌سازی چاپ می‌کند و هشدار می‌دهد که بیشتر setupها باید یک gateway برای هر ماشین اجرا کنند.
• --deep همچنین handoff اخیر restart سرپرست Gateway را گزارش می‌کند، وقتی process سرویس برای restart سرپرست خارجی به‌صورت clean خارج شده باشد.
• --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 زمان اجرای mergeشده resolve می‌کنند (ابتدا env فرمان سرویس، سپس process env به‌عنوان fallback).
• اگر احراز هویت توکنی عملاً فعال نباشد (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 را پذیرفته، اما diagnostics خواندن بعدی timeout شده یا شکست خورده است. این هم قابل دسترسی degraded است، نه Gateway غیرقابل دسترس.
• مانند gateway status، probe از احراز هویت دستگاه cacheشدهٔ موجود دوباره استفاده می‌کند اما هویت دستگاه یا وضعیت pairing اولین استفاده را ایجاد نمی‌کند.
• exit code فقط وقتی غیرصفر است که هیچ هدف probeشده‌ای قابل دسترس نباشد.

سطح بالا:

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

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

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

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

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

• ssh_tunnel_failed: راه‌اندازی تونل SSH شکست خورد؛ فرمان به probeهای مستقیم fallback کرد.
• multiple_gateways: هویت‌های متمایز gateway قابل دسترس بودند، یا OpenClaw نتوانست اثبات کند هدف‌های قابل دسترس همان gateway هستند. یک تونل SSH، URL proxy، یا URL remote پیکربندی‌شده به همان gateway این هشدار را فعال نمی‌کند.
• 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 را به‌عنوان جایگزین restart زنجیره نکنید.
• در macOS، gateway stop به‌طور پیش‌فرض از launchctl bootout استفاده می‌کند، که LaunchAgent را بدون پایدار کردن غیرفعال‌سازی از نشست بوت فعلی حذف می‌کند — بازیابی خودکار KeepAlive برای خرابی‌های آینده فعال می‌ماند و gateway start بدون نیاز به launchctl enable دستی دوباره به‌صورت تمیز فعال می‌شود. برای سرکوب پایدار KeepAlive و RunAtLoad، --disable را پاس دهید تا gateway تا gateway start صریح بعدی دوباره اجرا نشود؛ از این گزینه زمانی استفاده کنید که توقف دستی باید پس از reboot یا راه‌اندازی دوباره سیستم هم باقی بماند.
• gateway restart --safe از Gateway در حال اجرا می‌خواهد کار فعال را پیش‌پرواز کند و پس از تخلیه کار فعال، یک restart ادغام‌شده زمان‌بندی کند. restart ایمن پیش‌فرض تا سقف gateway.reload.deferralTimeoutMs پیکربندی‌شده (پیش‌فرض ۵ دقیقه) منتظر کار فعال می‌ماند؛ وقتی این بودجه تمام شود restart اجباری می‌شود. برای انتظار ایمن نامحدود که هرگز اجباری نمی‌شود، gateway.reload.deferralTimeoutMs را روی 0 تنظیم کنید. --safe نمی‌تواند با --force یا --wait ترکیب شود.
• gateway restart --wait 30s بودجه تخلیه restart پیکربندی‌شده را برای همان restart بازنویسی می‌کند. عددهای بدون واحد میلی‌ثانیه هستند؛ واحدهایی مانند s، m، و h پذیرفته می‌شوند. --wait 0 به‌طور نامحدود منتظر می‌ماند.
• gateway restart --safe --skip-deferral restart ایمن آگاه از OpenClaw را اجرا می‌کند اما دروازه defer را دور می‌زند تا Gateway حتی وقتی blocker گزارش شده‌اند restart را بی‌درنگ منتشر کند. راه گریز اپراتور برای deferهای اجرای task گیرکرده؛ به --safe نیاز دارد.
• gateway restart --force تخلیه کار فعال را نادیده می‌گیرد و بی‌درنگ restart می‌کند. زمانی از آن استفاده کنید که اپراتور blockerهای task فهرست‌شده را از قبل بررسی کرده و می‌خواهد gateway همین حالا برگردد.
• فرمان‌های چرخه عمر برای اسکریپت‌نویسی --json را می‌پذیرند.

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