openclaw agent

تشغيل دورة وكيل عبر Gateway (استخدم --local للتضمين). استخدم --agent <id> لاستهداف وكيل مُعدّ مباشرةً.

مرّر محدد جلسة واحدًا على الأقل:

• --to <dest>
• --session-key <key>
• --session-id <id>
• --agent <id>

ذات صلة:

• أداة إرسال الوكيل: إرسال الوكيل

الخيارات

• -m, --message <text>: نص الرسالة
• --message-file <path>: قراءة نص الرسالة من ملف UTF-8
• -t, --to <dest>: المستلم المستخدم لاشتقاق مفتاح الجلسة
• --session-key <key>: مفتاح جلسة صريح لاستخدامه في التوجيه
• --session-id <id>: معرف جلسة صريح
• --agent <id>: معرف الوكيل؛ يتجاوز ارتباطات التوجيه
• --model <id>: تجاوز النموذج لهذا التشغيل (provider/model أو معرف النموذج)
• --thinking <level>: مستوى تفكير الوكيل (off، minimal، low، medium، high، بالإضافة إلى المستويات المخصصة المدعومة من المزود مثل xhigh أو adaptive أو max)
• --verbose <on|off>: الاحتفاظ بمستوى الإسهاب للجلسة
• --channel <channel>: قناة التسليم؛ اتركه لاستخدام قناة الجلسة الرئيسية
• --reply-to <target>: تجاوز هدف التسليم
• --reply-channel <channel>: تجاوز قناة التسليم
• --reply-account <id>: تجاوز حساب التسليم
• --local: تشغيل الوكيل المضمن مباشرةً (بعد التحميل المسبق لسجل Plugin)
• --deliver: إرسال الرد مرة أخرى إلى القناة/الهدف المحدد
• --timeout <seconds>: تجاوز مهلة الوكيل (الافتراضي 600 أو قيمة الإعدادات)
• --json: إخراج JSON

أمثلة

openclaw agent --to +15555550123 --message "status update" --deliveropenclaw agent --agent ops --message "Summarize logs"openclaw agent --agent ops --message-file ./task.mdopenclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"openclaw agent --agent ops --session-key incident-42 --message "Summarize status"openclaw agent --session-id 1234 --message "Summarize inbox" --thinking mediumopenclaw agent --to +15555550123 --message "Trace logs" --verbose on --jsonopenclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"openclaw agent --agent ops --message "Run locally" --local

ملاحظات

• مرّر واحدًا بالضبط من --message أو --message-file. يحتفظ --message-file بمحتوى الملف متعدد الأسطر بعد إزالة UTF-8 BOM اختياري، ويرفض الملفات غير الصالحة كـ UTF-8.
• يعود وضع Gateway إلى الوكيل المضمن عند فشل طلب Gateway. استخدم --local لفرض التنفيذ المضمن من البداية.
• لا يزال --local يحمّل سجل Plugin مسبقًا أولًا، لذلك تبقى المزودات والأدوات والقنوات المقدمة من Plugin متاحة أثناء التشغيلات المضمنة.
• تُعامل تشغيلات --local وتشغيلات الرجوع المضمنة كتشغيلات لمرة واحدة. تُتقاعد موارد loopback الخاصة بـ MCP المجمّعة وجلسات stdio الدافئة لـ Claude التي فُتحت لذلك العملية المحلية بعد الرد، بحيث لا تبقي الاستدعاءات النصية العمليات الفرعية المحلية حيّة.
• تترك التشغيلات المدعومة من Gateway موارد loopback الخاصة بـ MCP المملوكة لـ Gateway ضمن عملية Gateway قيد التشغيل؛ قد يظل العملاء الأقدم يرسلون علم التنظيف التاريخي، لكن Gateway يقبله كعملية توافق بلا أثر.
• يؤثر --channel و--reply-channel و--reply-account في تسليم الرد، لا في توجيه الجلسة.
• يحدد --session-key مفتاح جلسة صريحًا. يجب أن تستخدم المفاتيح ذات بادئة الوكيل agent:<agent-id>:<session-key>، ويجب أن يطابق --agent معرف وكيل المفتاح عند تقديمهما معًا. تُنطاق المفاتيح العارية غير sentinel إلى --agent عند توفيره، أو إلى الوكيل الافتراضي المُعدّ بخلاف ذلك؛ على سبيل المثال، يوجّه --agent ops --session-key incident-42 إلى agent:ops:incident-42. يبقى الحرفيان global وunknown بلا نطاق فقط عند عدم توفير --agent؛ في تلك الحالة، يستخدم الرجوع المضمن وملكية المخزن الوكيل الافتراضي المُعدّ.
• يبقي --json stdout محجوزًا لاستجابة JSON. تُوجّه تشخيصات Gateway وPlugin والرجوع المضمن إلى stderr حتى تتمكن السكربتات من تحليل stdout مباشرةً.
• تتضمن JSON الرجوع المضمنة meta.transport: "embedded" وmeta.fallbackFrom: "gateway" حتى تتمكن السكربتات من تمييز تشغيلات الرجوع عن تشغيلات Gateway.
• إذا قبل Gateway تشغيل وكيل لكن CLI انتهت مهلته أثناء انتظار الرد النهائي، يستخدم الرجوع المضمن معرف جلسة/تشغيل صريحًا جديدًا من نمط gateway-fallback-* ويبلغ عن meta.fallbackReason: "gateway_timeout" بالإضافة إلى حقول جلسة الرجوع. يتجنب ذلك التسابق مع قفل النص المملوك لـ Gateway أو استبدال جلسة المحادثة الأصلية الموجّهة بصمت.
• بالنسبة إلى التشغيلات المدعومة من Gateway، يقاطع SIGTERM وSIGINT طلب CLI المنتظر. إذا كان Gateway قد قبل التشغيل بالفعل، ترسل CLI أيضًا chat.abort لمعرف التشغيل المقبول ذلك قبل الخروج. تتلقى تشغيلات --local المحلية وتشغيلات الرجوع المضمنة إشارة الإجهاض نفسها، لكنها لا ترسل chat.abort. إذا وصل --run-id مكرر إلى Gateway بينما تشغيل الوكيل الأصلي لا يزال نشطًا، تبلغ الاستجابة المكررة عن status: "in_flight" وتطبع CLI غير JSON تشخيص stderr بدلًا من رد فارغ. بالنسبة إلى أغلفة cron/systemd الخارجية، احتفظ بمسند إيقاف قسري خارجي مثل timeout -k 60 600 openclaw agent ... حتى يتمكن المشرف من حصاد العملية إذا تعذر تصريف إيقاف التشغيل.
• عندما يؤدي هذا الأمر إلى إعادة إنشاء models.json، تُحفظ بيانات اعتماد المزودين المُدارة عبر SecretRef كعلامات غير سرية (على سبيل المثال أسماء متغيرات البيئة، أو secretref-env:ENV_VAR_NAME، أو secretref-managed)، لا كنصوص أسرار صريحة محلولة.
• كتابات العلامات ذات مصدر موثوق: يحفظ OpenClaw العلامات من لقطة إعدادات المصدر النشطة، لا من قيم أسرار وقت التشغيل المحلولة.

