工作看板命令列介面

openclaw workboard 是內建 Workboard 外掛的終端操作介面。它可讓操作人員列出卡片、建立卡片、檢視單一卡片，以及要求執行中的閘道將已就緒的工作分派至子代理工作執行。

使用此命令前，請先啟用外掛：

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]

此命令讀寫儀表板與 Workboard 代理工具所使用的同一個外掛自有 SQLite 資料庫。卡片 ID 是 UUID；接受卡片 ID 的命令也接受可明確識別的 ID 前綴（精簡文字輸出會顯示前 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  修正過期的工作程序心跳偵測

各欄依序為 ID 前綴、狀態、優先順序、看板 ID、選用的代理 ID，以及標題。

精簡文字輸出預設會隱藏已封存的卡片，使命令列介面與 /workboard list 保持一致。傳入 --include-archived 即可顯示。為了支援既有自動化，JSON 輸出一律保留完整卡片清單，包括已封存的卡片。

create

openclaw workboard create "修正過期的工作程序心跳偵測" --priority high --labels bug,workboardopenclaw workboard create "撰寫 Workboard 文件" --status ready --agent docs-agent --board docs --notes "涵蓋命令列介面、斜線命令、分派與 SQLite 狀態。"

create 會直接寫入 Workboard SQLite 狀態。卡片會立即顯示於控制介面的 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 使用與在儀表板拖曳卡片相同的手動操作人員路徑變更卡片狀態。它接受完整卡片 ID 或可明確識別的前綴。有效的相依項目與排程暫停仍會套用。操作人員可在沒有代理認領權杖的情況下移動已認領的卡片；認領權杖仍僅適用於代理工具的變更操作，且會從 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；該方法使用與儀表板分派動作相同的子代理執行環境，因此已就緒的卡片會成為具備連結工作階段金鑰、受任務追蹤的工作程序執行。--max-starts 使用增補的 workboard.cards.dispatchWithOptions 方法，因此較舊的閘道會在啟動任何工作程序前拒絕此選項；升級後，請先重新啟動閘道再使用此旗標。已指派代理的卡片會使用代理範圍的子代理工作階段金鑰；未指派的卡片則保留不限定範圍的子代理金鑰，以維持閘道所設定的預設代理。

分派迴圈會：

1. 將相依項目已就緒的子卡片提升為 ready。
2. 封鎖已過期的認領或逾時的工作程序執行。
3. 在已就緒的卡片上記錄分派中繼資料。
4. 選取一小批尚未認領的已就緒卡片。
5. 由分派器或獲指派的代理認領每張選定卡片。
6. 使用受限的卡片內容與卡片認領權杖啟動子代理工作程序執行。
7. 在卡片上儲存工作程序執行 ID、工作階段金鑰、閘道任務帳本回報的任務連結、執行狀態及工作程序記錄。

選取方式較為保守：每次分派預設最多啟動三個工作程序、略過已封存或已認領的卡片，且單次處理中，每位擁有者或代理只會啟動一張卡片。若卡片的擁有者已有進行中或待審查的工作，該卡片會留待後續分派。傳入具有正整數值的 --max-starts <count> 可變更每次處理的上限；每位擁有者限一張卡片的規則仍會套用，因此實際啟動數可能較低。

如果卡片認領後無法啟動工作程序，Workboard 會封鎖該卡片、清除認領，並將失敗記錄於卡片執行及工作程序記錄中繼資料，使啟動失敗保持可見，而不是默默將卡片送回佇列。

若未指定明確的閘道目標，且本機閘道無法使用或尚未公開 Workboard 分派方法，命令列介面會改用本機 Workboard 狀態執行僅資料分派。僅資料分派仍可提升相依項目、清除過期認領及封鎖逾時執行，但不會啟動工作程序。驗證、權限與驗證規則失敗，以及明確指定 --url 或 --token 目標時發生的失敗，都會直接回報，而不會觸發備援。

文字輸出會回報工作程序啟動結果：

分派完成：已啟動=2 失敗=0

備援輸出會明確標示：

閘道無法使用；僅執行資料分派：已提升=1 已封鎖=0

JSON 輸出包含分派結果。由閘道支援的分派可包含 started 與 startFailures；僅資料備援則包含 gatewayUnavailable: true。認領權杖會從卡片 JSON 輸出中遮蔽。

在儀表板中，相同的分派結果會顯示為簡短摘要，讓操作人員無須開啟卡片詳細資料，即可查看啟動、提升、封鎖、重新認領或失敗的卡片數量。

斜線命令對等功能

支援命令的頻道可使用相對應的斜線命令：

/workboard list/workboard show 7f4a2c10/workboard create 修正過期的工作程序心跳偵測/workboard move 7f4a2c10 --status review/workboard dispatch

斜線命令分派也會使用閘道子代理執行環境，因此其認領、工作程序啟動及失敗行為與儀表板及命令列介面的閘道路徑相同。

/workboard list 與 /workboard show 是供已授權命令傳送者使用的讀取命令。/workboard create、/workboard move 與 /workboard dispatch 會變更看板狀態，並要求聊天介面上的擁有者身分，或具有 operator.write 或 operator.admin 的閘道用戶端。

權限

命令列介面的分派路徑通常會要求閘道 operator.write 與 operator.read 範圍。繫結至工作區的卡片會直接在精確設定的代理工作區中執行；工作樹要求會限制在該目錄內，而不會讓主機具現化由儲存庫控制的程式碼。所選工作程序必須具備對該確切工作區的可寫入、非共用 Docker 沙箱存取權，擁有符合所要求掛載與政策的有效容器雜湊，且不具備逸出主機的能力。傳入 --admin 可明確要求 operator.admin、允許使用另一個主機簽出，並採用一般受管理的工作樹設定；若該範圍未獲用戶端核准，連線將會失敗。唯讀閘道權杖可透過讀取方法檢視 Workboard 資料，但無法建立卡片或分派工作程序。對具有 Workboard 變更權限的呼叫端而言，工作區限制不會以其他方式變更手動移動卡片的行為。

本機 list、create、show 與 move 命令會操作目前設定檔使用的本機 OpenClaw 狀態目錄。需要使用不同的狀態根目錄時，請在頂層 openclaw 命令上使用 --dev 或 --profile <name>。

疑難排解

未顯示任何卡片

確認已針對相同的設定檔與狀態根目錄啟用外掛：

openclaw plugins inspect workboard --runtime --json

若儀表板顯示卡片，但命令列介面沒有，請檢查兩個命令是否使用相同的 --dev 或 --profile 設定。

分派顯示僅資料模式

啟動或重新啟動閘道：

openclaw gateway restartopenclaw gateway status --deep

接著重試 openclaw workboard dispatch。僅資料備援適合用於清理本機狀態，但工作程序執行需要可用的閘道。

分派未啟動任何項目

檢查是否至少有一張沒有有效認領的 ready 卡片：

openclaw workboard list --status ready

若同一擁有者已有執行中或待審查的工作，也可能略過卡片。請將已完成的工作移至 done、透過 Workboard 工具釋放過期認領，或在目前的工作程序完成後再次執行分派。

相關內容

• Workboard 外掛
• 命令列介面參考
• 斜線命令
• 控制介面