Como configurar o Hermes Slack no ZimaOS e corrigir erros de gateway

O Hermes Agent pode ligar-se ao Slack sem expor um endpoint de webhook público, porque a integração Slack atual utiliza o Socket Mode. O relato da comunidade que está na origem desta página conseguiu realizar a maior parte dessa configuração: o utilizador criou uma nova aplicação Slack, obteve um xoxb- token do bot e um xapp- token ao nível da aplicação, executou hermes gateway setup dentro do contentor Hermes no ZimaOS e convidou o bot para um canal Slack.

A falha ocorreu quando o Hermes tentou reiniciar o gateway. A CLI devolveu PermissionError: [Errno 13] Permissão negada: '/opt/data/gateway.lock'e, embora a aplicação aparecesse no Slack, uma @Hermes uma menção não produziu resposta. A documentação atual da ZimaSpace identifica explicitamente /opt/data erros de permissões como um problema de propriedade do Hermes que pode ocorrer depois de operações do gateway terem sido executadas anteriormente como root. A documentação atual do Hermes para o Slack também acrescenta vários requisitos de configuração que é mais seguro verificar do que tentar adivinhar manualmente os âmbitos.

O que aconteceu no relato do Hermes no ZimaOS sobre o Slack

A publicação da comunidade de maio de 2026 utilizou uma instalação limpa do Hermes no ZimaOS e um novo espaço de trabalho Slack. O utilizador criou uma aplicação Slack com o Socket Mode ativado, copiou os dois tipos de token necessários e configurou o Slack através do assistente do gateway Hermes.

A sequência essencial foi:

1. Crie uma aplicação Slack e ative o Socket Mode.
2. Obtenha um token OAuth de utilizador do bot que comece por xoxb-.
3. Obtenha um token ao nível da aplicação que comece por xapp-.
4. Execute hermes gateway setup dentro do contentor Hermes.
5. Selecione Slack e introduza os dois tokens.
6. Aceite a mensagem para reiniciar o gateway.

O reinício falhou com:

PermissionError: [Errno 13] Permissão negada: '/opt/data/gateway.lock'

O utilizador reiniciou então o gateway a partir da interface Web do Hermes, convidou @Hermes num canal Slack e viu o Slack confirmar que a aplicação tinha sido adicionada. No entanto, uma menção num canal continuou sem obter resposta. Isto significa que era necessário resolver potencialmente duas camadas: o processo de gateway do lado do ZimaOS e a configuração de eventos do lado do Slack.

Utilizar o manifesto Slack atual do Hermes em vez de recriar manualmente todos os âmbitos

A documentação atual do Hermes recomenda gerar um manifesto de aplicação Slack. Isto é mais seguro do que recriar manualmente, de memória, todos os âmbitos OAuth, comandos de barra, subscrições de eventos e definições do Socket Mode.

Num ambiente Hermes atual, gere o manifesto com:

hermes slack manifest --agent-view --write

O ficheiro gerado é escrito em:

~/.hermes/slack-manifest.json

Em seguida, crie uma nova aplicação Slack a partir desse manifesto na interface de administração de aplicações do Slack. A documentação atual do Hermes explica que o manifesto declara conjuntamente os comandos incorporados, os âmbitos necessários, as subscrições de eventos e a configuração do Socket Mode.

Para consultar o procedimento atual a montante, veja o guia de configuração do Hermes Agent para Slack.

Os dois tokens Slack de que o Hermes necessita

O Hermes utiliza duas credenciais Slack diferentes, que não são intercambiáveis:

• Token do bot: começa por xoxb- e torna-se SLACK_BOT_TOKEN.
• Token ao nível da aplicação: começa por xapp-, tem de suportar o Socket Mode e torna-se SLACK_APP_TOKEN.

Um ficheiro de ambiente atual do Hermes pode conter:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_ALLOWED_USERS=U01ABC2DEF3

