Plugin Workboard

O Plugin Workboard adiciona um quadro opcional no estilo Kanban à IU de Controle. Use-o para reunir cartões de trabalho em tamanho adequado para agentes, atribuí-los a agentes e acompanhar a tarefa em segundo plano, a execução e a sessão de painel vinculadas a partir de um único cartão.

O Workboard é intencionalmente pequeno. Ele acompanha o trabalho operacional local de um OpenClaw Gateway; não é um substituto para GitHub Issues, Linear, Jira ou outros sistemas de gerenciamento de projetos de equipe.

Estado padrão

O Workboard é um Plugin incluído e fica desabilitado por padrão, a menos que você o habilite na configuração de Plugin.

Habilite-o com:

openclaw plugins enable workboardopenclaw gateway restart

Depois abra o painel:

openclaw dashboard

A aba Workboard aparece na navegação do painel. Se a aba estiver visível, mas o Plugin estiver desabilitado ou bloqueado por plugins.allow / plugins.deny, a visualização mostrará um estado de Plugin indisponível em vez dos dados locais dos cartões.

O que os cartões contêm

Cada cartão armazena:

• título e notas
• status: triage, backlog, todo, scheduled, ready, running, review, blocked ou done
• prioridade: low, normal, high ou urgent
• rótulos
• ID de agente opcional
• tarefa, execução, sessão ou URL de origem vinculada opcional
• metadados de execução opcionais para uma execução do Codex ou Claude iniciada a partir do cartão
• metadados compactos para tentativas, comentários, links, provas, artefatos, automação, anexos, logs de worker, estado de protocolo de worker, reivindicações, diagnósticos, notificações, modelos, estado de arquivamento e detecção de sessões obsoletas
• eventos recentes do cartão, como alterações de criação, movimentação, vinculação, reivindicação, Heartbeat, tentativa, prova, artefato, diagnóstico, notificação, despacho, arquivamento, obsolescência ou atualização por agente

Os cartões são armazenados no estado de Gateway do Plugin. Eles são locais ao diretório de estado do Gateway e se movem com o restante do estado OpenClaw desse Gateway.

O Workboard mantém metadados compactos por cartão para que operadores possam ver como um cartão avançou pelo quadro sem abrir a sessão vinculada. Eventos, resumos de tentativas, trechos de prova, links relacionados, comentários, marcadores de arquivamento e marcadores de sessões obsoletas são metadados locais intencionais; eles não substituem transcrições de sessão nem o histórico de issues do GitHub.

Execuções de cartões e tarefas

Cartões sem vínculo podem iniciar trabalho a partir do cartão. Inícios autônomos usam o caminho de execução de agente rastreado por tarefa do Gateway; depois, o Workboard vincula a tarefa resultante, o ID da execução e a chave de sessão de volta ao cartão. O início usa o agente e o modelo padrão configurados no Gateway. As ações do Codex e do Claude são escolhas opcionais explícitas de modelo:

• Executar Codex ou Executar Claude inicia uma execução de agente com tarefa, envia o prompt do cartão e marca o cartão como running.
• Abrir Codex ou Abrir Claude cria uma sessão de painel vinculada sem enviar o prompt do cartão nem mover o cartão, para que você possa trabalhar manualmente enquanto ele permanece anexado ao quadro.

Os metadados de execução armazenam no cartão o mecanismo selecionado, modo, referência de modelo, chave de sessão, ID de execução, ID da tarefa quando disponível e status do ciclo de vida. Execuções do Codex usam openai/gpt-5.5; execuções do Claude usam anthropic/claude-sonnet-4-6.

Cada execução vinculada também registra um resumo de tentativa no mesmo registro do cartão. O resumo de tentativa mantém o mecanismo, modo, modelo, ID de execução, carimbos de data/hora, status e contagem contínua de falhas para que falhas repetidas permaneçam visíveis no quadro.

