caoyachao/openclaw-criar-agente

Cenários de Uso

Ative esta Skill quando o usuário precisar de:

• "Me ajude a criar um novo agente"
• "Adicionar um novo agent"
• "Configurar um robô do Feishu"
• "Criar um agent para meu personagem de romance/assistente/avatar"
• "Como adicionar um agent no OpenClaw"

Conceitos Principais

Divisão de Dois Diretórios

Diretório	Finalidade	Mantido Manualmente?
~/.openclaw/workspace/agents/<agent>/	Workspace da Alma (personalidade, memória, diário, regras)	✅ Sim, criado e mantido manualmente
~/.openclaw/agents/<agent>/	Dados de Runtime (histórico de sessões, models.json)	❌ Gerado automaticamente pelo sistema

Regra: Nunca crie arquivos manualmente dentro de ~/.openclaw/agents/.

Estrutura Padrão do Diretório do Agent

Ao criar um agent, estabeleça os seguintes arquivos e diretórios em ~/.openclaw/workspace/agents/<nome-do-agent>/:

~/.openclaw/workspace/agents/<nome-do-agent>/
├── AGENTS.md              # Regras de trabalho, políticas de segurança, comportamento de heartbeat
├── IDENTITY.md            # Arquivo de identidade (nome, espécie, temperamento, frase de efeito, emoji)
├── SOUL.md                # Definição da alma (personalidade central, modo de falar, âncoras de valor)
├── MEMORY.md              # Memória de longo prazo (responsabilidades, configurações, registro de decisões importantes)
├── USER.md                # Arquivo humano sobre o usuário (existe apenas na sessão principal)
├── TOOLS.md               # Lembrete de ferramentas locais (apelido do dispositivo, SSH, preferências de áudio, etc.)
├── HEARTBEAT.md           # Lista de tarefas de heartbeat (vazia se nenhuma)
├── BOOTSTRAP.md           # Guia de inicialização (opcional, pode ser excluído após conclusão)
├── memory/                # Arquivos de memória diária (`YYYY-MM-DD.md`)
├── diary/                 # Diário privado (fragmentos, observações, pensamentos não solicitados)
├── saves/                 # Salvamentos de jogos/projetos (se aplicável)
├── output/                # Arquivos de saída de tarefas/projetos (veja as regras em AGENTS.md)
└── .openclaw/
    └── workspace-state.json   # Marcadores de estado

Regras da Pasta Output (Importante)

Regra central: Todos os arquivos de saída de tarefas/projetos devem ser armazenados de forma estruturada no diretório output/.

output/
├── task-001-descricao/       # Subdiretório de tarefa
│   ├── README.md            # Descrição e contexto da tarefa
│   ├── arquivos...          # Arquivos relacionados à tarefa
│   └── result/              # Saída final
├── nome-do-projeto/         # Subdiretório de projeto
│   ├── src/                 # Código fonte
│   ├── assets/              # Arquivos de recursos
│   └── docs/                # Documentação
└── ...

Regras de execução:

1. Cada nova tarefa/projeto → crie um subdiretório em output/
2. Nomeação de subdiretórios → use o formato task-número-descrição-curta ou nome-do-projeto
3. Criação padrão → antes de operações com arquivos, crie o diretório output/ (se não existir)
4. Propriedade dos arquivos → todos os arquivos gerados, conteúdos baixados e saídas de scripts devem ser colocados no subdiretório correspondente

Por que isso é importante:

• Evita bagunça na raiz do workspace
• Tarefas rastreáveis e auditáveis
• Facilita limpeza e arquivamento
• Suporta multitarefa paralela

Lista de Arquivos Essenciais (Conjunto Mínimo Executável)

Arquivo	Função	Obrigatório
AGENTS.md	Define comportamento de cada sessão, regras de memória, limites de segurança	✅
IDENTITY.md	Define "quem sou eu"	✅
SOUL.md	Define "como penso e expresso"	✅
MEMORY.md	Container de memória de longo prazo	✅
USER.md	Perfil do usuário (fortemente recomendado para o agent principal, opcional para outros)	Recomendado
TOOLS.md	Lembrete específico do ambiente	Recomendado
HEARTBEAT.md	Tarefas de verificação periódica	Opcional
.openclaw/workspace-state.json	Marca conclusão do onboarding	Recomendado
memory/	Armazena memórias diárias	✅
diary/	Espaço de diário privado	Recomendado

