OpenClaw와 Nextcloud Talk 연동하기: 5분 퀵 가이드

새로운 도구를 기존 워크플로우에 연결하는 과정은 때때로 번거로울 수 있죠. 특히 자체 호스팅하는 Nextcloud Talk 같은 플랫폼에 봇을 연동하려고 하면 어디서부터 시작해야 할지 막막할 때가 있습니다. OpenClaw를 사용하면 이런 복잡한 과정을 줄이고 효율적으로 통신 채널을 구축할 수 있어요.

Nextcloud Talk (플러그인)

상태: 플러그인(webhook bot)을 통해 지원됩니다. 다이렉트 메시지(DM), 룸, 리액션 및 markdown 메시지를 지원해요.

플러그인 설치가 필요해요

Nextcloud Talk는 플러그인으로 제공되며 코어 설치본에 포함되어 있지 않습니다.

CLI를 통한 설치 (npm 레지스트리):

openclaw plugins install @openclaw/nextcloud-talk

로컬 체크아웃 (git 레포지토리에서 실행 중인 경우):

openclaw plugins install ./path/to/local/nextcloud-talk-plugin

설정 중에 Nextcloud Talk를 선택하고 git 체크아웃이 감지되면, OpenClaw가 로컬 설치 경로를 자동으로 제안해 줄 거예요.

상세 내용: Plugins

빠른 설정 가이드 (초보자용)

Nextcloud Talk 플러그인을 설치하세요.

Nextcloud 서버에서 봇을 생성하세요:

./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction

대상 룸 설정에서 봇을 활성화하세요.
OpenClaw를 설정하세요:
- Config: channels.nextcloud-talk.baseUrl + channels.nextcloud-talk.botSecret
- 또는 env: NEXTCLOUD_TALK_BOT_SECRET (기본 계정 전용)
Gateway를 재시작하거나 설정을 완료하세요.

최소 설정 예시:

{
  channels: {
    "nextcloud-talk": {
      enabled: true,
      baseUrl: "https://cloud.example.com",
      botSecret: "shared-secret",
      dmPolicy: "pairing",
    },
  },
}

참고 사항

봇이 먼저 DM을 시작할 수는 없어요. 사용자가 먼저 봇에게 메시지를 보내야 합니다.
Webhook URL은 Gateway가 접근할 수 있는 주소여야 해요. 프록시 뒤에 있다면 webhookPublicUrl을 설정하세요.
봇 API에서는 미디어 업로드를 지원하지 않아요. 미디어는 URL 형태로 전송됩니다.
Webhook 페이로드는 DM과 룸을 구분하지 않습니다. DM 여부를 확인하려면 apiUser와 apiPassword를 설정해서 룸 타입 조회를 활성화하세요. 설정하지 않으면 DM도 일반 룸으로 처리됩니다.

액세스 제어 (DM)

기본값: channels.nextcloud-talk.dmPolicy = "pairing". 알 수 없는 발신자에게는 페어링 코드가 발송됩니다.
승인 방법:
- openclaw pairing list nextcloud-talk
- openclaw pairing approve nextcloud-talk <CODE>
공개 DM: channels.nextcloud-talk.dmPolicy="open" 설정과 함께 channels.nextcloud-talk.allowFrom=["*"]를 추가하세요.
allowFrom은 Nextcloud 사용자 ID와만 매칭되며, 표시 이름(display name)은 무시됩니다.

룸 (그룹)

기본값: channels.nextcloud-talk.groupPolicy = "allowlist" (멘션 기반).
channels.nextcloud-talk.rooms를 사용해 룸을 허용 목록에 추가하세요:

{
  channels: {
    "nextcloud-talk": {
      rooms: {
        "room-token": { requireMention: true },
      },
    },
  },
}

어떤 룸도 허용하지 않으려면 허용 목록을 비워두거나 channels.nextcloud-talk.groupPolicy="disabled"로 설정하세요.

지원 기능

기능	상태
다이렉트 메시지 (DM)	지원함
룸 (Rooms)	지원함
스레드 (Threads)	지원 안 함
미디어 (Media)	URL 전용
리액션 (Reactions)	지원함
네이티브 커맨드	지원 안 함

설정 레퍼런스 (Nextcloud Talk)

전체 설정 안내: Configuration

제공 옵션:

channels.nextcloud-talk.enabled: 채널 활성화 여부.
channels.nextcloud-talk.baseUrl: Nextcloud 인스턴스 URL.
channels.nextcloud-talk.botSecret: 봇 공유 비밀키(shared secret).
channels.nextcloud-talk.botSecretFile: 비밀키가 저장된 파일 경로. 심볼릭 링크는 거부됩니다.
channels.nextcloud-talk.apiUser: 룸 조회용 API 사용자 (DM 감지용).
channels.nextcloud-talk.apiPassword: 룸 조회용 API/앱 비밀번호.
channels.nextcloud-talk.apiPasswordFile: API 비밀번호 파일 경로.
channels.nextcloud-talk.webhookPort: Webhook 리스너 포트 (기본값: 8788).
channels.nextcloud-talk.webhookHost: Webhook 호스트 (기본값: 0.0.0.0).
channels.nextcloud-talk.webhookPath: Webhook 경로 (기본값: /nextcloud-talk-webhook).
channels.nextcloud-talk.webhookPublicUrl: 외부에서 접근 가능한 Webhook URL.
channels.nextcloud-talk.dmPolicy: pairing | allowlist | open | disabled.
channels.nextcloud-talk.allowFrom: DM 허용 목록 (사용자 ID). open 정책 사용 시 "*"가 필요합니다.
channels.nextcloud-talk.groupPolicy: allowlist | open | disabled.
channels.nextcloud-talk.groupAllowFrom: 그룹 허용 목록 (사용자 ID).
channels.nextcloud-talk.rooms: 룸별 설정 및 허용 목록.
channels.nextcloud-talk.historyLimit: 그룹 히스토리 제한 (0은 비활성화).
channels.nextcloud-talk.dmHistoryLimit: DM 히스토리 제한 (0은 비활성화).
channels.nextcloud-talk.dms: DM별 개별 설정 (historyLimit 등).
channels.nextcloud-talk.textChunkLimit: 아웃바운드 텍스트 청크 크기 (글자 수).
channels.nextcloud-talk.chunkMode: length(기본값) 또는 글자 수 제한 전에 빈 줄(단락 구분) 기준으로 나누는 newline.
channels.nextcloud-talk.blockStreaming: 이 채널에 대해 블록 스트리밍 비활성화.
channels.nextcloud-talk.blockStreamingCoalesce: 블록 스트리밍 병합 튜닝.
channels.nextcloud-talk.mediaMaxMb: 인바운드 미디어 용량 제한 (MB).

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.