OpenClaw

OpenClaw Nextcloud Talk 채널

엔터프라이즈
보통

Nextcloud 생태계에 내장된 프라이버시 중심의 기업용 커뮤니케이션 플랫폼인 Nextcloud Talk에 OpenClaw를 연결하세요. 이 통합은 웹훅 기반 봇 아키텍처를 사용합니다 — Nextcloud Talk이 웹훅을 통해 메시지 이벤트를 Gateway로 전송하고, 봇은 Talk REST API를 통해 응답합니다. 이를 통해 AI 어시스턴트가 자체 호스팅 Nextcloud 환경 내에서 다이렉트 메시지, 채팅방 대화에 참여하고 이모지로 메시지에 반응할 수 있습니다.

기본 정보
난이도보통
카테고리엔터프라이즈
지원 기능 수4 / 6

Nextcloud Talk 지원 기능

텍스트 메시지

지원

미디어 및 파일

지원

리액션

지원

스레드

미지원

음성 메시지

미지원

그룹 채팅

지원

Nextcloud Talk 사전 요구사항

  • 관리자 권한이 있고 Talk 앱이 설치된 Nextcloud 서버(v27.1 이상)
  • 웹훅 서명 검증을 위한 공유 시크릿(40-128자)
  • Nextcloud 서버에서 접근 가능한 Gateway의 웹훅 엔드포인트(공개 URL 또는 내부 네트워크)
  • OpenClaw Gateway 설치 및 실행 중
  • 'openclaw plugins install @openclaw/nextcloud-talk' 명령으로 설치된 Nextcloud Talk 플러그인

Nextcloud Talk 빠른 설정

1

Nextcloud Talk 플러그인 설치

'openclaw plugins install @openclaw/nextcloud-talk' 명령을 실행하여 Gateway에 Nextcloud Talk 지원을 추가합니다.

2

Nextcloud 서버에 봇 등록