SLACK_ALLOWED_USERS utiliza IDs de membro do Slack, não nomes de apresentação. Se os tokens estiverem corretos, mas o utilizador que faz o pedido não estiver autorizado, o Hermes pode continuar a parecer ligado, embora se recuse a processar as mensagens desse utilizador.

Nunca publique tokens reais xoxb- ou xapp- valores numa publicação da comunidade, captura de ecrã, repositório Git ou registo de suporte. Revogue e gere um novo token se este tiver sido exposto.

As menções em canais requerem os eventos Slack corretos

A visibilidade de um bot num canal não prova que o Slack esteja a entregar eventos de mensagens ao Hermes. A documentação atual do Hermes identifica as subscrições de eventos como uma causa comum de falhas.

Numa aplicação Slack configurada manualmente, verifique os eventos necessários para a versão atual do Hermes. A documentação atual inclui eventos como:

• app_mention para mensagens diretas @Hermes menções.
• message.channels para mensagens em canais públicos onde o bot seja membro.
• message.groups quando for necessário o suporte de canais privados.
• message.im para mensagens diretas.

Se alterar os âmbitos ou as subscrições de eventos depois de instalar a aplicação do Slack, reinstale a aplicação na área de trabalho quando o Slack lho solicitar. Caso contrário, as definições apresentadas e as permissões efetivamente concedidas ao bot instalado podem ser diferentes.

Convide o Hermes para o canal antes de testar

O Hermes não entra automaticamente em todos os canais do Slack. Convide-o explicitamente:

/invite @Hermes

Em seguida, teste uma simples menção de um utilizador do Slack cujo ID de membro esteja incluído na lista de permissões do Hermes. Se as mensagens diretas funcionarem, mas as menções em canais públicos não, concentre-se em app_mention, message.channels, adesão ao canal e as permissões da aplicação instalada antes de alterar a configuração de rede do ZimaOS.

Por que razão /opt/data/gateway.lock pode devolver «Permissão negada»

O guia do ZimaSpace para o Hermes Agent documenta agora um problema de permissões em /opt/data. Afirma que este problema é normalmente causado pela execução anterior do Hermes Gateway como root, que deixou ficheiros pertencentes ao root dentro de $HERMES_HOME.

O fluxo de trabalho documentado pelo ZimaSpace para o contentor consiste em entrar no contentor como o hermes utilizador:

docker exec -it -u hermes hermes bash

Em seguida, ative o ambiente virtual do Hermes:

source /opt/hermes/.venv/bin/activate

A configuração das mensagens pode então ser aberta com:

hermes gateway setup

Se o gateway falhar imediatamente em /opt/data/gateway.locke não execute repetidamente todo o gateway como root. Primeiro, confirme a identidade e a propriedade envolvidas:

id
ls -ld /opt/data
ls -l /opt/data/gateway.lock 2>/dev/null

O guia atual do ZimaSpace recomenda verificar os registos do Hermes no Painel do ZimaOS e utilizar temporariamente uma shell de root apenas quando for necessário reparar a propriedade dos ficheiros. Não aplique uma alteração recursiva cega da propriedade a /opt/data a menos que tenha verificado a que pertencem os ficheiros e qual o utilizador/grupo esperado pelo pacote ZimaOS instalado.

Reinicie o gateway apenas depois de o Hermes conseguir escrever os respetivos ficheiros de execução

No relatório da comunidade, clicar em Reiniciar gateway na interface Web não foi suficiente para provar que o gateway estava saudável. Se o processo subjacente não conseguir criar ou atualizar o respetivo ficheiro de bloqueio, a ação da interface pode continuar a deixar a integração com o Slack indisponível.

Depois de corrigir o problema efetivo de propriedade, entre no contentor como hermes utilizador, ative o ambiente e execute ou reinicie o gateway utilizando os comandos compatíveis com a versão instalada do Hermes. Observe os registos do Hermes no ZimaOS enquanto envia uma mensagem de teste no Slack.

