Telegram 요청을 계속 받으면서 복잡한 코드 작업도 처리하려면 수신, 실행, 결과 전달의 수명을 따로 설계해야 합니다. 저는 처음에 Claude Code 세션 하나에 상시 수신과 작업 실행을 모두 맡기려 했지만 운영 방식이 맞지 않았습니다. 이 글은 그 실패에서 출발한 오케스트레이션 설계 기록입니다.
2026년 4월의 시도에서 확인한 핵심은 상시 대기하는 서비스와 필요할 때 실행하는 세션형 도구는 역할이 다르다는 점이었습니다. 이 글은 당시 실패와 설계 판단을 재구성한 사례입니다. 현재 제품 정책, 지원 채널, 실제 배포 상태는 별도로 확인해야 합니다.
처음 설계가 실패한 이유
당시에는 Telegram 메시지를 일정 간격으로 확인해 Claude Code 세션이 자동으로 처리하도록 구성하려 했습니다. 메시지가 도착한 흔적은 있었지만 세션이 새 요청을 안정적으로 인식하고 응답하는 흐름으로 이어지지 않았습니다.
| 관찰한 문제 | 운영상 영향 |
|---|---|
| 메시지가 없어도 주기적으로 확인 | 불필요한 실행과 비용이 생길 수 있음 |
| 세션이 길어짐 | 문맥이 누적되고 작업 경계를 설명하기 어려움 |
| 세션이 종료됨 | 수신과 처리 흐름도 함께 멈춤 |
| 전달 확인이 없음 | 실행 성공과 사용자 수신 성공을 구분할 수 없음 |
이 문제는 프롬프트를 더 길게 쓰는 것으로 해결되지 않았습니다. 요청 접수, 실행, 결과 전달의 수명 주기가 서로 다른데 한 세션에 묶은 것이 원인이었습니다.
상시 수신과 고품질 처리를 분리했습니다
| 역할 | 담당 | 완료 기준 |
|---|---|---|
| 메시지 수신 | 항상 실행되는 OpenClaw 측 에이전트 | 요청과 돌아갈 대화를 식별 |
| 간단한 처리 | 수신 에이전트 | 응답을 원래 대화에 전달 |
| 복잡한 작업 | 필요할 때 시작하는 Claude Code 세션 | 결과 또는 실패 상태를 남김 |
| 최종 전달 | 수신 에이전트 | 사용자에게 결과가 전송됐는지 확인 |
여기서 제품 이름보다 중요한 것은 실행 모드입니다. 상시 수신자는 짧은 요청을 계속 받아야 하고, 세션형 실행자는 입력과 작업 범위가 정해졌을 때 시작해 결과를 남긴 뒤 종료할 수 있어야 합니다.
파일 기반 비동기 브리지를 사용했습니다
당시 설계에서는 두 시스템을 직접 호출하는 대신 파일을 작업 큐처럼 사용했습니다.
Telegram 요청
→ OpenClaw가 요청 식별자와 작업 범위를 기록
→ pending 영역에 요청 파일 생성
→ 로컬 watcher가 새 요청 확인
→ Claude Code 세션이 작업 수행
→ done 또는 failed 영역에 결과 기록
→ OpenClaw가 원래 대화로 전달파일 브리지는 단순하지만 자동으로 신뢰성을 보장하지는 않습니다. 파일이 반쯤 쓰인 상태를 읽거나 같은 요청을 두 번 처리하거나, 결과 전달 뒤 상태 이동에 실패할 수 있습니다. 따라서 디렉터리 이름보다 상태 전이 규칙이 중요합니다.
요청에 최소한 남길 항목
- 중복되지 않는 요청 식별자
- 요청이 들어온 시각과 원래 대화의 내부 참조값
- 실행할 작업과 금지된 작업
- 현재 상태: pending, running, done, failed, cancelled
- 결과 위치와 오류 요약
- 재시도 횟수와 마지막 갱신 시각
대화 전문, 개인 식별 정보, 인증값을 요청 파일에 그대로 넣지 않습니다. 실행에 필요한 최소 정보와 사용자에게 돌려줄 참조만 남기는 편이 안전합니다.
요청을 가져간 담당자와 전달 상태를 따로 남깁니다
파일 브리지를 다시 구현한다면 요청 상태 하나에 실행과 전달을 모두 담지 않는 편이 좋겠습니다. 예를 들어 실행이 done이어도 전달은 아직 대기 중일 수 있습니다. 아래는 당시 구현 성능을 보고하는 표가 아니라, 기존 설계를 보완할 때 정해야 할 계약입니다.
| 경계 | 추가로 정할 규칙 |
|---|---|
| pending → running | 어느 실행자가 요청을 가져갔는지 기록하고 다른 실행자의 중복 인수를 막는 방법 결정 |
| running → done 또는 failed | 결과 파일과 종료 근거를 확인한 뒤 상태 확정. 세션 종료만으로 성공 처리하지 않음 |
| done → 전달 확인 | 실행 상태는 유지하고 전달 대상·시도·확인 결과를 별도로 기록 |
| 취소 또는 재시작 | 실행자 생존 여부와 부분 결과 확인 후 인계. 시간 경과만으로 새 실행자를 투입하지 않음 |
파일 이동만으로 이 계약이 구현됐다고 볼 수는 없습니다. 소유권 충돌과 중간 종료를 실제로 재현해 확인해야 합니다. 수신 경로부터 막힌 경우는 OpenClaw 채널 장애 점검으로, 여러 단계의 완료 근거를 설계하려면 루프 엔지니어링의 상태·검증 구조로 나눠 살펴보세요.
에스컬레이션 기준을 먼저 정했습니다
모든 요청을 고품질 세션으로 보내면 분리 효과가 줄어듭니다. 당시에는 아래 기준으로 구분했습니다.
| 직접 처리 후보 | 에스컬레이션 후보 |
|---|---|
| 짧은 대화와 상태 안내 | 코드 수정·생성 |
| 이미 확인된 정보 전달 | 허용된 로컬 파일 작업 |
| 일정과 단순 리포트 | 여러 단계의 분석과 검증 |
| 실행 결과의 사용자 전달 | 사용자가 고품질 세션을 명시적으로 요청한 작업 |
기준은 작업 위험도와 비용에 맞춰 바뀔 수 있습니다. 결제, 외부 공개, 삭제처럼 되돌리기 어려운 작업은 모델 선택과 별개로 사람의 승인을 받아야 합니다.
실패와 중복을 상태로 다룹니다
- pending이 오래됨: 자동 성공 처리하지 않고 watcher와 실행 환경을 확인합니다.
- running에서 멈춤: 세션이 실제로 살아 있는지 확인하고 재시도 전에 부분 결과를 찾습니다.
- done인데 전달되지 않음: 실행을 다시 하지 말고 전달 단계만 재개합니다.
- 전송 응답이 불명확함: 같은 답을 즉시 다시 보내지 않고 실제 전송 여부를 확인합니다.
- cancelled 이후 결과 도착: 사용자에게 자동 전달하지 않고 정책에 따라 보류하거나 폐기합니다.
작업 실행과 메시지 전달을 분리하면 “모델은 답을 만들었지만 사용자는 받지 못한 상태”를 표현할 수 있습니다. 이 구분이 있어야 재시도가 중복 작업으로 이어지는 것을 줄일 수 있습니다.
구현 전 테스트 목록
- [ ] 같은 요청 파일을 두 번 읽어도 실행은 한 번만 되는가
- [ ] 세션이 실패하면 failed 상태와 오류 요약이 남는가
- [ ] watcher를 재시작해도 진행 중 작업을 구분하는가
- [ ] 결과 전달 실패가 작업 재실행으로 이어지지 않는가
- [ ] 사용자가 취소한 뒤 늦게 도착한 결과를 처리하는 규칙이 있는가
- [ ] 요청·결과 파일에서 비밀값과 대화 전문을 제외했는가
- [ ] 오래된 파일의 보관과 삭제 기준이 있는가
당시 결론과 아직 확인하지 못한 것
세션형 도구에 상시 서버 역할을 맡기기보다 수신, 실행, 전달을 나누는 편이 구조를 설명하고 실패를 복구하기 쉬웠습니다. 다만 원문은 이 아키텍처의 장기 운영 결과를 보고하지 않았습니다. 파일 큐의 처리량, 동시 요청 충돌, 장애 복구 시간, 현재 Claude Code와 OpenClaw의 지원 범위도 이 글에서 새로 검증하지 않았습니다.
또한 당시 정책 변화에 대한 설명은 2026년 4월의 판단 배경일 뿐입니다. 구독 정책과 서드파티 연동 가능 여부는 현재 공식 안내를 다시 확인해야 합니다.
사례 기준일: 2026-04-06
재편집일: 2026-09-03
확인한 범위: Telegram 수신, OpenClaw 조정자, Claude Code 세션, 파일 기반 비동기 브리지의 설계 기록
미확인 범위: 장기 운영 안정성, 최신 제품 정책, 처리량과 장애 복구 성능
편집 보완: 2026-09-10. 기존 사례와 작성·재편집 날짜를 유지하며 판단 절차와 관련 글을 보강했습니다. 이 날짜는 새 설치·성능 시험 또는 현재 운영 상태 확인을 뜻하지 않습니다.