Bot do Discord e relay em nuvem

Configuração do bot do Discord do Saba-chan e o fluxo de pareamento com o relay em nuvem, que permite controlar seu servidor sem encaminhamento de portas.

Bot do Discord e relay em nuvem

O bot do Discord do Saba-chan é um bot oficial operado no servidor de relay em nuvem. Você não precisa rodar um processo de bot nem gerenciar um token do Discord. Convide o bot oficial para o seu servidor do Discord e depois pareie-o uma vez com um código do aplicativo Saba-chan.


1. Como funciona

Nuvem
DiscordComandos pelo chat
Relay do DiscordBot do Saba-chan · nuvem
Seu PC
Daemon do Saba-chanSeu PC
Servidor de jogoSeu PC
  1. 1
    Daemon do Saba-chanRelay do Discord

    Esperar novos comandos (long polling)

  2. 2
    DiscordRelay do Discord

    Enviar um comando /saba … ou chat

  3. 3
    Relay do DiscordDaemon do Saba-chan

    Entregar o comando

  4. 4
    Daemon do Saba-chan

    Verificar permissões

  5. 5
    Daemon do Saba-chanServidor de jogo

    Início · comando de console

  6. 6
    Daemon do Saba-chanRelay do Discord

    Enviar o resultado

  7. 7
    Relay do DiscordDiscord

    Responder com o resultado

Seu PC conecta para fora e busca os comandos, então nenhuma porta do roteador precisa ser aberta. As requisições são assinadas com o token emitido no pareamento. A cada 60 segundos o daemon informa ao relay a lista e o estado dos servidores.
  • O bot em si roda dentro do servidor de relay. Nada relacionado ao bot é instalado no seu PC.
  • Os servidores de jogo rodam no seu PC. O daemon do Saba-chan no seu PC se conecta para fora ao servidor de relay com long-polling, busca os comandos e envia os resultados de volta.
  • O daemon envia os comandos de jogo na ordem stdin (console do servidor) → REST → RCON. O Palworld usa a REST API dele. O RCON só é usado para um jogo que suporta apenas RCON, e apenas por loopback (127.0.0.1).
  • O tráfego daemon ↔ relay é apenas HTTPS de saída a partir do seu PC. Não é necessário encaminhamento de portas no roteador.
  • A música é tratada do lado do relay sem passar pelo seu PC, então funciona mesmo com o PC desligado.

2. Pareamento

O pareamento registra um host (o daemon do Saba-chan) e nós (servidores do Discord) no servidor de relay. Ele termina com uma única digitação de código.

2.1 Diagrama de fluxo

Seu PC
App GUISeu PC
Daemon do Saba-chanSeu PC
Nuvem
Relay do DiscordBot do Saba-chan · nuvem
DiscordComando de barra
  1. 1
    App GUIDaemon do Saba-chan

    Pedir um código de pareamento

  2. 2
    Daemon do Saba-chanRelay do Discord

    Solicitar um código

  3. 3
    Relay do DiscordDaemon do Saba-chan

    Código + segredo de consulta (5 min)

  4. 4
    Daemon do Saba-chanApp GUI

    Mostrar o código

  5. 5
    DiscordRelay do Discord

    /saba connect code:…

  6. 6
    Relay do Discord

    Registrar o PC · emitir token de nó

  7. 7
    App GUIDaemon do Saba-chan

    Verificar o status a cada 3 s

  8. 8
    Daemon do Saba-chanRelay do Discord

    Verificar o status (com o segredo)

  9. 9
    Relay do DiscordDaemon do Saba-chan

    Conectado + token de nó (só uma vez)

  10. 10
    Daemon do Saba-chan

    Salvar o token · iniciar a conexão com o relay

  11. 11
    Daemon do Saba-chanApp GUI

    Mostrar “conectado”

