الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

استخدم هذه الصفحة لبدء تشغيل خدمة Gateway في اليوم الأول وعمليات اليوم الثاني.

استكشاف الأخطاء المتعمق

تشخيصات تبدأ بالأعراض مع سلالم أوامر دقيقة وبصمات السجلات.

الإعدادات

دليل إعداد موجه للمهام + مرجع إعدادات كامل.

إدارة الأسرار

عقد SecretRef، وسلوك لقطة وقت التشغيل، وعمليات الترحيل/إعادة التحميل.

عقد خطة الأسرار

قواعد الهدف/المسار الدقيقة لـ secrets apply وسلوك ملف تعريف المصادقة المعتمد على المراجع فقط.

​
بدء تشغيل محلي خلال 5 دقائق

1

بدء تشغيل 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
2

التحقق من صحة الخدمة

openclaw gateway status
openclaw status
openclaw logs --follow
خط الأساس السليم: Runtime: running، وConnectivity probe: ok، وCapability: ... التي تطابق ما تتوقعه. استخدم openclaw gateway status --require-rpc عندما تحتاج إلى إثبات RPC بنطاق القراءة، وليس مجرد قابلية الوصول.
3

التحقق من جاهزية القناة

openclaw channels status --probe
مع Gateway قابل للوصول، يشغل هذا فحوصات قنوات مباشرة لكل حساب وعمليات تدقيق اختيارية. إذا كان Gateway غير قابل للوصول، يعود CLI إلى ملخصات قنوات مستندة إلى الإعدادات فقط بدلا من مخرجات الفحص المباشر.
تراقب إعادة تحميل إعدادات Gateway مسار ملف الإعدادات النشط (المحلول من الإعدادات الافتراضية للملف الشخصي/الحالة، أو من OPENCLAW_CONFIG_PATH عند ضبطه). الوضع الافتراضي هو gateway.reload.mode="hybrid". بعد أول تحميل ناجح، تخدم العملية الجارية لقطة إعدادات الذاكرة النشطة؛ وتستبدل إعادة التحميل الناجحة تلك اللقطة ذرّيا.

​
نموذج وقت التشغيل

  • عملية واحدة تعمل دائما للتوجيه، ومستوى التحكم، واتصالات القنوات.
  • منفذ واحد متعدد الإرسال لـ:
    • تحكم/RPC عبر WebSocket
    • واجهات HTTP API، متوافقة مع OpenAI (/v1/models، /v1/embeddings، /v1/chat/completions، /v1/responses، /tools/invoke)
    • واجهة التحكم والخطافات
  • وضع الربط الافتراضي: 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 الرئيسي وتستخدم حد مصادقة المشغل الموثوق نفسه كبقية واجهة Gateway HTTP API.

​
أسبقية المنفذ والربط

الإعدادترتيب الحل
منفذ Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
وضع الربطCLI/override → gateway.bind → loopback
تسجل خدمات 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 صراحة.

​
أوضاع إعادة التحميل الساخن

gateway.reload.modeالسلوك
offلا توجد إعادة تحميل للإعدادات
hotتطبيق التغييرات الآمنة ساخنا فقط
restartإعادة التشغيل عند تغييرات تتطلب إعادة تحميل
hybrid (افتراضي)تطبيق ساخن عندما يكون آمنا، وإعادة التشغيل عند اللزوم

​
مجموعة أوامر المشغل

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/schtasks)، وليس فحصا أعمق لصحة RPC.

​
عدة Gateways (المضيف نفسه)

يجب أن تشغل معظم عمليات التثبيت Gateway واحدا لكل جهاز. يمكن لـ Gateway واحد استضافة عدة وكلاء وقنوات. لا تحتاج إلى عدة Gateways إلا عندما تريد العزل عمدا أو بوت إنقاذ. فحوصات مفيدة: 
openclaw gateway status --deep
openclaw gateway probe
ما يمكن توقعه:
  • يمكن لـ gateway status --deep الإبلاغ عن Other gateway-like services detected (best effort) وطباعة تلميحات تنظيف عندما تبقى تثبيتات launchd/systemd/schtasks قديمة.
  • يمكن لـ gateway probe التحذير من multiple reachable gateways عندما يجيب أكثر من هدف واحد.
  • إذا كان ذلك مقصودا، فاعزل المنافذ والإعدادات/الحالة وجذور مساحات العمل لكل 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 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.
