구성 — 채널

​

채널

​

DM 및 그룹 접근

​

채널 모델 재정의

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-5.5",
        "user:U12345": "openai/gpt-5.4-mini",
      },
      telegram: {
        "-1001234567890": "openai/gpt-5.4-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
        "123456789": "openai/gpt-4.1",
      },
    },
  },
}

​

채널 기본값 및 Heartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: 제공자 수준의 groupPolicy가 설정되지 않았을 때의 폴백 그룹 정책입니다.
• channels.defaults.contextVisibility: 모든 채널의 기본 보조 컨텍스트 표시 모드입니다. 값: all(기본값, 모든 인용/스레드/기록 컨텍스트 포함), allowlist(허용 목록의 발신자 컨텍스트만 포함), allowlist_quote(allowlist와 같지만 명시적 인용/답글 컨텍스트 유지). 채널별 재정의: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: 정상 채널 상태를 Heartbeat 출력에 포함합니다.
• channels.defaults.heartbeat.showAlerts: 성능 저하/오류 상태를 Heartbeat 출력에 포함합니다.
• channels.defaults.heartbeat.useIndicator: 간결한 표시기 스타일의 Heartbeat 출력을 렌더링합니다.

​

WhatsApp

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    whatsapp: {
      keepAliveIntervalMs: 25000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

• type: "acp"가 있는 최상위 bindings[] 항목은 WhatsApp DM 및 그룹에 대한 영구 ACP 바인딩을 구성합니다. match.peer.id에는 E.164 다이렉트 번호 또는 WhatsApp 그룹 JID를 사용하세요. 필드 의미는 ACP 에이전트에서 공유됩니다.

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: partial)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      apiRoot: "https://api.telegram.org",
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• 봇 토큰: channels.telegram.botToken 또는 channels.telegram.tokenFile(일반 파일만 허용, 심볼릭 링크는 거부됨)이며, 기본 계정의 폴백으로 TELEGRAM_BOT_TOKEN을 사용합니다.
• apiRoot는 Telegram Bot API 루트만 의미합니다. https://api.telegram.org/bot<TOKEN>이 아니라 https://api.telegram.org 또는 자체 호스팅/프록시 루트를 사용하세요. openclaw doctor --fix는 실수로 붙은 후행 /bot<TOKEN> 접미사를 제거합니다.
• 선택적 channels.telegram.defaultAccount는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다.
• 다중 계정 설정(계정 ID 2개 이상)에서는 폴백 라우팅을 피하기 위해 명시적 기본값(channels.telegram.defaultAccount 또는 channels.telegram.accounts.default)을 설정하세요. 이것이 없거나 유효하지 않으면 openclaw doctor가 경고합니다.
• configWrites: false는 Telegram에서 시작된 구성 쓰기(슈퍼그룹 ID 마이그레이션, /config set|unset)를 차단합니다.
• type: "acp"가 있는 최상위 bindings[] 항목은 포럼 토픽에 대한 영구 ACP 바인딩을 구성합니다(match.peer.id에 정식 chatId:topic:topicId 사용). 필드 의미는 ACP 에이전트에서 공유됩니다.
• Telegram 스트림 미리보기는 sendMessage + editMessageText를 사용합니다(다이렉트 및 그룹 채팅에서 작동).
• 재시도 정책: 재시도 정책을 참조하세요.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      suppressEmbeds: true,
      chunkMode: "length", // length | newline
      streaming: {
        mode: "progress", // off | partial | block | progress (Discord default: progress)
        progress: {
          label: "auto",
          maxLines: 8,
          maxLineChars: 120,
          toolProgress: true,
        },
      },
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• 토큰: channels.discord.token, 기본 계정의 대체값으로 DISCORD_BOT_TOKEN을 사용합니다.
• 명시적인 Discord token을 제공하는 직접 아웃바운드 호출은 해당 호출에 그 토큰을 사용합니다. 계정 재시도/정책 설정은 여전히 활성 런타임 스냅샷에서 선택된 계정에서 가져옵니다.
• 선택 사항인 channels.discord.defaultAccount는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다.
• 전달 대상에는 user:<id>(DM) 또는 channel:<id>(길드 채널)를 사용합니다. 숫자 ID만 단독으로 쓰면 거부됩니다.
• 길드 슬러그는 소문자이며 공백은 -로 바뀝니다. 채널 키는 슬러그화된 이름을 사용합니다(# 없음). 길드 ID 사용을 권장합니다.
• 봇이 작성한 메시지는 기본적으로 무시됩니다. allowBots: true로 활성화할 수 있습니다. 봇을 멘션하는 봇 메시지만 허용하려면 allowBots: "mentions"를 사용합니다(자체 메시지는 계속 필터링됨).
• 봇 작성 인바운드 메시지를 지원하는 채널은 공유 봇 루프 보호를 사용할 수 있습니다. 기준 쌍 예산에는 channels.defaults.botLoopProtection을 설정하고, 한 표면에 다른 제한이 필요할 때만 채널 또는 계정을 재정의합니다.
• channels.discord.guilds.<id>.ignoreOtherMentions(및 채널 재정의)는 다른 사용자나 역할을 멘션하지만 봇은 멘션하지 않는 메시지를 드롭합니다(@everyone/@here 제외).
• channels.discord.mentionAliases는 전송 전에 안정적인 아웃바운드 @handle 텍스트를 Discord 사용자 ID에 매핑하므로, 임시 디렉터리 캐시가 비어 있어도 알려진 팀원을 결정적으로 멘션할 수 있습니다. 계정별 재정의는 channels.discord.accounts.<accountId>.mentionAliases 아래에 있습니다.
• maxLinesPerMessage(기본값 17)는 2000자 미만이어도 긴 메시지를 분할합니다.
• channels.discord.suppressEmbeds의 기본값은 true이므로, 비활성화하지 않는 한 아웃바운드 URL은 Discord 링크 미리보기로 확장되지 않습니다. 명시적인 embeds 페이로드는 계속 정상적으로 전송됩니다. 메시지별 도구 호출은 suppressEmbeds로 재정의할 수 있습니다.
• channels.discord.threadBindings는 Discord 스레드 바인딩 라우팅을 제어합니다.
  • enabled: 스레드 바인딩 세션 기능(/focus, /unfocus, /agents, /session idle, /session max-age, 바인딩된 전달/라우팅)에 대한 Discord 재정의
  • idleHours: 비활성 상태 자동 언포커스 시간 단위 Discord 재정의(0은 비활성화)
  • maxAgeHours: 하드 최대 수명 시간 단위 Discord 재정의(0은 비활성화)
  • spawnSessions: sessions_spawn({ thread: true }) 및 ACP 스레드 스폰 자동 스레드 생성/바인딩 스위치(기본값: true)
  • defaultSpawnContext: 스레드 바인딩 스폰의 네이티브 서브에이전트 컨텍스트(기본값 "fork")
• type: "acp"가 있는 최상위 bindings[] 항목은 채널과 스레드에 대한 영구 ACP 바인딩을 구성합니다(match.peer.id에 채널/스레드 ID 사용). 필드 의미는 ACP 에이전트에서 공유됩니다.
• channels.discord.ui.components.accentColor는 Discord 컴포넌트 v2 컨테이너의 강조 색상을 설정합니다.
• channels.discord.agentComponents.ttlMs는 전송된 Discord 컴포넌트 콜백이 등록 상태로 유지되는 시간을 제어합니다. 기본값은 1800000(30분), 최대값은 86400000(24시간)이며, 계정별 재정의는 channels.discord.accounts.<accountId>.agentComponents.ttlMs 아래에 있습니다. 값이 길수록 오래된 버튼/선택/폼을 더 오래 사용할 수 있으므로, 워크플로에 맞는 가장 짧은 TTL을 권장합니다.
• channels.discord.voice는 Discord 음성 채널 대화와 선택적 자동 참여 + LLM + TTS 재정의를 활성화합니다. 텍스트 전용 Discord 구성은 기본적으로 음성을 끕니다. 사용하려면 channels.discord.voice.enabled=true를 설정합니다.
• channels.discord.voice.model은 Discord 음성 채널 응답에 사용되는 LLM 모델을 선택적으로 재정의합니다.
• channels.discord.voice.daveEncryption 및 channels.discord.voice.decryptionFailureTolerance는 @discordjs/voice DAVE 옵션으로 그대로 전달됩니다(기본값은 true 및 24).
• channels.discord.voice.connectTimeoutMs는 /vc join 및 자동 참여 시도에서 초기 @discordjs/voice Ready 대기를 제어합니다(기본값 30000).
• channels.discord.voice.reconnectGraceMs는 연결이 끊긴 음성 세션이 OpenClaw에 의해 파기되기 전 재연결 신호 상태로 진입하는 데 걸릴 수 있는 시간을 제어합니다(기본값 15000).
• Discord 음성 재생은 다른 사용자의 말하기 시작 이벤트로 중단되지 않습니다. 피드백 루프를 피하기 위해 OpenClaw는 TTS 재생 중 새 음성 캡처를 무시합니다.
• 또한 OpenClaw는 반복적인 복호화 실패 후 음성 세션을 나갔다가 다시 참여하는 방식으로 음성 수신 복구를 시도합니다.
• channels.discord.streaming은 표준 스트림 모드 키입니다. Discord 기본값은 streaming.mode: "progress"이므로 도구/작업 진행 상황이 하나의 편집된 미리보기 메시지에 표시됩니다. 비활성화하려면 streaming.mode: "off"를 설정합니다. 레거시 streamMode 및 불리언 streaming 값은 런타임 별칭으로 남아 있습니다. 저장된 구성을 다시 쓰려면 openclaw doctor --fix를 실행합니다.
• channels.discord.autoPresence는 런타임 가용성을 봇 프레즌스에 매핑하고(healthy => online, degraded => idle, exhausted => dnd) 선택적 상태 텍스트 재정의를 허용합니다.
• channels.discord.dangerouslyAllowNameMatching은 변경 가능한 이름/태그 매칭을 다시 활성화합니다(비상 호환성 모드).
• channels.discord.execApprovals: Discord 네이티브 exec 승인 전달 및 승인자 권한 부여입니다.
  • enabled: true, false 또는 "auto"(기본값). 자동 모드에서는 approvers 또는 commands.ownerAllowFrom에서 승인자를 해석할 수 있을 때 exec 승인이 활성화됩니다.
  • approvers: exec 요청을 승인할 수 있는 Discord 사용자 ID입니다. 생략하면 commands.ownerAllowFrom으로 대체됩니다.
  • agentFilter: 선택적 에이전트 ID 허용 목록입니다. 생략하면 모든 에이전트의 승인을 전달합니다.
  • sessionFilter: 선택적 세션 키 패턴(부분 문자열 또는 정규식)입니다.
  • target: 승인 프롬프트를 보낼 위치입니다. "dm"(기본값)은 승인자 DM으로 보내고, "channel"은 원본 채널로 보내며, "both"는 둘 다로 보냅니다. 대상에 "channel"이 포함된 경우 버튼은 해석된 승인자만 사용할 수 있습니다.
  • cleanupAfterResolve: true이면 승인, 거부 또는 시간 초과 후 승인 DM을 삭제합니다.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• 서비스 계정 JSON: 인라인(serviceAccount) 또는 파일 기반(serviceAccountFile)입니다.
• 서비스 계정 SecretRef도 지원됩니다(serviceAccountRef).
• 환경 변수 대체값: GOOGLE_CHAT_SERVICE_ACCOUNT 또는 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• 전달 대상에는 spaces/<spaceId> 또는 users/<userId>를 사용합니다.
• channels.googlechat.dangerouslyAllowNameMatching은 변경 가능한 이메일 주체 매칭을 다시 활성화합니다(비상 호환성 모드).

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      socketMode: {
        clientPingTimeout: 15000,
        serverPingTimeout: 30000,
        pingPongLoggingEnabled: false,
      },
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      unfurlLinks: false,
      unfurlMedia: false,
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // use Slack native streaming API when mode=partial
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• 소켓 모드에는 botToken과 appToken이 모두 필요합니다(기본 계정 env 폴백의 경우 SLACK_BOT_TOKEN + SLACK_APP_TOKEN).
• HTTP 모드에는 botToken과 signingSecret(루트 또는 계정별)이 필요합니다.
• socketMode는 Slack SDK Socket Mode 전송 튜닝을 공개 Bolt receiver API로 전달합니다. ping/pong 시간 초과 또는 오래된 websocket 동작을 조사할 때만 사용하세요. clientPingTimeout의 기본값은 15000이며, serverPingTimeout과 pingPongLoggingEnabled는 구성된 경우에만 전달됩니다.
• botToken, appToken, signingSecret, userToken은 일반 텍스트 문자열 또는 SecretRef 객체를 허용합니다.
• Slack 계정 스냅샷은 botTokenSource, botTokenStatus, appTokenStatus 및 HTTP 모드의 signingSecretStatus와 같은 자격 증명별 소스/상태 필드를 노출합니다. configured_unavailable은 계정이 SecretRef를 통해 구성되었지만 현재 명령/runtime 경로가 secret 값을 확인할 수 없었음을 의미합니다.
• configWrites: false는 Slack에서 시작된 config 쓰기를 차단합니다.
• 선택 사항인 channels.slack.defaultAccount는 구성된 계정 id와 일치할 때 기본 계정 선택을 재정의합니다.
• channels.slack.streaming.mode는 정식 Slack 스트림 모드 키입니다. channels.slack.streaming.nativeTransport는 Slack의 native streaming transport를 제어합니다. 레거시 streamMode, boolean streaming, nativeStreaming 값은 runtime alias로 유지됩니다. 저장된 config를 다시 쓰려면 openclaw doctor --fix를 실행하세요.
• unfurlLinks와 unfurlMedia는 봇 응답에 대해 Slack의 chat.postMessage 링크 및 미디어 unfurl boolean을 전달합니다. unfurlLinks의 기본값은 false이므로 활성화하지 않는 한 아웃바운드 봇 링크가 인라인으로 확장되지 않습니다. unfurlMedia는 구성하지 않는 한 생략됩니다. 한 계정에 대해 최상위 값을 재정의하려면 channels.slack.accounts.<accountId>에서 어느 값이든 설정하세요.
• 전달 대상에는 user:<id>(DM) 또는 channel:<id>를 사용하세요.

• Slack native streaming과 Slack assistant 스타일의 “is typing…” 스레드 상태에는 응답 스레드 대상이 필요합니다. 최상위 DM은 기본적으로 스레드 밖에 유지되므로 스레드 스타일의 native stream/status 미리보기를 표시하는 대신 Slack draft post-and-edit 미리보기를 통해 계속 스트리밍할 수 있습니다.
• typingReaction은 응답이 실행되는 동안 인바운드 Slack 메시지에 임시 반응을 추가한 뒤 완료 시 제거합니다. "hourglass_flowing_sand"와 같은 Slack emoji shortcode를 사용하세요.
• channels.slack.execApprovals: Slack native approval-client 전달 및 exec 승인자 권한 부여입니다. Discord와 동일한 schema를 사용합니다. enabled(true/false/"auto"), approvers(Slack 사용자 ID), agentFilter, sessionFilter, target("dm", "channel" 또는 "both"). Plugin approval은 Slack plugin 승인자가 확인되는 경우 Slack-origin 요청에 이 native-client 경로를 사용할 수 있습니다. Slack-native plugin approval 전달은 Slack-origin 세션 또는 Slack 대상에 대해 approvals.plugin을 통해서도 활성화할 수 있습니다. Plugin approval은 exec 승인자가 아니라 allowFrom의 Slack plugin 승인자와 기본 routing을 사용합니다.

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• commands.callbackPath는 전체 URL이 아니라 경로여야 합니다(예: /api/channels/mattermost/command).
• commands.callbackUrl은 OpenClaw gateway endpoint로 확인되어야 하며 Mattermost 서버에서 접근할 수 있어야 합니다.
• Native slash callback은 slash command 등록 중 Mattermost가 반환한 명령별 토큰으로 인증됩니다. 등록이 실패하거나 활성화된 명령이 없으면 OpenClaw는 Unauthorized: invalid command token.으로 callback을 거부합니다.
• 비공개/tailnet/internal callback 호스트의 경우 Mattermost는 ServiceSettings.AllowedUntrustedInternalConnections에 callback host/domain을 포함하도록 요구할 수 있습니다. 전체 URL이 아니라 host/domain 값을 사용하세요.
• channels.mattermost.configWrites: Mattermost에서 시작된 config 쓰기를 허용하거나 거부합니다.
• channels.mattermost.requireMention: 채널에서 응답하기 전에 @mention을 요구합니다.
• channels.mattermost.groups.<channelId>.requireMention: 채널별 mention-gating 재정의(기본값은 "*").
• 선택 사항인 channels.mattermost.defaultAccount는 구성된 계정 id와 일치할 때 기본 계정 선택을 재정의합니다.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account: 채널 시작을 특정 Signal 계정 ID에 고정합니다.
• channels.signal.configWrites: Signal에서 시작된 config 쓰기를 허용하거나 거부합니다.
• 선택 사항인 channels.signal.defaultAccount는 구성된 계정 id와 일치할 때 기본 계정 선택을 재정의합니다.

​

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      sendTransport: "auto",
      region: "US",
      actions: {
        reactions: true,
        edit: true,
        unsend: true,
        reply: true,
        sendWithEffect: true,
        sendAttachment: true,
      },
    },
  },
}