Mesmo que alguém veja o código, sem o segredo de consulta não consegue o token. O token é entregue só uma vez, e quem o salva é o daemon, não a GUI. Para parear em um servidor do Discord é preciso a permissão “Gerenciar servidor”.
  • O código de pareamento tem 32 caracteres, e o pollSecret tem 48 caracteres. O código vale por 5 minutos.
  • O token é devolvido exatamente uma vez (troca atômica). É o daemon, não a GUI, que o salva em .node_token assim que chega e inicia a conexão com o relay. O app só entrega o segredo de polling ao daemon do seu PC, e o daemon o envia ao relay em um cabeçalho, nunca na URL.
  • Mesmo que alguém veja o seu código de pareamento, não consegue interceptar o token sem o pollSecret.
  • Você pode conectar vários PCs a uma conta do Discord. Ao conectar de uma conta que já tem um PC, aparecem os botões Conectar como PC novo e Reconectar para seus PCs anteriores. Reconectar um PC faz o token antigo dele parar de valer. Um servidor do Discord também pode ter PCs de várias pessoas (Discord).

2.2 Passos no aplicativo

  1. No aplicativo Saba-chan, abra Discord → Conexão e clique em Conectar um servidor do Discord.
  2. Se o bot oficial do Saba-chan ainda não estiver no seu servidor do Discord, convide-o primeiro com Convidar o bot.
  3. A tela mostra um código de conexão e o comando a digitar. Clique em Copiar e digite-o em um canal do Discord como /saba connect code:<code> (o aplicativo pode mostrar o nome coreano /사바쨩 연결 코드:<code>; é o mesmo comando).
  4. Só membros com a permissão Gerenciar servidor naquele servidor do Discord podem executar esse comando. Se você o enviar na DM com o bot, apenas o PC é conectado à sua conta, sem nenhum servidor do Discord.
  5. Se for a primeira vez dessa conta do Discord, o bot orienta o cadastro antes. Com Cadastrar, você confere os termos no site e se cadastra, e essa resposta vira a confirmação da conexão. Enquanto você não aceitar, nenhum PC é conectado.
  6. Quando o bot mostrar um botão perguntando se deve conectar, clique em Conectar. Se você usar um código dado por outra pessoa, o PC dela será conectado à sua conta; por isso só clique se o código foi obtido por você mesmo no aplicativo Saba-chan.
  7. O aplicativo verifica o status a cada 3 segundos por meio do daemon e muda para "Conectado" assim que o daemon salva o .node_token.

Depois de pareado, o daemon mantém automaticamente uma conexão de long-poll com o servidor de relay. Se você desligar a chave Retransmissão de comandos no aplicativo, seu PC para de receber comandos do Discord e o bot não responde.

2.3 Conectando outro servidor do Discord sem código

Se a sua conta do Discord já estiver pareada, você pode executar só /saba connect (sem código) em outro servidor do Discord.

  • O bot conecta de imediato a esse servidor do Discord todos os PCs vinculados à sua conta. Não é preciso aceitar nada no PC nem escolher um PC.
  • Se for a primeira vez da conta, ela é cadastrada antes. Com o cadastro, esse servidor do Discord também passa a existir no Saba-chan e, se não houver PC conectado, fica como servidor sem PC (§2.5). Se a conta já está cadastrada e não tem PC, o bot pede que você conecte com um código de pareamento.
  • Num servidor do Discord conectado assim, nenhum servidor de jogo aparece no início. Escolha, no aplicativo Saba-chan do PC, quais servidores usar nesse servidor do Discord.
  • Um servidor do Discord conectado com um código de pareamento segue a opção Abrir meus servidores de imediato em novos servidores do Discord, na tela de conexão do Discord do aplicativo. Se estiver ligada, todos os servidores aparecem de imediato; se estiver desligada, você os escolhe.
  • Assim como com o código, você precisa da permissão Gerenciar servidor. Se outro PC já estiver conectado ao servidor do Discord, ele não é tomado: o seu PC é conectado junto.

2.4 Desfazendo o pareamento

  • Clique em Desconectar no aplicativo → o daemon para a retransmissão de comandos e apaga o .node_token. Este PC é desconectado de todos os servidores do Discord.
  • Para desvincular apenas um servidor do Discord, execute /saba disconnect nele. Só quem o conectou ou o dono do servidor do Discord pode usá-lo, e as atribuições de canal desse servidor também são removidas.