O painel atualiza o status da tarefa a partir do livro-razão de tarefas do Gateway e corresponde tarefas de volta aos cartões por ID da tarefa, ID da execução ou chave de sessão vinculada. Se uma tarefa estiver enfileirada ou em execução, o ciclo de vida do cartão mostra o estado ativo da tarefa. Se a tarefa terminar, falhar, expirar ou for cancelada, o ciclo de vida do cartão avança para status de revisão ou bloqueio usando a mesma sincronização de ciclo de vida das sessões vinculadas.

Coordenação de agentes

O Workboard também expõe ferramentas opcionais de agente para fluxos de trabalho cientes do quadro:

• workboard_list lista cartões compactos com estado de reivindicação e diagnóstico, com um filtro opcional de quadro.
• workboard_read retorna um cartão mais contexto limitado de worker criado a partir de notas, tentativas, comentários, links, provas, artefatos, resultados de pais, trabalho recente do responsável e diagnósticos ativos.
• workboard_create cria um cartão com pais opcionais, locatário, Skills, quadro, metadados de espaço de trabalho, chave de idempotência, limite de runtime e orçamento de novas tentativas.
• workboard_link vincula um cartão pai a um cartão filho. Filhos permanecem em todo até que todos os pais cheguem a done; então a promoção de despacho os move para ready.
• workboard_claim reivindica um cartão para o agente chamador e move cartões de backlog, todo ou ready para running.
• workboard_heartbeat atualiza o Heartbeat da reivindicação durante execuções mais longas.
• workboard_release libera a reivindicação após conclusão, pausa ou repasse e pode mover o cartão para um próximo status.
• workboard_complete e workboard_block são ferramentas estruturadas de ciclo de vida para resumos finais, provas, artefatos, manifestos de cartões criados e motivos de bloqueio. Manifestos de cartões criados devem referenciar cartões vinculados de volta ao cartão concluído, o que mantém filhos fantasmas fora dos resumos.
• workboard_attachment_add, workboard_attachment_read e workboard_attachment_delete armazenam pequenos anexos de cartão no estado SQLite do Plugin, indexam-nos no cartão e os expõem no contexto do worker.
• workboard_worker_log e workboard_protocol_violation registram linhas de log de worker e bloqueiam cartões quando um worker automatizado para sem chamar workboard_complete ou workboard_block.
• workboard_board_create, workboard_board_archive e workboard_board_delete gerenciam metadados persistidos de quadro, como nome de exibição, descrição, estado de arquivamento e espaço de trabalho padrão.
• workboard_runs retorna o histórico persistido de tentativas de execução armazenado em um cartão.
• workboard_specify transforma um cartão bruto de triagem ou backlog em um cartão todo esclarecido e registra o resumo de especificação no cartão.
• workboard_decompose distribui um cartão pai de orquestração em filhos vinculados, herda metadados de quadro e locatário e pode concluir o pai com um manifesto de cartões criados.
• workboard_notify_subscribe, workboard_notify_list, workboard_notify_events, workboard_notify_advance e workboard_notify_unsubscribe gerenciam assinaturas de notificação no estado do Plugin. Leituras de eventos são seguras para repetição; a ferramenta de avanço move o cursor durável para que chamadores possam retomar sem perder nem ler duas vezes eventos de cartões concluídos, com falha ou obsoletos.
• workboard_boards, workboard_stats, workboard_promote, workboard_reassign, workboard_reclaim, workboard_comment, workboard_proof, workboard_unblock e workboard_dispatch permitem que um agente inspecione namespaces de quadros, veja estatísticas de fila, recupere trabalho travado, adicione notas de repasse, anexe referências de prova ou artefato, mova trabalho bloqueado de volta para todo e acione a promoção de dependências ou a limpeza de reivindicações obsoletas.

