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

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

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

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

مدل زمان اجرا

• یک فرایند همیشه روشن برای مسیریابی، control plane، و اتصال‌های کانال.
• یک پورت multiplexed واحد برای:
  • کنترل/RPC WebSocket
  • APIهای HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • مسیرهای HTTP مربوط به Plugin، مانند /api/v1/admin/rpc اختیاری
  • Control UI و hookها
• حالت bind پیش‌فرض: loopback.
• احراز هویت به‌طور پیش‌فرض الزامی است. راه‌اندازی‌های shared-secret از gateway.auth.token / gateway.auth.password (یا OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) استفاده می‌کنند، و راه‌اندازی‌های reverse-proxy غیر loopback می‌توانند از gateway.auth.mode: "trusted-proxy" استفاده کنند.

endpointهای سازگار با 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 را probe می‌کنند.
• بسیاری از pipelineهای RAG و حافظه انتظار /v1/embeddings را دارند.
• کلاینت‌های agent-native به‌طور فزاینده‌ای /v1/responses را ترجیح می‌دهند.

نکته برنامه‌ریزی:

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

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

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

تقدم پورت و bind

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

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

حالت‌های hot reload

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

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

چند Gateway (همان میزبان)

بیشتر نصب‌ها باید برای هر ماشین یک Gateway اجرا کنند. یک Gateway واحد می‌تواند چند agent و کانال را میزبانی کند.

فقط زمانی به چند Gateway نیاز دارید که عمداً isolation یا bot نجات می‌خواهید.

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

openclaw gateway status --deepopenclaw gateway probe

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

• gateway status --deep می‌تواند Other gateway-like services detected (best effort) را گزارش کند و وقتی نصب‌های قدیمی launchd/systemd/schtasks هنوز وجود دارند، راهنمای cleanup چاپ کند.
• gateway probe وقتی Gatewayهای متمایز پاسخ می‌دهند، یا وقتی OpenClaw نمی‌تواند ثابت کند هدف‌های قابل دسترس همان Gateway هستند، می‌تواند درباره multiple reachable gateway identities هشدار دهد. یک تونل SSH، URL proxy، یا URL راه دور پیکربندی‌شده به همان Gateway، یک Gateway با چند transport است، حتی وقتی پورت‌های transport متفاوت باشند.
• اگر این عمدی است، پورت‌ها، پیکربندی/وضعیت، و ریشه‌های workspace را برای هر 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. fallback: تونل SSH.

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

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

ببینید: Gateway راه دور، احراز هویت، Tailscale.

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

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

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 <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=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

مسیر سریع نمایه توسعه

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

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

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

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

اجرای agent دو مرحله‌ای است:

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

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

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

زنده بودن

• WS را باز کنید و connect ارسال کنید.
• انتظار پاسخ hello-ok همراه با snapshot را داشته باشید.

آمادگی

openclaw gateway statusopenclaw channels status --probeopenclaw health

بازیابی شکاف

رویدادها replay نمی‌شوند. هنگام شکاف‌های sequence، پیش از ادامه وضعیت را refresh کنید (health، system-presence).

امضاهای رایج خرابی

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

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

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

مرتبط:

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

مرتبط

• پیکربندی
• عیب‌یابی Gateway
• دسترسی راه دور
• مدیریت اسرار