Nextcloud 서버에 SSH로 접속한 후 OCC 명령을 실행합니다: ./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction. <shared-secret>을 40자 이상의 강력한 시크릿으로, <webhook-url>을 Gateway의 공개 접근 가능한 웹훅 엔드포인트(예: https://gateway.example.com:8788/webhook)로 대체하세요.

3

봇 활성화 및 설정

Nextcloud Talk에서 채팅방 설정으로 이동하여 OpenClaw 봇을 활성화합니다. 그런 다음 baseUrl과 botSecret을 포함한 채널 설정을 ~/.openclaw/openclaw.json에 추가합니다. 'openclaw start'로 Gateway를 시작하고 채팅방에서 메시지를 보내 연결을 확인합니다.

Nextcloud Talk 구성 예시

config.json
{
  "channels": {
    "nextcloud-talk": {
      "enabled": true,
      "baseUrl": "https://nextcloud.example.com",
      "botSecret": "your-shared-secret-min-40-chars",
      "dmPolicy": "pairing"
    }
  }
}

Nextcloud Talk 상세 문서

아키텍처 개요

OpenClaw는 Talk Bot API(Nextcloud 27.1부터 사용 가능)를 통해 Nextcloud Talk과 통합됩니다. 아키텍처는 웹훅 기반입니다: 1. 봇은 OCC 명령줄 도구를 사용하여 공유 시크릿과 Webhook URL로 Nextcloud 서버에 등록됩니다. 2. 봇이 활성화된 채팅방에 메시지가 게시되면, Nextcloud Talk은 공유 시크릿으로 서명된 메시지 페이로드와 함께 설정된 Webhook URL로 HTTP POST를 전송합니다. 3. Gateway는 웹훅 서명을 검증하고, AI 에이전트를 통해 메시지를 처리한 후, Talk REST API를 사용하여 대화에 응답을 게시합니다. 이 설계는 Gateway가 Nextcloud 서버에서 접근 가능한 웹훅 엔드포인트를 노출해야 함을 의미합니다. 웹훅 리스너는 기본적으로 포트 8788에서 실행되며, webhookPort 및 webhookHost 설정 옵션을 통해 사용자 정의할 수 있습니다.
Webhook URL은 Nextcloud 서버에서 접근 가능해야 합니다. 로컬 개발 시에는 ngrok과 같은 터널 서비스를 사용하세요.
각 봇 설치 시 메시지의 actor ID로 사용되는 고유한 URL 해시(bot-<hash>)가 생성됩니다.

OCC를 통한 봇 등록

Nextcloud Talk 봇은 OCC(Nextcloud Command Console) 명령을 사용하여 서버에 등록됩니다. 이 작업은 SSH 또는 콘솔 접근이 필요한 서버 측 작업입니다. 봇 설치 명령: ./occ talk:bot:install "OpenClaw" "<secret>" "<webhook-url>" --feature reaction 매개변수: • name(필수): 메시지 작성자로 표시되는 이름(1-64자) • secret(필수): 웹훅 서명 검증을 위한 공유 시크릿(40-128자) • url(필수): Gateway의 웹훅 엔드포인트 URL • --feature: 봇 기능 — 이모지 리액션을 활성화하려면 'reaction'을 사용 • --no-setup: 모더레이터가 채팅방별로 봇을 전환하는 것을 방지 기타 유용한 OCC 명령: • talk:bot:list — 설치된 모든 봇 목록 조회 • talk:bot:remove <bot-id> — 특정 대화에서 봇 제거 • talk:bot:setup <bot-id> <token> — 대화에서 봇 활성화 • talk:bot:state <bot-id> <state> — 봇 상태 변경(0=비활성, 1=활성, 2=설정 불가) • talk:bot:uninstall <id> — 서버에서 봇 완전 제거
Terminal
./occ talk:bot:install "OpenClaw" "a]72@Bz&V!LKMO*xhQib7p^E%yzGMG(8a7Bp*x6o" "https://gateway.example.com:8788/webhook" --feature reaction
강력한 공유 시크릿을 생성하려면 다음 명령을 사용하세요: openssl rand -base64 48
봇이 이모지로 메시지에 리액션할 수 있도록 --feature reaction 플래그를 사용하는 것을 권장합니다.

DM 정책

DM(다이렉트 메시지) 정책은 봇이 일대일 비공개 대화를 처리하는 방식을 제어합니다. **pairing(기본값)** — 알 수 없는 발신자에게 페어링 코드가 전송되며, 봇이 응답하기 전에 코드를 검증해야 합니다. 명시적인 사용자 인증이 필요한 가장 안전한 모드입니다. **open** — 봇에게 메시지를 보내는 모든 사용자가 응답을 받습니다. allowFrom을 ["*"]로 설정해야 합니다. **disabled** — 봇이 다이렉트 메시지에 전혀 응답하지 않습니다. 참고: Nextcloud Talk 봇은 DM을 먼저 시작할 수 없으며, 사용자가 봇에게 먼저 메시지를 보내야 합니다. allowFrom 필드는 Nextcloud 사용자 ID(표시 이름이 아닌)와 매칭됩니다.
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "dmPolicy": "pairing",
      "allowFrom": ["user-id-1", "user-id-2"]
    }
  }
}
Nextcloud Talk에서 봇은 다이렉트 메시지를 먼저 시작할 수 없습니다. 대화를 시작하려면 사용자가 먼저 봇에게 연락해야 합니다.

채팅방 설정

채팅방(그룹 채팅) 정책은 봇이 참여하는 대화와 트리거 방식을 제어합니다. **allowlist(기본값)** — 봇은 모더레이터가 채팅방 설정을 통해 명시적으로 활성화한 채팅방에서만 응답합니다. rooms 객체를 사용하여 채팅방별 설정을 사용자 정의할 수 있습니다. 각 채팅방은 대화 토큰으로 식별되며 독립적인 설정을 가질 수 있습니다: • requireMention — true로 설정하면 봇은 @멘션될 때만 응답합니다(채팅방에서의 기본 동작) • 설정에 나열되지 않은 채팅방은 기본 채팅방 설정을 사용합니다 채팅방 토큰을 확인하려면 Nextcloud Talk에서 해당 채팅방을 볼 때의 URL을 확인하세요(예: https://nextcloud.example.com/call/<token>).
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "groupPolicy": "allowlist",
      "rooms": {
        "abc123token": {
          "requireMention": true
        },
        "def456token": {
          "requireMention": false
        }
      }
    }
  }
}
봇이 메시지를 수신하려면 채팅방 모더레이터가 채팅방 설정에서 봇을 활성화해야 합니다.
활발한 채팅방에서 봇이 모든 메시지에 응답하지 않도록 requireMention: true를 사용하세요.

채팅방 유형 감지를 위한 API 자격 증명

