CLI commands
CLI تختهکار
openclaw workboard رابط ترمینالی Plugin وُرکبورد همراه برنامه است. این فرمان به اپراتور امکان میدهد کارتها را فهرست کند، کارتی بسازد، یک کارت را بررسی کند و از Gateway در حال اجرا بخواهد کارهای آماده را برای اجراهای کارگرِ زیرعامل اعزام کند.
پیش از استفاده از فرمان، Plugin را فعال کنید:
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 dispatch [--url <url>] [--token <token>] [--timeout <ms>] [--json]این فرمان همان پایگاه داده SQLite متعلق به Plugin را میخواند و مینویسد که داشبورد و ابزارهای عامل وُرکبورد نیز از آن استفاده میکنند. شناسه کارتها UUID هستند؛ فرمانهایی که شناسه کارت میپذیرند، پیشوند بدون ابهام شناسه را نیز قبول میکنند (خروجی متنی فشرده ۸ نویسه نخست را نشان میدهد).
مقادیر معتبر 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 Fix stale worker heartbeatستونها بهترتیب شامل پیشوند شناسه، وضعیت، اولویت، شناسه بورد، شناسه اختیاری عامل و عنوان هستند.
| پرچم | کاربرد |
|---|---|
--board <id> |
محدودکردن نتایج به فضای نام یک بورد |
--status <status> |
محدودکردن نتایج به یک وضعیت وُرکبورد |
--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 وُرکبورد مینویسد. کارت بلافاصله در زبانه وُرکبورد رابط کنترل و برای ابزارهای وُرکبورد قابل مشاهده است.
show
openclaw workboard show 7f4a2c10openclaw workboard show 7f4a2c10 --jsonخروجی متنی، خط فشرده کارت و یادداشتها را چاپ میکند. خروجی JSON رکورد کامل کارت را برمیگرداند که شامل فراداده اجرا، تلاشها، دیدگاهها، پیوندها، مدرک، مصنوعات، گزارشهای کارگر، وضعیت پروتکل، دادههای تشخیصی و فراداده خودکارسازی است.
dispatch
openclaw workboard dispatchopenclaw workboard dispatch --jsonopenclaw workboard dispatch --url http://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"dispatch ابتدا متد RPC با نام workboard.cards.dispatch را در Gateway در حال اجرا فراخوانی میکند. این متد از همان محیط اجرای زیرعاملِ کنش اعزام داشبورد استفاده میکند؛ در نتیجه، کارتهای آماده به اجراهای کارگرِ ردیابیشده بهعنوان وظیفه، همراه با کلیدهای نشست پیوندخورده تبدیل میشوند. کارتهایی که عامل مشخصی به آنها تخصیص یافته است از کلیدهای نشست زیرعاملِ محدود به همان عامل استفاده میکنند؛ کارتهای بدون تخصیص، کلید زیرعاملِ بدون دامنه را حفظ میکنند تا عامل پیشفرض پیکربندیشده Gateway حفظ شود.
حلقه اعزام:
- فرزندان با وابستگیهای آماده را به
readyارتقا میدهد. - ادعاهای منقضی یا اجراهای کارگرِ دچار مهلتپایان را مسدود میکند.
- فراداده اعزام را روی کارتهای آماده ثبت میکند.
- دسته کوچکی از کارتهای آماده و بدون ادعا را انتخاب میکند.
- هر کارت انتخابشده را برای اعزامکننده یا عامل تخصیصیافته ادعا میکند.
- اجرای یک کارگرِ زیرعامل را با زمینه محدود کارت و توکن ادعای کارت آغاز میکند.
- شناسه اجرای کارگر، کلید نشست، پیوند وظیفه در صورت گزارش آن توسط دفترکل وظایف Gateway، وضعیت اجرا و گزارش کارگر را روی کارت ذخیره میکند.
انتخاب محافظهکارانه است: هر اعزام بهطور پیشفرض حداکثر سه کارگر را آغاز میکند، کارتهای بایگانیشده یا ازپیشادعاشده را نادیده میگیرد و در هر نوبت تنها یک کارت را برای هر مالک یا عامل آغاز میکند. کارتهایی که مالکشان از قبل کار فعال در وضعیت اجرا یا بازبینی دارد، برای اعزام بعدی باقی میمانند.
اگر آغاز کارگر پس از ادعای کارت ناموفق باشد، وُرکبورد آن کارت را مسدود میکند، ادعا را پاک میکند و شکست را در فراداده اجرا و گزارش کارگر کارت ثبت میکند؛ بنابراین آغازهای ناموفق بهجای بازگرداندن بیسروصدای کارت به صف، قابل مشاهده میمانند.
اگر مقصد صریحی برای Gateway تعیین نشده باشد و Gateway محلی در دسترس نباشد یا هنوز متد اعزام وُرکبورد را ارائه نکند، CLI به اعزام صرفاً دادهای بر پایه وضعیت محلی وُرکبورد بازمیگردد. اعزام صرفاً دادهای همچنان میتواند وابستگیها را ارتقا دهد، ادعاهای کهنه را پاک کند و اجراهای دچار مهلتپایان را مسدود کند، اما کارگری را آغاز نمیکند. خطاهای احراز هویت، مجوز و اعتبارسنجی، و همچنین خطاهای مقصد صریح --url یا --token، بهجای فعالکردن مسیر جایگزین مستقیماً گزارش میشوند.
خروجی متنی، آغاز کارگرها را گزارش میکند:
dispatch complete: started=2 failures=0خروجی مسیر جایگزین صریح است:
gateway unavailable; data dispatch only: promoted=1 blocked=0خروجی JSON نتیجه اعزام را در بر میگیرد. اعزام با پشتوانه Gateway میتواند شامل started و startFailures باشد؛ مسیر جایگزین صرفاً دادهای شامل gatewayUnavailable: true است. توکنهای ادعا در خروجی JSON کارت پوشانده میشوند.
در داشبورد، همان نتیجه اعزام بهصورت خلاصهای کوتاه نمایش داده میشود تا اپراتور بدون بازکردن جزئیات کارت ببیند چند کارت آغاز، ارتقا، مسدود، بازپسگیری یا ناموفق شدهاند.
همارزی فرمان اسلش
کانالهای دارای قابلیت فرمان میتوانند از فرمان اسلش متناظر استفاده کنند:
/workboard list/workboard show 7f4a2c10/workboard create Fix stale worker heartbeat/workboard dispatchاعزام با فرمان اسلش نیز از محیط اجرای زیرعامل Gateway استفاده میکند؛ بنابراین همان رفتار ادعا، آغاز کارگر و شکست را مانند مسیر Gateway در داشبورد و CLI دنبال میکند.
/workboard list و /workboard show فرمانهای خواندن برای فرستندگان مجاز فرمان هستند. /workboard create و /workboard dispatch وضعیت بورد را تغییر میدهند و در رابطهای گفتوگو به وضعیت مالک، یا در یک کارخواه Gateway به operator.write یا operator.admin نیاز دارند.
مجوزها
مسیر اعزام CLI، RPC در Gateway را با دامنههای operator.read و operator.write فراخوانی میکند. توکن فقطخواندنی Gateway میتواند دادههای وُرکبورد را از طریق متدهای خواندن بررسی کند، اما نمیتواند کارت بسازد یا کارگر اعزام کند.
فرمانهای محلی list، create و show روی پوشه وضعیت محلی OpenClaw که نمایه کنونی استفاده میکند عمل میکنند. هنگامی که به ریشه وضعیت دیگری نیاز دارید، در فرمان سطحبالای openclaw از --dev یا --profile <name> استفاده کنید.
عیبیابی
هیچ کارتی ظاهر نمیشود
تأیید کنید که Plugin برای همان نمایه و ریشه وضعیت فعال است:
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 منتقل کنید، ادعاهای کهنه را با ابزارهای وُرکبورد آزاد کنید، یا پس از پایان کارگر فعال دوباره اعزام را اجرا کنید.
