구성 — 채널

channels.* 아래의 채널별 구성 키입니다. DM 및 그룹 접근, 다중 계정 설정, 멘션 게이팅, Slack, Discord, Telegram, WhatsApp, Matrix, iMessage 및 기타 번들 채널 Plugin의 채널별 키를 다룹니다. 에이전트, 도구, Gateway 런타임 및 기타 최상위 키는 구성 참조를 참조하세요.

채널

각 채널은 해당 구성 섹션이 있으면 자동으로 시작됩니다(enabled: false인 경우 제외).

DM 및 그룹 접근

모든 채널은 DM 정책과 그룹 정책을 지원합니다.

DM 정책	동작
`pairing` (기본값)	알 수 없는 발신자는 일회성 페어링 코드를 받으며, 소유자가 승인해야 함
`allowlist`	`allowFrom`에 있는 발신자만 허용(또는 페어링된 허용 저장소)
`open`	모든 인바운드 DM 허용(`allowFrom: ["*"]` 필요)
`disabled`	모든 인바운드 DM 무시

그룹 정책	동작
`allowlist` (기본값)	구성된 허용 목록과 일치하는 그룹만 허용
`open`	그룹 허용 목록 우회(멘션 게이팅은 계속 적용됨)
`disabled`	모든 그룹/룸 메시지 차단

channels.defaults.groupPolicy는 제공자의 groupPolicy가 설정되지 않았을 때 기본값을 설정합니다. 페어링 코드는 1시간 후 만료됩니다. 대기 중인 DM 페어링 요청은 채널당 3개로 제한됩니다. 제공자 블록이 완전히 없으면(channels.<provider> 없음), 런타임 그룹 정책은 시작 경고와 함께 allowlist(fail-closed)로 대체됩니다.

채널 모델 재정의

특정 채널 ID를 모델에 고정하려면 channels.modelByChannel을 사용하세요. 값은 provider/model 또는 구성된 모델 별칭을 허용합니다. 채널 매핑은 세션에 이미 모델 재정의가 없을 때 적용됩니다(예: /model로 설정한 경우).

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

채널 기본값 및 Heartbeat

제공자 전반에 걸친 공유 그룹 정책 및 Heartbeat 동작에는 channels.defaults를 사용하세요.

{
  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(허용 목록과 같지만 명시적 인용/답장 컨텍스트 유지). 채널별 재정의: channels.<channel>.contextVisibility.
channels.defaults.heartbeat.showOk: Heartbeat 출력에 정상 채널 상태를 포함합니다.
channels.defaults.heartbeat.showAlerts: Heartbeat 출력에 저하/오류 상태를 포함합니다.
channels.defaults.heartbeat.useIndicator: 압축된 표시기 스타일 Heartbeat 출력을 렌더링합니다.

WhatsApp은 Gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결된 세션이 있으면 자동으로 시작됩니다.

{
  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"],
    },
  },
}

다중 계정 WhatsApp

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

아웃바운드 명령은 계정 default가 있으면 기본적으로 해당 계정을 사용하고, 없으면 처음 구성된 계정 ID(정렬 기준)를 사용합니다.
선택 사항인 channels.whatsapp.defaultAccount는 구성된 계정 ID와 일치할 때 해당 대체 기본 계정 선택을 재정의합니다.
레거시 단일 계정 Baileys 인증 디렉터리는 openclaw doctor에 의해 whatsapp/default로 마이그레이션됩니다.
계정별 재정의: channels.whatsapp.accounts.<id>.sendReadReceipts, channels.whatsapp.accounts.<id>.dmPolicy, channels.whatsapp.accounts.<id>.allowFrom.

{
  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: off; opt in explicitly to avoid preview-edit rate limits)
      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,
      chunkMode: "length", // length | newline
      streaming: {
        mode: "progress", // off | partial | block | progress (Discord default: progress)
        progress: {
          label: "auto",
          maxLines: 8,
          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,
      },
    },
  },
}

