Introdução ao OpenMOSS: Transforme a IA em uma equipe de empresa que opera 24 horas por dia através da colaboração Multi-Agent

Dificuldade: Iniciante | Duração: 30 Minutos | Ganhos: Compreender o sistema de colaboração de quatro funções do OpenMOSS e construir sua própria equipe de IA

---

Público-Alvo

Você já usa o OpenClaw e sentiu o poder de um Agente único — ele pode conversar, escrever código e executar tarefas. Mas você também deve ter notado: assim que a tarefa se torna complexa ou exige colaboração em várias etapas, um Agente individual pode facilmente ficar travado em algum ponto e "morrer" ali, esperando que você o impulsione.

O OpenMOSS visa resolver exatamente esse problema. Sua ideia é simples: não deixe que um único Agente carregue tudo sozinho; em vez disso, instale uma estrutura organizacional na IA. O Planejador desmembra as demandas, o Executor faz o trabalho, o Revisor controla a qualidade e o Patrulheiro monitora tudo — quatro funções, cada uma com suas responsabilidades, operando de forma autônoma através de despertadores agendados para formar uma equipe de IA em ciclo fechado.

O OpenMOSS em si é um middleware; ele não se preocupa com o negócio específico, mas sim com o agendamento e a colaboração. Quaisquer Skills que você configurar para ele, ele poderá colaborar automaticamente para concluir a tarefa.

Este artigo é ideal para:

• Quem já usa o OpenClaw e quer experimentar a colaboração Multi-Agent.
• Quem precisa que a IA funcione de forma contínua e automática, sem supervisão humana.
• Quem deseja construir pipelines de produção de conteúdo, operações automatizadas (AIOps), revisão de código e outros fluxos de trabalho.

---

Dependências Principais e Ambiente

Repositório GitHub: https://github.com/uluckyXH/OpenMOSS

---

Estrutura Completa do Projeto

OpenMOSS/
├── app/                          # Backend FastAPI
│   ├── main.py                   # Entrada: registro de rotas, middleware, serviço estático SPA
│   ├── config.py                 # Carregamento de configuração
│   ├── database.py               # Inicialização do banco (SQLAlchemy)
│   ├── models/                  # Modelos de dados (10 tabelas)
│   ├── routers/                 # Rotas da API
│   ├── services/                # Camada de lógica de negócio
│   └── schemas/                 # Modelos de serialização Pydantic
├── webui/                        # Código-fonte do frontend Vue 3 (precisa de build)
├── static/                       # Artefatos de build do frontend (servidos pelo backend)
├── prompts/                      # Templates de prompts para funções de Agentes
│   ├── templates/                # Templates base das funções
│   ├── agents/                   # Exemplos de prompts de Agentes
│   └── tool/                    # Prompts para chamadas de ferramentas
├── skills/                        # Definições de Skills do Agente OpenClaw
│   ├── task-cli.py              # Script de chamada de API comum a todas as Skills
│   ├── task-planner-skill/      # Skill do Planejador
│   ├── task-executor-skill/      # Skill do Executor
│   ├── task-reviewer-skill/     # Skill do Revisor
│   ├── task-patrol-skill/       # Skill do Patrulheiro
│   └── dist/                    # Pacotes .zip de Skills compiladas
├── config.example.yaml            # Template de arquivo de configuração
├── requirements.txt              # Dependências Python
├── Dockerfile
└── docker-compose.yml

---

Passo a Passo

Passo 1: Clonar o Projeto e Instalar Dependências

# Clonar o projeto
git clone https://github.com/uluckyXH/OpenMOSS.git openmoss
cd openmoss

# Instalar dependências Python
pip install -r requirements.txt

Se não houver o diretório static/ no seu repositório (frontend não buildado), você precisará buildar o frontend:

cd webui
npm install
npm run build