لا تتجاوز أنفاق SSH مصادقة Gateway. بالنسبة لمصادقة السر المشترك، ما يزال يجب على العملاء إرسال token/password حتى عبر النفق. وبالنسبة للأوضاع الحاملة للهوية، ما يزال على الطلب استيفاء مسار المصادقة ذلك.
راجع: Gateway البعيد، المصادقة، Tailscale.

​
الإشراف ودورة حياة الخدمة

استخدم التشغيل تحت الإشراف لموثوقية شبيهة بالإنتاج. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
استخدم openclaw gateway restart لإعادة التشغيل. لا تسلسل openclaw gateway stop وopenclaw gateway start كبديل لإعادة التشغيل.على macOS، يستخدم gateway stop الأمر launchctl bootout افتراضيا — وهذا يزيل LaunchAgent من جلسة الإقلاع الحالية دون حفظ تعطيل دائم، لذلك يستمر الاسترداد التلقائي KeepAlive في العمل بعد الأعطال غير المتوقعة، ويعيد gateway start التمكين بنظافة. لكبت إعادة التشغيل التلقائي بشكل دائم عبر عمليات إعادة الإقلاع، مرر --disable: openclaw gateway stop --disable.تسميات LaunchAgent هي ai.openclaw.gateway (افتراضي) أو ai.openclaw.<profile> (ملف شخصي مسمى). يدقق openclaw doctor انحراف إعدادات الخدمة ويصلحه.

​
المسار السريع لملف التطوير الشخصي

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
تشمل الإعدادات الافتراضية حالة/إعدادات معزولة ومنفذ Gateway الأساسي 19001.

​
مرجع سريع للبروتوكول (عرض المشغل)

  • يجب أن يكون أول إطار من العميل هو connect.
  • يعيد Gateway لقطة hello-ok (presence، health، stateVersion، uptimeMs، الحدود/السياسة).
  • hello-ok.features.methods / events هي قائمة اكتشاف محافظة، وليست تفريغا مولدا لكل مسار مساعد قابل للاستدعاء.
  • الطلبات: req(method, params) → res(ok/payload|error).
  • تشمل الأحداث الشائعة connect.challenge، وagent، وchat، وsession.message، وsession.tool، وsessions.changed، وpresence، وtick، وhealth، وheartbeat، وأحداث دورة حياة الاقتران/الموافقة، وshutdown.
تشغيلات الوكيل من مرحلتين:
  1. إقرار قبول فوري (status:"accepted")
  2. استجابة إكمال نهائية (status:"ok"|"error")، مع أحداث agent مبثوثة بينها.
راجع وثائق البروتوكول الكاملة: بروتوكول Gateway.

​
الفحوصات التشغيلية

​
الحيوية

  • افتح WS وأرسل connect.
  • توقع استجابة hello-ok مع لقطة.

​
الجاهزية

openclaw gateway status
openclaw channels status --probe
openclaw health

​
استرداد الفجوات

لا يعاد تشغيل الأحداث. عند فجوات التسلسل، حدّث الحالة (health، system-presence) قبل المتابعة.

​
بصمات الفشل الشائعة

التوقيعالمشكلة المحتملة
refusing to bind gateway ... without authربط غير حلقة الرجوع من دون مسار مصادقة Gateway صالح
another gateway instance is already listening / EADDRINUSEتعارض في المنفذ
Gateway start blocked: set gateway.mode=localتم ضبط الإعدادات على الوضع البعيد، أو أن وسم الوضع المحلي مفقود من إعدادات تالفة
unauthorized أثناء الاتصالعدم تطابق المصادقة بين العميل وGateway
للحصول على سلالم التشخيص الكاملة، استخدم استكشاف أخطاء Gateway وإصلاحها.

​
ضمانات السلامة

  • تفشل عملاء بروتوكول Gateway بسرعة عندما لا يكون Gateway متاحًا (لا يوجد رجوع احتياطي ضمني إلى قناة مباشرة).
  • تُرفض الإطارات الأولى غير الصالحة/غير الخاصة بالاتصال وتُغلق.
  • يصدر الإيقاف المنظّم حدث shutdown قبل إغلاق المقبس.
ذات صلة:

​
ذات صلة