CLI commands
CLI لوحة العمل
openclaw workboard هي واجهة الطرفية الخاصة بـإضافة Workboard المضمّنة. وهي تتيح للمشغّل سرد البطاقات، وإنشاء بطاقة، وفحص بطاقة واحدة، ومطالبة Gateway قيد التشغيل بتوجيه العمل الجاهز إلى عمليات تشغيل عمّال الوكلاء الفرعيين.
فعّل الإضافة قبل استخدام الأمر:
openclaw plugins enable workboardopenclaw gateway restartالاستخدام
openclaw workboard list [--board <id>] [--status <status>] [--include-archived] [--json]openclaw workboard create <title...> [--notes <text>] [--status <status>] [--priority <priority>] [--agent <id>] [--board <id>] [--labels <items>] [--json]openclaw workboard show <id> [--json]openclaw workboard move <id> --status <status> [--json]openclaw workboard dispatch [--board <id>] [--max-starts <count>] [--admin] [--url <url>] [--token <token>] [--timeout <ms>] [--json]يقرأ الأمر ويكتب قاعدة بيانات SQLite نفسها المملوكة للإضافة، التي تستخدمها لوحة المعلومات وأدوات وكيل Workboard. معرّفات البطاقات هي UUID؛ كما تقبل الأوامر التي تأخذ معرّف بطاقة بادئة معرّف غير ملتبسة (يعرض الإخراج النصي الموجز أول 8 أحرف).
قيم status الصالحة: triage، وbacklog، وtodo، وscheduled، وready، وrunning، وreview، وblocked، وdone. قيم priority الصالحة: low، وnormal، وhigh، وurgent.
list
openclaw workboard listopenclaw workboard list --board default --status readyopenclaw workboard list --jsonالإخراج النصي موجز:
7f4a2c10 ready high default agent-a إصلاح Heartbeat قديم للعاملالأعمدة هي بادئة المعرّف، والحالة، والأولوية، ومعرّف اللوحة، ومعرّف الوكيل الاختياري، والعنوان.
| الخيار | الغرض |
|---|---|
--board <id> |
قصر النتائج على نطاق لوحة واحد |
--status <status> |
قصر النتائج على حالة Workboard واحدة |
--include-archived |
تضمين البطاقات المؤرشفة في الإخراج النصي الموجز |
--json |
طباعة قائمة البطاقات الكاملة بصيغة JSON آلية |
يخفي الإخراج النصي الموجز البطاقات المؤرشفة افتراضيًا بحيث تتطابق CLI مع /workboard list. مرّر --include-archived لإظهارها. يحتفظ إخراج JSON دائمًا بقائمة البطاقات الكاملة، بما فيها البطاقات المؤرشفة، من أجل عمليات الأتمتة الحالية.
create
openclaw workboard create "Fix stale worker heartbeat" --priority high --labels bug,workboardopenclaw workboard create "Write Workboard docs" --status ready --agent docs-agent --board docs --notes "Cover CLI, slash command, dispatch, and SQLite state."| الخيار | الغرض |
|---|---|
--notes <text> |
الملاحظات الأولية للبطاقة |
--status <status> |
الحالة الأولية، والقيمة الافتراضية todo |
--priority <priority> |
الأولوية، والقيمة الافتراضية normal |
--agent <id> |
إسناد البطاقة إلى معرّف وكيل أو مالك |
--board <id> |
تخزين البطاقة ضمن نطاق لوحة |
--labels <items> |
تسميات مفصولة بفواصل |
--json |
طباعة البطاقة المنشأة بصيغة JSON آلية |
يكتب create مباشرةً إلى حالة SQLite الخاصة بـWorkboard. تظهر البطاقة فورًا في علامة تبويب Workboard ضمن واجهة التحكم، وتصبح متاحة لأدوات Workboard.
show
openclaw workboard show 7f4a2c10openclaw workboard show 7f4a2c10 --jsonيطبع الإخراج النصي سطر البطاقة الموجز والملاحظات. ويعيد إخراج JSON سجل البطاقة الكامل، بما في ذلك بيانات التنفيذ الوصفية، والمحاولات، والتعليقات، والروابط، والإثباتات، والعناصر الناتجة، وسجلات العامل، وحالة البروتوكول، والتشخيصات، وبيانات الأتمتة الوصفية.
move
openclaw workboard move 7f4a2c10 --status reviewopenclaw workboard move 7f4a2c10 --status done --jsonيغيّر move حالة البطاقة باستخدام مسار المشغّل اليدوي نفسه المستخدم عند سحب بطاقة في لوحة المعلومات. وهو يقبل معرّف بطاقة كاملًا أو بادئة غير ملتبسة. تظل قيود التبعيات النشطة والجدولة سارية. يمكن للمشغّلين نقل بطاقة مطالب بها من دون رمز مطالبة وكيلها؛ وتظل رموز المطالبة مقتصرة على التعديلات التي تجريها أدوات الوكيل، وتُحجب من إخراج JSON.
dispatch
openclaw workboard dispatchopenclaw workboard dispatch --jsonopenclaw workboard dispatch --max-starts 10openclaw workboard dispatch --adminopenclaw workboard dispatch --url http://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"يستدعي dispatch أولًا طريقة RPC workboard.cards.dispatch في Gateway قيد التشغيل، التي تستخدم بيئة تشغيل الوكيل الفرعي نفسها المستخدمة في إجراء التوجيه بلوحة المعلومات، بحيث تصبح البطاقات الجاهزة عمليات تشغيل عمّال متتبعة كمهام ومرتبطة بمفاتيح جلسات. يستخدم --max-starts الطريقة الإضافية workboard.cards.dispatchWithOptions كي يرفض Gateway أقدم الخيار قبل بدء أي عمّال؛ أعد تشغيل Gateway بعد الترقية قبل استخدام الخيار. تستخدم البطاقات المسندة إلى وكيل مفاتيح جلسات وكيل فرعي مقيّدة بنطاق الوكيل؛ أما البطاقات غير المسندة فتحتفظ بمفتاح وكيل فرعي غير مقيّد النطاق، للحفاظ على الوكيل الافتراضي المضبوط في Gateway.
حلقة التوجيه:
- ترقّي العناصر التابعة الجاهزة من ناحية التبعيات إلى
ready. - تحظر المطالبات المنتهية الصلاحية أو عمليات تشغيل العمّال التي انتهت مهلتها.
- تسجّل بيانات التوجيه الوصفية على البطاقات الجاهزة.
- تحدّد دفعة صغيرة من البطاقات الجاهزة غير المطالب بها.
- تطالب بكل بطاقة محددة لصالح الموجّه أو الوكيل المسند.
- تبدأ عملية تشغيل عامل وكيل فرعي بسياق بطاقة محدود ورمز مطالبة البطاقة.
- تخزّن معرّف عملية تشغيل العامل، ومفتاح الجلسة، وارتباط المهمة عندما يبلغ عنها سجل مهام Gateway، وحالة التنفيذ، وسجل العامل على البطاقة.
يكون التحديد متحفظًا: يبدأ التوجيه الواحد ثلاثة عمّال كحد أقصى افتراضيًا، ويتخطى البطاقات المؤرشفة أو المطالب بها مسبقًا، ولا يبدأ سوى بطاقة واحدة لكل مالك أو وكيل في المرور الواحد. تُترك البطاقات التي يملكها بالفعل عمل نشط قيد التشغيل أو المراجعة لعملية توجيه لاحقة. مرّر --max-starts <count> مع عدد صحيح موجب لتغيير الحد الأقصى لكل مرور؛ وتظل قاعدة بطاقة واحدة لكل مالك سارية، لذا قد يكون العدد الفعلي لعمليات البدء أقل.
إذا فشل بدء العامل بعد المطالبة ببطاقة، يحظر Workboard تلك البطاقة، ويمحو المطالبة، ويسجّل الفشل في بيانات تنفيذ البطاقة وسجل العامل الوصفية، ما يبقي عمليات البدء الفاشلة مرئية بدلًا من إعادة البطاقة بصمت إلى قائمة الانتظار.
إذا لم يُحدَّد هدف Gateway صراحةً وكان Gateway المحلي غير متاح أو لم يوفّر بعد طريقة توجيه Workboard، تتراجع CLI إلى التوجيه المعتمد على البيانات فقط في حالة Workboard المحلية. لا يزال بإمكان التوجيه المعتمد على البيانات فقط ترقية التبعيات، وتنظيف المطالبات القديمة، وحظر عمليات التشغيل التي انتهت مهلتها، لكنه لا يبدأ العمّال. تُبلّغ إخفاقات المصادقة والأذونات والتحقق، وإخفاقات هدف --url أو --token المحدد صراحةً، مباشرةً بدلًا من تشغيل التراجع.
يبلغ الإخراج النصي عن عمليات بدء العمّال:
اكتمل التوجيه: started=2 failures=0إخراج التراجع صريح:
Gateway غير متاح؛ توجيه بيانات فقط: promoted=1 blocked=0يتضمن إخراج JSON نتيجة التوجيه. قد يتضمن التوجيه المدعوم بـGateway started وstartFailures؛ بينما يتضمن التراجع المعتمد على البيانات فقط gatewayUnavailable: true. تُحجب رموز المطالبة من إخراج JSON للبطاقة.
في لوحة المعلومات، تظهر نتيجة التوجيه نفسها في ملخص قصير، كي يتمكن المشغّل من معرفة عدد البطاقات التي بدأت أو رُقّيت أو حُظرت أو استُعيدت مطالبتها أو فشلت، من دون فتح تفاصيل البطاقة.
التكافؤ مع أمر الشرطة المائلة
يمكن للقنوات الداعمة للأوامر استخدام أمر الشرطة المائلة المطابق:
/workboard list/workboard show 7f4a2c10/workboard create إصلاح Heartbeat قديم للعامل/workboard move 7f4a2c10 --status review/workboard dispatchيستخدم توجيه أمر الشرطة المائلة أيضًا بيئة تشغيل الوكيل الفرعي في Gateway، لذا يتبع سلوك المطالبة وبدء العامل والفشل نفسه المتبع في لوحة المعلومات ومسار Gateway في CLI.
يُعد /workboard list و/workboard show أمري قراءة لمرسلي الأوامر المصرّح لهم. يعدّل /workboard create و/workboard move و/workboard dispatch حالة اللوحة، ويتطلب حالة المالك على واجهات المحادثة أو عميل Gateway يمتلك operator.write أو operator.admin.
الأذونات
يطلب مسار التوجيه في CLI عادةً نطاقي Gateway operator.write وoperator.read. تعمل البطاقات المرتبطة بمساحة عمل مباشرةً داخل مساحة عمل وكيل مضبوطة بدقة؛ ويُضيّق طلب شجرة العمل إلى ذلك الدليل بدلًا من السماح للمضيف بإنشاء شيفرة يتحكم فيها المستودع. يجب أن يمتلك العامل المحدد وصولًا قابلًا للكتابة وغير مشترك إلى وضع الحماية Docker لمساحة العمل نفسها، وتجزئة حاوية نشطة تطابق عمليات التركيب والسياسة المطلوبتين، وألّا يمتلك أي إمكانية للإفلات إلى المضيف. مرّر --admin لطلب operator.admin صراحةً، والسماح بعملية استخراج أخرى على المضيف، واستخدام إعداد شجرة العمل المُدارة المعتاد؛ يفشل الاتصال إذا لم يُعتمد ذلك النطاق للعميل. يمكن لرمز Gateway المخصص للقراءة فقط فحص بيانات Workboard عبر طرق القراءة، لكنه لا يستطيع إنشاء بطاقات أو توجيه العمّال. ولا تغيّر حدود مساحة العمل بخلاف ذلك النقل اليدوي للبطاقات لدى المستدعين الذين يمتلكون إذن تعديل Workboard.
تعمل أوامر list وcreate وshow وmove المحلية على دليل حالة OpenClaw المحلي الذي يستخدمه الملف الشخصي الحالي. استخدم --dev أو --profile <name> مع أمر openclaw ذي المستوى الأعلى عند الحاجة إلى جذر حالة مختلف.
استكشاف الأخطاء وإصلاحها
لا تظهر أي بطاقات
تأكد من تمكين الإضافة للملف الشخصي وجذر الحالة نفسيهما:
openclaw plugins inspect workboard --runtime --jsonإذا كانت لوحة المعلومات تعرض بطاقات بينما لا تعرضها CLI، فتحقق من أن كلا الأمرين يستخدم إعداد --dev أو --profile نفسه.
يفيد التوجيه بأنه معتمد على البيانات فقط
ابدأ Gateway أو أعد تشغيله:
openclaw gateway restartopenclaw gateway status --deepثم أعد محاولة openclaw workboard dispatch. يفيد التراجع المعتمد على البيانات فقط في تنظيف الحالة المحلية، لكن عمليات تشغيل العمّال تحتاج إلى Gateway نشط.
لا يبدأ التوجيه أي شيء
تحقق من وجود بطاقة ready واحدة على الأقل من دون مطالبة نشطة:
openclaw workboard list --status readyقد تُتخطى البطاقات أيضًا عندما يمتلك المالك نفسه بالفعل عملًا قيد التشغيل أو المراجعة. انقل العمل المكتمل إلى done، أو حرّر المطالبات القديمة عبر أدوات Workboard، أو شغّل التوجيه مجددًا بعد انتهاء العامل النشط.
