راهنمای عملیاتی 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، و اتصال‌های channel.
• یک پورت multiplexed واحد برای:
  • کنترل/RPC از طریق WebSocket
  • APIهای HTTP، سازگار با OpenAI (/v1/models، /v1/embeddings، /v1/chat/completions، /v1/responses، /tools/invoke)
  • 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 و memory انتظار /v1/embeddings را دارند.
• clientهای agent-native به‌طور فزاینده‌ای /v1/responses را ترجیح می‌دهند.

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

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

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

اولویت پورت و bind

سرویس‌های gateway نصب‌شده --port حل‌شده را در metadata ناظر ثبت می‌کنند. پس از تغییر 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

مجموعه فرمان‌های operator

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 و channel را میزبانی کند.

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

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

openclaw gateway status --deepopenclaw gateway probe

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

• gateway status --deep می‌تواند Other gateway-like services detected (best effort) را گزارش کند و وقتی نصب‌های stale launchd/systemd/schtasks هنوز وجود دارند، راهنمای cleanup چاپ کند.
• gateway probe وقتی بیش از یک هدف پاسخ دهد می‌تواند درباره multiple reachable gateways هشدار دهد.
• اگر این عمدی است، پورت‌ها، config/state، و ریشه‌های workspace را برای هر gateway جدا کنید.

چک‌لیست برای هر instance:

• 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

سپس clientها را به‌صورت محلی به 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 143KillMode=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

مسیر سریع profile توسعه

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

پیش‌فرض‌ها شامل state/config جداافتاده و پورت پایه gateway برابر 19001 هستند.

مرجع سریع protocol (نمای operator)

• نخستین frame client باید 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).
• eventهای رایج شامل connect.challenge، agent، chat، session.message، session.tool، sessions.changed، presence، tick، health، heartbeat، eventهای چرخه‌عمر pairing/approval، و shutdown هستند.

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

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

مستندات کامل protocol را ببینید: Protocol Gateway.

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

زنده بودن

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

آمادگی

openclaw gateway statusopenclaw channels status --probeopenclaw health

بازیابی gap

eventها replay نمی‌شوند. در gapهای sequence، پیش از ادامه state (health، system-presence) را refresh کنید.

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

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

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

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

مرتبط:

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

مرتبط

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