2.5 Servidor do Discord sem PC

Quem não instalou o aplicativo Saba-chan também pode convidar o bot e usar a Saba-chan cantora, a Saba-chan falante, a Saba-chan leitora, os comandos de gerenciamento do servidor e as estatísticas de jogos.

  • As configurações ficam guardadas no relay. O dono do servidor do Discord ou quem tem a permissão Gerenciar servidor altera o idioma, os canais da Saba-chan falante e da Saba-chan cantora, a ampliação de emojis, as configurações da Saba-chan falante e as da Saba-chan leitora. Isso é feito pelos comandos /saba do Discord ou pelo Saba-chan web, e o cadastro é pedido na primeira alteração.
  • Não há níveis do Saba-chan (a escada de permissões) nem comandos de servidor de jogo. Os canais de alertas, de chat do jogo e de status board são enviados pelo PC, então não podem ser definidos.
  • Quando você conectar um PC depois, as configurações são herdadas como estão, e a partir daí a origem delas passa a ser esse PC.
  • O uso comum por membros, como ouvir música ou conversar, não exige cadastro.

3. Comandos de barra do bot

Estes são os comandos sob o comando raiz do bot oficial. Em clientes do Discord configurados em um idioma diferente do coreano, a raiz aparece como /saba com nomes de subcomandos em inglês; em coreano, ela é /사바쨩. Em um servidor do Discord sem PC conectado, aparecem apenas conectar, atribuir, idioma, configurações, leitura, web, emoji grande e ajuda, e quem os usa é o dono do servidor do Discord ou quem tem a permissão Gerenciar servidor, no lugar do "dono do nó". Os demais comandos de barra (/tts, /stats, /clear etc.) estão em Comandos.

ComandoQuemAção
/saba statusQualquer pessoaMostra o status do PC conectado a este servidor e de cada servidor de jogo (CPU, RAM)
/saba connect [code]Permissão Gerenciar servidorConecta com um código de pareamento. Deixe o código vazio para conectar a este servidor todos os PCs da sua conta (§2.3). Se for a primeira vez, o cadastro vem antes
/saba disconnectQuem conectou ou dono do servidorDesconecta este servidor do PC
/saba permission <level> [user]Dono do nóSe você escolher um usuário, dá a esse membro um nível de comando (Remover na lista de níveis apaga o nível próprio e o devolve ao nível padrão); se deixar vazio, define o nível padrão para membros sem nível próprio (Usuário no início). A lista de níveis é a escada de permissões deste servidor
Clique direito num membro → Apps → Change Saba-chan levelDono do nóEscolhe o nível de comando desse membro numa lista (também há Remover). É o mesmo que /saba permission. O menu só aparece para quem tem a permissão Gerenciar servidor
/saba sleepDono do nóPõe o bot para dormir neste servidor (ignora todas as mensagens)
/saba wakeDono do nóAcorda o bot
/saba assign kind:<Saba-chan falante|Saba-chan cantora|Alertas|Chat do jogo|Status board>Dono do nó e dono do servidorDefine este canal como canal da Saba-chan falante (vários, até 20; a Saba-chan falante só conversa neles), canal da Saba-chan cantora (um; mensagens comuns são apagadas, por isso ele pede confirmação), canal de alertas (um; avisos de crash do servidor, atualização, backup e reinício agendado, além de um botão Reiniciar nos alertas de crash), canal de chat do jogo (um; repassa o chat de dentro do servidor de jogo) ou canal de status board (um; um cartão de status para cada servidor ligado). Detalhes em Comandos, na parte de recursos de canal. Um canal tem apenas um tipo; executar o mesmo tipo de novo o remove. Também é possível mudar isso no app, em servidor do Discord → aba Gerenciar servidor, em Atribuição da Saba-chan
/saba language <language>Dono do nóIdioma em que o bot responde neste servidor (Automático = segue o idioma do aplicativo vinculado)
/saba readingDono do nóVolume, velocidade e tom da Saba-chan leitora neste servidor, e a opção de chamar pelo nome. Só você vê
/saba big-emoji state:<On|Off>Dono do nó e dono do servidorTroca uma mensagem com só um emoji personalizado por uma imagem grande (desligado por padrão)
/saba webQualquer pessoa (a própria conta)Link de uso único (5 minutos) para o Saba-chan web. Mostra o PC, se houver, ou só as configurações dos servidores do Discord que você gerencia. Só você vê
/saba settingsDono do nóAltera as configurações da Saba-chan falante deste servidor (ligado/desligado, intervenção, memória, moderação por IA, etapa de confirmação antes de executar, ferramentas por categoria, palavras de ativação). Ferramentas bloqueadas em Ferramentas permitidas no app não podem ser ligadas. Só você vê
/saba helpQualquer pessoaMostra como usar o Saba-chan e a lista de comandos (só você vê)
/mysaba webQualquer pessoa (a própria conta)O mesmo que /saba web. Funciona em qualquer servidor e também em DMs
/mysaba my-pcsQualquer pessoa (os próprios PCs)Lista os PCs conectados à sua conta do Discord, para renomear ou remover (só você vê)
/mysaba agentQualquer pessoa (a própria conta)Mostra e desconecta os agentes de IA (MCP remoto) conectados à sua conta do Discord. Se não houver, mostra o endereço para colocar no agente. Funciona em DMs, só você vê (Conectar um agente de IA)
/saba updateQuem conectou o PCProcura atualizações do Saba-chan no PC conectado a este servidor e aplica depois que você clica no botão de confirmação