# Copiar os artefatos para o diretório static/
rm -rf ../static/*
cp -r dist/* ../static/
cd ..

---

Passo 2: Configurar o config.yaml

Na primeira inicialização, o OpenMOSS gerará automaticamente o config.yaml a partir do config.example.yaml. Recomenda-se copiar o template e modificar:

cp config.example.yaml config.yaml

Em seguida, edite o config.yaml. Os seguintes campos devem ser configurados:

# Senha do administrador (criptografada automaticamente após o primeiro login)
admin:
  password: "sua-senha-segura-aqui"

# Token de registro do Agente (necessário ao registrar Agentes, recomenda-se gerar aleatoriamente)
agent:
  registration_token: "seu-token-aleatorio-aqui"
  allow_registration: true

# Diretório de trabalho (onde os produtos dos Agentes serão armazenados)
workspace:
  root: "/home/seu-usuario/TaskWork"

# Endereço externo do serviço (endereço que o Agente acessa ao se conectar)
server:
  external_url: "http://seu-ip-do-servidor:6565"

---

Passo 3: Iniciar o Serviço e Concluir o Assistente de Inicialização

python -m uvicorn app.main:app --host 0.0.0.0 --port 6565

A primeira inicialização fará automaticamente:

1. Gerar o config.yaml (se não existir)
2. Inicializar o banco de dados SQLite (data/tasks.db)
3. Montar o frontend (se o diretório static/ existir)

Abra o navegador em http://localhost:6565. Você será redirecionado para o assistente que o guiará para:

• Definir a senha do administrador
• Configurar o nome do projeto
• Gerar o token de registro de Agentes
• Configurar canais de notificação (opcional)

Ao concluir, os endereços do serviço serão exibidos:

---

Passo 4: Login na WebUI e Familiarização com o Painel

Após a inicialização, faça login com a conta de administrador. Você verá as seguintes páginas:

A lista de Agentes estará vazia no início — ainda não registramos nenhum Agente. Começaremos a criá-los no Passo 5.

---

Passo 5: Criar os Quatro Agentes e Registrá-los no OpenClaw

As quatro funções do OpenMOSS correspondem a responsabilidades distintas:

Cada Agente é essencialmente uma instância executando o OpenClaw. Usaremos a criação do planner como exemplo; o processo para as outras três funções é idêntico.

Opção 1: Registro via WebUI (Recomendado)

1. Na página de Agentes da WebUI, clique em "Registrar Agente".
2. Preencha as informações básicas:

Função: planner
Nome: OpenMOSS-Planner
Token de Registro: (Preencha com o agent.registration_token do config.yaml)

1. Após o envio, a WebUI retornará:
   • API Key do Agente (salve-a, ela aparece apenas uma vez)
   • Endereços de download do SKILL.md e task-cli.py do Agente
   • Guia de integração (comandos de registro, método de configuração)

Opção 2: Registro via API

curl -X POST http://localhost:6565/api/agents/register \
  -H "X-Registration-Token: seu-token-de-registro" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenMOSS-Planner",
    "role": "planner"
  }'

O retorno conterá a API Key, o comando de registro e as URLs de Skills:

{
  "api_key": "om_xxxxxxxxxxxxxxxxxxxx",
  "skill_cli_url": "http://localhost:6565/skills/task-cli.py",
  "skill_url": "http://localhost:6565/skills/task-planner-skill/SKILL.md",
  "register_command": "openclaw agents add ..."
}

Registre os outros três Agentes da mesma forma:

executor → task-executor-skill
reviewer → task-reviewer-skill
patrol   → task-patrol-skill

---

Passo 6: Configurar as Skills do Agente

Após o registro bem-sucedido, cada Agente receberá dois arquivos cruciais:

• task-cli.py — Script de chamada de API do OpenMOSS compartilhado entre as funções.
• SKILL.md — Definição de Skill exclusiva para aquela função.

Coloque-os em um diretório legível pelo OpenClaw (geralmente junto com o prompt do Agente):

# Supondo o diretório de configuração do Agente OpenClaw
mkdir -p ~/.openclaw/agents/openmoss-planner/skills

# Baixar arquivos de Skill
curl -o ~/.openclaw/agents/openmoss-planner/skills/task-cli.py \
  http://localhost:6565/skills/task-cli.py

curl -o ~/.openclaw/agents/openmoss-planner/skills/SKILL.md \
  http://localhost:6565/skills/task-planner-skill/SKILL.md

Em seguida, na configuração do Agente no OpenClaw, adicione o caminho do SKILL.md ao Prompt ou à configuração de Skills para que o Agente saiba quais APIs do OpenMOSS ele pode chamar.

---

Passo 7: Configurar o Cron para Despertar e Fazer o Agente "Trabalhar"

Esta é a maior diferença entre o OpenMOSS e um Agente comum: o Agente não espera você enviar uma mensagem para agir; ele bate o ponto como um funcionário.

Na configuração do Agente no OpenClaw, defina tarefas cron para cada Agente:

planner (Planejador) — Verifica novas tarefas a cada 30 minutos:

{
  "cron": "*/30 * * * *",
  "task": "Verificar a fila de tarefas do OpenMOSS; se houver novas tarefas não planejadas, executar o fluxo de planejamento"
}

executor (Executor) — Verifica tarefas pendentes a cada 15 minutos:

{
  "cron": "*/15 * * * *",
  "task": "Verificar a fila de subtarefas do OpenMOSS, reivindicar e executar"
}

reviewer (Revisor) — Verifica entregas para revisão a cada 20 minutos:

{
  "cron": "*/20 * * * *",
  "task": "Verificar a fila de revisão do OpenMOSS, processar entregas pendentes"
}

patrol (Patrulheiro) — Inspeciona o estado do sistema a cada 10 minutos:

{
  "cron": "*/10 * * * *",
  "task": "Verificar o estado do sistema OpenMOSS, marcar tarefas bloqueadas e alertar sobre anomalias imediatamente"
}

O fluxo de trabalho do Agente ao ser despertado é fixo:

1. Chama a API do OpenMOSS para obter o status atual.
2. Executa a operação correspondente à sua função.
3. Grava o resultado de volta no OpenMOSS.
4. Entra em modo de hibernação, aguardando o próximo despertar.

Todo o processo não requer intervenção humana.

---

Passo 8: Emitir a Primeira Tarefa e Validar o Ciclo de Colaboração

Na página de "Gestão de Tarefas" da WebUI, clique em "Criar Tarefa" e preencha:

Nome da Tarefa: Tradução e Publicação Automática de Notícias de IA
Objetivo: Coletar notícias de IA/Tecnologia/Digital da internet chinesa, traduzi-las para o inglês e publicá-las

Quando o Planejador (planner) for despertado pelo cron, ele irá:

1. Receber a tarefa e dividi-la em módulos (Coleta → Tradução → Revisão → Publicação).
2. Criar subtarefas (sub-tasks) para cada módulo.
3. Definir critérios de aceitação para cada subtarefa.

Quando o Executor (executor) for despertado, ele irá:

1. Reivindicar a primeira subtarefa pendente da fila.
2. Executar o trabalho (busca online, tradução de conteúdo).
3. Enviar a entrega para a fila de revisão.

Quando o Revisor (reviewer) for despertado, ele irá:

1. Obter as entregas pendentes de revisão.
2. Pontuar com base nos critérios de aceitação.
3. Se aprovado, marcar a subtarefa como concluída; se rejeitado, devolver ao Executor para retrabalho.

O Patrulheiro (patrol) monitora continuamente o sistema:

• Se uma subtarefa não tiver progresso além do limite, ele marca automaticamente como blocked.
• Se detectar um aumento anômalo na taxa de rejeição, envia um alerta.
• Se detectar que um Executor entrou em loop infinito, notifica o administrador.

Você pode acompanhar toda a dinâmica de trabalho dos Agentes em tempo real na página "Fluxo de Atividade" da WebUI.

---

Passo 9: Configurar Canais de Notificação

O OpenMOSS suporta notificações automáticas para eventos críticos. Configure os canais no config.yaml:

notification:
  enabled: true
  channels:
    - "ID-do-Grupo-Lark"    # É necessário adicionar o Agente ao grupo e mencioná-lo para obter o chat_id
    - "user:ou_xxx"         # open_id do usuário Lark
  events:
    - task_completed        # Subtarefa concluída
    - review_rejected       # Revisão rejeitada (retrabalho)
    - all_done              # Todas as subtarefas concluídas
    - patrol_alert           # Anomalia detectada pela patrulha

O Agente lerá as configurações de notificação da interface GET /config/notification e usará suas próprias capacidades (e-mail, Lark, etc.) para enviar as notificações.

---

Solução de Problemas Comuns

1. Falha no registro do Agente (registration_token incompatível)

Sintoma: O registro do Agente retorna erro 403 ou "invalid token".

A causa mais comum é a inconsistência do registration_token. Verifique dois pontos:

1. O valor de agent.registration_token no config.yaml do OpenMOSS.
2. O valor de X-Registration-Token no Header da requisição de registro do Agente.

Ambos devem ser idênticos, incluindo espaços e maiúsculas. Se você alterou o config.yaml, lembre-se de reiniciar o serviço OpenMOSS.

---

2. O cron não desperta o Agente

Sintoma: O Agente não inicia o trabalho automaticamente e não há logs de erro no console.

Ordem de verificação:

1. Confirme se a configuração cron no OpenClaw está correta — a expressão cron é válida? A descrição da tarefa está clara?
2. Confirme se a instância OpenClaw está rodando — o processo OpenClaw correspondente ao Agente está ativo?
3. Verifique se a API Key do Agente é válida — veja se o status na página de Agentes da WebUI é "active".

Você pode usar a página de Agentes na WebUI para ver a hora da última atividade de um Agente específico e julgar se ele está sendo despertado.

---

3. Subtarefa rejeitada repetidamente, entrando em loop

Sintoma: A entrega do executor é constantemente rejeitada pelo revisor, e a mesma subtarefa é refeita sem parar.

Isso geralmente indica que o executor tem uma interpretação errada dos critérios de aceitação ou que os próprios critérios estão mal definidos.

Solução:

1. Veja os registros de rejeição na WebUI para ler a justificativa do revisor.
2. Ajuste os critérios de aceitação que o planeador escreveu ao criar a subtarefa, tornando-os mais específicos e quantificáveis.
3. Se for insuficiência de capacidade do executor, tente mudar para um modelo mais potente (atualize a API Key do LLM no Agente OpenClaw).

