openclaw workboard é a interface de terminal do Plugin Workboard incluído. Ele permite que um operador liste cartões, crie um cartão, inspecione um cartão e solicite que o Gateway em execução despache trabalhos prontos para execuções de workers de subagentes.
Ative o Plugin antes de usar o comando:
Uso
status: triage, backlog, todo, scheduled, ready, running, review, blocked, done. Valores válidos de priority: low, normal, high, urgent.
list
Por padrão, a saída de texto compacta oculta os cartões arquivados para que a CLI corresponda a
/workboard list. Passe --include-archived para exibi-los. A saída JSON sempre mantém a lista completa de cartões, incluindo os cartões arquivados, para as automações existentes.
create
create grava diretamente no estado SQLite do Workboard. O cartão fica imediatamente visível na aba Workboard da interface de controle e para as ferramentas do Workboard.
show
move
move altera o status do cartão usando o mesmo fluxo de operador manual usado ao arrastar um cartão no painel. Ele aceita um ID completo de cartão ou um prefixo não ambíguo. As retenções ativas por dependência e agendamento continuam aplicáveis. Os operadores podem mover um cartão reivindicado sem o token de reivindicação do agente; os tokens de reivindicação permanecem restritos às mutações das ferramentas do agente e são ocultados da saída JSON.
dispatch
dispatch primeiro chama o método RPC workboard.cards.dispatch do Gateway em execução, que usa o mesmo runtime de subagentes da ação de despacho do painel, para que os cartões prontos se tornem execuções de workers rastreadas como tarefas com chaves de sessão vinculadas. --max-starts usa o método aditivo workboard.cards.dispatchWithOptions para que um Gateway mais antigo rejeite a opção antes de iniciar qualquer worker; reinicie o Gateway após a atualização antes de usar o sinalizador. Cartões com um agente atribuído usam chaves de sessão de subagente com escopo de agente; cartões não atribuídos mantêm uma chave de subagente sem escopo para preservar o agente padrão configurado do Gateway.
O loop de despacho:
- Promove filhos cujas dependências estão prontas para
ready. - Bloqueia reivindicações expiradas ou execuções de workers que excederam o tempo limite.
- Registra metadados de despacho nos cartões prontos.
- Seleciona um pequeno lote de cartões prontos não reivindicados.
- Reivindica cada cartão selecionado para o despachante ou agente atribuído.
- Inicia uma execução de worker de subagente com contexto limitado do cartão e o token de reivindicação do cartão.
- Armazena no cartão o ID da execução do worker, a chave de sessão, o vínculo com a tarefa quando informado pelo registro de tarefas do Gateway, o status da execução e o log do worker.
--max-starts <count> com um número inteiro positivo para alterar o limite por passagem; a regra de um cartão por proprietário continua aplicável, portanto o número efetivo de inicializações pode ser menor.
Se a inicialização do worker falhar após a reivindicação de um cartão, o Workboard bloqueia esse cartão, remove a reivindicação e registra a falha nos metadados de execução e de log do worker do cartão, mantendo as inicializações com falha visíveis em vez de devolver silenciosamente o cartão à fila.
Se nenhum destino explícito do Gateway for fornecido e o Gateway local estiver indisponível ou ainda não expuser o método de despacho do Workboard, a CLI recorre ao despacho somente de dados no estado local do Workboard. O despacho somente de dados ainda pode promover dependências, limpar reivindicações obsoletas e bloquear execuções que excederam o tempo limite, mas não inicia workers. Falhas de autenticação, permissão e validação, assim como falhas de um destino explícito --url ou --token, são informadas diretamente em vez de acionar o fallback.
A saída de texto informa as inicializações de workers:
started e startFailures; o fallback somente de dados inclui gatewayUnavailable: true. Os tokens de reivindicação são ocultados da saída JSON dos cartões.
No painel, o mesmo resultado do despacho é exibido como um resumo curto para que um operador veja quantos cartões foram iniciados, promovidos, bloqueados, recuperados ou falharam sem abrir os detalhes dos cartões.
Paridade com comandos de barra
Os canais compatíveis com comandos podem usar o comando de barra correspondente:/workboard list e /workboard show são comandos de leitura para remetentes de comandos autorizados. /workboard create, /workboard move e /workboard dispatch alteram o estado do quadro e exigem status de proprietário nas interfaces de chat ou um cliente Gateway com operator.write ou operator.admin.
Permissões
O fluxo de despacho da CLI normalmente solicita os escoposoperator.write e operator.read do Gateway. Cartões vinculados a um workspace são executados diretamente em um workspace de agente configurado exato; uma solicitação de worktree é restringida a esse diretório, em vez de permitir que o host materialize código controlado pelo repositório. O worker selecionado deve ter acesso de gravação e não compartilhado ao sandbox do Docker nesse workspace exato, um hash de contêiner ativo correspondente às montagens e à política solicitadas e nenhuma capacidade de escape para o host. Passe --admin para solicitar explicitamente operator.admin, permitir outro checkout do host e usar a configuração normal de worktree gerenciada; a conexão falhará se esse escopo não for aprovado para o cliente. Um token do Gateway somente leitura pode inspecionar os dados do Workboard por meio de métodos de leitura, mas não pode criar cartões nem despachar workers. De resto, os limites do workspace não alteram a movimentação manual de cartões para chamadores com permissão de alteração do Workboard.
Os comandos locais list, create, show e move operam no diretório de estado local do OpenClaw usado pelo perfil atual. Use --dev ou --profile <name> no comando de nível superior openclaw quando precisar de uma raiz de estado diferente.
Solução de problemas
Nenhum cartão aparece
Confirme que o Plugin está ativado para o mesmo perfil e a mesma raiz de estado:--dev ou --profile.
O despacho informa que é somente de dados
Inicie ou reinicie o Gateway:openclaw workboard dispatch novamente. O fallback somente de dados é útil para a limpeza do estado local, mas as execuções de workers precisam de um Gateway ativo.
O despacho não inicia nada
Verifique se há pelo menos um cartãoready sem uma reivindicação ativa:
done, libere reivindicações obsoletas pelas ferramentas do Workboard ou execute o despacho novamente após a conclusão do worker ativo.