토큰: 기본 계정의 fallback으로 DISCORD_BOT_TOKEN을 사용하는 channels.discord.token.
명시적 Discord token을 제공하는 직접 outbound 호출은 해당 호출에 그 토큰을 사용하며, 계정 재시도/정책 설정은 여전히 활성 런타임 snapshot에서 선택된 계정에서 가져옵니다.
선택 사항인 channels.discord.defaultAccount는 구성된 계정 id와 일치할 때 기본 계정 선택을 재정의합니다.
전달 대상에는 user:<id>(DM) 또는 channel:<id>(guild channel)를 사용하세요. 단독 숫자 ID는 거부됩니다.
Guild slug는 소문자이며 공백은 -로 대체됩니다. channel key는 slug 처리된 이름을 사용합니다(# 없음). guild ID를 권장합니다.
봇이 작성한 메시지는 기본적으로 무시됩니다. allowBots: true는 이를 활성화합니다. 봇을 mention하는 봇 메시지만 허용하려면 allowBots: "mentions"를 사용하세요(자신의 메시지는 계속 필터링됨).
channels.discord.guilds.<id>.ignoreOtherMentions(및 channel override)는 봇이 아닌 다른 사용자나 role을 mention하는 메시지를 드롭합니다(@everyone/@here 제외).
channels.discord.mentionAliases는 전송 전에 안정적인 outbound @handle 텍스트를 Discord 사용자 ID에 매핑하므로, 일시적 디렉터리 캐시가 비어 있어도 알려진 팀원을 결정론적으로 mention할 수 있습니다. 계정별 override는 channels.discord.accounts.<accountId>.mentionAliases 아래에 있습니다.
maxLinesPerMessage(기본값 17)는 2000자 미만이어도 긴 메시지를 분할합니다.
channels.discord.threadBindings는 Discord thread-bound 라우팅을 제어합니다.
- enabled: thread-bound 세션 기능(/focus, /unfocus, /agents, /session idle, /session max-age, bound 전달/라우팅)에 대한 Discord override
- idleHours: 비활성 auto-unfocus 시간 단위 Discord override(0은 비활성화)
- maxAgeHours: hard max age 시간 단위 Discord override(0은 비활성화)
- spawnSessions: sessions_spawn({ thread: true }) 및 ACP thread-spawn 자동 thread 생성/binding을 위한 switch(기본값: true)
- defaultSpawnContext: thread-bound spawn을 위한 native subagent context(기본값 "fork")
type: "acp"가 있는 최상위 bindings[] 항목은 channel 및 thread용 persistent ACP binding을 구성합니다(match.peer.id에 channel/thread id 사용). 필드 의미 체계는 ACP Agents에서 공유됩니다.
channels.discord.ui.components.accentColor는 Discord components v2 container의 accent color를 설정합니다.
channels.discord.voice는 Discord voice channel 대화와 선택적 auto-join + LLM + TTS override를 활성화합니다. 텍스트 전용 Discord config는 기본적으로 voice가 꺼져 있습니다. 사용하려면 channels.discord.voice.enabled=true를 설정하세요.
channels.discord.voice.model은 Discord voice channel 응답에 사용되는 LLM model을 선택적으로 재정의합니다.
channels.discord.voice.daveEncryption 및 channels.discord.voice.decryptionFailureTolerance는 @discordjs/voice DAVE option으로 전달됩니다(기본값은 true 및 24).
channels.discord.voice.connectTimeoutMs는 /vc join 및 auto-join 시도의 초기 @discordjs/voice Ready 대기를 제어합니다(기본값 30000).
channels.discord.voice.reconnectGraceMs는 연결이 끊긴 voice session이 OpenClaw가 이를 제거하기 전에 reconnect signalling에 진입할 수 있는 시간을 제어합니다(기본값 15000).
Discord voice playback은 다른 사용자의 speaking-start event로 중단되지 않습니다. feedback loop를 피하기 위해 OpenClaw는 TTS 재생 중 새 voice capture를 무시합니다.
OpenClaw는 반복되는 decrypt failure 후 voice session을 나갔다가 다시 참여하여 voice receive recovery도 시도합니다.
channels.discord.streaming은 canonical stream mode key입니다. Discord의 기본값은 streaming.mode: "progress"이므로 tool/work 진행 상황이 하나의 편집된 preview message에 표시됩니다. 비활성화하려면 streaming.mode: "off"를 설정하세요. 기존 streamMode 및 boolean streaming 값은 runtime alias로 남아 있습니다. 저장된 config를 다시 쓰려면 openclaw doctor --fix를 실행하세요.
channels.discord.autoPresence는 runtime availability를 bot presence에 매핑하고(healthy => online, degraded => idle, exhausted => dnd) 선택적 status text override를 허용합니다.
channels.discord.dangerouslyAllowNameMatching은 mutable name/tag matching을 다시 활성화합니다(break-glass compatibility mode).
channels.discord.execApprovals: Discord-native exec approval 전달 및 approver authorization.
- enabled: true, false 또는 "auto"(기본값). auto mode에서는 approvers 또는 commands.ownerAllowFrom에서 approver를 확인할 수 있을 때 exec approval이 활성화됩니다.
- approvers: exec request를 승인할 수 있는 Discord user ID. 생략하면 commands.ownerAllowFrom으로 fallback합니다.
- agentFilter: 선택적 agent ID allowlist. 모든 agent에 대한 approval을 forward하려면 생략하세요.
- sessionFilter: 선택적 session key pattern(substring 또는 regex).
- target: approval prompt를 보낼 위치. "dm"(기본값)은 approver DM으로 보내고, "channel"은 원본 channel로 보내며, "both"는 둘 다로 보냅니다. target에 "channel"이 포함되면 button은 확인된 approver만 사용할 수 있습니다.
- cleanupAfterResolve: true이면 approval, denial 또는 timeout 후 approval DM을 삭제합니다.

Reaction notification mode: off(없음), own(bot의 메시지, 기본값), all(모든 메시지), allowlist(모든 메시지에서 guilds.<id>.users 기준).

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: inline(serviceAccount) 또는 file-based(serviceAccountFile).
서비스 계정 SecretRef도 지원됩니다(serviceAccountRef).
Env fallback: GOOGLE_CHAT_SERVICE_ACCOUNT 또는 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
전달 대상에는 spaces/<spaceId> 또는 users/<userId>를 사용하세요.
channels.googlechat.dangerouslyAllowNameMatching은 mutable email principal matching을 다시 활성화합니다(break-glass compatibility mode).

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
      },
    },
  },
}