기본적으로 Nextcloud Talk의 웹훅 페이로드는 다이렉트 메시지와 채팅방 메시지를 구분하지 않습니다. 정확한 채팅방 유형 감지를 활성화하려면 API 자격 증명을 제공할 수 있습니다. apiUser와 apiPassword가 설정되면, Gateway는 수신 메시지가 DM인지 채팅방 대화인지 판별하기 위해 추가 API 호출을 수행합니다. 이를 통해 봇이 서로 다른 정책(dmPolicy 대 groupPolicy)을 올바르게 적용할 수 있습니다. API 자격 증명이 없으면 봇은 모든 메시지를 통합 정책에 따라 처리하며, 이는 단순한 배포에는 충분할 수 있습니다.
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "apiUser": "bot-service-account",
      "apiPassword": "service-account-password",
      "apiPasswordFile": "/run/secrets/nc-api-password"
    }
  }
}
API 자격 증명에는 관리자 계정 대신 전용 Nextcloud 사용자 계정을 생성하여 사용하세요.
설정 파일에 비밀번호를 직접 저장하는 대신 apiPasswordFile을 사용하여 파일(예: Docker 시크릿)에서 비밀번호를 로드하세요.
API 자격 증명이 없으면 봇이 DM과 채팅방 메시지를 구분할 수 없습니다. 이로 인해 DM 전용 정책이 올바르게 작동하지 않을 수 있습니다.

웹훅 설정

Gateway는 Nextcloud Talk에서 웹훅 이벤트를 수신하기 위해 내장 HTTP 서버를 시작합니다. 웹훅 리스너 설정은 서버가 수신 대기하는 방식과 위치를 제어합니다. **webhookPort**(기본값: 8788) — 웹훅 HTTP 서버의 포트입니다. **webhookHost**(기본값: 0.0.0.0) — 바인딩할 인터페이스입니다. 모든 인터페이스에서 수신하려면 0.0.0.0을, 로컬호스트만 사용하려면 127.0.0.1을 사용합니다. **webhookPath** — 웹훅 엔드포인트의 사용자 정의 URL 경로입니다. **webhookPublicUrl** — Nextcloud가 웹훅에 도달하는 데 사용해야 하는 전체 공개 URL입니다. 리버스 프록시 또는 NAT 뒤에 있을 때 필요합니다. 봇 설치(OCC 명령) 시 제공한 Webhook URL은 이 리스너로 연결되는 공개 URL과 일치해야 합니다.
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "webhookPort": 8788,
      "webhookHost": "0.0.0.0",
      "webhookPath": "/webhook",
      "webhookPublicUrl": "https://gateway.example.com:8788/webhook"
    }
  }
}
리버스 프록시 뒤에서 실행 중인 경우, webhookPublicUrl을 외부에서 접근 가능한 URL로 설정하세요.
방화벽이 Nextcloud 서버에서 웹훅 포트로의 인바운드 연결을 허용하는지 확인하세요.

메시지 처리 및 스트리밍

OpenClaw는 Nextcloud Talk으로 메시지가 분할되고 전달되는 방식을 세밀하게 제어할 수 있습니다. **textChunkLimit** — 메시지 청크당 최대 문자 수입니다. Nextcloud Talk은 긴 메시지를 지원하지만, 청크 분할을 통해 긴 AI 응답의 가독성을 높일 수 있습니다. **chunkMode** — 텍스트 분할 방식을 제어합니다: 'length'는 문자 수 제한에서 분할하고, 'newline'은 문단 경계에서 분할하여 더 자연스럽게 나눕니다. **blockStreaming** — 활성화하면 봇이 부분 응답을 스트리밍하는 대신 완전한 AI 응답을 기다린 후 전송합니다. **blockStreamingCoalesce** — 블록 스트리밍이 활성화된 경우, 최종 응답을 여러 청크 대신 하나의 메시지로 결합합니다. **mediaMaxMb** — 미디어 첨부 파일의 최대 파일 크기(MB)입니다. Nextcloud Talk은 직접 파일 업로드 대신 URL로 미디어를 전송합니다.
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": true,
      "blockStreamingCoalesce": true,
      "mediaMaxMb": 10
    }
  }
}
여러 사용자가 활동하는 채팅방에서 더 깔끔한 응답을 위해 blockStreaming: true를 사용하세요.
Nextcloud Talk에서 미디어는 URL로 공유됩니다 — 봇은 파일을 직접 업로드할 수 없습니다.

대화 기록