Modificação do Arquivo de Configuração: ~/.openclaw/openclaw.json

Passo 1: Registrar o Agent

Adicione no array agents.list:

{
  "id": "<seu-agent-id>",
  "name": "<seu-agent-name>",
  "workspace": "/root/.openclaw/workspace/agents/<seu-agent-id>",
  "agentDir": "/root/.openclaw/agents/<seu-agent-id>",
  "memorySearch": {
    "enabled": true
  },
  "subagents": {
    "allowAgents": ["*"]
  }
}

Explicação dos placeholders:

• <seu-agent-id>: Identificador único do agent, ex: writer, assistant, novelist
• <seu-agent-name>: Nome de exibição (opcional, por padrão igual ao id)

Descrição dos campos:

• id: Identificador único do agent em todo o sistema, não pode repetir com outros agents
• name: Nome de exibição (opcional), aparece em logs e respostas
• workspace: Caminho do workspace da alma, o sistema lê daqui os arquivos de personalidade (IDENTITY.md, SOUL.md, etc.)
• agentDir: Caminho de runtime, o sistema cria automaticamente sessions/ e models.json
• memorySearch.enabled: Ativa ou não a recuperação de memória vetorial, recomendado ativar
• subagents.allowAgents: Lista de outros agents que este agent pode spawnar, ["*"] permite spawnar qualquer agent

Sobre configuração de modelo: O modelo não é configurado separadamente no nível do agent, mas sim definido globalmente via agents.defaults.model. Todos os agents herdam o modelo padrão. Para especificar um modelo diferente para um agent específico, defina uma referência de alias em agents.defaults.models no openclaw.json.

Sobre subagents.allowAgents

A configuração subagents.allowAgents controla se este agent pode iniciar outros agents via sessions_spawn e quais agents ele pode ver em agents_list.

Valor da Configuração	Significado	Efeito em agents_list
["*"]	Permite spawnar qualquer agent	allowAny: true, mostra todos os agents
["player", "writer"]	Modo lista branca	Mostra apenas os agents especificados
[] ou não configurado	Só pode spawnar a si mesmo	Retorna apenas ele mesmo

Recomendação: Para cenários de colaboração multi-agent, defina como ["*"] para habilitar capacidade completa de descoberta de agents.

Passo 2: Configurar Conta do Canal Feishu

Adicione uma conta em channels.feishu.accounts (independente da configuração de agents, pode ser reutilizada para vários agents):

"<seu-feishu-account-id>": {
  "appId": "<seu-app-id>",
  "appSecret": "<seu-app-secret>",
  "dmPolicy": "pairing",
  "groupPolicy": "pairing",
  "allowFrom": [],
  "groupAllowFrom": []
}

Explicação dos placeholders:

• <seu-feishu-account-id>: Identificador da conta Feishu, string arbitrária, ex: mybot, writer-feishu
• <seu-app-id>: AppID obtido do Feishu Open Platform (formato cli_xxxxxxxx)
• <seu-app-secret>: AppSecret obtido do Feishu Open Platform

Descrição detalhada das políticas do canal:

Campo	Tipo	Obrigatório	Descrição
appId	string	✅	AppID do aplicativo Feishu, obtido do Feishu Open Platform
appSecret	string	✅	AppSecret do aplicativo Feishu, pareado com AppID
dmPolicy	string	✅	Política de mensagem privada, veja tabela abaixo
groupPolicy	string	✅	Política de mensagem em grupo, veja tabela abaixo
allowFrom	string[]	Opcional	Lista branca de mensagens privadas, apenas esses open_id podem enviar mensagens privadas
groupAllowFrom	string[]	Opcional	Lista branca de mensagens em grupo, apenas esses open_id podem mencionar o robô no grupo
requireMention	boolean	Opcional	No grupo, é necessário mencionar o robô para obter resposta

Tipos de política detalhados:

