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

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

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

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

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

# مدل زمان اجرا

• یک فرایند همیشه روشن برای مسیریابی، control plane، و اتصال‌های کانال.
• یک پورت multiplexed واحد برای:
  • کنترل/RPC از طریق WebSocket
  • APIهای HTTP، سازگار با OpenAI (/v1/models، /v1/embeddings، /v1/chat/completions، /v1/responses، /tools/invoke)
  • 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 نام مستعار پایداری است که همیشه به agent پیش‌فرض پیکربندی‌شده نگاشت می‌شود.
• وقتی override برای backend provider/model می‌خواهید از x-openclaw-model استفاده کنید؛ در غیر این صورت، مدل عادی و راه‌اندازی embedding مربوط به agent انتخاب‌شده کنترل را حفظ می‌کند.

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

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

سرویس‌های Gateway نصب‌شده --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

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

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

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

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

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

فقط زمانی به چند gateway نیاز دارید که عمدا isolation یا rescue bot بخواهید.

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

openclaw gateway status --deep
openclaw gateway probe

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

• gateway status --deep می‌تواند Other gateway-like services detected (best effort) را گزارش کند و وقتی نصب‌های قدیمی launchd/systemd/schtasks هنوز باقی هستند، راهنمای cleanup چاپ کند.
• gateway probe وقتی بیش از یک target پاسخ دهد می‌تواند درباره 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 19001
OPENCLAW_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@host

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

ببینید: Remote Gateway، Authentication، Tailscale.

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

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

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

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

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

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

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

• نخستین frame کلاینت باید connect باشد.
• Gateway snapshot مربوط به hello-ok را برمی‌گرداند (presence، health، stateVersion، uptimeMs، limits/policy).
• hello-ok.features.methods / events یک فهرست conservative discovery است، نه dump تولیدشده از هر helper route قابل فراخوانی.
• درخواست‌ها: 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های streamed مربوط به agent در بین آن‌ها.

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

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

# زنده بودن

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

# آمادگی

openclaw gateway status
openclaw channels status --probe
openclaw health

# بازیابی gap

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

# امضاهای رایج failure

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

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

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

مرتبط:

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

# مرتبط

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