Um agente não é um chatbot

Um chatbot responde perguntas. Um agente de IA operacional é um colaborador digital: executa tarefas repetitivas do seu dia a dia com autonomia parcial, dentro de um domínio bem definido. Ele não fica esperando a próxima pergunta — ele tem função, rotina e responsabilidade sobre um pedaço da operação.

A diferença prática: você não "usa" um agente como usa um chat. Você delega a ele — e cobra resultado sobre uma métrica.

A anatomia mínima de qualquer agente

Todo agente, por mais simples, é feito das mesmas seis peças:

• 1 · LLMO raciocínio (Claude, GPT, Gemini…). Terceirizado via API.
• 2 · RuntimeO "corpo" que hospeda o agente e orquestra tudo. Aqui: OpenClaw.
• 3 · CanalComo você conversa com ele (Telegram, WhatsApp, webchat, e-mail).
• 4 · MemóriaO que ele sabe sobre você, o negócio e decisões passadas.
• 5 · FerramentasAs integrações que ele opera (planilhas, CRM, ads, e-mail).
• 6 · IdentidadeQuem ele é, como fala, o que pode e o que não pode fazer.

Os próximos módulos montam exatamente essas peças, nessa ordem: primeiro o corpo e o canal, depois a identidade, a memória e as ferramentas.

Por que a LLM é sua, não da plataforma

A API key da LLM é sempre contratada no nome do cliente. Isso não é detalhe burocrático: é o que garante que o agente pertença a você. Se amanhã você trocar de runtime, de servidor ou de fornecedor, o cérebro continua sendo seu — você não fica refém de ninguém.

Checklist antes de criar qualquer agente

Não abra o terminal ainda. Todo agente começa respondendo cinco perguntas. Se alguma ficar em branco, o agente vai nascer sem foco.

1. Qual é a métrica-âncora que ele vai mover? (uma só)
2. Qual é a hipótese? "Se este agente executar X, a métrica sobe porque Y."
3. Quais são as 3 a 5 tarefas concretas que ele deve executar no primeiro mês?
4. Que ferramentas ele precisa acessar para fazer isso?
5. Qual é o canal em que o dono do agente vai falar com ele?

Três contratos independentes

A infraestrutura do agente são três contratações separadas. Você faz as três uma vez; depois é só manter.

• 1 · HospedagemUma VPS Linux (ex.: Hostinger, DigitalOcean, Hetzner). Custo único ou mensal, no CNPJ do negócio.
• 2 · Runtime OpenClawInstalado sobre a hospedagem. É open-source — o "corpo" do agente.
• 3 · LLMConta na Anthropic (Claude), OpenAI (GPT) ou um agregador (OpenRouter). A API key mora no cofre.

Por que separado? Porque cada peça é trocável de forma independente. Quer mudar de LLM amanhã? Troca a key. Quer migrar de servidor? Sobe o runtime em outro lugar. Você nunca perde o agente por trocar um fornecedor.

Subir o ambiente

1. A VPS

Configuração mínima recomendada para começar (ajuste conforme o número de agentes):

• 4 vCPU
• 8 GB RAM
• 80 GB SSD
• Ubuntu 22.04 LTS

2. Instalar e inicializar o OpenClaw

Com acesso à VPS, o fluxo básico é instalar o runtime, criar o profile do agente e conferir que subiu:

# 1. instalar o runtime OpenClaw na VPS
npm install -g openclaw

# 2. criar o profile do agente
openclaw init

# 3. abrir a configuração inicial
openclaw config

# 4. conferir que o ambiente subiu
openclaw status

3. A API key da LLM

Gere a API key na plataforma escolhida (Anthropic, OpenAI ou agregador) e guarde no cofre de senhas do negócio antes de colar em qualquer arquivo de configuração.

O bot é só a porta de entrada

Um “bot” não é o agente — é uma identidade em um canal (Telegram, WhatsApp, webchat, Slack…) que o OpenClaw controla. As mensagens que chegam nesse bot são entregues ao agente; as respostas do agente saem por ele. O cérebro é o agente; o bot é a boca e o ouvido.

Qual canal escolher

A regra é simples: onde a pessoa já mora o dia todo. Não adianta um canal lindo que ninguém abre. Para a maioria, o Telegram é o primeiro canal — rápido de configurar e sem burocracia.

