Secção 4: Criar os Ficheiros dos Teus Agentes

O Que Vais Construir

Cada agente precisa de um conjunto de ficheiros para funcionar corretamente. O OpenClaw lê os ficheiros principais automaticamente no início de cada sessão. Outros ficheiros de workspace dão a cada agente contexto, tarefas fixas e regras de ferramentas.

Configuração do agente — gerada automaticamente pelo OpenClaw, não crias isto aqui:

Ficheiro	Localização	Finalidade
`config.json`	`agents/[id]/config.json`	Definição do agente no OpenClaw, system prompt
`models.json`	`agents/[id]/models.json`	Definições do modelo de IA

Não crias estes ficheiros na Secção 4. Executar openclaw agents add [id] --workspace ... na Secção 5 gera ambos automaticamente ao registares cada agente — não há nada a fazer aqui além de saberes que existem.

Ficheiros de workspace — carregados automaticamente pelo OpenClaw em cada sessão:

Ficheiro	Finalidade
`SOUL.md`	Personalidade, tom, limites absolutos, missão — mantém abaixo de 400 palavras
`AGENTS.md`	Regras de operação, procedimentos de reporte — mantém abaixo de 400 palavras
`IDENTITY.md`	Nome, função, a quem reporta — apenas factos, mantém curto
`HEARTBEAT.md`	Tarefas fixas, trabalho periódico, resposta a anomalias
`TOOLS.md`	Ferramentas permitidas, regras de skills, ações proibidas
`USER.md`	Preferências do Comandante, estilo de comunicação, fuso horário

Ficheiro de detalhe da função — lido uma vez por sessão via instrução do AGENTS.md:

Ficheiro	Finalidade
`SPEC_[NOME].md`	Função detalhada, responsabilidades, caminhos-chave

Apenas CEO — pasta de identidade:

Ficheiro	Finalidade
`identity/COMPANY_PROFILE.md`	Contexto da empresa, detalhes do negócio
`identity/PERSONAL_PROFILE.md`	Historial do proprietário, competências, experiência
`identity/VALUES.md`	Estilo de pensamento, valores, princípios de decisão

Estrutura completa do workspace — todos os agentes:

INFO

$env:USERPROFILE/.opengoat/ ├── agents/ │ └── [agentid]/ │ ├── config.json ← gerado automaticamente na Secção 5 │ └── models.json ← gerado automaticamente na Secção 5 └── workspaces/ └── [agentid]/ ├── SOUL.md ← carregado automaticamente ├── AGENTS.md ← carregado automaticamente ├── IDENTITY.md ← carregado automaticamente ├── HEARTBEAT.md ← carregado automaticamente ├── TOOLS.md ← carregado automaticamente ├── USER.md ← carregado automaticamente └── SPEC_[NAME].md ← lido via instrução do AGENTS.md

Workspace do CEO — pasta de identidade adicional:

INFO

workspaces/ceo/ └── identity/ ├── COMPANY_PROFILE.md ├── PERSONAL_PROFILE.md └── VALUES.md

Como Funciona a Secção 4

Nesta secção, vais trabalhar com o teu AI concierge para conceber cada agente. Para cada agente, vais decidir:

Nome e função
Personalidade e estilo de comunicação
Que ferramentas pode usar

Depois de finalizares o design com o teu AI concierge, o teu Guardião de Segurança vai escrever os ficheiros de configuração automaticamente. Não precisas de editar nenhum ficheiro manualmente.

Como Esta Secção Funciona — Duas Partes

Esta secção tem duas partes. Completa-as por ordem:

Parte 1 — Configuração do Discord (o prompt abaixo) Cria o teu servidor do Discord, os canais, e obtém os URLs de Webhook para cada agente. Demora cerca de 10 minutos.

Parte 2 — Ficheiros de Agente (o próximo prompt) Gera os ficheiros reais de cada agente usando o teu Documento de Design de Equipa. A IA gera comandos de terminal — cola-os no VS Code para criar os ficheiros automaticamente.

Começa agora pela Parte 1.

URLs de Webhook do Discord — Obtém-nos Primeiro

Cada agente reporta ao seu próprio canal do Discord através de um URL de Webhook. Precisas destes URLs antes de escreveres os ficheiros AGENTS.md.

▶ Cola isto no teu AI para começar

Anexa o teu Documento de Design de Equipa antes de enviares.