Socket mode에는 botToken과 appToken이 모두 필요합니다(기본 계정 env fallback은 SLACK_BOT_TOKEN + SLACK_APP_TOKEN).
HTTP mode에는 botToken과 signingSecret(root 또는 per-account)이 필요합니다.
socketMode는 Slack SDK Socket Mode transport tuning을 public Bolt receiver API로 전달합니다. ping/pong timeout 또는 stale websocket 동작을 조사할 때만 사용하세요.
botToken, appToken, signingSecret, userToken은 plaintext string 또는 SecretRef object를 허용합니다.
Slack account snapshot은 botTokenSource, botTokenStatus, appTokenStatus, HTTP mode의 signingSecretStatus 같은 credential별 source/status field를 노출합니다. configured_unavailable은 계정이 SecretRef를 통해 구성되었지만 현재 command/runtime path가 secret value를 resolve할 수 없었음을 의미합니다.
configWrites: false는 Slack에서 시작된 config write를 차단합니다.
선택 사항인 channels.slack.defaultAccount는 구성된 계정 id와 일치할 때 기본 계정 선택을 재정의합니다.
channels.slack.streaming.mode는 canonical Slack stream mode key입니다. channels.slack.streaming.nativeTransport는 Slack의 native streaming transport를 제어합니다. 기존 streamMode, boolean streaming, nativeStreaming 값은 runtime alias로 남아 있습니다. 저장된 config를 다시 쓰려면 openclaw doctor --fix를 실행하세요.
unfurlLinks와 unfurlMedia는 bot reply를 위해 Slack의 chat.postMessage link 및 media unfurl boolean을 전달합니다. Slack의 기본 동작을 유지하려면 생략하세요. 한 계정에 대해 최상위 기본값을 재정의하려면 channels.slack.accounts.<accountId>에 설정하세요.
전달 대상에는 user:<id>(DM) 또는 channel:<id>를 사용하세요.

