18. 카카오 채널 연결 실패, shared relay부터 확인

카카오 채널을 붙이려는데 세션 생성 단계에서 HTTP 500이나 fetch failed가 반복되면, 사람은 보통 휴대폰 문제나 설정 실수부터 의심한다. 그런데 실제 운영에서는 내 설정이 틀린 경우와 shared relay 자체가 흔들린 경우가 꽤 다르게 보인다. 이 둘을 먼저 분리하지 않으면, 계정·폰·플러그인만 계속 다시 만지게 된다.

핵심은 간단하다. 카카오 채널 연결 실패 = 무조건 내 기기 문제로 보면 안 된다. 먼저 릴레이가 살아 있는가, 내 relayUrl/relayToken이 맞는가, 페어링 코드 흐름이 실제로 끝까지 가는가를 순서대로 자르면 훨씬 빨리 풀린다.

안내: 이 문서는 생성형 AI를 활용해 초안을 정리하고, 현재 운영 메모와 로컬 연동 문서를 기준으로 사람이 검수해 보정했습니다.

flowchart LR
A[카카오 채널 연결 시도] --> B{shared relay 응답 정상?}
B -- 아니오 --> C[내 설정 탓으로 단정하지 말고 relay 장애 먼저 확인]
B -- 예 --> D{relayUrl / relayToken 맞음?}
D -- 아니오 --> E[OpenClaw 계정 설정 수정]
D -- 예 --> F{페어링 코드 생성/입력 성공?}
F -- 아니오 --> G[페어링 흐름 점검]
F -- 예 --> H{메시지 폴링/응답 경로 정상?}
H -- 아니오 --> I[채널 권한·callback·라우팅 점검]
H -- 예 --> J[연결 완료]

30초 핵심 요약

• 카카오 채널 연결이 안 될 때는 휴대폰 문제 / 내 설정 문제 / shared relay 장애를 먼저 나눠 봐야 한다.
• 세션 생성 직후 HTTP 500, fetch failed가 반복되면, shared relay 쪽 장애 가능성이 생각보다 크다.
• 릴레이 문서 기준으로 연결 핵심은 relayUrl, relayToken, 페어링 코드, 웹훅/콜백 흐름이다.
• 업무용으로 안정 운영할 생각이면 공유 릴레이 하나에만 기대기보다 자체 릴레이 + 자체 카카오 채널 구성이 훨씬 덜 흔들린다.

칠판 판서형 치트시트

1. HTTP 500이면 먼저 relay 장애인지 본다
2. relayUrl·relayToken이 맞는지 확인한다
3. /pair 코드 흐름이 끝까지 되는지 본다
4. callback/webhook이 붙었는지 본다
5. 안정 운영은 shared relay보다 자체 릴레이가 유리하다

먼저 이 구조를 이해하면 덜 헷갈린다

카카오 채널 연동 문서 기준으로, 메시지 흐름은 단순히 “카카오 ↔ OpenClaw”가 아니다. 실제로는 중간에 릴레이 서버가 있다.

• 사용자는 카카오 채널로 메시지를 보낸다.
• 카카오는 웹훅으로 릴레이 서버에 전달한다.
• 릴레이 서버는 페어링된 계정 기준으로 라우팅한다.
• OpenClaw는 long-poll로 메시지를 받아 처리한 뒤 다시 릴레이를 통해 응답한다.

즉, 중간 릴레이가 흔들리면 폰이 멀쩡해도 연결 실패처럼 보일 수 있다. 그래서 이 문제는 “카카오가 안 된다”보다 어느 구간에서 끊겼는가로 보는 편이 정확하다. 브라우저 attach 성격의 연결 구조를 먼저 감 잡고 싶다면 12. 브라우저 릴레이 연동 구조를 같이 보면 흐름이 더 빨리 잡힌다.

왜 자주 생기나

1) shared relay 자체가 흔들린다

가장 먼저 봐야 할 축이다. 공유 릴레이는 편하지만, 장애가 나면 사용자 입장에서는 전부 자기 설정 문제처럼 보인다.

대표 신호는 이렇다.

• 세션 생성 단계에서 HTTP 500
• fetch failed 반복
• 플러그인은 살아 있는데 실제 페어링이 진행되지 않음
• 같은 시각 여러 연결 시도가 비슷하게 막힘

이 경우에는 폰을 바꾸거나 앱을 다시 여는 것보다 릴레이 헬스체크와 응답 상태를 먼저 보는 편이 빠르다. 응답 자체가 오래 걸리거나 멈춘 것처럼 보이면 40. OpenClaw 답변 지연, 10분 먹통처럼 보일 때 해결도 함께 보는 편이 좋다.