O /mysaba trata da sua própria conta, então não aparece na lista de comandos dos membros do servidor. Depois de conectar um PC, o botão Instalar na minha conta que o bot mostra instala o Saba-chan na sua conta do Discord, e então ele aparece só para você em qualquer servidor e em DMs. Na DM com o bot, sem instalar, use /saba web, /saba my-pcs e /saba agent.

Em servidores do Discord com PC conectado, a origem das configurações de permissão, sono, idioma, Saba-chan cantora e Saba-chan leitora é a configuração do Saba-chan no PC, então esses comandos têm efeito enquanto o seu PC está ligado (servidor sem PC: §2.5). As mesmas configurações podem ser alteradas na tela do servidor do Discord no aplicativo. As permissões ficam nas telas Comandos por nível e Níveis por membro, abertas ao clicar num servidor na aba Instâncias; a Saba-chan cantora e a Saba-chan leitora têm abas próprias; idioma, prefixo e formato dos comandos de barra ficam na aba Configurações do bot. Pôr todos os servidores do Discord para dormir de uma vez é feito em Discord → Conexão.

3.1 Comandos de barra por servidor e o menu de ações

Após o pareamento, o bot registra comandos extras em cada servidor do Discord.

  • /<nome do servidor> command:<comando> arg1:… arg2:…: um comando por instância de servidor de jogo. Na lista de comandos do Discord, cada servidor aparece em uma única linha. Ao tocar no campo command, aparece a lista de comandos que podem ser usados nesse servidor (iniciar, parar, status, ações e comandos do módulo), e digitar filtra pelo nome. Os campos de argumento mostram uma lista de opções, sim/não, uma faixa numérica ou uma dica de entrada, conforme o comando escolhido.
  • A lista deixa de fora os comandos que seu nível não permite e os que não combinam com o estado atual do servidor (iniciar num servidor ligado, parar num desligado), e os que você usou por último nesse servidor vêm primeiro. Quem decide se você realmente pode usar é o aplicativo Saba-chan.
  • Ações: as ações que o aplicativo Saba-chan abre para o Discord (reiniciar, backup etc.) também entram na mesma lista de comandos. Ações que precisam de confirmação, conforme a configuração de confirmação (§5), mostram o que vai mudar, e quem pediu precisa apertar o botão de executar. As atualizações do app Saba-chan não ficam no menu de tarefas; use /saba update.
  • Jogadores: servidores cujo jogo oferece suporte ganham um comando jogadores na lista, que mostra quantas pessoas estão online e seus nomes.
  • Restaurar backup: escolha o backup em uma lista (digitar filtra). Se o servidor estiver ligado, o bot pergunta antes; Parar e continuar para o servidor e depois restaura. Restaurar é uma ação perigosa, então pede confirmação mais uma vez. Só quem pediu pode apertar os botões.
  • Aviso de pronto: ao iniciar ou reiniciar um servidor pelo comando /<nome do servidor>, pelo botão Reiniciar de um aviso ou pela Saba-chan falante, o mesmo canal é avisado quando ele passa a aceitar jogadores. Se não ligar, você recebe o motivo em uma linha.
  • Só aparecem as instâncias permitidas para aquele servidor (aba Instâncias do servidor do Discord no aplicativo).