AI 에이전트가 새 메시지를 처리할 때 컨텍스트로 포함할 이전 메시지 수를 제어합니다. **historyLimit** — 채팅방 대화에 포함할 최대 이전 메시지 수입니다. **dmHistoryLimit** — 다이렉트 메시지 대화에 포함할 최대 이전 메시지 수입니다. 채팅방 기록 제한과 독립적으로 설정할 수 있습니다. DM별 개별 재정의도 지원되어 특정 사용자에 대해 다른 기록 제한을 설정할 수 있습니다. 기록 제한이 높을수록 AI에 더 많은 컨텍스트를 제공하지만, 토큰 사용량과 처리 시간이 증가합니다.
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "historyLimit": 20,
      "dmHistoryLimit": 50
    }
  }
}

리액션 지원

Nextcloud Talk은 메시지에 대한 이모지 리액션을 지원하며, OpenClaw 봇은 리액션을 읽고 추가할 수 있습니다. 리액션 지원을 활성화하려면, OCC 설치 시 --feature reaction 플래그로 봇을 등록해야 합니다. 활성화되면 AI 에이전트는 사용자 메시지에 이모지로 리액션하여 확인이나 피드백을 제공할 수 있습니다. 리액션은 봇이 전체 텍스트 응답을 게시하지 않고도 상호작용할 수 있는 가벼운 방법입니다 — 예를 들어, 완료된 작업을 확인하기 위해 체크 이모지로 리액션할 수 있습니다. Nextcloud Talk Reaction API(bots-v1 기능부터 사용 가능)가 리액션의 추가 및 제거에 대한 기본 메커니즘을 처리합니다.
리액션이 작동하려면 봇 설치 시 --feature reaction 플래그를 설정해야 합니다.
리액션은 활발한 채팅방에서 방해가 적은 확인 메커니즘으로 사용할 수 있습니다.

보안 및 웹훅 서명

Nextcloud Talk의 모든 웹훅 페이로드는 봇 설치 시 설정된 공유 시크릿을 사용하여 서명됩니다. Gateway는 진위성과 무결성을 보장하기 위해 각 서명을 검증합니다. 서명 메커니즘은 HMAC-SHA256을 사용합니다: 1. Nextcloud는 공유 시크릿을 사용하여 웹훅 페이로드 본문의 HMAC-SHA256 해시를 계산합니다. 2. 서명은 웹훅 요청의 HTTP 헤더에 포함됩니다. 3. Gateway가 독립적으로 해시를 계산하고 수신된 서명과 비교합니다. 4. 서명이 일치하지 않으면 요청이 거부됩니다. 이를 통해 Nextcloud 서버의 정당한 요청만 처리됩니다. 공유 시크릿을 기밀로 유지하고, 새로운 시크릿으로 봇을 재설치하여 주기적으로 교체하세요.
암호학적으로 강력한 시크릿을 사용하세요: openssl rand -base64 48 명령으로 적절한 값을 생성할 수 있습니다.
시크릿을 버전 관리에 커밋하지 않으려면 botSecretFile을 사용하여 저장하세요.
공유 시크릿을 공개 저장소나 로그에 절대 노출하지 마세요. 프로덕션 배포 시에는 환경 변수나 시크릿 파일을 사용하세요.

Nextcloud Talk 구성 참조

enabled
Type: booleanDefault: true

Nextcloud Talk 채널 활성화 또는 비활성화

baseUrl
Type: stringDefault: ""