Estás a ajudar-me a configurar os canais do Discord e os URLs de Webhook
para a minha equipa multi-agente do BALIA OS.

Guia-me passo a passo. Faz uma pergunta de cada vez.
Se eu ficar preso, pede-me para tirar uma captura de ecrã e descrever o que vejo.

Anexei o meu Documento de Design de Equipa.

PASSO 1 — Verificar o Discord
Pergunta: "Tens o Discord instalado e uma conta configurada?"
Se não: guia-me a discord.com para descarregar e criar uma conta.
Se sim: avança para o Passo 2.

PASSO 2 — Criar um servidor do Discord
Guia-me a criar um novo servidor:
- Clicar no botão + na barra lateral esquerda
- Selecionar "Criar o Meu" -> "Para mim e para os meus amigos"
- Chamar-lhe "BALIA OS Team"
Confirma que consigo vê-lo antes de continuares.

PASSO 3 — Criar canais para cada agente
Lê o meu Documento de Design de Equipa para os nomes dos canais.
Para cada agente, cria um canal de texto:
- Clicar com o botão direito em "Canais de Texto" -> Adicionar Canal -> Texto
- Usar o nome do canal do meu Documento de Design de Equipa
Repete para os 6 agentes. Confirma que todos os canais existem antes de continuares.

PASSO 4 — Obter um URL de Webhook para cada canal
Um canal de cada vez:
1. Clicar com o botão direito no canal -> Editar Canal
2. Integrações -> Webhooks -> Novo Webhook
3. Dar-lhe o nome do agente (ex. "Marcus")
4. Copiar o URL do Webhook
5. Pedir-me para colar num sítio seguro
Repete para os 6. Confirma que os 6 URLs estão guardados antes de continuares.

PASSO 5 — Adicionar ao ficheiro .env
Guia-me a abrir o ficheiro .env no VS Code.
O ficheiro está em:
- Windows: $env:USERPROFILE\.opengoat\.env
- Mac: ~/.opengoat/.env
Adiciona cada webhook:
DISCORD_WEBHOOK_[NOMEAGENTE]=https://discord.com/api/webhooks/xxxxx/xxxxx
(nomes de agentes em MAIÚSCULAS)
Diz-me: "Nunca partilhes este ficheiro. Nunca o submetas ao GitHub."

Quando todos os webhooks estiverem guardados: "Configuração do Discord concluída."

Começa agora. Faz-me a primeira pergunta.

Usar o Prompt de IA

Cola o prompt abaixo no teu chat de IA e anexa:

O teu Documento de Design de Equipa da Secção 2

A IA gera comandos de terminal para cada agente, um de cada vez. Cola os comandos no teu terminal do VS Code para criar os ficheiros automaticamente.

▶ Cola isto no teu AI para começar

Estás a ajudar-me a criar os ficheiros dos agentes para o BALIA OS,
um sistema operativo de IA multi-agente construído sobre o OpenClaw.

Anexo:
1. O meu Documento de Design de Equipa (da Secção 2)

Lê-o antes de gerares o que quer que seja.
Extrai todos os nomes de agentes, IDs e nomes de canais do Discord deste documento.

ARQUITETURA:

1. Eu sou o Comandante. Comando cada agente diretamente. Sem orquestrador.

2. Cada agente tem dois locais:
   - agents/[id]/ — configuração do OpenClaw (config.json + models.json)
   - workspaces/[id]/ — ficheiros de workspace (SOUL, AGENTS, IDENTITY, HEARTBEAT, TOOLS, USER, SPEC)
   Todos os caminhos ficam dentro de $env:USERPROFILE/.opengoat/

3. O OpenClaw auto-injeta SOUL.md, AGENTS.md, IDENTITY.md, HEARTBEAT.md,
   TOOLS.md, USER.md no início de cada sessão. Não escrevas instruções
   "lê-te a ti próprio" nestes ficheiros.

4. SPEC_[NOME].md NÃO é auto-injetado. Adiciona ao "Início de Sessão" do AGENTS.md:
   "Ler SPEC_[NOMEAGENTE].md para detalhes completos da função"

5. Só o CEO tem uma pasta identity/ dentro de workspaces/ceo/:
   identity/COMPANY_PROFILE.md
   identity/PERSONAL_PROFILE.md
   identity/VALUES.md
   Gera estes ficheiros apenas para o agente CEO.