---

4. Patrulha (patrol) sem resposta

Sintoma: Existem tarefas bloqueadas no sistema, mas o patrulheiro não as marcou nem enviou alertas.

Verificação:

1. A instância OpenClaw do Agente patrol está rodando?
2. O intervalo do cron do patrol é muito longo? (Configurar */10 é muito mais sensível que */60).
3. O notification está ativado no config.yaml e os canais estão corretos?
4. O Agente patrol possui a Skill de envio de notificações (Lark/E-mail)?

---

5. API Key expirada ou permissões insuficientes

Sintoma: O Agente para de trabalhar repentinamente, aparecendo erros 401 ou 403 nos logs.

A API Key do Agente (começando com om_xxx) é a credencial interna do OpenMOSS, não é a mesma do LLM. Se houver erro de autenticação do LLM nos logs, o problema é com a API Key do provedor de IA (cota esgotada, revogação, etc.).

Solução: Atualize a API Key do LLM na configuração do Agente OpenClaw e reinicie a instância do Agente.

---

6. Múltiplos executores reivindicando a mesma tarefa

Sintoma: Dois executores começam a fazer a mesma subtarefa, gerando trabalho duplicado.

A fila de tarefas do OpenMOSS possui proteção de atomicidade; teoricamente, isso não deveria ocorrer. Se acontecer, pode ser:

1. Intervalos cron dos executores muito curtos, fazendo-os acordar quase simultaneamente.
2. Atraso na atualização do status da tarefa, fazendo o executor ler dados antigos.

Solução: Aumente o intervalo cron dos executores (ex: de */5 para */15) para dar tempo suficiente para a atualização do status após cada processamento.

---

Leituras Complementares / Direções Avançadas

1. Personalização de Prompts de Funções

O diretório prompts/ contém templates para cada função. Você pode modificá-los para criar uma personalidade de Agente que atenda às suas necessidades específicas:

# Editar prompt do Planejador
vim prompts/agents/planner-agent-prompt.md

# Editar prompt do Executor
vim prompts/agents/executor-agent-prompt.md

Após a alteração, o Agente lerá a nova versão no próximo despertar.

2. Integração com Skill do WordPress para Publicação Automática

O diretório skills/wordpress-skill/ oferece a capacidade de publicação em WordPress. Usado com um executor, permite que o Agente publique automaticamente artigos traduzidos sem intervenção humana.

É necessário configurar a URL do site WordPress e a API Key:

# Ver instruções de configuração da Skill do WordPress
cat skills/wordpress-skill/SKILL.md

3. Ajuste do Sistema de Pontos e Desempenho

O OpenMOSS possui um mecanismo de pontos nativo. A pontuação do revisor afeta diretamente o ranking de desempenho do executor. Você pode conferir a qualidade da produção na página de Ranking de Pontos na WebUI.

Para tornar o sistema mais rigoroso ou flexível, basta modificar a descrição dos critérios de pontuação no prompt do revisor.

4. Integração com Skill Grok Search para Busca Online

O diretório skills/grok-search-runtime/ fornece a capacidade de busca Grok. Com esta Skill, o Executor pode capturar notícias em tempo real para traduzir e publicar — este é o fluxo principal do caso real 1M Reviews.

5. Migração para PostgreSQL / MySQL

Por padrão, o OpenMOSS usa SQLite, ideal para equipes de pequeno e médio porte. Para maior suporte a concorrência, mude para PostgreSQL ou MySQL:

# config.yaml
database:
  type: postgresql  # ou mysql
  path: ""           # deixe vazio se usar a string de conexão abaixo
  connection_string: "postgresql://usuario:senha@localhost:5432/openmoss"

6. Implantação com Docker

O projeto oferece Dockerfile e docker-compose.yml para implantar todo o ambiente com um comando:

# Iniciar todos os serviços
docker-compose up -d

# Ver logs
docker-compose logs -f

Isso empacotará o OpenMOSS, o banco de dados e o frontend, ideal para validação rápida ou migração para servidor.

7. Construa seu Próprio Pipeline de Produção de Conteúdo

Referenciando o caso real da 1M Reviews, o pipeline completo é:

1. planner divide a tarefa: Coleta → Tradução → Revisão → Publicação.
2. executor (Coleta) captura notícias via Grok Search Skill.
3. executor (Tradução) chama API de tradução para reescrever o conteúdo.
4. reviewer revisa a qualidade e o formato do conteúdo.
5. executor (Publicação) chama a Skill do WordPress para publicar no site.
6. patrol monitora o estado de execução e alerta sobre anomalias.

Todo o fluxo opera de forma autônoma; você só define o objetivo no início e valida o resultado no final.