4. Comandos de chat (prefixo)

Depois de pareado, você pode controlar os servidores pelos canais de texto do Discord usando comandos com prefixo.

Saba-chan <server> <command> [args…]

O prefixo padrão é Saba-chan. Você pode mudá-lo ou acrescentar outros, para cada servidor do Discord, em servidor do Discord → aba Configurações do bot, em Prefixo dos comandos, no aplicativo.

<server> pode ser um nome de instância, uma palavra de chamada do servidor, ou um nome ou apelido de módulo. Comandos comuns a todos os módulos:

ComandoDescrição
startInicia o servidor. Exemplo: Saba-chan minecraft start
stopPara o servidor
statusConsulta o status

As palavras que chamam o servidor e seus comandos são definidas na tela do servidor no aplicativo, na aba Discord. Veja o documento Comandos para a lista completa de comandos.


5. Níveis de permissão

Os níveis são Dono (3) > Admin (2) > Usuário (1) > Convidado (0) > Banido (-1). Os níveis são cumulativos: cada nível usa todos os comandos que os níveis abaixo dele podem usar.

  • O Dono é a pessoa que conectou o servidor (o dono do nó). Ele pode usar todos os comandos e não pode ser rebaixado.
  • Cada comando tem um risco (Seguro, Cuidado, Perigo). Com a predefinição padrão, os níveis exigidos são Seguro = Convidado, Cuidado = Usuário, Perigo = Admin. No aplicativo, em servidor do Discord → aba Instâncias, clique num servidor e, na escada Comandos por nível, escolha uma predefinição (Flexível, Padrão, Rígido) ou mova o chip de um comando para outro nível. Os níveis dos membros e o nível padrão são definidos em Níveis por membro, no mesmo lugar, e valem para todos os servidores desse servidor do Discord.
  • Ajuda e lista podem ser usadas por qualquer pessoa que não esteja banida. Membros Banidos não podem usar nenhum recurso do bot, incluindo a Saba-chan cantora e a Saba-chan falante.
  • Pedidos que passam pela Saba-chan falante não podem exceder o Limite da Saba-chan falante (Convidado por padrão).

Confirmação: se o bot pede ao solicitante um botão de confirmação antes de executar, isso é definido no aplicativo, em servidor do Discord → aba Configurações do bot, no cartão Confirmação (ou com saba-chan-cli bot confirm). Nos pedidos feitos diretamente ao bot (prefixo e comandos de barra), no início só os comandos perigosos pedem confirmação; a Saba-chan falante pede confirmação para todos os comandos no início. Para os dois você escolhe entre Todos os comandos, Cuidado ou acima, Só comandos perigosos e Nunca perguntar. O nível de risco usado na confirmação de cada comando pode ser mudado na janela de edição do chip, na tela de permissões (o nível exigido não muda). Ações de administração escolhidas pela Saba-chan falante sempre pedem confirmação, seja qual for a configuração. Só quem pediu pode apertar o botão de confirmação.


6. Saba-chan cantora