미니 사례:

• before: 안드로이드 기기 문제로 생각하고 기기 쪽만 계속 재시도
• actual: 공유 릴레이에서 세션 생성 단계가 500으로 실패
• after: 원인을 relay 장애로 분리하고 자체 릴레이 경로로 전환

2) relayUrl 또는 relayToken이 안 맞는다

연동 가이드 기준으로 카카오 채널 플러그인은 relayUrl과 relayToken을 정확히 가져야 한다. 둘 중 하나라도 틀리면 겉으로는 “연결 안 됨”으로만 보이지만, 실제로는 잘못된 릴레이를 바라보거나 인증이 틀린 상태일 수 있다.

체크 포인트는 단순하다.

• 지금 붙으려는 릴레이 URL이 맞는가
• 발급받은 계정 토큰을 그 인스턴스가 실제로 쓰고 있는가
• 예전 shared relay 값이 남아 있지는 않은가

특히 shared relay에서 자체 릴레이로 바꾼 직후에는 예전 값이 남아 있어 헷갈리기 쉽다. 토큰·원격 경로가 뒤섞여 보인다면 41. gateway token mismatch로 remote unauthorized 뜰 때 해결 문서도 같이 확인하면 원인 분리가 쉬워진다.

3) 페어링 코드 흐름이 중간에서 끊긴다

로컬 문서 기준으로 페어링은 명시적이다. 사용자는 생성된 코드를 받아 카카오 채널에서 /pair <코드>를 입력해야 특정 인스턴스와 연결된다.

여기서 흔히 막히는 지점은 3개다.

1. 코드가 만료됐다
2. 코드가 이미 사용됐다
3. 릴레이가 /pair 요청을 받았지만 계정 매핑을 끝내지 못했다

즉, 사용자가 채널을 추가했다고 바로 연결되는 구조가 아니다. 페어링 코드 생성 → 사용자 입력 → 매핑 저장까지 끝나야 한다. 비슷하게 채널 권한·그룹 정책 때문에 막히는 패턴은 22. 텔레그램 그룹 협업 세팅 + 보안 가이드나 30. 텔레그램 완전설정 운영가이드와 비교해 보면 구조 이해에 도움이 된다.

4) callback/webhook은 붙었는데 응답 시간이 흐트러진다

설정 가이드 문서 기준으로 카카오는 callback 기반 비동기 응답을 사용하고, callbackUrl 유효시간도 제한된다. 그래서 연결은 되어 보여도 실제 응답이 늦거나 누락되면 사용자는 또 “연결 실패”로 느낄 수 있다.

여기서는 다음을 같이 봐야 한다.

• 카카오 웹훅 URL이 릴레이를 정확히 가리키는가
• callback 기능이 승인/활성화됐는가
• 릴레이가 메시지를 받고 OpenClaw로 넘긴 뒤 다시 callback까지 끝내는가

즉, 연결 성공과 실사용 응답 성공은 같은 말이 아니다.

5분 복구 순서

1) relay 장애부터 자른다

가장 먼저 릴레이 자체 헬스체크를 본다. 공유 릴레이라면 내 설정을 건드리기 전에 지금 relay가 실제로 응답 가능한지를 확인한다.

질문은 이것만 먼저 던지면 된다.

• 헬스 엔드포인트가 살아 있는가
• 세션 생성 시 500이 나는가
• 다른 사용자/인스턴스도 비슷하게 막히는가

여기서 이상하면 내 기기나 플러그인만 만져도 해결되지 않는다.

2) relayUrl과 relayToken을 다시 맞춘다

연동 문서 기준으로 계정마다 relay token이 따로 생기고, OpenClaw 쪽은 그 값을 설정에 넣어야 한다. 따라서 shared relay에서 자체 릴레이로 옮겼다면 URL과 토큰 둘 다 같이 바꿨는지를 보는 편이 중요하다.

한 줄 점검:

• URL은 새 릴레이를 가리키는가
• 토큰은 그 릴레이에서 발급한 값인가
• 예전 값이 캐시처럼 남아 있지 않은가

3) 페어링 코드로 실제 연결을 끝까지 본다

페어링 흐름은 문서상 분명하다.

1. 계정 생성
2. 페어링 코드 생성
3. 사용자에게 /pair 코드 입력 안내
4. 매핑이 PAIRED 상태가 되는지 확인

즉, 채널 추가까지만 보고 끝내지 말고 코드 입력 후 연결 완료 응답까지 봐야 한다.