Nextcloud 서버의 전체 URL(예: https://nextcloud.example.com)

botSecret
Type: stringDefault: ""

웹훅 서명 검증에 사용되는 공유 시크릿(OCC 설치 시크릿과 일치해야 함)

botSecretFile
Type: stringDefault: ""

공유 시크릿이 포함된 파일 경로(인라인 botSecret의 대안)

apiUser
Type: stringDefault: ""

API 호출에 사용되는 Nextcloud 사용자 이름(채팅방 유형 감지에 사용)

apiPassword
Type: stringDefault: ""

API 사용자 계정의 비밀번호

apiPasswordFile
Type: stringDefault: ""

API 비밀번호가 포함된 파일 경로(인라인 apiPassword의 대안)

dmPolicy
Type: stringDefault: "pairing"

DM 접근 정책: 'pairing'(인증 코드), 'open'(모든 사용자), 또는 'disabled'(DM 비활성)

allowFrom
Type: string[]Default: []

봇에 DM을 보낼 수 있는 Nextcloud 사용자 ID(["*"]로 개방 접근)

groupPolicy
Type: stringDefault: "allowlist"

채팅방 접근 정책: 'allowlist'(모더레이터가 활성화한 채팅방만 허용)

webhookPort
Type: numberDefault: 8788

내장 웹훅 HTTP 서버의 포트

webhookHost
Type: stringDefault: "0.0.0.0"

웹훅 서버를 바인딩할 인터페이스

webhookPath
Type: stringDefault: "/webhook"

웹훅 엔드포인트의 URL 경로

webhookPublicUrl
Type: stringDefault: ""

웹훅 엔드포인트의 전체 공개 URL(리버스 프록시 뒤에서 필요)

historyLimit
Type: numberDefault: 20

채팅방 대화의 컨텍스트로 포함되는 최대 이전 메시지 수

dmHistoryLimit
Type: numberDefault: 50

DM 대화의 컨텍스트로 포함되는 최대 이전 메시지 수

textChunkLimit
Type: numberDefault: 4000

메시지 청크당 최대 문자 수

chunkMode
Type: stringDefault: "length"

텍스트 분할 모드: 'length'(문자 수 제한) 또는 'newline'(문단 경계)

blockStreaming
Type: booleanDefault: false

전송 전 완전한 AI 응답 대기(스트리밍 없음)

blockStreamingCoalesce
Type: booleanDefault: false

스트리밍 청크를 하나의 최종 메시지로 결합

mediaMaxMb
Type: numberDefault: 10

미디어 URL 참조의 최대 파일 크기(MB)

Nextcloud Talk 자주 묻는 질문

Nextcloud Talk 문제 해결

봇이 메시지에 응답하지 않음

Webhook URL에 접근할 수 없거나, 채팅방에서 봇이 활성화되지 않았거나, 공유 시크릿이 일치하지 않습니다.

Nextcloud 서버에서 Webhook URL에 접근 가능한지 확인하세요(curl로 테스트). 채팅방 설정에서 봇이 활성화되어 있는지 확인하세요. openclaw.json의 botSecret이 OCC 설치 명령에서 사용한 시크릿과 일치하는지 확인하세요.
웹훅 서명 검증 실패

openclaw.json의 공유 시크릿이 봇 설치 시 사용된 것과 일치하지 않습니다.

두 시크릿이 정확히 일치하는지 확인하세요. 확실하지 않다면 봇을 제거하고 알려진 시크릿으로 재설치하세요. Gateway 로그에서 서명 불일치 오류를 확인하세요.
봇이 DM에서는 응답하지만 채팅방에서는 응답하지 않음

대상 채팅방에서 모더레이터가 봇을 활성화하지 않았거나, requireMention이 true인데 봇이 @멘션되지 않았습니다.

채팅방 모더레이터에게 채팅방 설정에서 봇을 활성화하도록 요청하세요. requireMention이 설정된 경우, 사용자가 봇 이름을 @멘션하는지 확인하세요. openclaw.json의 rooms 설정을 확인하세요.
DM과 채팅방 메시지를 구분할 수 없음

API 자격 증명(apiUser, apiPassword)이 설정되지 않았습니다.

nextcloud-talk 채널 설정에 apiUser와 apiPassword를 추가하세요. 이 용도로 전용 Nextcloud 서비스 계정을 생성하세요. Gateway는 이 자격 증명을 사용하여 Talk API에 대화 유형 감지를 요청합니다.
Gateway가 웹훅 리스너를 시작하지 못함

설정된 웹훅 포트가 이미 사용 중이거나 호스트 바인딩이 유효하지 않습니다.

webhookPort를 사용 가능한 포트로 변경하세요(기본값: 8788). 특정 인터페이스에 바인딩하는 경우, webhookHost IP 주소가 올바른지 확인하세요. 'lsof -i :8788' 또는 'netstat -tlnp'를 사용하여 포트 충돌을 확인하세요.
전체 문서 보기모든 채널로 돌아가기

관련 채널

Feishu / Lark

Medium

OpenClaw WebSocket을 통한 Feishu/Lark 통합

설정 가이드

Slack

Medium

OpenClaw Bolt SDK를 통한 워크스페이스 앱 통합

설정 가이드

Google Chat

Medium

OpenClaw HTTP 엔드포인트를 통한 Google Chat API 앱

설정 가이드