Notas direto da oficina
Como pensamos os agentes que vivem nos seus apps de mensagens, o que aprendemos ao construí-los e os detalhes práticos que você pode usar hoje.
329 posts
Todos os posts
O que o OpenClaw envia para casa
Por padrão, o OpenClaw faz uma requisição de saída por dia, e a documentação diz exatamente o que ela carrega: versão, sistema operacional, versão do Node.js, arquitetura e superfície, sem identificador de instalação. Aqui está o quadro completo, incluindo a localização derivada da Cloudflare mantida por três meses, além de cada opção que interrompe as requisições.
A Control UI do OpenClaw
O Gateway serve um painel no navegador na porta 18789, e a primeira coisa que ele mostra é um único campo Gateway secret. O que esse campo aceita, por que um navegador na mesma máquina ainda precisa preenchê-lo, o que fazem a lista de agentes e o modo equipe, e o que executar quando a URL da LAN está bloqueada.
Failed to start Chrome CDP on port 18800
O erro traz uma única linha e nenhuma pista. Em um servidor Linux, a causa quase sempre é o navegador: apt install chromium entrega um wrapper snap cujo confinamento quebra a forma como o OpenClaw inicia e monitora o Chrome. Aqui estão as correções, as seis configurações que importam e a verificação que distingue uma falha de inicialização do CDP de um bloqueio de navegação.
O relay de navegador do OpenClaw
O OpenClaw consegue controlar um navegador que não está na máquina do Gateway: um node host retransmite as ações, ou um cdpUrl se conecta a um Chromium hospedado. Veja como se comportam o roteamento, os perfis e as credenciais.
Agentes ACP do OpenClaw
O OpenClaw executa harnesses de programação externos pelo Agent Client Protocol: Claude Code, Gemini CLI, Cursor, Copilot, Droid, OpenCode e mais onze, iniciados a partir de uma mensagem de chat e acompanhados como tarefas em segundo plano. A instalação do acpx em dois comandos, as armadilhas da primeira execução (incluindo a de plugins.allow), a lista de pré-requisitos que decide se esse caminho chega a ser oferecido e os dezessete IDs de destino de harness.
Acionando o OpenClaw a partir do Gmail
Os eventos da caixa de entrada do Gmail chegam ao OpenClaw por um tópico do Google Pub/Sub, um processo observador e o hook HTTP do Gateway, e o preset integrado dá a cada e-mail a própria sessão sem restringir mais nada. Veja a configuração do tópico e do watch com gcloud, o modelo de dois tokens, o agente mail_reader restrito e em sandbox que a documentação recomenda e o teste de fronteira que mostra se o leitor está mesmo contido.
Sair da sandbox de propósito
O modo elevado permite que um agente do OpenClaw em sandbox execute comandos fora dela, sob controles de aprovação que continuam configuráveis. Ele não faz nada por um agente que nunca esteve em sandbox e não pode sobrescrever a política de ferramentas nem um papel que exigiu a sandbox desde o início. Este post cobre as quatro diretivas, a ordem de resolução, os controles e as listas de permissões que precisam todos liberar, e o que a elevação deixa intocado de propósito.
Motores de contexto do OpenClaw
Um motor de contexto decide quais mensagens chegam ao modelo, como o histórico mais antigo é resumido e como o contexto atravessa as fronteiras de subagentes; o OpenClaw inclui um motor legacy e o usa por padrão, um motor de plugin é selecionado por um slot de configuração, a interface exige ingest, assemble e compact, com hooks opcionais de bootstrap, maintain, ingestão em lote e subagentes, um motor de plugin que falha fica em quarentena durante o processo e o trabalho recorre ao legacy, e um ownsCompaction false não restaura o caminho de compactação do legacy.
Exec em segundo plano e a ferramenta process do OpenClaw
Um comando que passa do prazo de yield devolve um ID de sessão e um trecho final curto da saída em vez de bloquear; a saída fica na memória até o limite agregado, sessões concluídas expiram segundo um tempo de vida contado a partir do término, com no máximo 50 sessões concluídas e dois milhões de caracteres retidos, ambientes de worker apoiados em nós mantêm comandos em segundo plano vivos entre turnos, e a ferramenta process consulta, lê logs paginados, escreve no stdin, envia teclas, confirma, cola, mata e limpa.
A ferramenta exec do OpenClaw
O exec executa comandos de shell no espaço de trabalho e pode criar, editar ou excluir arquivos onde quer que o host escolhido permita, então desativar as ferramentas de arquivos não o torna somente leitura; o parâmetro host resolve para a sandbox quando um runtime de sandbox está ativo e para o gateway caso contrário, a chave mode define deny, allowlist, ask, auto ou full, o revisor automático devolve allow, deny ou ask para os comandos elegíveis fora da allowlist, com toda a cadeia de despacho vinculada e verificada de novo antes da execução, e os comandos de sessão só podem tornar a política mais restritiva.
API OpenResponses do OpenClaw
O gateway serve um endpoint responses compatível com OpenResponses assim que gateway.http.endpoints.responses é ativado, com as mesmas regras de autenticação, escopo e agente de destino do chat completions; a entrada é uma string ou uma lista de itens, os resultados de ferramentas voltam como function_call_output, previous_response_id reutiliza uma sessão dentro do mesmo escopo de agente, usuário e sessão, os arquivos são decodificados no prompt de sistema como conteúdo não confiável, com PDFs rasterizados quando há pouco texto, e o streaming emite eventos de resposta tipados que terminam em DONE.
Autenticação por proxy confiável do OpenClaw
No modo trusted-proxy, o gateway só confia em um cabeçalho de identidade de usuário vindo de endereços de origem listados como proxies confiáveis, rejeita origens de loopback a menos que a opção esteja deliberadamente ativada, rejeita origens que coincidem com as próprias interfaces dele, exige os cabeçalhos configurados e uma correspondência na lista de permissões, se recusa a iniciar quando um token compartilhado também está configurado, e a auditoria de segurança sinaliza o modo como crítico de propósito; os escopos por identidade concedem escopos só de sessão a usuários verificados, a aprovação automática de dispositivos pode transformar a identidade do proxy na fronteira de registro, e o cabeçalho de escopos só restringe.
Aprovações de exec avançadas no OpenClaw
Safe bins como cut, head, tail, tr, uniq e wc rodam no modo allowlist sem entradas porque rejeitam argumentos de arquivo e tokens com cara de caminho; grep e sort são opt-in, awk, sed e jq nunca são safe bins, interpretadores nunca entram nessa lista, safe bins precisam ser resolvidos a partir dos diretórios padrão do sistema, a menos que outros sejam marcados como confiáveis, o encadeamento é permitido quando todos os segmentos passam, execuções de interpretador vinculam toda a cadeia de despacho antes da revisão, resolver uma aprovação exige o escopo dedicado approvals em vez de write, e os pedidos de aprovação podem ser encaminhados para Slack, Telegram, Discord e outros.
Solução de problemas do gateway do OpenClaw
O runbook aprofundado do gateway começa com os mesmos cinco comandos, em ordem, espera um runtime em execução, uma sonda de conectividade ok e uma linha de capacidade e, então, direciona por sintoma para seis páginas: atualizações e rollbacks, skills e provedores de modelo, respostas do agente e interface de controle, serviço e processo do gateway, validação de configuração e sondas, entrega nos canais e ferramentas; a maior parte das quebras após uma atualização é desvio de configuração ou padrões mais rígidos, verificados pelo modo do gateway e pela URL remota, pelos binds fora do loopback que agora exigem um caminho de autenticação real e pelas aprovações pendentes de pareamento de dispositivo ou de mensagem direta.
API HTTP compatível com OpenAI do OpenClaw
O gateway pode servir chat completions, models e embeddings na própria porta assim que gateway.http.endpoints.chatCompletions é ativado; um token válido é acesso de nível proprietário, então a documentação o mantém em loopback, tailnet ou ingress privado; o campo model nomeia um agente como openclaw/default, e não um modelo de provedor, a string user deriva uma chave de sessão estável, x-openclaw-model substitui o modelo de backend, e as ferramentas de função, tool_choice e o streaming SSE seguem os formatos da OpenAI, com limites documentados.
Escopos de operador do OpenClaw
Os escopos controlam o que um cliente do gateway pode fazer depois de se autenticar, como uma proteção dentro de um único domínio de operador confiável, e não como isolamento entre locatários hostis; operator.write implica read e talk, operator.admin implica tudo, papéis nomeados limitam os escopos e podem exigir sandbox por criador, concessões por identidade associam escopos a uma identidade verificada de proxy ou do Tailscale, cada RPC tem um escopo de método de privilégio mínimo, e aprovar uma solicitação de dispositivo só pode emitir escopos que o aprovador já possui.
Controle de acesso do Matrix no OpenClaw
Quem pode alcançar o OpenClaw pelo Matrix e o que ele mantém em torno de uma mensagem: mensagens de outras contas Matrix do OpenClaw configuradas, ignoradas por padrão, e a configuração allow-bots com true ou mentions, mais substituições por sala, a proteção compartilhada contra loops e sua precedência, a regra do próprio ID, a definição de autoria de bot em uma plataforma sem flag de bot, os três modos de visibilidade do contexto, que filtram respostas recuperadas, raízes de thread e histórico pendente sem decidir o que dispara uma resposta, o exemplo de políticas de mensagens diretas e de salas com listas de permissões e uma sala que exige menção, a desativação total das mensagens diretas, os comandos de pareamento e o código pendente reutilizado com um lembrete após um cooldown, e os comandos de barra reconhecidos nas salas quando prefixados pela própria menção do bot, ainda sujeitos à mesma autorização.
Regras de push do Matrix no OpenClaw para prévias silenciosas
A configuração do lado do homeserver que faz o streaming no modo quiet do Matrix tocar no momento certo: prévias enviadas como notices que não notificam, com a edição finalizada carregando um marcador, clientes notificando apenas quando uma regra de push por usuário corresponde a ela, o modo progress finalizando pelo mesmo caminho, os pré-requisitos de um usuário destinatário, um usuário bot, o token do destinatário, o ID completo do bot como remetente e pushers saudáveis, os seis passos desde ativar o modo quiet até gerar ou reutilizar um token, listar os pushers, instalar a regra override com suas quatro condições e ações de notificação, verificá-la e testar uma resposta em streaming, a exclusão, IDs de regra únicos por bot e por destinatário, com novas execuções atualizando no lugar, regras override de usuário inseridas antes das regras suppress do servidor, as edições só de texto que a regra afeta, enquanto mídia, fallbacks de prévia obsoleta e respostas finais que ativam menções notificam normalmente, o Synapse exigindo a condição event-property-is de 2023, com versões mais antigas silenciosamente nunca correspondendo, e a opção do Tuwunel de suprimir push em dispositivo ativo.
Configuração do Microsoft Teams no OpenClaw
As configurações do Teams no bloco do canal: as oito chaves de autenticação que variáveis de ambiente podem substituir, enquanto todo o resto fica só na configuração, o limite de histórico com seus fallbacks e o contexto de thread do Graph, que adiciona a mensagem pai e até cinquenta respostas sem deixar que comandos citados sejam executados, os modos de visibilidade all, allowlist e allowlist-quote, os limites de histórico de mensagens diretas por usuário, as chaves de nuvem e de URL de serviço para as nuvens pública, do governo dos EUA, DoD e China, a porta e o caminho do webhook, as quatro políticas de mensagens diretas com IDs de objeto do AAD recomendados, o destino padrão, o interruptor de emergência de correspondência por nome, o limite de 4000 caracteres por fragmento, a fragmentação por quebra de linha, as listas de permissões de hosts de mídia e o fallback de mídia pelo Graph, a exigência de menção e o estilo de resposta com substituições por equipe e por canal, incluindo políticas de ferramentas, o site do SharePoint para uploads em grupo, os cartões de boas-vindas e de boas-vindas em grupo com sugestões de prompt, o prefixo de resposta, o feedback de polegar com reflexão e o SSO com escopos delegados do Graph.
Configuração do Telegram no OpenClaw
Conectar um bot do Telegram ao OpenClaw do zero: os fluxos por chat e pela web no BotFather, que terminam ambos em um token, o comando channels add que o grava na configuração, a alternativa editada à mão com uma política de DM pairing e uma entrada de grupo curinga, o fallback por variável de ambiente que só serve à conta padrão, por que não existe comando de login para o Telegram, a verificação de status com recarga a quente, os comandos pairing list e approve, com códigos que expiram após uma hora, os dois IDs de que um grupo precisa e onde cada um vai, a precedência de tokens por conta e o cache de identidade de 24 horas, o modo de privacidade e o status de admin do lado do Telegram, com a regra de remover e adicionar de novo, as opções úteis do BotFather e a escolha de transporte entre long polling, com sua posição de reinício durável, e o modo webhook, com seu segredo, seus padrões de listener, seu caminho de health reservado e seu cabeçalho de aceitação durável.
Gráficos, tabelas e aprovações do Slack no OpenClaw
As superfícies do Block Kit que o OpenClaw renderiza nativamente no Slack: o bloco de gráfico portável mapeado para o bloco de visualização de dados do Slack sem escopo extra, os limites impostos a títulos, segmentos, séries e categorias, a representação em texto que todo gráfico carrega, a recuperação quando o Slack rejeita blocos, o limite não documentado de dois gráficos por mensagem e como os gráficos extras transbordam para mensagens seguintes, o bloco de tabela portável mapeado para a tabela de dados atual, com células de texto bruto e de número bruto e cabeçalhos de linha, o limite de 20 colunas, 100 linhas e 10 000 caracteres, o fallback em texto completo e o erro de tamanho explícito na edição, por que tabelas Markdown com barras verticais continuam como texto e blocos brutos ainda passam, tabelas coladas recebidas como TSV, os dois padrões de roteamento para envios de modais pertencentes a plugins e o evento compacto, com dados ocultados, que o agente vê, e o Slack como cliente de aprovação nativo para solicitações de execução e de plugins, com seus aprovadores, destinos, filtros e a retenção do espaço de trabalho no Enterprise Grid.
Threads e sessões do Slack no OpenClaw
Onde uma mensagem do Slack chega no OpenClaw e para onde vai a resposta: mensagens diretas como direct, canais como channel e mensagens diretas em grupo como group, vínculos de rota que aceitam as formas de destino do Slack, o escopo main de mensagens diretas, que junta as mensagens diretas comuns, sessões por canal e o sufixo de thread tirado do timestamp da mensagem pai, a raiz semeada que mantém uma menção e sua thread em uma única sessão, o escopo de histórico, a herança da mensagem pai e a busca inicial de histórico, as duas flags de menção implícita e a chave de menção explícita migrada, os modos de resposta por canal, por tipo de chat e com o fallback legado de mensagens diretas, as tags de resposta manuais, o broadcast de respostas para texto e Block Kit, o opt-out de nível superior, por que off no Slack também desativa as tags explícitas, ao contrário do Telegram, e as mensagens diretas do Agent View, em que cada raiz do campo de composição é uma conversa própria e o marcador é aprendido a partir de três sinais e guardado por conta, espaço de trabalho e app.
Mensagens ricas e aprovações do Telegram no OpenClaw
As superfícies ricas que um bot do Telegram com OpenClaw pode usar: o HTML convencional do Telegram por padrão, com negrito, itálico, links, código, spoilers e citações, a flag de mensagens ricas que renderiza Markdown como blocos tipados da Bot API 10.3, como títulos, tabelas, detalhes, checklists e fórmulas, com as legendas ainda em HTML e as tabelas com mais de 20 colunas recorrendo a código, por que ela fica desativada por compatibilidade com os clientes, prévias de links, os cinco escopos dos botões inline com allowlist como padrão, o bloco de botões com ações de callback e de web app e o limite das Mini Apps a chats privados, como callbacks não reivindicados chegam ao agente como texto, a confirmação com ingestão durável, as seis ações de mensagem com seus aliases e seus controles desativados por padrão, a inspeção da lista de emojis e as aprovações de execução com seus aprovadores, destinos, expiração e a exigência de botões inline.
Criptografia e verificação do Matrix no OpenClaw
Como uma conta Matrix do OpenClaw ganha criptografia de ponta a ponta e continua confiável: o comando de configuração que inicializa o armazenamento de segredos, a assinatura cruzada e um backup das chaves de sala, por que as chaves de recuperação passam pelo stdin, os três sinais de confiança independentes e a regra de que só a verificação por assinatura cruzada conta como verificado pelo proprietário, a verificação do dispositivo e a autoverificação, o comando de bootstrap ou reparo e os fallbacks de UIA dele, status, restauração e redefinição do backup, os comandos de verificação SAS, observações sobre várias contas, a autoverificação na inicialização com o intervalo de espera dela, os avisos de verificação e o que fazer quando o dispositivo foi excluído.
Mostrando 24 de 50 posts
O restante do blog está em inglês. Ler em inglês
Pare de ler sobre isso e crie o seu
Configure um agente, escolha um canal e coloque-o para trabalhar dentro do app que você já deixa aberto.