Valor da Política	Significado	Cenário de Uso
"pairing"	Precisa completar o pareamento primeiro	Agent privado, precisa controlar acesso
"open"	Qualquer um pode interagir	Agent público, como atendimento ao cliente, consulta de informações
"allowlist"	Apenas usuários na lista branca podem interagir	Uso por grupos específicos, combinado com configuração allowFrom

Notas importantes:

• Ao usar a política pairing pela primeira vez, mensagens privadas exibirão um código de pareamento. O usuário precisa ver o código na página de configuração do Kimi Claw Web e inseri-lo
• Em allowFrom e groupAllowFrom, preencha o open_id do usuário (formato ou_xxxxxxxx)

Passo 3: Vincular Agent à Conta Feishu (Bindings)

Adicione no array bindings para associar o agent à conta do canal Feishu:

{
  "agentId": "<seu-agent-id>",
  "match": {
    "channel": "feishu",
    "accountId": "<seu-feishu-account-id>"
  }
}

Explicação da lógica de vinculação:

• agentId: Aponta para o id do agent definido em agents.list
• match.channel: Tipo de canal, aqui é feishu
• match.accountId: Aponta para a chave da conta definida em channels.feishu.accounts

Regras de correspondência de vinculação:

Quando o canal Feishu recebe uma mensagem, o OpenClaw faz a correspondência na seguinte ordem:

1. Determina a conta Feishu de origem da mensagem (accountId)
2. Busca em bindings entradas com match.accountId correspondente
3. Encontra a configuração do agent correspondente via agentId
4. Roteia a mensagem para o workspace do agent processar

Um para Um vs Um para Muitos:

• Vinculação um para um (recomendado): Uma conta Feishu vinculada a um agent

  { "agentId": "writer", "match": { "channel": "feishu", "accountId": "writer-feishu" } }
  

• Vinculação um para muitos: Várias contas Feishu podem ser vinculadas ao mesmo agent

  { "agentId": "assistant", "match": { "channel": "feishu", "accountId": "assistant-bot-1" } }
  { "agentId": "assistant", "match": { "channel": "feishu", "accountId": "assistant-bot-2" } }
  

• Vinculação muitos para um: Uma conta Feishu roteia para diferentes agents com base em condições (precisa de regras de correspondência avançadas)

Fluxo Completo de Criação (Exemplo com Agent writer)

O exemplo a seguir assume que você deseja criar um agent chamado writer, vinculado à conta Feishu writer-feishu:

Passo 1: Criar Diretórios

mkdir -p /root/.openclaw/workspace/agents/writer/{memory,diary,output,.openclaw}

Nota: O diretório output/ é usado para armazenar todos os arquivos de saída de tarefas/projetos, seguindo as regras da pasta Output em AGENTS.md.

Passo 2: Escrever Arquivos de Personalidade

Crie os seguintes arquivos (conteúdo personalizado conforme a personalidade):

• IDENTITY.md — Nome, temperamento, frase de efeito, emoji
• SOUL.md — Personalidade central, modo de falar, gostos e aversões
• AGENTS.md — Regras de trabalho, regras de memória, comportamento de heartbeat, regras da pasta Output
• MEMORY.md — Página inicial da memória de longo prazo (responsabilidades, registro de alterações)
• USER.md — Modelo de perfil do usuário
• TOOLS.md — Modelo de lembretes do ambiente
• HEARTBEAT.md — Pode ser deixado vazio inicialmente ou com comentários

Passo 3: Escrever Arquivo de Estado

cat > /root/.openclaw/workspace/agents/writer/.openclaw/workspace-state.json << 'EOF'
{
  "version": 1,
  "onboardingCompletedAt": "2026-04-14T02:46:05.000Z"
}
EOF

Passo 4: Modificar ~/.openclaw/openclaw.json

① Registrar agent (adicionar em agents.list):

{
  "id": "writer",
  "name": "writer",
  "workspace": "/root/.openclaw/workspace/agents/writer",
  "agentDir": "/root/.openclaw/agents/writer",
  "memorySearch": {
    "enabled": true
  }
}

Nota: O modelo não é configurado no nível do agent, mas herdado do modelo global padrão ou definido via agents.defaults.model.

② Configurar canal Feishu (adicionar em channels.feishu.accounts):