4) 업무용이면 자체 릴레이를 우선 검토한다

shared relay는 빠르게 테스트하기엔 좋지만, 장애가 나면 내가 통제할 수 있는 범위가 작다. 반면 자체 릴레이는 세팅이 조금 더 필요해도 운영 기준이 훨씬 명확하다.

• 헬스체크를 직접 볼 수 있음
• 계정/토큰/로그를 직접 관리 가능
• 장애 원인을 내 환경 기준으로 바로 좁힐 수 있음

그래서 테스트는 shared relay로 해도, 실운영은 자체 릴레이 + 자체 카카오 채널 쪽이 훨씬 안정적이다. 멀티 경로 운영 감각은 28. 듀얼 릴레이 운영 가이드를 같이 보면 더 잘 잡힌다.

미니 사례 2개

사례 A) 플러그인은 보이는데 페어링이 전혀 안 될 때

• 증상: 플러그인은 loaded 상태인데 세션 생성에서 실패
• 원인: shared relay 응답 자체가 500으로 흔들림
• 대응: 사용자 기기 문제로 보지 않고 relay 상태부터 분리 점검
• 결과: 원인 범위를 빠르게 줄이고 자체 릴레이 전환 기준 확보

사례 B) 자체 릴레이로 바꿨는데 여전히 연결이 안 될 때

• 증상: 새 릴레이를 띄웠는데도 연결 실패
• 원인: 설정에는 예전 relay 값이 남아 있었음
• 대응: relayUrl과 relayToken을 세트로 재정렬
• 결과: 페어링 코드 생성과 /pair 흐름이 정상화됨

누가 / 무엇을 / 어떤 순서로 보면 되나

1. 운영자: relay 헬스체크와 세션 생성 응답부터 본다.
2. 설정 담당자: relayUrl, relayToken, 계정 매핑을 다시 맞춘다.
3. 실사용자: 채널 추가 후 /pair 코드까지 입력해 실제 연결 완료 응답을 확인한다.
4. 실운영 전환 담당자: shared relay가 불안정하면 자체 릴레이 전환 여부를 결정한다.

적용 체크리스트

• 세션 생성 단계에서 HTTP 500 / fetch failed 여부를 확인했다.
• relay 자체 헬스체크를 먼저 봤다.
• relayUrl과 relayToken을 세트로 확인했다.
• 페어링 코드 생성 후 /pair 코드까지 실제로 검증했다.
• 웹훅/콜백 흐름이 끝까지 이어지는지 확인했다.
• 실운영은 자체 릴레이 + 자체 채널 구성을 검토했다.

상황별 바로 가기

• 설치/첫 연결부터 다시 볼 때 → 01. 설치
• 기본 실행 흐름을 다시 잡을 때 → 02. 시작하기
• OpenClaw 구조를 먼저 이해할 때 → 03. 핵심개념
• 브라우저 기반 연결 흐름을 비교할 때 → 12. 브라우저 릴레이 연동 구조
• 텔레그램처럼 채널 복구 감각을 같이 익힐 때 → 18. 텔레그램 안될 때 5분 복구
• 권한/협업 정책까지 같이 볼 때 → 22. 텔레그램 그룹 협업 세팅 + 보안 가이드
• 멀티 릴레이 운영을 비교할 때 → 28. 듀얼 릴레이 운영 가이드
• 채널 설정 전체를 다시 점검할 때 → 30. 텔레그램 완전설정 운영가이드
• 게이트웨이/응답 지연까지 함께 볼 때 → 33. 게이트웨이 무응답 PM2·systemd 충돌 10분 복구
• 전달 단계 분리 문제를 같이 볼 때 → 43. cron은 돌았는데 텔레그램 전달이 안 올 때

다음 읽기

• 12. 브라우저 릴레이 연동 구조
• 18. 텔레그램 안될 때 5분 복구
• 22. 텔레그램 그룹 협업 세팅 + 보안 가이드
• 28. 듀얼 릴레이 운영 가이드
• 30. 텔레그램 완전설정 운영가이드
• 33. 게이트웨이 무응답 PM2·systemd 충돌 10분 복구
• 40. OpenClaw 답변 지연, 10분 먹통처럼 보일 때 해결
• 41. gateway token mismatch로 remote unauthorized 뜰 때 해결
• 42. cron 시간을 바꿨는데 예전 시각에 계속 돌 때
• 43. cron은 돌았는데 텔레그램 전달이 안 올 때

---

안내: 이 문서는 생성형 AI를 활용해 작성되었습니다.