--- id: "cloud.conectar-ao-seu-bot" titulo: "Conectar ao seu bot" resumo: "Deixe o seu bot (OpenClaw, Hermes, Grok Bot, dot da OpenAI, OpenBot, MausBot, nanobot e outros) comandar o Elyra, e faça o Elyra avisá-lo quando um agente terminar." idioma: "pt-br" tipo: "tutorial" categoria: "cloud" aplicavelDesde: "0.0.16" capabilities: [] estadoEditorial: "aprovado" nivelEvidencia: "artefato-distribuido" refFonte: "84e3f6465900b817684ac57323b97fb8bc17076a" revisaoFonte: "2026-10-18" revisor: "mantenedor (pediu a página dos bots, 2026-10-18)" rota: "/docs/pt-br/cloud/conectar-ao-seu-bot/" fonte: "pt-br/cloud/conectar-ao-seu-bot.md" caminhoPublico: "docs/publica/pt-br/cloud/conectar-ao-seu-bot.md" hashFonte: "sha256:3e9ff62b9c1746fee329c7517af16929bf6bf4e9906398a6bfdf9c90e139f75c" hashDestaPagina: "sha256:3e9ff62b9c1746fee329c7517af16929bf6bf4e9906398a6bfdf9c90e139f75c" traducaoAssistidaPorIA: false traducaoDesatualizada: false corpoRetido: false --- Um **bot** é um assistente que fica de pé o tempo todo e conversa com você pelo chat, pelo celular ou por um mensageiro: OpenClaw, Hermes, Grok Bot, dot da OpenAI, OpenBot, MausBot, nanobot e outros. Esta página mostra como ligá-lo ao Elyra em duas direções: - **O bot comanda o Elyra**: ele abre cartões, manda tarefas a agentes, lê terminais e arquivos. - **O Elyra avisa o bot**: quando um agente termina, o Elyra chama um endereço do bot, e ele conta a você. Em cada seção há um **prompt pronto**. Copie, cole no seu bot e ele faz a configuração por você. Onde a configuração depende do bot, o prompt pede que ele siga a **documentação dele**. ## O que o bot consegue fazer no Elyra Conectado, o bot usa as **mesmas ferramentas** do conector do Cloud, que agem com as suas permissões no computador onde o Elyra roda: - **`elyra`**: roda a [CLI do Elyra](/docs/pt-br/cloud/operar-pela-cli/): projetos, workspaces, cartões do Canvas, terminais, agentes, o navegador embutido e as automações; - **`shell`**, **`read_file`**, **`write_file`**, **`edit_file`**, **`list_dir`** e **`search`**: comandos e arquivos; - **`screenshot`** e **`browser_screenshot`**: mostram o que o Elyra ou uma página exibe (no Cloud, com link para a imagem); - **`list_skills`** e **`read_skill`**: os manuais das skills do Elyra. A tabela completa está em [Conectar agentes de fora pelo MCP](/docs/pt-br/cloud/conectar-agentes-mcp/#o-que-o-agente-consegue-fazer). > **Segurança.** O bot age como você, sem pedir confirmação a cada passo. Conecte só bots em que você > confia e revogue o acesso quando não precisar mais (veja [Segurança](/docs/pt-br/cloud/conectar-agentes-mcp/#segurança)). ## Escolha o caminho | Onde o bot roda | Caminho | Precisa de | |---|---|---| | **No mesmo computador** do Elyra | [`elyra mcp`](#bot-no-mesmo-computador-elyra-mcp), por stdio | O Elyra aberto | | **Em outra máquina** (servidor, nuvem, celular) | [MCP do Cloud com OAuth](#bot-em-outra-máquina-o-mcp-do-cloud) | O Elyra Cloud ligado | ## Bot no mesmo computador: `elyra mcp` `elyra mcp` é um servidor MCP por **stdio**: o bot o inicia como um subprocesso e conversa com ele por linhas de JSON. Ele repassa cada pedido ao **Elyra aberto** neste computador, com as **mesmas ferramentas** do conector do Cloud. Não usa túnel, não usa o Cloud e não pede login. A configuração, em qualquer cliente MCP que aceite um servidor por comando, é esta: ```json { "mcpServers": { "elyra": { "command": "elyra", "args": ["mcp"] } } } ``` O nome das chaves e o arquivo onde ela entra mudam de bot para bot: use o formato que a documentação dele pede e mantenha o **comando `elyra`** com o **argumento `mcp`**. Pontos de atenção: - **O Elyra precisa estar aberto.** Com o app fechado, cada pedido volta com um erro dizendo para abrir o Elyra, e o `elyra mcp` continua de pé para o próximo pedido. - **O bot precisa achar o executável.** Se ele não encontrar `elyra`, ponha o **caminho completo** em `command`. Para descobri-lo, rode `command -v elyra` (macOS e Linux) ou `Get-Command elyra` (PowerShell). - **O bot e o Elyra têm de estar no mesmo computador e no mesmo usuário.** Um bot dentro de um contêiner ou de um servidor não alcança o Elyra do seu computador: para esse caso, use o caminho do Cloud. - O que sai no terminal do `elyra mcp` é só o protocolo MCP; avisos e erros vão para o `stderr`. **MausBot**: o [MausBot](https://github.com/milind-soni/OpenMausBot) trabalha com o Claude Code e o Codex do seu computador. Cadastre o `elyra mcp` neles, e o MausBot passa a comandar o Elyra: ```bash claude mcp add --scope user elyra -- elyra mcp codex mcp add elyra -- elyra mcp ``` **Prompt para o seu bot:** ```text Configure um servidor MCP chamado "elyra" com o comando `elyra mcp` (transporte stdio). Se o comando `elyra` não for encontrado, use o caminho completo do executável. Depois liste as ferramentas do servidor e chame a ferramenta `elyra` com os argumentos `workspace list` para confirmar que funcionou. Use a documentação do seu próprio MCP para saber onde registrar o servidor; não invente comandos. ``` ## Bot em outra máquina: o MCP do Cloud Quando o bot não roda no seu computador, ele alcança o Elyra pelo **conector do Cloud**: um endereço `https://-cloud.elyra.sh/mcp`, com login **OAuth**. Você aprova a conexão uma vez, e o acesso se renova sozinho; nada de chave fixa para copiar. O passo a passo, a tela de consentimento e a revogação estão em [Conectar agentes de fora pelo MCP](/docs/pt-br/cloud/conectar-agentes-mcp/); não se repetem aqui. O conector responde com **JSON por HTTP (`POST`)**, sem SSE. Um bot que só fale o transporte SSE antigo não conecta. Onde cadastrar o servidor em cada bot: | Bot | Onde cadastrar o servidor remoto | |---|---| | **Grok Bot** | **Setup → Plugins**, servidor **Remote HTTPS** com **OAuth** ([fonte](https://docs.x.ai/grok-bot/team-bots)) | | **dot, da OpenAI** | **Plugins → + → Add custom MCP server**, para uso pessoal, sem revisão ([fonte](https://developers.openai.com/plugins/quickstart)) | | **OpenClaw** | **Settings → MCP**, no painel de controle (Control UI), com transporte HTTP e login OAuth ([fonte](https://docs.openclaw.ai/tools/mcp)) | | **Hermes** | `hermes mcp add --url --auth oauth elyra` e, depois, `hermes mcp test elyra` ([fonte](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)) | | **nanobot** | **Apps → MCP → Connect**, com `auth` em `oauth` ([fonte](https://github.com/HKUDS/nanobot/blob/main/docs/configuration.md)) | Cada fluxo termina numa página do seu Cloud, onde você entra com a conta Elyra e toca em **Permitir**. Se o bot rodar num servidor sem navegador, o login precisa voltar à máquina do bot (por encaminhamento de porta, por exemplo); a documentação do bot explica como. **Prompt para o seu bot:** ```text Adicione o servidor MCP remoto https://-cloud.elyra.sh/mcp com autenticação OAuth e me mande o link de login para eu autorizar. Siga a documentação do seu próprio MCP para fazer isso; não invente comandos. Quando eu tiver autorizado, liste as ferramentas do servidor e chame a ferramenta `elyra` com os argumentos `workspace list` para confirmar. ``` ## Avisar o bot: a ação "Chamar URL" Para o bot saber que um agente **terminou** (ou ficou esperando você, ou o CI falhou), o Elyra faz uma chamada HTTP ao endereço que o bot publica. É a ação **Chamar URL** das [automações](/docs/pt-br/fluxos/automacoes-acoes/). ### Criar pela tela 1. Abra **Automações** e use **Criar automação**. 2. Em **quando**, escolha o evento, por exemplo **um agente terminar**. 3. Em **faça isto**, escolha **Chamar URL** e preencha: - **Método**: `GET`, `POST`, `PUT`, `PATCH` ou `DELETE`; - **Endereço (URL)**: o endereço do bot, com a query, se houver; - **Cabeçalhos**: pares nome/valor; - **Corpo**: só nos métodos que levam corpo. O padrão é um JSON com o evento; - **Assinar com segredo**: liga a assinatura (veja abaixo). 4. **Criar automação**. ### Variáveis do evento A URL e o corpo aceitam estas variáveis, escritas entre chaves duplas: | Variável | O que traz | |---|---| | `{{trigger}}` | O evento que disparou, como `agent-finished`, `agent-waiting` ou `card-message`; `manual` quando você roda a automação à mão; nos outros casos, o tipo do gatilho | | `{{agent}}` | Em evento do Elyra que vem de um cartão (agente terminou, agente esperando, mensagem de cartão), o agente desse cartão, quando o Elyra o conhece; nos outros casos, o agente da automação | | `{{card}}` | Nesses eventos, o título do cartão que disparou; nos outros casos, o título da execução | | `{{project}}` | O nome do projeto | | `{{time}}` | O horário, em ISO 8601 | | `{{summary}}` | Evento de GitHub, GitLab ou webhook: evento, repositório, título e endereço, no que vier. Evento do Elyra com cartão: o evento e o título do cartão (`agent-finished · Revisor do PR`). Nos outros casos, vazio | Na URL os valores entram **codificados**; no corpo entram **escapados para JSON**. O corpo padrão é: ```json { "trigger": "{{trigger}}", "agent": "{{agent}}", "card": "{{card}}", "project": "{{project}}", "time": "{{time}}", "summary": "{{summary}}" } ``` E o bot recebe, por exemplo: ```json { "trigger": "agent-finished", "agent": "claude", "card": "Revisor do PR", "project": "meu-app", "time": "2026-10-18T14:03:00.000Z", "summary": "agent-finished · Revisor do PR" } ``` ### Assinatura Com **Assinar com segredo** ligado, cada chamada leva o cabeçalho: ```text X-Elyra-Signature-256: sha256= ``` É o mesmo formato do [webhook de entrada](/docs/pt-br/fluxos/automacoes-webhook/#chamar-o-webhook-genérico). O segredo é gerado pelo Elyra e guardado cifrado no cofre do sistema, como o do webhook: 1. Salve a automação e abra o detalhe dela. 2. Na seção **Assinatura de Chamar URL**, toque em **Gerar segredo** e **copie na hora**: ele aparece uma única vez. Se perder, use **Trocar segredo**. 3. Entregue o segredo ao bot. Quem recebe confere a assinatura sobre os **bytes exatos** do corpo. Em Node.js: ```js import { createHmac, timingSafeEqual } from 'node:crypto' function assinaturaConfere(corpoBruto, cabecalho, segredo) { const esperado = createHmac('sha256', segredo).update(corpoBruto).digest() if (!/^sha256=[0-9a-f]{64}$/i.test(cabecalho ?? '')) return false const recebido = Buffer.from(cabecalho.slice(7), 'hex') return recebido.length === esperado.length && timingSafeEqual(recebido, esperado) } ``` Sem a assinatura ligada, **o Elyra não prova quem chamou**: use só em endereço que você controla e que não aceita nada de estranhos. ### O que acontece na chamada - **Prazo de 10 segundos** e **nenhum reenvio**. Se o bot estiver fora do ar, o Elyra não guarda fila. - **A chamada sai do seu computador, e endereços locais (`localhost`) e da rede interna são aceitos.** É assim que um bot na mesma máquina, como o gateway do OpenClaw, é avisado. Use só URLs em que você confia. - **Só uma resposta 2xx conta como sucesso.** O histórico da execução mostra `HTTP 200 · 120 ms`. Qualquer outra resposta, um erro de conexão ou o estouro do prazo **falha a ação** e para a cadeia, com o motivo em português no histórico; na tela, a falha também aparece num aviso. - **O Elyra não segue redirecionamento**: um `3xx` conta como falha, para o corpo assinado nunca ser reenviado a outro endereço. - **Segredo e cabeçalhos não vão para log**, e o resumo da ação mostra só o servidor, nunca a query. - Os **valores dos cabeçalhos ficam salvos com a automação**. Prefira a assinatura a um token fixo num cabeçalho. ### Exemplo: avisar o OpenBot O [OpenBot](https://github.com/meetopenbot/openbot) roda um servidor local na porta `4132` e recebe eventos em `POST /api/publish`. Uma automação **um agente terminar → Chamar URL** com estes campos manda o aviso direto para ele: - **Método**: `POST`; - **Endereço (URL)**: `http://localhost:4132/api/publish`; - **Cabeçalhos**: `content-type` = `application/json`; - **Corpo**: ```json { "type": "agent:invoke", "data": { "role": "user", "content": "O agente {{agent}} terminou no cartão {{card}} do projeto {{project}}. Me avise." } } ``` ### Criar pela linha de comando O bot também pode criar a automação, pela ferramenta `elyra`, com `--actions`. O segredo de assinatura, porém, só é gerado **no app**, no detalhe da automação: ```bash elyra automations create --name "Avisar o bot" \ --trigger-json '{"kind":"elyra-event","events":["agent-finished"]}' \ --actions '[{"kind":"http-call","method":"POST","url":"https://bot.exemplo.com/elyra","headers":[],"body":"{\"card\":\"{{card}}\"}","sign":true}]' \ --trigger daily --prompt "Aviso de evento" --provider codex --repo ``` **Prompt para o seu bot:** ```text Quero que você receba avisos do Elyra. Publique um endereço HTTP POST (ou me diga qual endereço seu devo usar) e, quando um aviso chegar, confira o cabeçalho X-Elyra-Signature-256: ele vale "sha256=" mais o HMAC-SHA256 em hexadecimal do corpo exato, usando como chave o segredo que eu vou te passar. Se a assinatura não bater, ignore o aviso. Se bater, o corpo é um JSON com trigger, agent, card, project, time e summary: me conte no chat o que aconteceu. Responda 200 ao Elyra em até 10 segundos. Depois que o endereço existir, crie no Elyra, com a ferramenta `elyra`, a automação "um agente terminar → Chamar URL" (método POST, esse endereço, assinatura ligada) e me avise para eu gerar o segredo no detalhe da automação. ``` ## Skills nas pastas dos bots As **skills do Elyra** são manuais curtos que ensinam o agente a usar a CLI. O Elyra as instala sozinho nas pastas de skills dos assistentes que **já estão no seu computador**, e isso agora inclui o **OpenClaw**: | Bot | Pasta | |---|---| | **OpenClaw** | `~/.openclaw/skills` (ou `/skills`, se você mudou a pasta de estado) | | **Hermes** | a pasta de skills do Hermes (`~/.hermes/skills`, `%LOCALAPPDATA%\hermes\skills` no Windows ou `HERMES_HOME`) | | Outros assistentes | `~/.agents/skills` e as pastas do Claude, Codex, Grok CLI, Cursor e demais | As regras são sempre as mesmas: - **O Elyra nunca cria a pasta de um bot.** Sem o OpenClaw instalado, nada é gravado. - Cada skill instalada leva o marcador `.elyra-managed.json`. **O que não é do Elyra não é tocado**, e desinstalar o Elyra remove só o que tem o marcador. - **MausBot**: ele usa as skills das pastas do Claude Code e do Codex, onde o Elyra já as instala. - **OpenBot**: recebe os avisos do Elyra pela ação **Chamar URL** ([exemplo acima](#exemplo-avisar-o-openbot)). - A pasta `~/.grok/skills` é a do **Grok CLI**, não a do Grok Bot; o Grok Bot recebe o Elyra pelo conector. Um bot que não vê as skills pode precisar recarregar as próprias skills; veja como na documentação dele. **Prompt para o seu bot:** ```text Liste as skills que você tem carregadas e me diga se existe uma chamada "elyra". Se existir, leia-a agora e, antes de usar a ferramenta `elyra`, siga o que ela manda. Se não existir, recarregue suas skills seguindo a documentação do seu próprio bot e confira de novo; não invente comandos. ``` ## Exemplo de ponta a ponta O bot manda uma tarefa a um agente e é avisado quando ela termina. 1. **Conecte o bot** ao Elyra por [`elyra mcp`](#bot-no-mesmo-computador-elyra-mcp) ou pelo [Cloud](#bot-em-outra-máquina-o-mcp-do-cloud). 2. **Crie a automação** "um agente terminar → Chamar URL" apontando para o endereço do bot, com assinatura, e entregue o segredo a ele (veja [Avisar o bot](#avisar-o-bot-a-ação-chamar-url)). 3. **Peça no chat do bot**: "peça a um agente para revisar as mudanças do projeto X". 4. O bot usa a ferramenta `elyra` para localizar o projeto e abrir o agente, algo como: ```bash elyra workspace list --json elyra canvas create terminal --workspace 'id:' --agent --title 'Tarefa do bot' --json elyra terminal wait --terminal '' --for tui-idle --json elyra terminal send --terminal '' --text-file --json ``` O `` vem da resposta do segundo comando. 5. O agente trabalha. Quando termina, o Elyra faz a chamada **Chamar URL**, o bot confere a assinatura e conta a você, no chat, que acabou. Para ler o resultado, o bot usa `elyra terminal read --terminal ''`. **Prompt para o seu bot:** ```text Use o Elyra para esta tarefa: abra um agente no projeto "" (liste os workspaces com `elyra workspace list --json` pela ferramenta `elyra`, leia antes a skill "elyra"), peça a ele para "" e fique de olho. Quando o Elyra me avisar no seu endereço que o agente terminou (confira a assinatura X-Elyra-Signature-256), leia o resultado do terminal dele e me conte aqui, no chat, o que foi feito. ``` ## Resolver problemas | Sintoma | O que fazer | |---|---| | O bot recebe "abra o aplicativo Elyra" | O Elyra está fechado. Abra o app; o `elyra mcp` volta a funcionar no pedido seguinte. | | O bot não encontra o comando `elyra` | Use o caminho completo do executável em `command`. | | O Cloud recusa a conexão do bot | Veja [Resolver problemas do Cloud](/docs/pt-br/cloud/resolver-problemas/). | | A ação falhou com "O servidor respondeu 401" | O bot recusou a chamada. Confira o endereço e o segredo que ele usa para validar. | | A ação falhou com "assinatura ligada, mas o segredo não existe" | Abra o detalhe da automação e toque em **Gerar segredo**. | | A ação falhou com "passou de 10 s sem resposta" | O bot demorou demais. Responda `200` logo e processe o aviso depois. |