​

Telegram (Bot API)

​

Quick setup

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

​

Telegram side settings

​

Access control and activation

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          allowFrom: ["8734062810", "745123456"],
        },
      },
    },
  },
}

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

​

Runtime behavior

• Telegram은 gateway process가 직접 소유합니다.
• routing은 deterministic합니다. Telegram inbound는 다시 Telegram으로 reply됩니다(model이 channel을 선택하지 않음).
• inbound message는 reply metadata와 media placeholder를 포함한 공통 channel envelope로 정규화됩니다.
• group session은 group ID별로 격리됩니다. forum topic은 :topic:<threadId>를 덧붙여 topic 단위로 격리합니다.
• DM message는 message_thread_id를 포함할 수 있습니다. OpenClaw는 thread-aware session key로 라우팅하고 reply 시 thread ID를 보존합니다.
• Long polling은 grammY runner를 사용하며, chat/thread별 sequencing을 유지합니다. 전체 runner sink concurrency는 agents.defaults.maxConcurrent를 사용합니다.
• Telegram Bot API는 read-receipt를 지원하지 않습니다(sendReadReceipts는 적용되지 않음).

​

Feature reference

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}

{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "allowlist",
          },
        },
      },
    },
  },
}

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", callback_data: "cancel" }],
  ],
}

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // General topic -> main agent
            "3": { agentId: "zu" },        // Dev topic -> zu agent
            "5": { agentId: "coder" }      // Code review -> coder agent
          }
        }
      }
    }
  }
}

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

{
  channels: {
    telegram: {
      configWrites: false,
    },
  },
}

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

​

Troubleshooting

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

channels:
  telegram:
    network:
      autoSelectFamily: false

dig +short api.telegram.org A
dig +short api.telegram.org AAAA

​

Telegram config reference pointers

• channels.telegram.enabled: 채널 startup enable/disable
• channels.telegram.botToken: bot token (BotFather)
• channels.telegram.tokenFile: 일반 파일 경로에서 token 읽기. symlink는 거부됨
• channels.telegram.dmPolicy: pairing | allowlist | open | disabled (default: pairing)
• channels.telegram.allowFrom: DM allowlist (숫자형 Telegram user ID). allowlist는 최소 하나의 sender ID가 필요하고, open은 "*"가 필요합니다. openclaw doctor --fix는 legacy @username 항목을 ID로 resolve할 수 있고, allowlist migration 흐름에서 pairing-store 파일의 항목을 복구할 수 있습니다.
• channels.telegram.actions.poll: Telegram poll 생성 enable/disable (default: enabled, 여전히 sendMessage 필요)
• channels.telegram.defaultTo: CLI --deliver가 explicit --reply-to 없이 동작할 때 사용할 기본 Telegram target
• channels.telegram.groupPolicy: open | allowlist | disabled (default: allowlist)
• channels.telegram.groupAllowFrom: group sender allowlist (숫자형 Telegram user ID). openclaw doctor --fix는 legacy @username을 ID로 resolve할 수 있습니다. 숫자가 아닌 항목은 auth 시 무시됩니다. group auth는 DM pairing-store fallback을 사용하지 않습니다(2026.2.25+).
• Multi-account precedence:
  • 두 개 이상의 account ID가 구성되어 있다면 default routing을 명확히 하기 위해 channels.telegram.defaultAccount를 설정하거나 channels.telegram.accounts.default를 포함하세요.
  • 둘 다 없으면 OpenClaw는 첫 normalized account ID로 fallback하고 openclaw doctor가 경고합니다.
  • channels.telegram.accounts.default.allowFrom 과 channels.telegram.accounts.default.groupAllowFrom 은 default account에만 적용됩니다.
  • named account는 account-level 값이 없으면 channels.telegram.allowFrom 과 channels.telegram.groupAllowFrom 을 상속합니다.
  • named account는 channels.telegram.accounts.default.allowFrom / groupAllowFrom 을 상속하지 않습니다.
• channels.telegram.groups: 그룹별 기본값 + allowlist ("*"로 전역 기본값 설정 가능)
  • channels.telegram.groups.<id>.groupPolicy: groupPolicy의 그룹별 override (open | allowlist | disabled)
  • channels.telegram.groups.<id>.requireMention: mention gating 기본값
  • channels.telegram.groups.<id>.skills: skill filter (omit = 모든 skill, empty = 없음)
  • channels.telegram.groups.<id>.allowFrom: 그룹별 sender allowlist override
  • channels.telegram.groups.<id>.systemPrompt: 그룹용 추가 system prompt
  • channels.telegram.groups.<id>.enabled: false일 때 그룹 비활성화
  • channels.telegram.groups.<id>.topics.<threadId>.*: topic별 override (group field + topic 전용 agentId)
  • channels.telegram.groups.<id>.topics.<threadId>.agentId: 이 topic을 특정 agent로 라우팅 (group-level 및 binding routing보다 우선)
