راهنمای عملیاتی Gateway

از این صفحه برای راه‌اندازی روز نخست و عملیات روز دوم سرویس Gateway استفاده کنید.

راه‌اندازی محلی ۵دقیقه‌ای

openclaw gateway --port 18789# اشکال‌زدایی/ردیابی در stdio بازتاب داده می‌شودopenclaw gateway --port 18789 --verbose# شنونده را در درگاه انتخاب‌شده به‌اجبار متوقف کنید، سپس راه‌اندازی کنیدopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

مدل زمان اجرا

• یک فرایند همیشه‌فعال برای مسیریابی، صفحه کنترل و اتصال‌های کانال.
• یک درگاه چندتسهیمی واحد برای:
  • کنترل/RPC مبتنی بر WebSocket
  • APIهای HTTP ‏(/v1/models، /v1/embeddings، /v1/chat/completions، /v1/responses، /tools/invoke)
  • مسیرهای HTTP مربوط به Plugin، مانند /api/v1/admin/rpc اختیاری
  • رابط کاربری کنترل و هوک‌ها
• حالت اتصال پیش‌فرض: loopback. درون یک محیط کانتینری شناسایی‌شده، پیش‌فرض مؤثر auto است (برای هدایت درگاه به 0.0.0.0 تفکیک می‌شود)، مگر اینکه سرویس‌دهی/تونل Tailscale فعال باشد که همیشه loopback را تحمیل می‌کند.
• احراز هویت به‌طور پیش‌فرض الزامی است. راه‌اندازی‌های مبتنی بر راز مشترک از gateway.auth.token / gateway.auth.password (یا OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) استفاده می‌کنند و راه‌اندازی‌های پراکسی معکوس غیر-loopback می‌توانند از gateway.auth.mode: "trusted-proxy" استفاده کنند.

نقاط پایانی سازگار با OpenAI

سطح سازگاری OpenClaw با بیشترین اهرم:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

دلیل اهمیت این مجموعه:

• بیشتر یکپارچه‌سازی‌های Open WebUI، LobeChat و LibreChat ابتدا /v1/models را کاوش می‌کنند.
• بسیاری از پایپ‌لاین‌های RAG و حافظه انتظار /v1/embeddings را دارند.
• کلاینت‌های بومی عامل به‌طور فزاینده‌ای /v1/responses را ترجیح می‌دهند.

/v1/models عامل‌محور است: برای هر عامل پیکربندی‌شده، openclaw، openclaw/default و openclaw/<agentId> را بازمی‌گرداند. openclaw/default نام مستعار پایداری است که همیشه به عامل پیش‌فرض پیکربندی‌شده نگاشت می‌شود. هنگامی که می‌خواهید ارائه‌دهنده/مدل پشتیبان را بازنویسی کنید، x-openclaw-model را ارسال کنید؛ در غیر این صورت، تنظیمات عادی مدل و تعبیه‌سازی عامل انتخاب‌شده کنترل را حفظ می‌کند.

همه این موارد روی درگاه اصلی Gateway اجرا می‌شوند و از همان مرز احراز هویت اپراتور مورد اعتماد استفاده می‌کنند که بقیه API ‏HTTP مربوط به Gateway به‌کار می‌برند.

RPC مدیریتی HTTP ‏(POST /api/v1/admin/rpc) یک مسیر Plugin جداگانه و به‌طور پیش‌فرض غیرفعال برای ابزارهای میزبان است که نمی‌توانند از RPC مبتنی بر WebSocket استفاده کنند. به RPC مدیریتی HTTP مراجعه کنید.

تقدم درگاه و اتصال

سرویس‌های Gateway نصب‌شده، --port تعیین‌شده را در فراداده ناظر ثبت می‌کنند. پس از تغییر gateway.port، فرمان openclaw doctor --fix یا openclaw gateway install --force را اجرا کنید تا launchd/systemd/schtasks فرایند را روی درگاه جدید راه‌اندازی کند.

راه‌اندازی Gateway هنگام مقداردهی اولیه مبدأهای محلی رابط کاربری کنترل برای اتصال‌های غیر-loopback، از همان درگاه و اتصال مؤثر استفاده می‌کند. برای نمونه، --bind lan --port 3000 پیش از اجرای اعتبارسنجی زمان اجرا، http://localhost:3000 و http://127.0.0.1:3000 را مقداردهی اولیه می‌کند. هر مبدأ مرورگر راه‌دور، مانند URLهای پراکسی HTTPS، را صراحتاً به gateway.controlUi.allowedOrigins اضافه کنید.

حالت‌های بارگذاری مجدد گرم

مجموعه فرمان‌های اپراتور

openclaw gateway statusopenclaw gateway status --deep   # یک پویش سرویس در سطح سیستم اضافه می‌کندopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep برای کشف سرویس بیشتر (LaunchDaemonها/واحدهای سیستمی systemd/schtasks) است، نه یک کاوش عمیق‌تر سلامت RPC.

چند Gateway (روی یک میزبان)

بیشتر نصب‌ها باید روی هر دستگاه یک Gateway اجرا کنند. یک Gateway می‌تواند میزبان چند عامل و کانال باشد. تنها زمانی به چند Gateway نیاز دارید که عمداً جداسازی یا یک ربات نجات بخواهید.

بررسی‌های مفید:

openclaw gateway status --deepopenclaw gateway probe

آنچه باید انتظار داشت:

• gateway status --deep می‌تواند Other gateway-like services detected (best effort) را گزارش کند و هنگامی که نصب‌های قدیمی launchd/systemd/schtasks هنوز باقی مانده‌اند، راهنمای پاک‌سازی را نمایش دهد.
• gateway probe می‌تواند درباره multiple reachable gateway identities هشدار دهد، هنگامی که Gatewayهای متمایز پاسخ می‌دهند یا OpenClaw نمی‌تواند اثبات کند مقصدهای دسترس‌پذیر همان Gateway هستند. یک تونل SSH، نشانی پراکسی یا نشانی راه‌دور پیکربندی‌شده به همان Gateway، حتی اگر درگاه‌های انتقال متفاوت باشند، یک Gateway با چند انتقال محسوب می‌شود.
• اگر این کار عمدی است، درگاه‌ها، پیکربندی/وضعیت و ریشه‌های فضای کاری را برای هر Gateway جدا کنید.

چک‌لیست هر نمونه:

• gateway.port یکتا
• OPENCLAW_CONFIG_PATH یکتا
• OPENCLAW_STATE_DIR یکتا
• agents.defaults.workspace یکتا

نمونه:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

راه‌اندازی تفصیلی: /gateway/multiple-gateways.

دسترسی راه‌دور

روش ترجیحی: Tailscale/VPN. روش جایگزین: تونل SSH.

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

سپس کلاینت‌ها را به‌صورت محلی به ws://127.0.0.1:18789 متصل کنید.

مراجعه کنید به: Gateway راه‌دور، احراز هویت، Tailscale.

نظارت و چرخه عمر سرویس

برای قابلیت اطمینان مشابه محیط عملیاتی، از اجرای تحت نظارت استفاده کنید.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

خطاهای پیکربندی نامعتبر با کد 78 خارج می‌شوند. واحدهای systemd لینوکس از RestartPreventExitStatus=78 استفاده می‌کنند تا تا زمان اصلاح پیکربندی از راه‌اندازی مجدد جلوگیری شود. launchd و Windows Task Scheduler قاعده توقف معادل برای هر کد خروج ندارند؛ بنابراین Gateway تاریخچه راه‌اندازی‌های سریع و ناپاک را نیز ماندگار می‌کند و پس از شکست‌های مکرر راه‌اندازی، شروع خودکار حساب‌های کانال/ارائه‌دهنده را متوقف می‌کند. در آن حالت امن، صفحه کنترل همچنان برای بازرسی و تعمیر راه‌اندازی می‌شود، بارگذاری‌های مجدد گرم پیکربندی و secrets.reload از بازراه‌اندازی خودکار کانال‌ها خودداری می‌کنند و یک درخواست صریح channels.start از سوی اپراتور می‌تواند این توقف را لغو کند.

مسیر سریع پروفایل توسعه

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

پیش‌فرض‌ها شامل وضعیت/پیکربندی جداشده و درگاه پایه Gateway با مقدار 19001 هستند.

مرجع سریع پروتکل (نمای اپراتور)

• نخستین فریم کلاینت باید connect باشد.
• Gateway یک فریم hello-ok را همراه با یک snapshot‏ (presence، health، stateVersion، uptimeMs) به‌علاوهٔ محدودیت‌های policy‏ (maxPayload، maxBufferedBytes، tickIntervalMs) برمی‌گرداند.
• hello-ok.features.methods / events یک فهرست اکتشافی محافظه‌کارانه هستند، نه خروجی تولیدشده‌ای از تمام مسیرهای کمکی قابل فراخوانی.
• درخواست‌ها: req(method, params) → res(ok/payload|error).
• رویدادهای رایج شامل connect.challenge، agent، chat، session.message، session.operation، session.tool، رویدادهای انتخابی session.approval، sessions.changed، presence، tick، health، heartbeat، رویدادهای چرخهٔ عمر جفت‌سازی/تأیید و shutdown هستند.

اجرای عامل‌ها دو مرحله دارد:

1. تأیید دریافت فوری پذیرفته‌شدن (status:"accepted")
2. پاسخ نهایی تکمیل (status:"ok"|"error")، با رویدادهای جریانی agent در فاصلهٔ میان آن‌ها.

مستندات کامل پروتکل را ببینید: پروتکل Gateway.

بررسی‌های عملیاتی

زنده‌بودن

• اتصال WS را باز کنید و connect را بفرستید.
• انتظار پاسخ hello-ok همراه با تصویر لحظه‌ای وضعیت را داشته باشید.

آمادگی

openclaw gateway statusopenclaw channels status --probeopenclaw health

بازیابی شکاف

رویدادها دوباره پخش نمی‌شوند. در صورت وجود شکاف در توالی، پیش از ادامه وضعیت را تازه‌سازی کنید (health، system-presence).

نشانه‌های رایج خرابی

برای مراحل کامل تشخیص، از عیب‌یابی Gateway استفاده کنید.

تضمین‌های ایمنی

• کلاینت‌های پروتکل Gateway هنگامی که Gateway در دسترس نباشد، سریعاً با خطا متوقف می‌شوند (هیچ بازگشت ضمنی به کانال مستقیم وجود ندارد).
• فریم‌های نخست نامعتبر یا غیراتصالی رد می‌شوند و اتصال بسته می‌شود.
• خاموش‌سازی تدریجی، پیش از بسته‌شدن سوکت رویداد shutdown را منتشر می‌کند.

مرتبط

• پیکربندی
• عیب‌یابی Gateway
• فرایند پس‌زمینه
• سلامت
• Doctor
• احراز هویت
• دسترسی راه‌دور
• مدیریت اسرار