6. SOUL.md e AGENTS.md: menos de 400 palavras cada (injetados em cada sessão).
   SPEC: pode ser detalhado (lido uma vez por sessão).

ANTES DE GERAR — pergunta-me:
"Qual é o teu nome de utilizador do Windows? (O nome em C:\Users\[nomedeutilizador])"
Aguarda a minha resposta e depois usa esse nome de utilizador em todos os caminhos de ficheiros.

GERAR PARA CADA AGENTE:

====================================
FICHEIRO 1: SOUL.md
Caminho: $env:USERPROFILE/.opengoat/workspaces/[agentid]/SOUL.md
Auto-injetado em cada sessão. Menos de 400 palavras.
====================================

# SOUL.md — [Nome do Agente]

## Quem És
[2-3 frases: identidade, personalidade, abordagem de trabalho]

## Tom
- [Regra 1]
- [Regra 2]
- [Regra 3]
- [Estilo proibido]

## Limites Absolutos
- Nunca agir fora da função definida
- Nunca reportar como concluído sem verificar o resultado
- Nunca tomar ação destrutiva sem aprovação do Comandante
- [1-2 limites específicos da função]

## Missão Atual
[1-2 frases sobre o foco atual]

====================================
FICHEIRO 2: AGENTS.md
Caminho: $env:USERPROFILE/.opengoat/workspaces/[agentid]/AGENTS.md
Auto-injetado em cada sessão. Menos de 400 palavras.
====================================

# AGENTS.md — Procedimentos de Operação de [Nome do Agente]

## Início de Sessão (Cada sessão — por esta ordem)
1. Confirmar identidade a partir do SOUL.md
2. Ler SPEC_[NOMEAGENTE].md para detalhes da função
3. Ler HEARTBEAT.md — anotar tarefas fixas
4. Ler TOOLS.md — anotar ferramentas permitidas e restrições
5. Ler USER.md — anotar preferências do Comandante
6. Reportar no Discord: "🔷 [Nome] pronto. [tarefa ou estado atual]"

(Apenas CEO — depois do passo 2, ler também:
  identity/COMPANY_PROFILE.md
  identity/PERSONAL_PROFILE.md
  identity/VALUES.md)

## Fim de Sessão (Cada sessão)
1. Reportar no Discord: "✅ [Nome] sessão concluída. [resumo]"
2. Anotar tarefas por concluir para a próxima sessão

