Pular para o conteúdo principal

​
Synology Chat

Status: canal de mensagens diretas por plugin incluído usando webhooks do Synology Chat. O plugin aceita mensagens de entrada de webhooks de saída do Synology Chat e envia respostas por um webhook de entrada do Synology Chat.

​
Plugin incluído

O Synology Chat é distribuído como um plugin incluído nas versões atuais do OpenClaw, então compilações empacotadas normais não precisam de uma instalação separada. Se você estiver em uma compilação mais antiga ou em uma instalação personalizada que exclua o Synology Chat, instale-o manualmente: Instale a partir de um checkout local: 
openclaw plugins install ./path/to/local/synology-chat-plugin
Detalhes: Plugins

​
Configuração rápida

  1. Verifique se o plugin do Synology Chat está disponível.
    • As versões empacotadas atuais do OpenClaw já o incluem.
    • Instalações antigas/personalizadas podem adicioná-lo manualmente a partir de um checkout do código-fonte com o comando acima.
    • openclaw onboard agora mostra o Synology Chat na mesma lista de configuração de canais que openclaw channels add.
    • Configuração não interativa: openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
  2. Nas integrações do Synology Chat:
    • Crie um webhook de entrada e copie sua URL.
    • Crie um webhook de saída com seu token secreto.
  3. Aponte a URL do webhook de saída para seu gateway OpenClaw:
    • https://gateway-host/webhook/synology por padrão.
    • Ou seu channels.synology-chat.webhookPath personalizado.
  4. Conclua a configuração no OpenClaw.
    • Guiada: openclaw onboard
    • Direta: openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
  5. Reinicie o gateway e envie uma DM para o bot do Synology Chat.
Detalhes de autenticação do webhook:
  • O OpenClaw aceita o token do webhook de saída de body.token, depois ?token=..., depois cabeçalhos.
  • Formatos de cabeçalho aceitos:
    • x-synology-token
    • x-webhook-token
    • x-openclaw-token
    • Authorization: Bearer <token>
  • Tokens vazios ou ausentes falham em modo fechado.
Configuração mínima: 
{
  channels: {
    "synology-chat": {
      enabled: true,
      token: "synology-outgoing-token",
      incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...",
      webhookPath: "/webhook/synology",
      dmPolicy: "allowlist",
      allowedUserIds: ["123456"],
      rateLimitPerMinute: 30,
      allowInsecureSsl: false,
    },
  },
}

​
Variáveis de ambiente

Para a conta padrão, você pode usar variáveis de ambiente:
  • SYNOLOGY_CHAT_TOKEN
  • SYNOLOGY_CHAT_INCOMING_URL
  • SYNOLOGY_NAS_HOST
  • SYNOLOGY_ALLOWED_USER_IDS (separados por vírgula)
  • SYNOLOGY_RATE_LIMIT
  • OPENCLAW_BOT_NAME
Os valores da configuração substituem as variáveis de ambiente.

​
Política de DM e controle de acesso

  • dmPolicy: "allowlist" é o padrão recomendado.
  • allowedUserIds aceita uma lista (ou string separada por vírgula) de IDs de usuário do Synology.
  • No modo allowlist, uma lista allowedUserIds vazia é tratada como configuração incorreta e a rota do webhook não será iniciada (use dmPolicy: "open" para permitir todos).
  • dmPolicy: "open" permite qualquer remetente.
  • dmPolicy: "disabled" bloqueia DMs.
  • O vínculo do destinatário da resposta permanece no user_id numérico estável por padrão. channels.synology-chat.dangerouslyAllowNameMatching: true é um modo de compatibilidade emergencial que reativa a busca por nome de usuário/apelido mutável para entrega de respostas.
  • Aprovações de pareamento funcionam com:
    • openclaw pairing list synology-chat
    • openclaw pairing approve synology-chat <CODE>

​
Entrega de saída

Use IDs numéricos de usuário do Synology Chat como destinos. Exemplos: 
openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw"
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
Envios de mídia são compatíveis por entrega de arquivo baseada em URL.

​
Múltiplas contas

Várias contas do Synology Chat são compatíveis em channels.synology-chat.accounts. Cada conta pode substituir token, URL de entrada, caminho do webhook, política de DM e limites. As sessões de mensagens diretas são isoladas por conta e usuário, então o mesmo user_id numérico em duas contas Synology diferentes não compartilha o estado da transcrição. Dê a cada conta habilitada um webhookPath distinto. O OpenClaw agora rejeita caminhos exatos duplicados e se recusa a iniciar contas nomeadas que apenas herdam um caminho de webhook compartilhado em configurações com várias contas. Se você precisar intencionalmente da herança legada para uma conta nomeada, defina dangerouslyAllowInheritedWebhookPath: true nessa conta ou em channels.synology-chat, mas caminhos exatos duplicados ainda são rejeitados em modo fechado. Prefira caminhos explícitos por conta. 
{
  channels: {
    "synology-chat": {
      enabled: true,
      accounts: {
        default: {
          token: "token-a",
          incomingUrl: "https://nas-a.example.com/...token=...",
        },
        alerts: {
          token: "token-b",
          incomingUrl: "https://nas-b.example.com/...token=...",
          webhookPath: "/webhook/synology-alerts",
          dmPolicy: "allowlist",
          allowedUserIds: ["987654"],
        },
      },
    },
  },
}

​
Observações de segurança

  • Mantenha token em segredo e faça a rotação se ele vazar.
  • Mantenha allowInsecureSsl: false a menos que você confie explicitamente em um certificado local autoassinado do NAS.
  • Requisições de webhook de entrada são verificadas por token e limitadas por taxa por remetente.
  • Verificações de token inválido usam comparação de segredo em tempo constante e falham em modo fechado.
  • Prefira dmPolicy: "allowlist" em produção.
  • Mantenha dangerouslyAllowNameMatching desativado, a menos que você precise explicitamente da entrega legada de respostas baseada em nome de usuário.
  • Mantenha dangerouslyAllowInheritedWebhookPath desativado, a menos que você aceite explicitamente o risco de roteamento por caminho compartilhado em uma configuração com várias contas.

​
Solução de problemas

  • Missing required fields (token, user_id, text):
    • a carga do webhook de saída não tem um dos campos obrigatórios
    • se o Synology enviar o token em cabeçalhos, verifique se o gateway/proxy preserva esses cabeçalhos
  • Invalid token:
    • o segredo do webhook de saída não corresponde a channels.synology-chat.token
    • a requisição está atingindo a conta/caminho de webhook errado
    • um proxy reverso removeu o cabeçalho do token antes de a requisição chegar ao OpenClaw
  • Rate limit exceeded:
    • muitas tentativas inválidas de token da mesma origem podem bloquear temporariamente essa origem
    • remetentes autenticados também têm um limite separado de taxa de mensagens por usuário
  • Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.:
    • dmPolicy="allowlist" está ativado, mas nenhum usuário foi configurado
  • User not authorized:
    • o user_id numérico do remetente não está em allowedUserIds

​
Relacionado

  • Channels Overview — todos os canais compatíveis
  • Pairing — autenticação por DM e fluxo de pareamento
  • Groups — comportamento de chat em grupo e bloqueio por menção
  • Channel Routing — roteamento de sessão para mensagens
  • Security — modelo de acesso e reforço de segurança