---
read_when:
    - Configurando o Synology Chat com o OpenClaw
    - Depurando o roteamento de webhook do Synology Chat
summary: Configuração de webhook do Synology Chat e configuração do OpenClaw
title: Synology Chat
x-i18n:
    generated_at: "2026-04-05T12:36:16Z"
    model: gpt-5.4
    provider: openai
    source_hash: ddb25fc6b53f896f15f43b4936d69ea071a29a91838a5b662819377271e89d81
    source_path: channels/synology-chat.md
    workflow: 15
---

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

```bash
openclaw plugins install ./path/to/local/synology-chat-plugin
```

Detalhes: [Plugins](/tools/plugin)

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

```json5
{
  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:

```bash
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.

```json5
{
  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](/channels) — todos os canais compatíveis
- [Pairing](/channels/pairing) — autenticação por DM e fluxo de pareamento
- [Groups](/channels/groups) — comportamento de chat em grupo e bloqueio por menção
- [Channel Routing](/channels/channel-routing) — roteamento de sessão para mensagens
- [Security](/gateway/security) — modelo de acesso e reforço de segurança