Telegram — o primeiro canal recomendado

Todo o processo acontece dentro do próprio Telegram, conversando com o @BotFather (o bot oficial que cria bots):

# 1. abra uma conversa com @BotFather e crie o bot
/newbot

# 2. informe um nome de exibição e um username terminando em "bot"
#    ex:  Atendimento  ->  _bot

# 3. dê cara ao bot (opcional, mas recomendado)
/setdescription
/setabouttext
/setuserpic

# 4. se o agente vai participar de GRUPOS e precisa ler tudo:
/setprivacy   ->   Disable

Canal: a ponte entre o bot e o agente

No OpenClaw, um canal é a ponte entre um bot (a identidade externa que você criou) e um agente (a identidade interna). É isso que faz o token do Telegram “apontar” para o seu agente. Um agente pode ter vários canais; um canal pertence a um agente por vez.

Ligar o canal Telegram ao agente

Tudo acontece no servidor, via openclaw gateway. Primeiro veja o estado atual, depois aponte o token e o agente do canal:

# 1. ver os canais já configurados
openclaw gateway config.get channels

# 2. apontar o token do bot e o agente que responde por ele
openclaw gateway config.patch channels.telegram.token "<TOKEN_DO_BOTFATHER>"
openclaw gateway config.patch channels.telegram.agent "<seu-agente>"

# 3. aplicar (hot-reload quando possível; senão, reiniciar)
openclaw gateway config.apply
openclaw gateway restart

# lê o token do cofre sem exibir o valor
op read "op://<vault-empresa>/telegram/token"

Os três jeitos de falar com o agente

• DMConversa 1-a-1. É o modo de trabalho padrão.
• GrupoO agente participa de um grupo com pessoas. Precisa saber quando falar e quando calar (menções, comandos).
• WebchatA conversa vive numa página web — site, atendimento.

Uma sessão vive dentro de um canal: a resposta do agente sempre volta por onde a mensagem entrou. Você não se perde sobre “onde ele respondeu”.

Comandos do dia a dia

Dentro da conversa, alguns comandos internos controlam a sessão:

/help              # lista os comandos disponíveis
/status            # estado da sessão: modelo, uso, tempo
/new               # encerra a sessão atual e começa outra
/model <alias>     # troca a LLM no meio da conversa

Um agente é um conjunto de arquivos

Um agente de verdade não é um prompt gigante — é um conjunto de arquivos em markdown, cada um com um papel. As 6 camadas abaixo definem quem o agente é. Escrevê-las é o coração da imersão.

HEARTBEAT.md — o motor operacional

Há ainda uma sétima peça, de natureza diferente. Enquanto as 6 camadas dizem quem o agente é, o HEARTBEAT.md diz como ele opera: frentes de atuação, rotinas e a estrutura padrão das respostas — por exemplo, “toda estratégia traz contexto, objetivo, público, ideia, canais, execução, métricas e próximos passos”.

O que entra em cada arquivo

Todos são markdown puro. Em resumo:

• SOUL.md — identidade em 1ª pessoa: essência (3–5 traços), não-negociáveis, o motor de execução e os critérios de prioridade.
• IDENTITY.md — o “manual da empresa”: nome, CNPJ, portfólio com valores, público-alvo, tom de voz, canais oficiais e regras comerciais.
• USER.md — escrito pra quem aciona o agente: como pedir bem, o que esperar e o que ele não faz sozinho.
• AGENTS.md — hierarquia e colaboração: se há sub-agentes, quem cuida de quê, protocolos e regra de escalonamento.
• TOOLS.md — inventário de ferramentas: para cada uma, o uso, as métricas prioritárias e o protocolo (ex.: “nunca alterar campanha ativa sem validação humana”).
• MEMORY.md — índice de memórias persistentes: uma linha por item, com link pro arquivo detalhado (máx. ~200 linhas).
• HEARTBEAT.md — a rotina: frentes de atuação e a estrutura padrão das respostas.

Na prática, o SOUL.md é o que mais muda o comportamento. Um esqueleto pra começar:

# SOUL

## Essência
- <3 a 5 traços que definem a personalidade dele>

## Não-negociáveis
- Evidência acima de achismo
- Zero enrolação; sempre com próximos passos explícitos

## Motor de execução
OBSERVAR -> ORIENTAR -> DECIDIR -> AGIR -> MEDIR -> APRENDER

