​

Synology Chat

​

번들 plugin

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

​

빠른 설정

1. Synology Chat plugin을 사용할 수 있는지 확인합니다.
   • 현재 패키지된 OpenClaw 릴리스에는 이미 번들로 포함되어 있습니다.
   • 이전/사용자 지정 설치에서는 위 명령으로 소스 체크아웃에서 수동 추가할 수 있습니다.
   • 이제 openclaw onboard는 openclaw channels add와 동일한 채널 설정 목록에 Synology Chat를 표시합니다.
   • 비대화형 설정: openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
2. Synology Chat 통합에서 다음을 수행합니다:
   • 인커밍 웹훅을 만들고 URL을 복사합니다.
   • 비밀 토큰으로 아웃고잉 웹훅을 만듭니다.
3. 아웃고잉 웹훅 URL이 OpenClaw 게이트웨이를 가리키도록 설정합니다:
   • 기본값: https://gateway-host/webhook/synology
   • 또는 사용자 지정 channels.synology-chat.webhookPath
4. OpenClaw에서 설정을 완료합니다.
   • 가이드 방식: openclaw onboard
   • 직접 방식: openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
5. 게이트웨이를 재시작하고 Synology Chat 봇에 DM을 보냅니다.

• OpenClaw는 먼저 body.token에서, 그다음 ?token=...에서, 그다음 헤더에서 아웃고잉 웹훅 토큰을 받아들입니다.
• 허용되는 헤더 형식:
  • x-synology-token
  • x-webhook-token
  • x-openclaw-token
  • Authorization: Bearer <token>
• 비어 있거나 누락된 토큰은 fail-closed 방식으로 거부됩니다.

{
  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,
    },
  },
}

​

환경 변수

• SYNOLOGY_CHAT_TOKEN
• SYNOLOGY_CHAT_INCOMING_URL
• SYNOLOGY_NAS_HOST
• SYNOLOGY_ALLOWED_USER_IDS (쉼표로 구분)
• SYNOLOGY_RATE_LIMIT
• OPENCLAW_BOT_NAME

​

DM 정책 및 액세스 제어

• dmPolicy: "allowlist"가 권장 기본값입니다.
• allowedUserIds는 Synology 사용자 ID 목록(또는 쉼표로 구분된 문자열)을 받습니다.
• allowlist 모드에서 빈 allowedUserIds 목록은 잘못된 구성으로 처리되며 웹훅 라우트가 시작되지 않습니다(모두 허용하려면 dmPolicy: "open" 사용).
• dmPolicy: "open"은 모든 발신자를 허용합니다.
• dmPolicy: "disabled"는 DM을 차단합니다.
• 응답 수신자 바인딩은 기본적으로 안정적인 숫자 user_id에 유지됩니다. channels.synology-chat.dangerouslyAllowNameMatching: true는 변경 가능한 사용자 이름/닉네임 조회를 통한 응답 전달을 다시 활성화하는 비상 호환 모드입니다.
• 페어링 승인은 다음과 함께 작동합니다:
  • openclaw pairing list synology-chat
  • openclaw pairing approve synology-chat <CODE>

​

아웃바운드 전달

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"

​

다중 계정

{
  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"],
        },
      },
    },
  },
}

​

보안 참고 사항

• token은 비밀로 유지하고 유출되면 교체하세요.
• 자체 서명된 로컬 NAS 인증서를 명시적으로 신뢰하는 경우가 아니라면 allowInsecureSsl: false를 유지하세요.
• 수신 웹훅 요청은 토큰 검증 및 발신자별 속도 제한이 적용됩니다.
• 잘못된 토큰 검사는 상수 시간 비밀 비교를 사용하며 fail-closed 방식으로 처리됩니다.
• 프로덕션에서는 dmPolicy: "allowlist"를 권장합니다.
• 레거시 사용자 이름 기반 응답 전달이 명시적으로 필요한 경우가 아니라면 dangerouslyAllowNameMatching을 끄세요.
• 다중 계정 설정에서 공유 경로 라우팅 위험을 명시적으로 수용하는 경우가 아니라면 dangerouslyAllowInheritedWebhookPath를 끄세요.

​

문제 해결

• Missing required fields (token, user_id, text):
  • 아웃고잉 웹훅 페이로드에 필수 필드 중 하나가 없습니다
  • Synology가 헤더로 토큰을 보낸다면 게이트웨이/프록시가 해당 헤더를 보존하는지 확인하세요
• Invalid token:
  • 아웃고잉 웹훅 비밀이 channels.synology-chat.token과 일치하지 않습니다
  • 요청이 잘못된 계정/웹훅 경로로 들어오고 있습니다
  • 요청이 OpenClaw에 도달하기 전에 리버스 프록시가 토큰 헤더를 제거했습니다
• Rate limit exceeded:
  • 동일한 소스에서 너무 많은 잘못된 토큰 시도가 있으면 해당 소스가 일시적으로 차단될 수 있습니다
  • 인증된 발신자에게도 별도의 사용자별 메시지 속도 제한이 적용됩니다
• Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.:
  • dmPolicy="allowlist"가 활성화되었지만 구성된 사용자가 없습니다
• User not authorized:
  • 발신자의 숫자 user_id가 allowedUserIds에 없습니다

​

관련 항목

• 채널 개요 — 지원되는 모든 채널
• 페어링 — DM 인증 및 페어링 흐름
• 그룹 — 그룹 채팅 동작 및 멘션 게이팅
• 채널 라우팅 — 메시지용 세션 라우팅
• 보안 — 액세스 모델 및 강화