Cartões reivindicados rejeitam mutações por ferramentas de agente vindas de outros agentes, a menos que o chamador tenha o token de reivindicação retornado por workboard_claim. Operadores do painel ainda usam a superfície RPC normal do Gateway e podem recuperar ou reatribuir cartões.

O Workboard armazena dados duráveis de quadro em um banco de dados relacional SQLite pertencente ao Plugin sob o diretório de estado do OpenClaw. Quadros, cartões, rótulos, eventos de ciclo de vida, tentativas de execução, comentários, links de dependência, provas, referências de artefatos, metadados e blobs de anexos, diagnósticos, notificações, logs de worker, estado de protocolo e assinaturas são persistidos em tabelas do Workboard em vez de entradas chave-valor do Plugin. Uma exportação de cartão ainda preserva a narrativa do quadro sem incorporar o conteúdo dos blobs de anexos.

Instalações que usaram o Workboard na versão .28 podem executar openclaw doctor --fix para migrar os namespaces legados de estado de Plugin enviados (workboard.cards, workboard.boards e workboard.notify) para o banco de dados relacional. Se um namespace legado workboard.attachments estiver presente, o doctor também migrará esses blobs de anexos.

Os diagnósticos do Workboard são calculados a partir de metadados locais dos cartões. As verificações integradas sinalizam cartões atribuídos que aguardam tempo demais, cartões em execução sem Heartbeat recente, cartões bloqueados que precisam de atenção, falhas repetidas, cartões concluídos sem prova e cartões em execução que têm apenas um vínculo frouxo de sessão.

O despacho é intencionalmente local ao Gateway. Ele não gera processos arbitrários do sistema operacional; sessões normais de subagente do OpenClaw ainda são responsáveis pela execução. A ação de despacho promove cartões prontos por dependência, registra metadados de despacho em cartões prontos, bloqueia reivindicações expiradas ou execuções com timeout, marca cartões de triagem configurados pelo quadro como candidatos de orquestração, depois reivindica um pequeno lote de cartões prontos e inicia execuções de worker pelo runtime de subagente do Gateway. Cartões atribuídos usam chaves de sessão de worker agent:<id>:subagent:workboard-*; cartões não atribuídos usam chaves sem escopo subagent:workboard-* para que o Gateway ainda resolva o agente padrão configurado. Workers recebem contexto limitado do cartão mais o token de reivindicação de que precisam para enviar Heartbeat, concluir ou bloquear o cartão pelas ferramentas do Workboard.

Seleção de worker pelo despacho

Cada passagem de despacho inicia no máximo três workers por padrão. Cartões prontos são ordenados por prioridade, posição e hora de criação, depois filtrados para evitar propriedade ativa duplicada. Um despacho inicia apenas um cartão para um determinado proprietário ou agente na mesma passagem e ignora proprietários que já têm trabalho em execução ou em revisão no quadro.

Cartões arquivados, cartões com reivindicações ativas e cartões sem status ready não são selecionados para inícios de worker. Eles ainda podem ser afetados pelo lado de dados do despacho quando houver reivindicações obsoletas, promoção de dependências ou limpeza de timeout.

Prompt e ciclo de vida do worker

O prompt do worker inclui o título do cartão, notas e contexto limitados, o quadro atribuído e o protocolo de worker do Workboard. Ele também inclui o proprietário da reivindicação e o token de reivindicação para que o worker possa chamar workboard_heartbeat, workboard_complete ou workboard_block sem que outro ator assuma o cartão.

Quando um worker inicia com sucesso, o Workboard armazena no cartão a chave de sessão, ID de execução, mecanismo, modo, rótulo do modelo, status e log de worker. A chave de sessão é determinística para o quadro e o cartão, o que faz com que despachos repetidos voltem para a mesma faixa de worker em vez de criar sessões não relacionadas.

Se um worker não puder ser iniciado depois que um cartão for reivindicado, o Workboard bloqueia o cartão, limpa a reivindicação, registra a falha de início da execução e acrescenta uma linha de log de worker. Essa falha fica visível no painel, no JSON da CLI, nas ferramentas de agente e nos diagnósticos do cartão.

