OpenClaw 마크다운 포맷팅 가이드: 여러 채널에서 일관된 메시지 보내기

여러 채팅 플랫폼에 메시지를 보낼 때 마크다운이 깨져서 당황한 적 없으신가요? 어떤 채널은 텍스트를 굵게 표시하지만, 다른 채널은 별표(**)를 그대로 노출하기도 하죠. 특히 긴 메시지를 자를 때 서식 코드가 중간에 끊기면 메시지 전체의 가독성이 크게 떨어집니다.

OpenClaw는 이런 문제를 해결하기 위해 마크다운을 직접 렌더링하는 대신, 중간 표현인 IR(Intermediate Representation)로 먼저 변환해요. 덕분에 각 채널의 특성에 맞추면서도 일관된 메시지를 전달할 수 있습니다.

필요한 것

• Slack, Telegram, Signal outbound adapters
• markdown.tables 설정 (선택 사항)

빠른 시작

OpenClaw의 마크다운 처리 파이프라인을 따라가면 5분 안에 설정을 이해할 수 있어요.

1. Parse Markdown -> IR: markdownToIR(...)를 사용해 마크다운을 일반 텍스트와 스타일 정보(bold, italic, links 등)가 담긴 IR로 변환합니다.
2. Chunk IR: chunkMarkdownIR(...)을 호출해 텍스트를 자릅니다. 이때 스타일이 잘리지 않도록 각 Chunk마다 스타일을 다시 적용합니다.
3. Render: 각 채널 어댑터에서 IR을 Slack mrkdwn, Telegram HTML, 또는 Signal 스타일로 변환하여 전송합니다.

IR (Intermediate Representation) 구조

입력된 마크다운이 어떻게 변환되는지 예시를 통해 살펴볼게요.

Input Markdown:

Hello **world** — see [docs](https://docs.openclaw.ai).

IR (schematic):

{
  "text": "Hello world — see docs.",
  "styles": [{ "start": 6, "end": 11, "style": "bold" }],
  "links": [{ "start": 19, "end": 23, "href": "https://docs.openclaw.ai" }]
}

테이블 처리하기

채팅 클라이언트마다 마크다운 테이블 지원 여부가 달라요. markdown.tables 설정을 통해 채널별 또는 계정별로 변환 방식을 제어할 수 있습니다.

• code: 테이블을 코드 블록으로 렌더링합니다 (대부분의 채널 기본값).
• bullets: 각 행을 불렛 포인트로 변환합니다 (Signal, WhatsApp 기본값).
• off: 테이블 파싱을 비활성화하고 원본 텍스트를 그대로 보냅니다.

Config 예시:

channels:
  discord:
    markdown:
      tables: code
    accounts:
      work:
        markdown:
          tables: off

주요 채널별 링크 정책

• Slack: [label](url) 형식을 <url|label>로 변환합니다. 중복 링크를 방지하기 위해 자동 링크 기능은 꺼져 있습니다.
• Telegram: HTML 파싱 모드를 사용하여 <a href="url">label</a> 형태로 변환합니다.
• Signal: label (url) 형태로 변환합니다. 다만, 라벨과 URL이 같으면 URL만 표시합니다.
• 기타 채널: WhatsApp, iMessage 등은 일반 텍스트를 사용하거나 자체 규칙을 따릅니다.

문제 해결

• Slack 토큰 오류: <@U123>이나 <#C123> 같은 특수 토큰이 깨지지 않도록 HTML 이스케이프 처리에 주의해야 해요.
• Telegram 마크업 깨짐: HTML 태그 외부의 텍스트가 제대로 이스케이프 되지 않으면 메시지 전송이 실패할 수 있습니다.
• Signal 스타일 위치 어긋남: Signal은 UTF-16 코드 단위를 기준으로 위치를 계산해요. 코드 포인트 오프셋을 사용하지 않도록 확인하세요.
• 코드 블록 서식: 코드 펜스(```) 뒤에 줄바꿈을 유지해야 채널에서 닫는 마커를 올바르게 인식합니다.

구현 중에 도움이 필요하다면 AI Setup Assistant에게 물어보세요.

다음 단계

• Streaming + chunking
• Channel outbound adapters
• Message formatting API
• Table conversion detailed rules