OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Developer and self-hosted

Synology Chat

Synology Chat은 Webhook 쌍을 통해 OpenClaw에 연결됩니다. Synology Chat 발신 Webhook은 수신된 다이렉트 메시지를 Gateway로 전송하고, 응답은 Synology Chat 수신 Webhook을 통해 다시 전달됩니다.

상태: 공식 Plugin이며 별도로 설치합니다. 다이렉트 메시지만 지원하며, 텍스트 및 URL 기반 파일 전송을 지원합니다.

설치

bash
openclaw plugins install @openclaw/synology-chat

로컬 체크아웃(git 저장소에서 실행하는 경우):

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

자세한 내용: Plugin

빠른 설정

  1. 위의 Plugin을 설치합니다.
  2. Synology Chat 통합에서:
    • 수신 Webhook을 생성하고 해당 URL을 복사합니다.
    • 비밀 토큰을 사용하여 발신 Webhook을 생성합니다.
  3. 발신 Webhook URL이 OpenClaw Gateway를 가리키도록 설정합니다.
    • 기본값은 https://gateway-host/webhook/synology입니다.
    • 또는 사용자 지정 channels.synology-chat.webhookPath를 사용합니다.
  4. OpenClaw에서 설정을 완료합니다. 두 흐름 모두 동일한 채널 설정 목록에 Synology Chat이 표시됩니다.
    • 안내 방식: openclaw onboard 또는 openclaw channels add
    • 직접 방식: openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
  5. Gateway를 다시 시작하고 Synology Chat 봇에 DM을 보냅니다.

Webhook 인증 세부 정보:

  • OpenClaw은 먼저 body.token, 그다음 ?token=..., 마지막으로 헤더에서 발신 Webhook 토큰을 받습니다.
  • 허용되는 헤더 형식:
    • x-synology-token
    • x-webhook-token
    • x-openclaw-token
    • Authorization: Bearer <token>
  • 토큰이 비어 있거나 없으면 안전하게 거부됩니다.
  • 페이로드는 application/x-www-form-urlencoded 또는 application/json 형식일 수 있으며, token, user_id, text가 필수입니다.

최소 구성:

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

환경 변수

기본 계정에는 다음 환경 변수를 사용할 수 있습니다.

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

구성 값은 환경 변수보다 우선합니다.

SYNOLOGY_CHAT_INCOMING_URL과 SYNOLOGY_NAS_HOST는 워크스페이스 .env에서 설정할 수 없습니다. 워크스페이스 .env 파일을 참조하세요.

DM 정책 및 접근 제어

  • 지원되는 dmPolicy 값은 allowlist(기본값), open, disabled입니다. Synology Chat에는 페어링 흐름이 없으므로, 발신자의 숫자형 Synology 사용자 ID를 allowedUserIds에 추가하여 승인합니다.
  • allowedUserIds에는 Synology 사용자 ID 목록 또는 쉼표로 구분된 문자열을 지정할 수 있습니다.
  • allowlist 모드에서 allowedUserIds 목록이 비어 있으면 잘못된 구성으로 처리되며 Webhook 경로가 시작되지 않습니다.
  • dmPolicy: "open"은 allowedUserIds에 "*"가 포함된 경우에만 공개 DM을 허용합니다. 제한적인 항목이 있으면 일치하는 사용자만 채팅할 수 있습니다. allowedUserIds 목록이 비어 있는 상태에서 open을 사용해도 경로 시작이 거부됩니다.
  • dmPolicy: "disabled"는 DM을 차단합니다.
  • 응답 수신자 바인딩은 기본적으로 변경되지 않는 숫자형 user_id를 사용합니다. channels.synology-chat.dangerouslyAllowNameMatching: true는 응답 전달을 위해 변경 가능한 사용자 이름/별명 조회를 다시 활성화하는 비상 호환 모드입니다.

발신 전달

대상에는 숫자형 Synology Chat 사용자 ID를 사용합니다. synology-chat:, synology_chat:, synology: 접두사를 사용할 수 있습니다.

예:

bash
openclaw message send --channel synology-chat --target 123456 --message "Hello from OpenClaw"openclaw message send --channel synology-chat --target synology-chat:123456 --message "Hello again"openclaw message send --channel synology-chat --target synology:123456 --message "Short prefix"

발신 텍스트는 2,000자 단위로 분할됩니다. URL 기반 파일 전달을 통한 미디어 전송을 지원합니다. NAS가 파일을 다운로드하여 첨부하며 최대 크기는 32MB입니다. 발신 파일 URL은 http 또는 https를 사용해야 하며, OpenClaw이 URL을 NAS Webhook으로 전달하기 전에 사설 네트워크 대상이나 그 밖의 차단된 네트워크 대상은 거부됩니다.

다중 계정

channels.synology-chat.accounts에서 여러 Synology Chat 계정을 지원합니다. 각 계정은 토큰, 수신 URL, Webhook 경로, DM 정책, 제한을 재정의할 수 있습니다. 다이렉트 메시지 세션은 계정 및 사용자별로 격리되므로 서로 다른 두 Synology 계정의 동일한 숫자형 user_id가 대화 기록 상태를 공유하지 않습니다. 활성화된 각 계정에 서로 다른 webhookPath를 지정하세요. OpenClaw은 정확히 중복되는 경로를 거부하며, 다중 계정 설정에서 공유 Webhook 경로만 상속하는 명명된 계정의 시작을 거부합니다. 명명된 계정에 레거시 상속이 의도적으로 필요한 경우 해당 계정 또는 channels.synology-chat에서 dangerouslyAllowInheritedWebhookPath: true를 설정하세요. 단, 정확히 중복되는 경로는 여전히 안전하게 거부됩니다. 계정별 경로를 명시적으로 지정하는 것이 좋습니다.

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

보안 참고 사항

  • token을 비밀로 유지하고 유출된 경우 교체하세요.
  • 자체 서명된 로컬 NAS 인증서를 명시적으로 신뢰하는 경우가 아니면 allowInsecureSsl: false를 유지하세요.
  • 수신 Webhook 요청은 토큰을 검증하며 발신자별로 속도가 제한됩니다(rateLimitPerMinute, 기본값 30).
  • 유효하지 않은 토큰 검사는 일정 시간 비밀 비교를 사용하고 안전하게 거부합니다. 유효하지 않은 토큰 시도가 반복되면 원본 IP가 일시적으로 차단됩니다.
  • 수신 메시지 텍스트는 알려진 프롬프트 인젝션 패턴을 방지하도록 정제되며 4,000자로 잘립니다.
  • 프로덕션 환경에서는 dmPolicy: "allowlist"를 사용하는 것이 좋습니다.
  • 레거시 사용자 이름 기반 응답 전달이 명시적으로 필요하지 않으면 dangerouslyAllowNameMatching을 끄세요.
  • 다중 계정 설정에서 공유 경로 라우팅 위험을 명시적으로 허용하지 않으면 dangerouslyAllowInheritedWebhookPath를 끄세요.

문제 해결

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

관련 항목

Was this useful?
On this page

On this page