• channels.telegram.groups.<id>.topics.<threadId>.groupPolicy: groupPolicy의 topic별 override (open | allowlist | disabled)
• channels.telegram.groups.<id>.topics.<threadId>.requireMention: topic별 mention gating override
• top-level bindings[] 와 type: "acp", 그리고 match.peer.id에 canonical topic id chatId:topic:topicId: persistent ACP topic binding field (ACP Agents 참고)
• channels.telegram.direct.<id>.topics.<threadId>.agentId: DM topic을 특정 agent로 라우팅 (forum topic과 동일 동작)
• channels.telegram.execApprovals.enabled: 이 account에서 Telegram을 chat-based exec approval client로 활성화
• channels.telegram.execApprovals.approvers: exec request approve/deny 권한이 있는 Telegram user ID. exec approval이 활성화되면 필수
• channels.telegram.execApprovals.target: dm | channel | both (default: dm). channel 과 both 는 originating Telegram topic이 있으면 이를 유지
• channels.telegram.execApprovals.agentFilter: forwarded approval prompt용 optional agent ID filter
• channels.telegram.execApprovals.sessionFilter: forwarded approval prompt용 optional session key filter (substring 또는 regex)
• channels.telegram.accounts.<account>.execApprovals: Telegram exec approval routing과 approver authorization의 account별 override
• channels.telegram.capabilities.inlineButtons: off | dm | group | all | allowlist (default: allowlist)
• channels.telegram.accounts.<account>.capabilities.inlineButtons: account별 override
• channels.telegram.commands.nativeSkills: Telegram native skills command enable/disable
• channels.telegram.replyToMode: off | first | all (default: off)
• channels.telegram.textChunkLimit: outbound chunk 크기(chars)
• channels.telegram.chunkMode: length (default) 또는 newline, 길이 기준 chunking 전에 빈 줄(문단 경계)에서 나눔
• channels.telegram.linkPreview: outbound message의 link preview 토글 (default: true)
• channels.telegram.streaming: off | partial | block | progress (live stream preview, default: partial; progress는 partial로 매핑; block은 legacy preview mode compatibility). Telegram preview streaming은 하나의 preview message를 같은 자리에서 edit하는 방식입니다.
• channels.telegram.mediaMaxMb: inbound/outbound Telegram media cap (MB, default: 100)
• channels.telegram.retry: recoverable outbound API error에 대한 Telegram send helper(CLI/tools/actions)의 retry policy (attempts, minDelayMs, maxDelayMs, jitter)
• channels.telegram.network.autoSelectFamily: Node autoSelectFamily override (true=enable, false=disable). Node 22+에서는 기본 활성, WSL2에서는 기본 비활성
• channels.telegram.network.dnsResultOrder: DNS result order override (ipv4first 또는 verbatim). Node 22+ 기본값은 ipv4first
• channels.telegram.proxy: Bot API 호출용 proxy URL (SOCKS/HTTP)
• channels.telegram.webhookUrl: webhook mode 활성화 (channels.telegram.webhookSecret 필요)
• channels.telegram.webhookSecret: webhook secret (webhookUrl이 있으면 필수)
• channels.telegram.webhookPath: local webhook path (default /telegram-webhook)
• channels.telegram.webhookHost: local webhook bind host (default 127.0.0.1)
• channels.telegram.webhookPort: local webhook bind port (default 8787)
• channels.telegram.actions.reactions: Telegram tool reaction gating
• channels.telegram.actions.sendMessage: Telegram tool message send gating
• channels.telegram.actions.deleteMessage: Telegram tool message delete gating
• channels.telegram.actions.sticker: Telegram sticker action gating - send와 search (default: false)
• channels.telegram.reactionNotifications: off | own | all - 어떤 reaction이 system event를 발생시킬지 제어 (설정되지 않으면 default own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive - agent의 reaction capability 제어 (설정되지 않으면 default minimal)
• Configuration reference - Telegram

• startup/auth: enabled, botToken, tokenFile, accounts.* (tokenFile은 일반 파일이어야 하며 symlink는 거부됨)
• access control: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, groups.*.topics.*, top-level bindings[] (type: "acp")
• exec approvals: execApprovals, accounts.*.execApprovals
• command/menu: commands.native, commands.nativeSkills, customCommands
• threading/replies: replyToMode
• streaming: streaming (preview), blockStreaming
• formatting/delivery: textChunkLimit, chunkMode, linkPreview, responsePrefix
• media/network: mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
• webhook: webhookUrl, webhookSecret, webhookPath, webhookHost
• actions/capabilities: capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker
• reactions: reactionNotifications, reactionLevel
• writes/history: configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

​

Related

• Pairing
• Channel routing
• Multi-agent routing
• Troubleshooting