"writer-feishu": {
  "appId": "cli_xxxxxxxxxxxxxxxx",
  "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "dmPolicy": "pairing",
  "groupPolicy": "pairing",
  "allowFrom": [],
  "groupAllowFrom": []
}

⚠️ Substitua cli_xxxxxxxxxxxxxxxx e xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx pelas credenciais reais obtidas do Feishu Open Platform.

③ Vincular agent ao Feishu (adicionar em bindings):

{
  "agentId": "writer",
  "match": {
    "channel": "feishu",
    "accountId": "writer-feishu"
  }
}

Passo 5: Reiniciar o Gateway

openclaw gateway restart

Deve informar claramente ao usuário antes de executar: "Agora vou reiniciar o OpenClaw Gateway para aplicar as novas configurações."

Passo 6: Verificar Conexão

Verifique os logs para confirmar que o WebSocket foi estabelecido:

cat /root/.openclaw/logs/openclaw.log | grep "feishu\[writer-feishu\]"

Saída esperada:

feishu[writer-feishu]: starting WebSocket connection...
feishu[writer-feishu]: received message from ...

Erros Comuns e Solução de Problemas

1. "Channel is required when multiple channels are configured"

• Se um cron job foi criado para o agent, mas o channel não foi especificado explicitamente, ocorrerá este erro
• Solução: Adicione "channel": "feishu" e "accountId": "writer-feishu" na configuração do cron

2. Mensagens do Feishu não estão sendo roteadas para o novo agent

• Verifique se accountId em bindings corresponde à chave em channels.feishu.accounts
• Verifique se agentId corresponde ao id em agents.list
• Verifique se a sintaxe do openclaw.json é válida (vírgulas, parênteses)
• Verifique se channels.feishu.enabled é true

3. Falha no pareamento

• Se dmPolicy é pairing, a primeira mensagem privada precisa de um código de pareamento
• O código de pareamento pode ser visto na página de configuração do Kimi Claw Web, ou um usuário já pareado pode encaminhar

4. "appId or appSecret not configured"

• Verifique se as credenciais do aplicativo Feishu foram preenchidas corretamente
• Verifique se o aplicativo Feishu foi ativado e uma versão foi publicada no Open Platform

Exemplo de Configuração Mínima Completa

Abaixo está um fragmento completo e executável de openclaw.json mostrando a relação entre agent, canal e bindings:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "kimi-coding/k2p5"
      }
    },
    "list": [
      {
        "id": "writer",
        "name": "writer",
        "workspace": "/root/.openclaw/workspace/agents/writer",
        "agentDir": "/root/.openclaw/agents/writer",
        "memorySearch": { "enabled": true },
        "subagents": {
          "allowAgents": ["*"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "writer",
      "match": { "channel": "feishu", "accountId": "writer-feishu" }
    }
  ],
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "requireMention": false,
      "defaultAccount": "main-bot",
      "accounts": {
        "writer-feishu": {
          "appId": "cli_xxxxxxxxxxxxxxxx",
          "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dmPolicy": "pairing",
          "groupPolicy": "pairing",
          "allowFrom": [],
          "groupAllowFrom": []
        }
      }
    }
  }
}

Nota:

• A configuração do modelo é definida em agents.defaults.model, todos os agents herdam este modelo padrão
• subagents.allowAgents: ["*"] ativa capacidade completa de descoberta de agents e colaboração multi-agent

Diagrama da relação de correspondência chave:

┌─────────────────────────────────────────────────────────────┐
│  Mensagem chega ao Feishu (appId: cli_xxxxxxxx)            │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Canal: channels.feishu.accounts["writer-feishu"]         │
│  → accountId identificado: "writer-feishu"                 │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Binding: bindings.find(b => b.match.accountId === "writer-feishu")
│  → Encontrado: { agentId: "writer", ... }                  │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent: agents.list.find(a => a.id === "writer")          │
│  → Encontrado: { workspace: "/root/.openclaw/workspace/agents/writer" }
│  → Carrega SOUL.md, IDENTITY.md, MEMORY.md deste caminho   │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent "writer" processa a mensagem e responde             │
└─────────────────────────────────────────────────────────────┘