Pontos de entrada do despacho

Inícios de worker para cartões prontos podem acontecer a partir de:

• a ação de despacho do painel
• openclaw workboard dispatch
• /workboard dispatch em um canal com suporte a comandos

Todos os três pontos de entrada usam o runtime de subagente do Gateway quando o Gateway está disponível. A CLI tem um fallback adicional para operadores: se o Gateway estiver offline ou não expuser o método de despacho do Workboard e nenhum destino explícito --url ou --token tiver sido fornecido, ela executa despacho somente de dados contra o estado SQLite local. Esse fallback pode promover dependências, limpar reivindicações obsoletas e bloquear execuções com timeout, mas não pode iniciar workers.

Metadados de quadro podem incluir configurações de orquestração como autoDecompose, autoDecomposePerDispatch, defaultAssignee e orchestratorProfile. O OpenClaw registra a intenção de orquestração e a expõe no contexto do worker; a especificação e decomposição reais ainda acontecem pelas ferramentas normais do Workboard.

CLI e comando slash

O Plugin registra um comando raiz da CLI:

openclaw workboard listopenclaw workboard create "Fix stale card lifecycle" --priority high --labels bug,workboardopenclaw workboard show <card-id>openclaw workboard dispatch

openclaw workboard dispatch chama o Gateway em execução para que os inícios de worker usem o mesmo runtime de subagente do painel. Se o Gateway estiver indisponível, ele faz fallback para despacho somente de dados para que a promoção de dependências, a limpeza de reivindicações obsoletas e o bloqueio por timeout ainda possam ser executados. Falhas de autenticação, permissão e validação ainda aparecem como erros de comando, assim como falhas para destinos explícitos --url ou --token.

O comando de barra /workboard oferece suporte ao mesmo caminho compacto para operadores: /workboard list, /workboard show <card-id>, /workboard create <title> e /workboard dispatch. List e show são operações de leitura para remetentes de comando autorizados. Create e dispatch exigem status de proprietário em superfícies de chat ou um cliente Gateway com operator.write ou operator.admin.

Consulte CLI do Workboard para flags de comando, saída JSON, comportamento de fallback do Gateway, tratamento inequívoco de prefixos de id, regras de seleção de despacho e solução de problemas.

Sincronização do ciclo de vida da sessão

Cartões podem ser vinculados a sessões existentes do painel ou à sessão criada quando você inicia o trabalho a partir de um cartão. Cartões vinculados mostram o ciclo de vida da sessão inline: em execução, obsoleto, vinculado ocioso, concluído, com falha ou ausente.

Se a sessão vinculada estiver ausente, o cartão permanece vinculado para contexto e ainda oferece controles de início para que você possa reiniciar o trabalho em uma nova sessão do painel. Se uma sessão vinculada ativa parar de reportar atividade recente, o Workboard marca o cartão como obsoleto e armazena o marcador como metadados do cartão até que o ciclo de vida o limpe.

Você também pode capturar uma sessão existente do painel pela aba Sessions com Add to Workboard. O cartão é vinculado a essa sessão, usa o rótulo da sessão ou o prompt recente do usuário como título, e preenche as notas a partir do prompt recente do usuário mais a resposta mais recente do assistente quando o histórico de chat está disponível.

O Workboard acompanha a sessão vinculada enquanto o cartão ainda está em um estado de trabalho ativo:

• sessão vinculada ativa -> running
• sessão vinculada concluída -> review
• sessão vinculada com falha, encerrada, expirada por timeout ou abortada -> blocked

Estados manuais de revisão prevalecem. Se você mover um cartão para review, blocked ou done, o Workboard para de mover automaticamente esse cartão até que você o mova de volta para todo ou running.

Fluxo de trabalho do painel

