Claude Code를 Railway에서 Telegram 봇으로 헤드리스 실행하는 방법

커뮤니티 반응

작성자의 상세한 트러블슈팅 과정과 구체적인 Docker 설정 공유에 대해 긍정적인 반응이 예상되며, 특히 문서화되지 않은 텔레메트리 관련 버그 발견이 유용한 정보로 평가받고 있다.

주요 논점

01찬성다수

Claude Code의 기본 채널 기능을 활용하여 별도의 프레임워크 없이도 강력한 원격 코딩 봇을 구축할 수 있다.

합의점 vs 논쟁점

합의점

Claude Code의 설정 파일 경로는 직관적이지 않아 주의가 필요하다.
헤드리스 환경에서의 자동화를 위해서는 JSON 설정 파일의 직접적인 조작이 필수적이다.

논쟁점

텔레메트리 비활성화가 핵심 기능인 채널 사용을 막는 설계 방식에 대한 사용자들의 불만이 있을 수 있다.

실용적 조언

Railway 배포 시 볼륨을 사용하여 /data/.claude 경로를 유지하면 재배포 시에도 인증 상태를 보존할 수 있다.
Telegram 봇 토큰은 한 번에 하나의 프로세스만 사용해야 하므로, 로컬 테스트 프로세스를 반드시 종료한 후 서버를 가동해야 한다.

섹션별 상세

온보딩 프롬프트 차단 및 설정 파일 경로 오류를 해결했다. Claude Code는 헤드리스 환경에서 테마 선택 등의 대화형 프롬프트에 의해 실행이 중단되는데, 이를 방지하기 위한 설정 파일 위치가 ~/.claude/.claude.json이 아닌 ~/.claude.json임을 확인했다. 해당 경로에 직접 JSON 파일을 생성하여 온보딩 완료 상태를 강제 주입함으로써 자동화된 부팅이 가능해졌다.

bash

CLAUDE_JSON="$HOME/.claude.json"
REQUIRED='{ "hasCompletedOnboarding": true, "theme": "dark", "projects": { "/app": { "hasTrustDialogAccepted": true, "hasCompletedProjectOnboarding": true } } }'
if [ -f "$CLAUDE_JSON" ]; then
  jq --argjson req "$REQUIRED" '. * $req' "$CLAUDE_JSON" > /tmp/cj.tmp && mv /tmp/cj.tmp "$CLAUDE_JSON"
else
  echo "$REQUIRED" | jq . > "$CLAUDE_JSON"
fi

jq를 사용하여 기존 설정 파일과 필수 온보딩 플래그를 안전하게 병합하는 로직

프로젝트 디렉토리 신뢰(Folder Trust) 설정을 JSON 구조로 자동화했다. 새로운 환경에서 실행 시 발생하는 '이 폴더를 신뢰합니까?'라는 질문을 우회하기 위해 ~/.claude.json 내 projects 객체 하위에 특정 경로와 hasTrustDialogAccepted 플래그를 명시했다. 이 방식을 통해 사용자 개입 없이도 에이전트가 작업 디렉토리에 즉시 접근할 수 있는 환경을 구축했다.

텔레메트리 비활성화 변수가 채널 기능을 차단하는 내부 메커니즘을 발견했다. DISABLE_TELEMETRY 또는 DO_NOT_TRACK 변수를 설정하면 Claude Code 내부의 기능 플래그 시스템인 GrowthBook이 중단되어 Telegram 채널 연동이 불가능해진다. 분석 결과 DISABLE_AUTOUPDATER=1과 DISABLE_ERROR_REPORTING=1은 채널 기능에 영향을 주지 않는 안전한 대안임이 확인됐다.

tmux 세션 내 환경 변수 유실 문제와 OAuth 토큰 관리 전략을 수립했다. tmux는 실행 시 새로운 셸을 생성하여 기존 export된 변수를 상속받지 못하므로, 환경 변수를 파일로 덤프한 뒤 세션 내부에서 source 명령으로 불러오는 방식을 적용했다. 또한 6일마다 만료되는 OAuth 토큰이 배포 시마다 초기화되지 않도록 기존 인증 파일 존재 여부를 확인하여 병합하는 로직을 구현했다.

bash

export -p > /tmp/env.sh
tmux new-session -d -s telegram \
  "source /tmp/env.sh; cd /app; claude --channels plugin:telegram@claude-plugins-official --dangerously-skip-permissions"

환경 변수를 덤프하여 tmux 세션 내에서 Claude Code를 실행하는 명령

용어 해설

헤드리스(Headless): — 그래픽 사용자 인터페이스(GUI) 없이 터미널이나 백그라운드에서 실행되는 소프트웨어 작동 방식이다. 서버 환경이나 자동화 스크립트에서 화면 출력 없이 프로세스만 구동할 때 필수적이며, 원격 배포의 효율성을 높인다.
텔레메트리(Telemetry): — 소프트웨어의 사용 패턴, 오류 로그, 성능 지표 등을 개발사 서버로 전송하는 원격 측정 기능이다. 제품 개선에 활용되지만 개인정보 보호를 위해 비활성화하기도 하며, 이 글에서는 특정 기능의 활성화 여부와 연동된 핵심 요소로 다뤄진다.
터미널 멀티플렉서(tmux): — 단일 터미널 창에서 여러 개의 가상 세션을 생성하고 관리할 수 있게 해주는 도구이다. SSH 연결이 끊겨도 프로세스를 백그라운드에서 계속 실행할 수 있어 서버용 에이전트 구동에 자주 사용된다.
오픈 인증(OAuth): — 사용자의 비밀번호를 노출하지 않고 제3자 앱에 권한을 부여하는 표준 인증 프로토콜이다. Claude Code는 이를 통해 사용자 계정을 인증하며, 토큰 만료 및 갱신 로직이 서비스 지속성에 중요한 역할을 한다.
제이큐(jq): — 커맨드라인에서 JSON 데이터를 슬라이싱, 필터링, 매핑, 변형할 수 있는 경량 프로세서이다. 셸 스크립트 내에서 설정 파일을 동적으로 수정하거나 병합할 때 강력한 기능을 제공한다.

언급된 도구

Claude Code추천

AI 코딩 에이전트 및 CLI 도구

Railway추천

클라우드 호스팅 및 배포 플랫폼

tmux추천

터미널 세션 유지 및 관리

jq추천

명령행 JSON 처리 및 변환