Mattermost

상태: 다운로드 가능한 Plugin(봇 토큰 + WebSocket 이벤트). Channels, 그룹, DM이 지원됩니다. Mattermost는 자체 호스팅 가능한 팀 메시징 플랫폼입니다. 제품 세부 정보와 다운로드는 공식 사이트 mattermost.com을 참조하세요.

# 설치

채널을 구성하기 전에 Mattermost를 설치하세요.

openclaw plugins install @openclaw/mattermost

openclaw plugins install ./path/to/local/mattermost-plugin

세부 정보: Plugins

# 빠른 설정

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
    },
  },
}

# 네이티브 슬래시 명령

네이티브 슬래시 명령은 선택 사항입니다. 활성화하면 OpenClaw가 Mattermost API를 통해 oc_* 슬래시 명령을 등록하고 Gateway HTTP 서버에서 콜백 POST를 수신합니다.

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Mattermost가 Gateway에 직접 도달할 수 없을 때 사용합니다(리버스 프록시/공개 URL).
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

# 환경 변수(기본 계정)

환경 변수를 선호한다면 Gateway 호스트에 다음을 설정하세요.

• MATTERMOST_BOT_TOKEN=...
• MATTERMOST_URL=https://chat.example.com

# 채팅 모드

Mattermost는 DM에 자동으로 응답합니다. 채널 동작은 chatmode로 제어됩니다.

구성 예시:

{
  channels: {
    mattermost: {
      chatmode: "onchar",
      oncharPrefixes: [">", "!"],
    },
  },
}

참고:

• onchar는 명시적 @멘션에도 계속 응답합니다.
• channels.mattermost.requireMention은 레거시 구성에서 존중되지만 chatmode가 권장됩니다.

# 스레드와 세션

channels.mattermost.replyToMode를 사용하여 채널 및 그룹 응답이 기본 채널에 유지될지, 트리거한 게시물 아래의 스레드를 시작할지 제어합니다.

• off(기본값): 인바운드 게시물이 이미 스레드 안에 있는 경우에만 스레드에 답글을 답니다.
• first: 최상위 채널/그룹 게시물의 경우 해당 게시물 아래에 스레드를 시작하고 대화를 스레드 범위 세션으로 라우팅합니다.
• all: 현재 Mattermost에서는 first와 동일한 동작입니다.
• Direct messages는 이 설정을 무시하고 스레드 없이 유지됩니다.

구성 예시:

{
  channels: {
    mattermost: {
      replyToMode: "all",
    },
  },
}

참고:

• 스레드 범위 세션은 트리거한 게시물 ID를 스레드 루트로 사용합니다.
• Mattermost에 스레드 루트가 생기면 후속 청크와 미디어가 같은 스레드에서 계속되므로 현재 first와 all은 동일합니다.

# 액세스 제어(DM)

• 기본값: channels.mattermost.dmPolicy = "pairing"(알 수 없는 발신자는 페어링 코드를 받음).
• 다음으로 승인:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• 공개 DM: channels.mattermost.dmPolicy="open" 및 channels.mattermost.allowFrom=["*"].

# 채널(그룹)

• 기본값: channels.mattermost.groupPolicy = "allowlist"(멘션 게이트 적용).
• channels.mattermost.groupAllowFrom으로 발신자를 허용 목록에 추가합니다(사용자 ID 권장).
• 채널별 멘션 재정의는 channels.mattermost.groups.<channelId>.requireMention 아래에 두거나, 기본값의 경우 channels.mattermost.groups["*"].requireMention 아래에 둡니다.
• @username 일치는 변경 가능하며 channels.mattermost.dangerouslyAllowNameMatching: true일 때만 활성화됩니다.
• 열린 채널: channels.mattermost.groupPolicy="open"(멘션 게이트 적용).
• 런타임 참고: channels.mattermost가 완전히 누락된 경우 런타임은 그룹 검사에 대해 groupPolicy="allowlist"로 대체합니다(channels.defaults.groupPolicy가 설정되어 있어도).

예시:

{
  channels: {
    mattermost: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
    },
  },
}

# 아웃바운드 전달 대상

openclaw message send 또는 cron/webhook에서 다음 대상 형식을 사용하세요.

• channel:<id>: 채널
• user:<id>: DM
• @username: DM(Mattermost API를 통해 확인됨)

# DM 채널 재시도

OpenClaw가 Mattermost DM 대상에 전송하면서 먼저 다이렉트 채널을 확인해야 하는 경우, 기본적으로 일시적인 다이렉트 채널 생성 실패를 재시도합니다.

Mattermost Plugin 전체에 대해 이 동작을 조정하려면 channels.mattermost.dmChannelRetry를 사용하고, 한 계정에 대해서는 channels.mattermost.accounts.<id>.dmChannelRetry를 사용하세요.

{
  channels: {
    mattermost: {
      dmChannelRetry: {
        maxRetries: 3,
        initialDelayMs: 1000,
        maxDelayMs: 10000,
        timeoutMs: 30000,
      },
    },
  },
}

참고:

• 이는 모든 Mattermost API 호출이 아니라 DM 채널 생성(/api/v4/channels/direct)에만 적용됩니다.
• 재시도는 속도 제한, 5xx 응답, 네트워크 또는 시간 초과 오류와 같은 일시적 실패에 적용됩니다.
• 429 이외의 4xx 클라이언트 오류는 영구 오류로 처리되어 재시도되지 않습니다.

# 미리보기 스트리밍

Mattermost는 사고 과정, 도구 활동, 부분 답글 텍스트를 단일 초안 미리보기 게시물로 스트리밍하며, 최종 답변을 안전하게 보낼 수 있을 때 제자리에서 최종화합니다. 미리보기는 채널에 청크별 메시지를 반복해서 보내는 대신 같은 게시물 ID에서 업데이트됩니다. 미디어/오류 최종 응답은 대기 중인 미리보기 편집을 취소하고 일회성 미리보기 게시물을 플러시하는 대신 일반 전달을 사용합니다.

channels.mattermost.streaming으로 활성화:

{
  channels: {
    mattermost: {
      streaming: "partial", // off | partial | block | progress
    },
  },
}

# 반응(메시지 도구)

• message action=react를 channel=mattermost와 함께 사용합니다.
• messageId는 Mattermost 게시물 ID입니다.
• emoji는 thumbsup 또는 :+1: 같은 이름을 허용합니다(콜론은 선택 사항).
• 반응을 제거하려면 remove=true(부울)를 설정합니다.
• 반응 추가/제거 이벤트는 라우팅된 에이전트 세션에 시스템 이벤트로 전달됩니다.

예시:

message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true

구성:

• channels.mattermost.actions.reactions: 반응 동작을 활성화/비활성화합니다(기본값 true).
• 계정별 재정의: channels.mattermost.accounts.<id>.actions.reactions.

# 대화형 버튼(메시지 도구)

클릭 가능한 버튼이 있는 메시지를 보냅니다. 사용자가 버튼을 클릭하면 에이전트가 선택 내용을 받고 응답할 수 있습니다.

채널 기능에 inlineButtons를 추가하여 버튼을 활성화하세요.

{
  channels: {
    mattermost: {
      capabilities: ["inlineButtons"],
    },
  },
}

buttons 매개변수와 함께 message action=send를 사용합니다. 버튼은 2D 배열(버튼 행)입니다.

message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]

버튼 필드:

사용자가 버튼을 클릭하면:

# 직접 API 통합(외부 스크립트)

외부 스크립트와 Webhook은 에이전트의 message 도구를 거치지 않고 Mattermost REST API를 통해 버튼을 직접 게시할 수 있습니다. 가능하면 Plugin의 buildButtonAttachments()를 사용하세요. 원시 JSON을 게시하는 경우 다음 규칙을 따르세요:

페이로드 구조:

{
  channel_id: "<channelId>",
  message: "Choose an option:",
  props: {
    attachments: [
      {
        actions: [
          {
            id: "mybutton01", // alphanumeric only - see below
            type: "button", // required, or clicks are silently ignored
            name: "Approve", // display label
            style: "primary", // optional: "default", "primary", "danger"
            integration: {
              url: "https://gateway.example.com/mattermost/interactions/default",
              context: {
                action_id: "mybutton01", // must match button id (for name lookup)
                action: "approve",
                // ... any custom fields ...
                _token: "<hmac>", // see HMAC section below
              },
            },
          },
        ],
      },
    ],
  },
}

HMAC 토큰 생성

Gateway는 HMAC-SHA256으로 버튼 클릭을 검증합니다. 외부 스크립트는 Gateway의 검증 로직과 일치하는 토큰을 생성해야 합니다:

Python 예시:

secret = hmac.new(
    b"openclaw-mattermost-interactions",
    bot_token.encode(), hashlib.sha256
).hexdigest()

ctx = {"action_id": "mybutton01", "action": "approve"}
payload = json.dumps(ctx, sort_keys=True, separators=(",", ":"))
token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

context = {**ctx, "_token": token}

# 디렉터리 어댑터

Mattermost Plugin에는 Mattermost API를 통해 채널 및 사용자 이름을 확인하는 디렉터리 어댑터가 포함되어 있습니다. 이를 통해 openclaw message send 및 Cron/Webhook 전달에서 #channel-name 및 @username 대상을 사용할 수 있습니다.

설정은 필요하지 않습니다. 어댑터는 계정 설정의 봇 토큰을 사용합니다.

# 다중 계정

Mattermost는 channels.mattermost.accounts 아래에서 여러 계정을 지원합니다:

{
  channels: {
    mattermost: {
      accounts: {
        default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
        alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
      },
    },
  },
}

# 문제 해결

# 관련 항목

• 채널 라우팅 - 메시지에 대한 세션 라우팅
• 채널 개요 - 지원되는 모든 채널
• 그룹 - 그룹 채팅 동작 및 멘션 게이팅
• 페어링 - DM 인증 및 페어링 흐름
• 보안 - 접근 모델 및 강화