1. Abra a aba Workboard na Control UI.
2. Crie um cartão com título, notas, prioridade, rótulos, agente opcional e sessão vinculada opcional.
3. Ou abra Sessions e escolha Add to Workboard para uma sessão existente.
4. Arraste o cartão entre colunas ou foque o controle compacto de status no cartão e use seu menu ou ArrowLeft/ArrowRight.
5. Inicie o trabalho a partir do cartão para criar ou reutilizar uma sessão do painel.
6. Abra a sessão vinculada pelo cartão enquanto o agente trabalha.
7. Deixe a sincronização do ciclo de vida mover o trabalho em execução para revisão ou bloqueado, depois mova manualmente o cartão para concluído quando aceito.

Iniciar um cartão usa sessões normais do Gateway. O plugin Workboard armazena apenas metadados e links do cartão; a transcrição da conversa, a seleção do modelo e o ciclo de vida da execução continuam pertencendo ao sistema regular de sessões.

Use Stop em um cartão vinculado ativo para abortar a execução da sessão ativa. O Workboard marca esse cartão como blocked para que ele permaneça visível para acompanhamento.

Novos cartões podem começar a partir de templates do Workboard para correções de bugs, docs, releases, revisões de PR ou trabalho em plugin. Os templates preenchem previamente título, notas, rótulos e prioridade, e o id do template selecionado é armazenado como metadados do cartão.

Permissões

O plugin registra métodos RPC do Gateway no namespace workboard.*:

• workboard.cards.list exige operator.read
• workboard.cards.export exige operator.read
• workboard.cards.diagnostics exige operator.read
• workboard.cards.diagnostics.refresh exige operator.write
• leituras de lista/obtenção de anexos e eventos de notificação exigem operator.read
• avanço do cursor de notificação exige operator.write
• métodos de criar, atualizar, mover, excluir, comentar, vincular, link de dependência, prova, artefato, adicionar/excluir anexo, log de worker, violação de protocolo, reivindicação, heartbeat, release, concluir, bloquear, desbloquear, despachar, em massa e arquivar exigem operator.write

Navegadores conectados com acesso de operador somente leitura podem inspecionar o quadro, mas não podem modificar cartões.

Configuração

O Workboard não tem configuração específica do plugin hoje. Habilite ou desabilite-o com a entrada padrão de plugin:

{  plugins: {    entries: {      workboard: {        enabled: true,        config: {},      },    },  },}

Desabilite-o novamente com:

openclaw plugins disable workboardopenclaw gateway restart

Solução de problemas

A aba diz que o Workboard está indisponível

Verifique a política de plugin:

openclaw plugins inspect workboard --runtime --json

Se plugins.allow estiver configurado, adicione workboard a essa lista de permissões. Se plugins.deny contiver workboard, remova-o antes de habilitar o plugin.

Cartões não são salvos

Confirme se a conexão do navegador tem acesso operator.write. Sessões de operador somente leitura podem listar cartões, mas não podem criá-los, editá-los, movê-los ou excluí-los.

Iniciar um cartão não abre a sessão esperada

O Workboard cria links para sessões normais do painel. Verifique o id do agente do cartão e a sessão vinculada, depois abra a visualização Sessions ou Chat para inspecionar o estado real da execução.

O despacho não inicia um worker

Confirme que há pelo menos um cartão ready sem uma reivindicação ativa:

openclaw workboard list --status ready

Se a CLI reportar despacho somente de dados, inicie ou reinicie o Gateway e tente novamente. O despacho somente de dados atualiza o estado local do quadro, mas não pode iniciar execuções de worker subagente.

Cartões também podem ser ignorados quando outro cartão para o mesmo proprietário ou agente já está em execução ou aguardando revisão. Conclua, bloqueie ou libere esse trabalho ativo antes de despachar mais trabalho para o mesmo proprietário.

Relacionado

• Control UI
• CLI do Workboard
• Plugins
• Gerenciar plugins
• Sessões