Reaction notification mode: off, own(기본값), all, allowlist(reactionAllowlist 기준). Thread session isolation: thread.historyScope는 thread별(기본값)이거나 channel 전체에서 공유됩니다. thread.inheritParent는 parent channel transcript를 새 thread로 복사합니다.

Slack native streaming과 Slack assistant-style “is typing…” thread status에는 reply thread target이 필요합니다. 최상위 DM은 기본적으로 off-thread이므로 thread-style native stream/status preview를 표시하는 대신 Slack draft post-and-edit preview를 통해 계속 stream할 수 있습니다.
typingReaction은 reply가 실행되는 동안 inbound Slack message에 임시 reaction을 추가한 다음 완료 시 제거합니다. "hourglass_flowing_sand" 같은 Slack emoji shortcode를 사용하세요.
channels.slack.execApprovals: Slack-native exec approval 전달 및 approver authorization. Discord와 같은 schema입니다: enabled(true/false/"auto"), approvers(Slack user ID), agentFilter, sessionFilter, target("dm", "channel" 또는 "both").

Action group	기본값	참고
reactions	활성화됨	reaction 추가 + reaction 목록
messages	활성화됨	읽기/보내기/편집/삭제
pins	활성화됨	고정/고정 해제/목록
memberInfo	활성화됨	member 정보
emojiList	활성화됨	custom emoji 목록

Mattermost

Mattermost는 현재 OpenClaw 릴리스에서 bundled Plugin으로 제공됩니다. 이전 또는 custom build는 openclaw plugins install @openclaw/mattermost로 현재 npm package를 설치할 수 있습니다. version을 pin하기 전에 npmjs.com/package/@openclaw/mattermost에서 현재 dist-tag를 확인하세요.

{
  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",
    },
  },
}

채팅 모드: oncall(@-멘션 시 응답, 기본값), onmessage(모든 메시지), onchar(트리거 접두사로 시작하는 메시지). Mattermost 네이티브 명령이 활성화된 경우:

commands.callbackPath는 전체 URL이 아니라 경로여야 합니다(예: /api/channels/mattermost/command).
commands.callbackUrl은 OpenClaw Gateway 엔드포인트로 확인되어야 하며 Mattermost 서버에서 접근 가능해야 합니다.
네이티브 슬래시 콜백은 슬래시 명령 등록 중 Mattermost가 반환한 명령별 토큰으로 인증됩니다. 등록에 실패하거나 활성화된 명령이 없으면 OpenClaw는 Unauthorized: invalid command token.으로 콜백을 거부합니다.
비공개/tailnet/내부 콜백 호스트의 경우 Mattermost에서 ServiceSettings.AllowedUntrustedInternalConnections에 콜백 호스트/도메인을 포함해야 할 수 있습니다. 전체 URL이 아니라 호스트/도메인 값을 사용하세요.
channels.mattermost.configWrites: Mattermost에서 시작한 config 쓰기를 허용하거나 거부합니다.
channels.mattermost.requireMention: 채널에서 응답하기 전에 @mention을 요구합니다.
channels.mattermost.groups.<channelId>.requireMention: 채널별 멘션 게이트 재정의(기본값은 "*").
선택적 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,
    },
  },
}

반응 알림 모드: off, own(기본값), all, allowlist(reactionAllowlist에서).

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

iMessage