حالة تسليم JSON

عند استخدام --json --deliver، قد تتضمن استجابة JSON من CLI حقل deliveryStatus في المستوى الأعلى حتى تتمكن السكربتات من التمييز بين الإرسالات المُسلّمة والمكبوتة والجزئية والفاشلة:

{  "payloads": [{ "text": "Report ready", "mediaUrl": null }],  "meta": { "durationMs": 1200 },  "deliveryStatus": {    "requested": true,    "attempted": true,    "status": "sent",    "succeeded": true,    "resultCount": 1  }}

deliveryStatus.status هو أحد sent أو suppressed أو partial_failed أو failed. تعني suppressed أن التسليم لم يُرسل عمدًا، على سبيل المثال ألغاه خطاف إرسال الرسائل أو لم تكن هناك نتيجة مرئية؛ ولا يزال ذلك نتيجة نهائية بلا إعادة محاولة. تعني partial_failed أنه تم إرسال حمولة واحدة على الأقل قبل فشل حمولة لاحقة. تعني failed أنه لم يكتمل أي إرسال دائم أو أن الفحص المسبق للتسليم فشل.

تحافظ استجابات CLI المدعومة من Gateway أيضًا على شكل نتيجة Gateway الخام، حيث يكون الكائن نفسه متاحًا عند result.deliveryStatus.

الحقول الشائعة:

• requested: دائمًا true عند وجود الكائن.
• attempted: ‏true بعد تشغيل مسار الإرسال الدائم؛ وfalse لإخفاقات الفحص المسبق أو عند عدم وجود حمولات مرئية.
• succeeded: ‏true أو false أو "partial"؛ تقترن "partial" مع status: "partial_failed".
• reason: سبب بأحرف صغيرة وبنمط snake-case من التسليم الدائم أو تحقق الفحص المسبق. تشمل الأسباب المعروفة cancelled_by_message_sending_hook وno_visible_payload وno_visible_result وchannel_resolved_to_internal وunknown_channel وinvalid_delivery_target وno_delivery_target؛ وقد تبلغ الإرسالات الدائمة الفاشلة أيضًا عن المرحلة الفاشلة. عامل القيم غير المعروفة كمعتمة لأن المجموعة قابلة للتوسع.
• resultCount: عدد نتائج إرسال القناة عند توفره.
• sentBeforeError: ‏true عندما يرسل فشل جزئي حمولة واحدة على الأقل قبل الخطأ.
• error: قيمة منطقية true للإرسالات الفاشلة أو الفاشلة جزئيًا.
• errorMessage: يُضمّن فقط عند التقاط رسالة خطأ تسليم أساسية. تحمل إخفاقات الفحص المسبق error وreason ولكن لا تحمل errorMessage.
• payloadOutcomes: نتائج اختيارية لكل حمولة مع index أو status أو reason أو resultCount أو error أو stage أو sentBeforeError أو بيانات تعريف الخطاف عند توفرها.

ذات صلة

• مرجع CLI
• زمن تشغيل الوكيل