Conectar ao seu bot

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.

Ver Markdown

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: 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.

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).

Escolha o caminho

Onde o bot roda	Caminho	Precisa de
No mesmo computador do Elyra	`elyra mcp`, por stdio	O Elyra aberto
Em outra máquina (servidor, nuvem, celular)	MCP do Cloud com OAuth	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:

{
  "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 trabalha com o Claude Code e o Codex do seu computador. Cadastre o elyra mcp neles, e o MausBot passa a comandar o Elyra:

claude mcp add --scope user elyra -- elyra mcp
codex mcp add elyra -- elyra mcp

Prompt para o seu bot:

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://<seu-usuário>-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; 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)
dot, da OpenAI	Plugins → + → Add custom MCP server, para uso pessoal, sem revisão (fonte)
OpenClaw	Settings → MCP, no painel de controle (Control UI), com transporte HTTP e login OAuth (fonte)
Hermes	`hermes mcp add --url <endereço> --auth oauth elyra` e, depois, `hermes mcp test elyra` (fonte)
nanobot	Apps → MCP → Connect, com `auth` em `oauth` (fonte)

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:

Adicione o servidor MCP remoto https://<meu-usuario>-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.

Criar pela tela

Abra Automações e use Criar automação.
Em quando, escolha o evento, por exemplo um agente terminar.
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).
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 é:

{
  "trigger": "{{trigger}}",
  "agent": "{{agent}}",
  "card": "{{card}}",
  "project": "{{project}}",
  "time": "{{time}}",
  "summary": "{{summary}}"
}

E o bot recebe, por exemplo:

{
  "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:

X-Elyra-Signature-256: sha256=<HMAC-SHA256, em hexadecimal, do corpo exato, com o segredo como chave>

É o mesmo formato do webhook de entrada. O segredo é gerado pelo Elyra e guardado cifrado no cofre do sistema, como o do webhook:

Salve a automação e abra o detalhe dela.
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.
Entregue o segredo ao bot.

Quem recebe confere a assinatura sobre os bytes exatos do corpo. Em Node.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 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:

{
  "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:

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 <projeto>

Prompt para o seu bot:

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 `<OPENCLAW_STATE_DIR>/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).
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:

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.

Conecte o bot ao Elyra por elyra mcp ou pelo Cloud.
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).
Peça no chat do bot: “peça a um agente para revisar as mudanças do projeto X”.

O bot usa a ferramenta elyra para localizar o projeto e abrir o agente, algo como:

elyra workspace list --json
elyra canvas create terminal --workspace 'id:<ID-DA-LISTAGEM>' --agent <agente> --title 'Tarefa do bot' --json
elyra terminal wait --terminal '<HANDLE>' --for tui-idle --json
elyra terminal send --terminal '<HANDLE>' --text-file <arquivo-com-a-tarefa> --json

O <HANDLE> vem da resposta do segundo comando.

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 '<HANDLE>'.

Prompt para o seu bot:

Use o Elyra para esta tarefa: abra um agente no projeto "<nome do projeto>" (liste os workspaces com
`elyra workspace list --json` pela ferramenta `elyra`, leia antes a skill "elyra"), peça a ele para
"<a tarefa>" 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.
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.

Conectar ao seu bot

O que o bot consegue fazer no Elyra

Escolha o caminho

Bot no mesmo computador: elyra mcp

Bot em outra máquina: o MCP do Cloud

Avisar o bot: a ação “Chamar URL”

Criar pela tela

Variáveis do evento

Assinatura

O que acontece na chamada

Exemplo: avisar o OpenBot

Criar pela linha de comando

Skills nas pastas dos bots

Exemplo de ponta a ponta

Resolver problemas

Bot no mesmo computador: `elyra mcp`