---
read_when:
    - OpenClaw에서 Synology Chat 설정하기
    - Synology Chat Webhook 라우팅 디버깅
summary: Synology Chat Webhook 설정 및 OpenClaw 구성
title: Synology Chat
x-i18n:
    generated_at: "2026-07-12T00:33:35Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 7829bb1464c4f5546adf086a96b7f3478e6f03e35ed2443bd92c160fa3d2bb8b
    source_path: channels/synology-chat.md
    workflow: 16
---

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](/ko/tools/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` 파일](/ko/gateway/security#workspace-env-files)을 참조하세요.

## 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`에 없습니다.

## 관련 항목

- [채널 개요](/ko/channels) — 지원되는 모든 채널
- [그룹](/ko/channels/groups) — 그룹 채팅 동작 및 멘션 제한
- [채널 라우팅](/ko/channels/channel-routing) — 메시지의 세션 라우팅
- [보안](/ko/gateway/security) — 접근 모델 및 보안 강화