## Relatórios
- Canal: #[canal-discord]
- Comando: python $env:USERPROFILE/.opengoat/scripts/discord_send.py
  DISCORD_WEBHOOK_[NOME] "mensagem"
  (o discord_send.py é implementado automaticamente na secção "Implementar
  o Guardião de Segurança" abaixo)
- HTTP 204 = sucesso. Caso contrário = reportar falha imediatamente.
- Formato: Conclusão -> Detalhe -> Próxima ação recomendada
- Reportar em: início de sessão / tarefa concluída / erro / fim de sessão

## Tratamento de Erros
1. Verificar SPEC_[NOME].md para padrões de erro conhecidos
2. Não resolvido -> reportar detalhes completos ao Comandante
3. Sem tentativas destrutivas sem aprovação do Comandante

## Regras Absolutas
- Verificar antes de reportar como concluído
- Sem ações fora da função definida
- Sem operações destrutivas sem aprovação do Comandante

====================================
FICHEIRO 3: IDENTITY.md
Caminho: $env:USERPROFILE/.opengoat/workspaces/[agentid]/IDENTITY.md
Auto-injetado. Apenas factos, mantém curto.
====================================

# IDENTITY.md

Name: [Nome do Agente]
Agent ID: [agentid-minúsculas]
Role: [Título da Função]
Department: BALIA OS Team
Reports To: Commander (directly)
Discord: #[nome do canal]

====================================
FICHEIRO 4: HEARTBEAT.md
Caminho: $env:USERPROFILE/.opengoat/workspaces/[agentid]/HEARTBEAT.md
Auto-injetado. Tarefas fixas e resposta a anomalias.
====================================

# HEARTBEAT.md — [Nome do Agente]

## Sempre Ativo
[O que este agente monitoriza ou mantém continuamente]

## Tarefas Periódicas
[Obrigações recorrentes — diárias, semanais, ou acionadas por um gatilho]

## No Início de Sessão
- Ler SOUL.md e AGENTS.md
- Reportar: "🔷 [Nome] pronto"

## Em Caso de Erro ou Anomalia
- Reportar imediatamente ao Comandante via Discord
- Nunca se autocorrigir sem aprovação do Comandante

====================================
FICHEIRO 5: TOOLS.md
Caminho: $env:USERPROFILE/.opengoat/workspaces/[agentid]/TOOLS.md
Auto-injetado. Regras e restrições de ferramentas.
====================================

# TOOLS.md — Regras de Ferramentas de [Nome do Agente]

## Princípio Central
- Verificar SPEC_[NOME].md antes de cada tarefa para as ferramentas permitidas
- Carregar apenas o que a tarefa exigir

## Ferramentas Permitidas
[Listar ferramentas relevantes para a função deste agente]

## Relatórios no Discord
Usar sempre diretamente o discord_send.py:
python $env:USERPROFILE/.opengoat/scripts/discord_send.py DISCORD_WEBHOOK_[NOME] "mensagem"
Confirmar HTTP 204 depois de enviar.

## Proibido
- Codificar chaves de API ou Webhooks diretamente (ler sempre do .env)
- Ações fora da função definida
- Comunicação externa desnecessária

====================================
FICHEIRO 6: USER.md
Caminho: $env:USERPROFILE/.opengoat/workspaces/[agentid]/USER.md
Auto-injetado. Preferências do Comandante.
====================================

# USER.md — Perfil do Comandante

## Nome
[Nome pelo qual o Comandante prefere ser tratado]

## Fuso Horário
[Fuso horário — pergunta-me se não estiver no Documento de Design de Equipa]

## Estilo de Comunicação
- [Preferência 1]
- [Preferência 2]

## Fase Atual
[Naquilo em que estamos focados a construir agora]

====================================
FICHEIRO 7: SPEC_[NOMEAGENTE].md
Caminho: $env:USERPROFILE/.opengoat/workspaces/[agentid]/SPEC_[NOMEAGENTE].md
Não auto-injetado. Lido uma vez por sessão via AGENTS.md.
====================================

# SPEC_[NOMEAGENTE] v1.0 — [Nome do Agente] ([Função])
Última atualização: [hoje]

## 1. Função
[2-3 frases]

## 2. Responsabilidades
[Lista de pontos do Documento de Design de Equipa]

## 3. O que Este Agente NÃO Faz
[Limites claros]

## 4. Missão da Fase Atual
[Foco atual]

## 5. Caminhos-Chave
- Workspace: $env:USERPROFILE/.opengoat/workspaces/[agentid]/
- Discord webhook: DISCORD_WEBHOOK_[NOME] (lido do .env)

## 6. Registo de Alterações
| Versão | Data | Alterações |
|---------|------|---------|
| v1.0 | [hoje] | Criação inicial |

====================================
APENAS CEO — FICHEIROS 8, 9, 10: pasta identity/
Faz estas 3 perguntas uma de cada vez antes de gerares.
====================================

Q1: "Fala-me sobre o teu negócio — o que faz, há quanto tempo
    está em funcionamento, que mercados serve."

Q2: "Fala-me sobre ti — experiência, competências, formação
    relevantes para este negócio."

Q3: "Como tomas decisões? Que valores te guiam?
    Que estilos de pensamento ou perspetivas gostarias de ter mais?"

Depois das 3 respostas, gera:

COMPANY_PROFILE.md — conteúdo da Q1, estruturado
PERSONAL_PROFILE.md — conteúdo da Q2, estruturado
VALUES.md — conteúdo da Q3, estruturado

Caminho: $env:USERPROFILE/.opengoat/workspaces/ceo/identity/

Quanto mais detalhe for dado aqui, mais o CEO pensa e
decide como o próprio proprietário.

====================================

COMO ENTREGAR OS FICHEIROS:

Depois de gerares o conteúdo de cada ficheiro, gera o comando python exato
para o criar. Formato:

--- COLA NO TERMINAL (Windows) ---
python -c "
content = '''[conteúdo completo do ficheiro aqui]'''
import os
path = r'$env:USERPROFILE/.opengoat/workspaces/[agentid]/SOUL.md'
os.makedirs(os.path.dirname(path), exist_ok=True)
open(path, 'w', encoding='utf-8').write(content)
print('Created:', path)
"

--- COLA NO TERMINAL (Mac) ---
python3 -c "
content = '''[conteúdo completo do ficheiro aqui]'''
import os
path = os.path.expanduser('~/.opengoat/workspaces/[agentid]/SOUL.md')
os.makedirs(os.path.dirname(path), exist_ok=True)
open(path, 'w', encoding='utf-8').write(content)
print('Created:', path)
"

Aguarda que eu cole o comando e confirme que correu antes de avançares
para o próximo ficheiro. Pergunta: "Viste 'Created: [caminho]'?"

COMO PROCEDER:
- Começa pelo Agente #1 (não o CEO)
- Gera um ficheiro de cada vez, um agente de cada vez
- Aguarda sempre a confirmação do terminal antes do próximo ficheiro
- Ao chegares ao CEO: faz primeiro as 3 perguntas de identidade,
  depois gera os 7 ficheiros principais + 3 ficheiros de identidade
- Termina com uma tabela de resumo de todos os ficheiros criados

Assim que o teu AI concierge confirmar o design, pede ao Guardião de Segurança que escreva os ficheiros:

Windows:

openclaw agent --agent security-guardian "Write the confirmed agent config to the correct path and verify the file was created."

O Guardian vai confirmar quando os ficheiros estiverem escritos corretamente.

Passo 2 — Confirma que os Ficheiros Foram Criados

Depois de a IA te guiar por todos os ficheiros, confirma o workspace de cada agente:

Windows:

dir $env:USERPROFILE\.opengoat\workspaces\[agentid]

Mac:

ls ~/.opengoat/workspaces/[agentid]

Deves ver:

SOUL.md
AGENTS.md
IDENTITY.md
HEARTBEAT.md
TOOLS.md
USER.md
SPEC_[NAME].md

O CEO terá adicionalmente:

identity/
├── COMPANY_PROFILE.md
├── PERSONAL_PROFILE.md
└── VALUES.md

Passo 3 — Verifica Antes de Avançar para o Próximo Agente

Abre o AGENTS.md. A secção "Início de Sessão" lista todos os passos, incluindo HEARTBEAT.md, TOOLS.md e USER.md?

Sim -> avança. Não -> pede à IA para corrigir primeiro.

Quando Esta Secção Estiver Completa

Workspace de cada agente:

INFO

workspaces/[agentid]/ ├── SOUL.md ✅ ├── AGENTS.md ✅ ├── IDENTITY.md ✅ ├── HEARTBEAT.md ✅ ├── TOOLS.md ✅ ├── USER.md ✅ └── SPEC_[NAME].md ✅

O CEO terá adicionalmente:

INFO

workspaces/ceo/ └── identity/ ├── COMPANY_PROFILE.md ✅ ├── PERSONAL_PROFILE.md ✅ └── VALUES.md ✅

Nota: O Guardião de Segurança foi implementado na Secção 3. Se saltaste a Secção 3, volta atrás e conclui-a antes de avançares para a Secção 5.

Verifica a Tua Configuração

Depois de completares todos os ficheiros de agentes, executa:

Windows:

node $env:USERPROFILE\.opengoat\workspaces\security-guardian\scripts\verify_setup.js --section 4

Mac:

node ~/.opengoat/workspaces/security-guardian/scripts/verify_setup.js --section 4

Isto confirma que todos os ficheiros dos agentes estão prontos antes de lançares a tua equipa na Secção 5.

O Que Vais Construir ​

Como Funciona a Secção 4 ​

Como Esta Secção Funciona — Duas Partes ​

URLs de Webhook do Discord — Obtém-nos Primeiro ​

▶ Cola isto no teu AI para começar

Usar o Prompt de IA ​

▶ Cola isto no teu AI para começar

Passo 2 — Confirma que os Ficheiros Foram Criados ​

Passo 3 — Verifica Antes de Avançar para o Próximo Agente ​

Quando Esta Secção Estiver Completa ​

Verifica a Tua Configuração ​

O Que Vais Construir

Como Funciona a Secção 4

Como Esta Secção Funciona — Duas Partes

URLs de Webhook do Discord — Obtém-nos Primeiro

Usar o Prompt de IA

Passo 2 — Confirma que os Ficheiros Foram Criados

Passo 3 — Verifica Antes de Avançar para o Próximo Agente

Quando Esta Secção Estiver Completa

Verifica a Tua Configuração