## Como prioriza
- <critério de priorização>

O agente que lembra

Memória é o que separa um assistente que recomeça do zero toda vez de um colaborador que acumula contexto. No OpenClaw, o próprio agente gerencia a memória — a auto-memory — escrevendo arquivos markdown num diretório dedicado.

Os quatro tipos de memória

• userQuem é a pessoa, papel e preferências.
• feedbackCorreções e validações explícitas (“faça assim, não assim”).
• projectProjetos e iniciativas em andamento, com prazos.
• referencePonteiros pra sistemas externos (dashboards, projetos, canais).

Como a memória é escrita

Cada memória é um arquivo próprio, com frontmatter (name, description, type) e um corpo curto:

---
name: <slug-da-memoria>
description: <quando essa memória é relevante, em 1 frase>
type: project
---

# <título curto>

- fato durável que o agente deve lembrar
- prazo, decisão ou preferência — com um <detalhe> quando útil

E o MEMORY.md funciona como índice — uma linha por memória, apontando pro arquivo:

# Índice de memórias

- project_<slug>.md   — <o que é, em poucas palavras>
- user_<slug>.md      — <quem é, papel, preferências>
- reference_<slug>.md — <ponteiro pra um sistema externo>

Ferramentas são as mãos do agente

Sem ferramentas, o agente só conversa. Com elas, ele age no mundo: lê e-mail, cria tarefa, ajusta campanha, atualiza planilha. Cada ferramenta é uma integração.

O padrão é sempre o mesmo, não importa a ferramenta: (1) autenticar uma vez, (2) guardar a credencial no cofre e (3) deixar o agente resolver por referência quando precisar. A chave nunca fica no código.

As integrações e como conectar

As principais integrações e o essencial de cada uma:

O Google entra por um wrapper único, o gog — autentica uma vez e opera Gmail, Drive, Docs, Sheets e Calendar:

# instala e autentica o wrapper do Google
npm install -g gog
gog auth login

# a partir daqui o agente opera o Google via gog

Para serviços com token de API (ClickUp, Notion, Chatwoot…), o padrão é resolver o token do cofre na própria chamada:

# o token nunca aparece no código: vem do cofre na hora
curl -H "Authorization: Bearer $(op read op://<vault-empresa>/clickup-api/token)" \
     https://api.clickup.com/api/v2/team

Skill: uma capacidade de prateleira

Uma skill é uma capacidade empacotada numa pasta, com um SKILL.md e os arquivos de apoio. O agente puxa a skill quando o contexto combina — é o playbook pronto para "fechar o relatório mensal" ou "fazer o onboarding de um cliente".

Anatomia de uma skill

Um SKILL.md tem frontmatter (name, description) e um corpo com o gatilho e o passo a passo:

---
name: <nome-da-skill>
description: <o que faz E quando usar — é isso que dispara a skill>
---

# <Nome da skill>

## Quando usar
- <situação que dispara a skill>

## Passo a passo
1. <primeiro passo>
2. <segundo passo, com o resultado esperado>

Cron: o agente proativo

Um cron é uma tarefa agendada que o agente roda por conta própria — relatórios, monitoramentos, sincronizações. É o que transforma o agente de reativo em proativo.

Agendando um cron

Um cron tem horário (a cron string), a tarefa, o modelo e a forma de entrega:

# resumo semanal, toda segunda 8h, entregue no canal
openclaw cron add \
  --schedule "0 8 * * 1" \
  --agent "<seu-agente>" \
  --model "anthropic/claude-sonnet-4-6" \
  --delivery channel \
  --task "Gere o resumo semanal de performance e poste no canal."

Sub-agentes: delegar para especialistas

Um sub-agente é um agente especializado a quem o principal delega uma tarefa. Ele trabalha isolado — com contexto próprio — e devolve só o resultado. Serve pra papéis recorrentes e específicos.

Como a delegação funciona

O AGENTS.md declara os sub-agentes. O principal abre uma sessão isolada (spawn), envia a tarefa com o contexto mínimo (send) e recebe o resultado de volta (yield):

# o principal delega uma tarefa isolada a um sub-agente
openclaw sessions spawn --agent "<sub-agente>" \
  --task "<tarefa específica + o contexto mínimo necessário>"

# o sub-agente trabalha isolado e devolve (yield) só o resultado