OpenClaw는 imsg rpc(stdio를 통한 JSON-RPC)를 생성합니다. 데몬이나 포트는 필요 없습니다. 호스트가 Messages 데이터베이스와 자동화 권한을 부여할 수 있는 경우, 새 OpenClaw iMessage 설정에 선호되는 경로입니다. BlueBubbles 지원은 제거되었습니다. channels.bluebubbles는 현재 OpenClaw에서 지원되는 런타임 config 표면이 아닙니다. 이전 config를 channels.imessage로 마이그레이션하세요. 짧은 버전은 BlueBubbles 제거 및 imsg iMessage 경로를, 전체 번역 표는 BlueBubbles에서 이전하기를 사용하세요. Gateway가 로그인된 Messages Mac에서 실행 중이 아니라면 channels.imessage.enabled=true를 유지하고 channels.imessage.cliPath를 해당 Mac에서 imsg "$@"를 실행하는 SSH 래퍼로 설정하세요. 기본 로컬 imsg 경로는 macOS 전용입니다.

{
  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",
      region: "US",
      actions: {
        reactions: true,
        edit: true,
        unsend: true,
        reply: true,
        sendWithEffect: true,
        sendAttachment: true,
      },
      catchup: {
        enabled: false,
      },
    },
  },
}

선택적 channels.imessage.defaultAccount는 구성된 계정 id와 일치할 때 기본 계정 선택을 재정의합니다.
Messages DB에 대한 전체 디스크 접근 권한이 필요합니다.
chat_id:<id> 대상을 권장합니다. 채팅 목록을 보려면 imsg chats --limit 20을 사용하세요.
cliPath는 SSH 래퍼를 가리킬 수 있습니다. SCP 첨부 파일 가져오기를 위해 remoteHost(host 또는 user@host)를 설정하세요.
attachmentRoots와 remoteAttachmentRoots는 인바운드 첨부 파일 경로를 제한합니다(기본값: /Users/*/Library/Messages/Attachments).
SCP는 엄격한 호스트 키 검사를 사용하므로 릴레이 호스트 키가 ~/.ssh/known_hosts에 이미 있는지 확인하세요.
channels.imessage.configWrites: iMessage에서 시작한 config 쓰기를 허용하거나 거부합니다.
channels.imessage.actions.*: imsg status / openclaw channels status --probe로도 게이트되는 비공개 API 작업을 활성화합니다.
channels.imessage.includeAttachments는 기본적으로 꺼져 있습니다. 에이전트 턴에서 인바운드 미디어를 기대하기 전에 true로 설정하세요.
channels.imessage.catchup.enabled: Gateway가 다운된 동안 도착한 인바운드 메시지 재생에 옵트인합니다.
channels.imessage.groups: 그룹 레지스트리 및 그룹별 설정입니다. groupPolicy: "allowlist"를 사용하는 경우 그룹 메시지가 레지스트리 게이트를 통과할 수 있도록 명시적 chat_id 키 또는 "*" 와일드카드 항목을 구성하세요.
type: "acp"가 있는 최상위 bindings[] 항목은 iMessage 대화를 지속 ACP 세션에 바인딩할 수 있습니다. match.peer.id에 정규화된 핸들 또는 명시적 채팅 대상(chat_id:*, chat_guid:*, chat_identifier:*)을 사용하세요. 공유 필드 의미: ACP 에이전트.

iMessage SSH 래퍼 예시

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

Matrix

Matrix는 Plugin 기반이며 channels.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는 비공개/내부 homeserver를 허용합니다. 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: 선택적 에이전트 ID 허용 목록입니다. 모든 에이전트의 승인을 전달하려면 생략하세요.
- 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

Microsoft Teams는 Plugin 기반이며 channels.msteams 아래에 구성됩니다.

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

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

IRC

IRC는 Plugin 기반이며 channels.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에 문서화되어 있습니다.

다중 계정(모든 채널)

채널당 여러 계정을 실행합니다(각각 고유한 accountId 포함).

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

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

기타 Plugin 채널

많은 Plugin 채널은 channels.<id>로 구성되며 전용 채널 페이지에 문서화되어 있습니다(예: Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, Twitch). 전체 채널 색인을 참조하세요: 채널.

그룹 채팅 멘션 게이트

그룹 메시지는 기본적으로 멘션 필요(메타데이터 멘션 또는 안전한 정규식 패턴)입니다. WhatsApp, Telegram, Discord, Google Chat, iMessage 그룹 채팅에 적용됩니다. 표시되는 응답은 별도로 제어됩니다. 그룹/채널 방은 기본적으로 messages.groupChat.visibleReplies: "message_tool"을 사용합니다. OpenClaw는 여전히 해당 턴을 처리하지만, 일반 최종 응답은 비공개로 유지되며 방에 표시되는 출력에는 message(action=send)가 필요합니다. 일반 응답이 방에 다시 게시되는 레거시 동작을 원할 때만 "automatic"으로 설정하세요. 동일한 도구 전용 표시 응답 동작을 다이렉트 채팅에도 적용하려면 messages.visibleReplies: "message_tool"을 설정하세요. Codex 하네스도 설정되지 않은 다이렉트 채팅 기본값으로 이 도구 전용 동작을 사용합니다. 도구 전용 표시 응답에는 도구를 안정적으로 호출하는 모델/런타임이 필요합니다. 세션 로그에 didSendViaMessagingTool: false인 어시스턴트 텍스트가 표시되면, 모델이 메시지 도구를 호출하는 대신 비공개 최종 답변을 생성한 것입니다. 해당 채널에 더 강력한 도구 호출 모델로 전환하거나, 레거시 표시 최종 응답을 복원하려면 messages.groupChat.visibleReplies: "automatic"을 설정하세요. 활성 도구 정책에서 메시지 도구를 사용할 수 없는 경우, OpenClaw는 응답을 조용히 억제하는 대신 자동 표시 응답으로 폴백합니다. openclaw doctor는 이 불일치에 대해 경고합니다. Gateway는 파일이 저장된 후 messages 구성을 핫 리로드합니다. 배포에서 파일 감시 또는 구성 리로드가 비활성화된 경우에만 다시 시작하세요. 멘션 유형:

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

{
  messages: {
    visibleReplies: "automatic", // global default for direct/source chats; Codex harness defaults unset direct chats to message_tool
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool", // default; use "automatic" for legacy final replies
    },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimit는 전역 기본값을 설정합니다. 채널은 channels.<channel>.historyLimit(또는 계정별 설정)로 재정의할 수 있습니다. 비활성화하려면 0으로 설정하세요. messages.visibleReplies는 전역 소스 턴 기본값입니다. messages.groupChat.visibleReplies는 그룹/채널 소스 턴에서 이를 재정의합니다. messages.visibleReplies가 설정되지 않은 경우, 하네스는 자체 다이렉트/소스 기본값을 제공할 수 있습니다. Codex 하네스는 기본값으로 message_tool을 사용합니다. 채널 허용 목록과 멘션 게이팅은 여전히 턴을 처리할지 결정합니다.

DM 기록 제한

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

해결 순서: DM별 재정의 → 제공자 기본값 → 제한 없음(모두 보존). 지원: telegram, whatsapp, discord, slack, signal, imessage, msteams.

셀프 채팅 모드

셀프 채팅 모드를 활성화하려면 allowFrom에 자신의 번호를 포함하세요(네이티브 @-멘션을 무시하고 텍스트 패턴에만 응답함).

{
  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,
  },
}

Command details

이 블록은 명령 표면을 구성합니다. 현재 내장 및 번들 명령 카탈로그는 슬래시 명령을 참조하세요.
이 페이지는 전체 명령 카탈로그가 아니라 구성 키 참조입니다. QQ Bot /bot-ping /bot-help /bot-logs, LINE /card, 기기 페어링 /pair, 메모리 /dreaming, 전화 제어 /phone, Talk /voice처럼 채널/Plugin이 소유한 명령은 해당 채널/Plugin 페이지와 슬래시 명령에 문서화되어 있습니다.
텍스트 명령은 선행 /가 있는 독립형 메시지여야 합니다.
native: "auto"는 Discord/Telegram의 네이티브 명령을 켜고 Slack은 꺼 둡니다.
nativeSkills: "auto"는 Discord/Telegram의 네이티브 skill 명령을 켜고 Slack은 꺼 둡니다.
채널별 재정의: channels.discord.commands.native(불리언 또는 "auto"). Discord의 경우 false는 시작 중 네이티브 명령 등록과 정리를 건너뜁니다.
channels.<provider>.commands.nativeSkills로 채널별 네이티브 skill 등록을 재정의합니다.
channels.telegram.customCommands는 추가 Telegram 봇 메뉴 항목을 추가합니다.
bash: true는 호스트 셸에 대해 ! <cmd>를 활성화합니다. tools.elevated.enabled와 tools.elevated.allowFrom.<channel>에 있는 발신자가 필요합니다.
config: true는 /config(openclaw.json 읽기/쓰기)를 활성화합니다. Gateway chat.send 클라이언트의 경우, 영구 /config set|unset 쓰기에는 operator.admin도 필요합니다. 읽기 전용 /config show는 일반 쓰기 범위 operator 클라이언트에서도 계속 사용할 수 있습니다.
mcp: true는 mcp.servers 아래 OpenClaw 관리 MCP 서버 구성에 대한 /mcp를 활성화합니다.
plugins: true는 Plugin 검색, 설치, 활성화/비활성화 제어를 위한 /plugins를 활성화합니다.
channels.<provider>.configWrites는 채널별 구성 변경을 게이트합니다(기본값: true).
다중 계정 채널의 경우, channels.<provider>.accounts.<id>.configWrites도 해당 계정을 대상으로 하는 쓰기를 게이트합니다(예: /allowlist --config --account <id> 또는 /config set channels.<provider>.accounts.<id>...).
restart: false는 /restart와 Gateway 재시작 도구 작업을 비활성화합니다. 기본값: true.
ownerAllowFrom은 소유자 전용 명령/도구에 대한 명시적 소유자 허용 목록입니다. allowFrom과는 별개입니다.
ownerDisplay: "hash"는 시스템 프롬프트에서 소유자 ID를 해시합니다. 해싱을 제어하려면 ownerDisplaySecret을 설정하세요.
allowFrom은 제공자별입니다. 설정된 경우 이것이 유일한 권한 부여 소스입니다(채널 허용 목록/페어링과 useAccessGroups는 무시됨).
useAccessGroups: false는 allowFrom이 설정되지 않은 경우 명령이 액세스 그룹 정책을 우회하도록 허용합니다.
명령 문서 맵:
- 내장 및 번들 카탈로그: 슬래시 명령
- 채널별 명령 표면: 채널
- QQ Bot 명령: QQ Bot
- 페어링 명령: 페어링
- LINE 카드 명령: LINE
- 메모리 Dreaming: Dreaming

Documentation Index

​채널

​DM 및 그룹 접근

​채널 모델 재정의

​채널 기본값 및 Heartbeat

​WhatsApp

​Telegram

​Discord

​Google Chat

​Slack

​Mattermost

​Signal

​iMessage

​Matrix

​Microsoft Teams

​IRC

​다중 계정(모든 채널)

​기타 Plugin 채널

​그룹 채팅 멘션 게이트

​DM 기록 제한

​셀프 채팅 모드

​명령(채팅 명령 처리)

​관련 항목

채널

DM 및 그룹 접근

채널 모델 재정의

채널 기본값 및 Heartbeat

WhatsApp

Telegram

Discord

Google Chat

Slack

Mattermost

Signal

iMessage

Matrix

Microsoft Teams

IRC

다중 계정(모든 채널)

기타 Plugin 채널

그룹 채팅 멘션 게이트

DM 기록 제한

셀프 채팅 모드

명령(채팅 명령 처리)

관련 항목