A reprodução de música é feita pelo servidor de música oficial (music-server), que roda junto com o servidor de relay.

  • Ao executar um comando como Saba-chan play …, o bot o repassa ao servidor de música, que transmite o áudio para o canal de voz do Discord.
  • Você não precisa instalar ffmpeg/yt-dlp no seu PC.
  • Os comandos de música funcionam em qualquer canal. Se você definir um canal da Saba-chan cantora com /saba assign kind:Saba-chan cantora, pode digitar comandos sem o prefixo (ou apenas um termo de busca) nele, e uma tela de player é exibida.
  • A Saba-chan cantora vem ligada por padrão; desligue-a no aplicativo, em servidor do Discord → aba Saba-chan cantora. Nos servidores em que ela está ligada, existe o comando de barra /music (veja Comandos, na parte da Saba-chan cantora).

7. Saba-chan falante (chat com IA)

  • A Saba-chan falante só funciona depois que você cadastra uma chave de API no aplicativo e a liga em cada servidor do Discord (aba Saba-chan falante da tela do servidor do Discord ou /saba settings; em servidores novos ela vem desligada). A chave só é conhecida pelo seu PC e pelo relay e nunca aparece no Discord.
  • As ferramentas que ela usa (controle dos servidores de jogo, pesquisa na web, estatísticas de LoL, TFT e PUBG, personagens de MapleStory, busca em vários jogos, informações do dia a dia e geração de imagens) também são ligadas por servidor do Discord. Ferramentas bloqueadas em Ferramentas permitidas, no menu comum do aplicativo, não são usadas em nenhum servidor. Sem ligar as ferramentas de servidor de jogo, ela não mexe nos servidores.
  • A Saba-chan falante só conversa nos canais definidos com /saba assign kind:Saba-chan falante. Em outros canais, ela não responde mesmo quando chamada.
  • A Saba-chan falante só pode usar as ações que um módulo ou extensão abre para ela. Todo o resto é recusado.
  • Consultas rodam na hora. Ações que mudam algo viram primeiro um plano e passam por um botão de confirmação conforme a etapa de confirmação (§5; no início, todos os comandos). Ações de administração sempre passam pelo botão de confirmação. Só quem pediu pode apertar o botão.
  • Ela nunca executa nada acima do Limite da Saba-chan falante (§5).
  • Com a Saba-chan falante ligada, um comando de chat que o daemon não reconhece é transformado pela Saba-chan falante em um comando exato e tentado mais uma vez.
  • Pergunte à Saba-chan falante sobre os logs e ela lê os logs do servidor, incluindo execuções anteriores. Peça o log como arquivo e ela anexa um .log sem passar pela IA (até 4 MiB, mantendo a parte mais recente; IPs, segredos e caminhos ocultos).

8. Modelo de segurança

  • O daemon envia o token de nó do pareamento (sbn_{hostId}.{secret}) no cabeçalho Authorization: Bearer via HTTPS. O relay compara esse token com o hash Argon2 que tem salvo.
  • O servidor de relay nunca guarda o token em si; ele compara com um hash Argon2.
  • O daemon não aceita conexões de entrada. As senhas dos servidores de jogo não são enviadas ao relay.

9. Solução de problemas

SintomaCausa / Solução
O bot não respondeConfira o prefixo (padrão Saba-chan) e se há um espaço depois dele. O bot precisa estar no servidor, o pareamento precisa estar concluído e a Retransmissão de comandos precisa estar ligada no aplicativo. Confira também se o bot não foi posto para dormir com /saba sleep
Saba-chan … start → servidor não encontradoA primeira palavra é o servidor (nome da instância, palavra de chamada do servidor ou nome/apelido do módulo) e a segunda é o comando. Se você roda vários servidores do mesmo jogo, use o nome da instância ou uma palavra de chamada do servidor
Código de pareamento expiradoO código vale por 5 minutos e esse tempo passou. Obtenha um novo código no aplicativo
O aplicativo fica esperandoConfira se o comando de barra /saba connect foi de fato executado e se você tem a permissão Gerenciar servidor
Os comandos do Discord não chegam ao PCSe, ao parear em outro lugar, você escolheu este PC com Reconectar, a conexão antiga deste PC é encerrada. Pareie este PC de novo

Para fluxos de solução de problemas mais detalhados, veja o documento Solução de problemas.