Uma divisão útil para a resolução de problemas é:

• O gateway não arranca: investigue as permissões de /opt/data e os registos do Hermes.
• O gateway está em execução, mas não existe ligação ao Slack: verifique o token xapp- e o Socket Mode.
• A ligação ao Slack existe, mas as menções no canal não produzem resposta: verifique os eventos da aplicação, a participação no canal, o estado da reinstalação e SLACK_ALLOWED_USERS.
• As mensagens diretas funcionam, mas o canal não: concentre-se nos eventos e nas permissões do canal, e não no fornecedor do modelo.

Utilize o Painel Web do Hermes para obter o estado, não como única verificação de integridade

O guia do ZimaSpace disponibiliza o Painel Web do Hermes em:

http://ZIMAOS_LAN_IP:9119

O painel pode mostrar o estado de execução, as sessões e as definições do modelo. É útil para reiniciar e observar o gateway, mas deve ser complementado pelos registos quando ocorre um erro de permissões ao nível do processo.

Lista de verificação para resolução de problemas do Hermes Slack no ZimaOS

1. Confirme que a própria configuração do modelo Hermes funciona antes de adicionar o Slack.
2. Entre no contentor ZimaOS como hermes utilizador, e não como root, para o funcionamento normal do gateway.
3. Quando possível, utilize o manifesto Slack atual do Hermes em vez de adivinhar manualmente os âmbitos.
4. Confirme que xoxb- o token do bot e xapp- o token da aplicação pertence à mesma aplicação Slack pretendida.
5. Confirme que o Socket Mode está ativado.
6. Confirme que o seu ID de membro do Slack está incluído em SLACK_ALLOWED_USERS.
7. Convide o Hermes para o canal que está a testar.
8. Verifique app_mention e de que os eventos de mensagens necessários estão subscritos.
9. Volte a instalar a aplicação Slack depois de alterar os âmbitos ou as subscrições de eventos, quando o Slack o solicitar.
10. Se /opt/data/gateway.lock falhar, verifique a propriedade dos ficheiros e os registos do Hermes no ZimaOS antes de reiniciar novamente.
11. Depois de o gateway estar operacional, teste separadamente uma mensagem direta e uma menção num canal.

Perguntas frequentes sobre o Hermes Slack no ZimaOS

O que significa o erro de permissões gateway.lock?

Significa que o processo Hermes não consegue aceder ao ficheiro de bloqueio do runtime na localização esperada. A documentação atual do ZimaSpace indica que um /opt/data o erro de permissões está normalmente associado a ficheiros que ficaram pertencentes ao root depois de o Hermes Gateway ter sido executado como root.

Devo executar o Hermes Gateway como root para corrigir o problema?

Não como solução normal. A documentação do ZimaSpace recomenda entrar no contentor como hermes utilizador para as operações normais do Hermes. Uma shell root só deve ser utilizada temporariamente quando tiver confirmado que é necessário corrigir a propriedade dos ficheiros.

Porque é que o bot Hermes está visível no Slack, mas não responde?

O facto de estar instalada e de ter sido convidada apenas prova que o Slack reconhece a aplicação. O Hermes continua a precisar de um gateway operacional, de uma ligação Socket Mode válida, de subscrições de eventos corretas, de permissões adequadas no espaço de trabalho e de um ID de membro do Slack autorizado.

O Hermes Slack precisa de um URL de webhook público?

Não. A integração Slack atual do Hermes utiliza o Socket Mode através de WebSockets, pelo que a instância do Hermes pode permanecer atrás de uma firewall sem um endpoint público de webhook do Slack.

Qual é a melhor forma atual de configurar a aplicação Slack?

Utilize o manifesto Slack gerado atualmente pelo Hermes quando a versão instalada do Hermes o suportar. Isto reduz os erros causados pela ausência de âmbitos, subscrições de eventos ou definições de comandos de barra.