• 선택 사항인 channels.imessage.defaultAccount는 구성된 계정 id와 일치할 때 기본 계정 선택을 재정의합니다.
• Messages DB에 대한 전체 디스크 접근 권한이 필요합니다.
• chat_id:<id> 대상을 권장합니다. 채팅 목록을 보려면 imsg chats --limit 20을 사용하세요.
• cliPath는 SSH wrapper를 가리킬 수 있습니다. SCP attachment 가져오기를 위해 remoteHost(host 또는 user@host)를 설정하세요.
• attachmentRoots와 remoteAttachmentRoots는 인바운드 attachment 경로를 제한합니다(기본값: /Users/*/Library/Messages/Attachments).
• SCP는 엄격한 host-key checking을 사용하므로 relay host key가 이미 ~/.ssh/known_hosts에 있는지 확인하세요.
• channels.imessage.configWrites: iMessage에서 시작된 config 쓰기를 허용하거나 거부합니다.
• channels.imessage.sendTransport: 일반 아웃바운드 응답에 선호되는 imsg RPC 전송 transport입니다. auto(기본값)는 실행 중인 경우 기존 채팅에 IMCore bridge를 사용한 다음 AppleScript로 폴백합니다. bridge는 private-API 전달이 필요합니다. applescript는 공개 Messages automation 경로를 강제합니다.
• channels.imessage.actions.*: imsg status / openclaw channels status --probe로도 제어되는 private API 작업을 활성화합니다.
• channels.imessage.includeAttachments는 기본적으로 꺼져 있습니다. agent turn에서 인바운드 media를 기대하기 전에 true로 설정하세요.
• bridge/gateway 재시작 후 인바운드 복구는 자동입니다(GUID dedupe와 stale-backlog age fence). 기존 channels.imessage.catchup.enabled: true config는 deprecated compatibility profile로 계속 존중됩니다.
• channels.imessage.groups: 그룹 registry 및 그룹별 설정입니다. groupPolicy: "allowlist"를 사용할 때는 그룹 메시지가 registry gate를 통과할 수 있도록 명시적 chat_id 키 또는 "*" wildcard entry를 구성하세요.
• type: "acp"가 있는 최상위 bindings[] entry는 iMessage 대화를 지속 ACP 세션에 bind할 수 있습니다. match.peer.id에는 정규화된 handle 또는 명시적 채팅 대상(chat_id:*, chat_guid:*, chat_identifier:*)을 사용하세요. 공유 필드 semantics: ACP Agents.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• 토큰 인증은 accessToken을 사용하고, 비밀번호 인증은 userId + password를 사용합니다.
• channels.matrix.proxy는 명시적 HTTP(S) 프록시를 통해 Matrix HTTP 트래픽을 라우팅합니다. 명명된 계정은 channels.matrix.accounts.<id>.proxy로 이를 재정의할 수 있습니다.
• channels.matrix.network.dangerouslyAllowPrivateNetwork는 비공개/내부 홈서버를 허용합니다. proxy와 이 네트워크 옵트인은 서로 독립적인 제어 항목입니다.
• channels.matrix.defaultAccount는 다중 계정 설정에서 선호 계정을 선택합니다.
• channels.matrix.autoJoin의 기본값은 off이므로, autoJoinAllowlist와 함께 autoJoin: "allowlist"를 설정하거나 autoJoin: "always"를 설정하기 전까지 초대된 방과 새 DM 스타일 초대는 무시됩니다.
• channels.matrix.execApprovals: Matrix 네이티브 exec 승인 전달 및 승인자 권한 부여.
  • enabled: true, false 또는 "auto"(기본값). 자동 모드에서는 approvers 또는 commands.ownerAllowFrom에서 승인자를 확인할 수 있을 때 exec 승인이 활성화됩니다.
  • approvers: exec 요청을 승인할 수 있는 Matrix 사용자 ID(예: @owner:example.org).
  • agentFilter: 선택적 agent ID 허용 목록. 생략하면 모든 agent의 승인을 전달합니다.
  • sessionFilter: 선택적 세션 키 패턴(부분 문자열 또는 정규식).
  • target: 승인 프롬프트를 보낼 위치. "dm"(기본값), "channel"(원본 방) 또는 "both".
  • 계정별 재정의: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope는 Matrix DM이 세션으로 그룹화되는 방식을 제어합니다. per-user(기본값)는 라우팅된 피어 기준으로 공유하고, per-room은 각 DM 방을 격리합니다.
• Matrix 상태 프로브와 라이브 디렉터리 조회는 런타임 트래픽과 동일한 프록시 정책을 사용합니다.
• 전체 Matrix 구성, 대상 지정 규칙, 설정 예시는 Matrix에 문서화되어 있습니다.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

• 여기에서 다루는 핵심 키 경로: channels.msteams, channels.msteams.configWrites.
• 전체 Teams 구성(자격 증명, Webhook, DM/그룹 정책, 팀별/채널별 재정의)은 Microsoft Teams에 문서화되어 있습니다.

​

IRC

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• 여기에서 다루는 핵심 키 경로: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• 선택적 channels.irc.defaultAccount는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다.
• 전체 IRC 채널 구성(호스트/포트/TLS/채널/허용 목록/멘션 게이팅)은 IRC에 문서화되어 있습니다.

​

다중 계정(모든 채널)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• accountId가 생략되면 default가 사용됩니다(CLI + 라우팅).
• Env 토큰은 기본 계정에만 적용됩니다.
• 기본 채널 설정은 계정별로 재정의하지 않는 한 모든 계정에 적용됩니다.
• bindings[].match.accountId를 사용해 각 계정을 다른 agent로 라우팅합니다.
• 단일 계정 최상위 채널 구성 상태에서 openclaw channels add(또는 채널 온보딩)를 통해 기본값이 아닌 계정을 추가하면, OpenClaw는 먼저 계정 범위의 최상위 단일 계정 값을 채널 계정 맵으로 승격하여 원래 계정이 계속 작동하게 합니다. 대부분의 채널은 이를 channels.<channel>.accounts.default로 이동합니다. Matrix는 기존의 일치하는 명명/기본 대상을 대신 보존할 수 있습니다.
• 기존 채널 전용 바인딩(accountId 없음)은 기본 계정과 계속 일치합니다. 계정 범위 바인딩은 계속 선택 사항입니다.
• openclaw doctor --fix도 계정 범위의 최상위 단일 계정 값을 해당 채널에 대해 선택된 승격 계정으로 이동하여 혼합 형태를 복구합니다. 대부분의 채널은 accounts.default를 사용합니다. Matrix는 기존의 일치하는 명명/기본 대상을 대신 보존할 수 있습니다.

​

기타 Plugin 채널

​

그룹 채팅 멘션 게이팅

• 메타데이터 멘션: 네이티브 플랫폼 @-멘션. WhatsApp 셀프 채팅 모드에서는 무시됩니다.
• 텍스트 패턴: agents.list[].groupChat.mentionPatterns의 안전한 정규식 패턴. 잘못된 패턴과 안전하지 않은 중첩 반복은 무시됩니다.
• 멘션 게이팅은 감지가 가능할 때만 적용됩니다(네이티브 멘션 또는 하나 이상의 패턴).

{
  messages: {
    visibleReplies: "automatic", // force old automatic final replies for direct/source chats
    groupChat: {
      historyLimit: 50,
      unmentionedInbound: "room_event", // always-on unmentioned room chatter becomes quiet context
      visibleReplies: "message_tool", // opt-in; require message(action=send) for visible room replies
    },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

​

DM 기록 제한

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

셀프 채팅 모드

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

명령(채팅 명령 처리)

{
  commands: {
    native: "auto", // register native commands when supported
    nativeSkills: "auto", // register native skill commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    mcp: false, // allow /mcp
    plugins: false, // allow /plugins
    debug: false, // allow /debug
    restart: true, // allow /restart + gateway restart tool
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

관련 항목

• 구성 참조 — 최상위 키
• 구성 — 에이전트
• 채널 개요