Railway에 OpenClaw 배포하기: 완벽 가이드
OpenClaw란 무엇인가요?
OpenClaw(구 Clawdbot / Moltbot)는 오픈 소스로 제공되는 자체 호스팅 AI 개인 비서 프레임워크입니다. Telegram, Discord, WhatsApp, Slack 등과 같은 채팅 플랫폼을 통해 사용자와 상호 작용하며 이메일 관리, 일정 관리, 코드 실행, 웹 브라우징, 반복 작업 자동화 등을 도와줍니다. 당신의 데이터를 완전히 통제할 수 있으며, 모든 정보는 당신의 자체 인스턴스에만 보관됩니다.
왜 Railway를 선택해야 할까요?
현재 Railway는 OpenClaw를 배포하는 데 가장 쉽고 안정적인 클라우드 기반 방식입니다. VPS 대여나 직접 Docker를 구성하는 것과 비교할 때 Railway의 장점은 다음과 같습니다:
- 원클릭 배포 템플릿: 공식 문서(docs.openclaw.ai)에서 강력히 권장하는 방식이며, 커뮤니티 템플릿을 통해 프로덕션 환경에 2000회 이상 배포되었습니다.
- 번거로운 터미널 조작 없음: 모든 구성은 브라우저 내의
/setup마법사를 통해 이루어지며, 명령어를 입력할 필요가 전혀 없습니다. - HTTPS 및 도메인 기본 제공: Railway는 자동으로
*.up.railway.app도메인과 SSL 인증서를 제공하며, 커스텀 도메인도 지원합니다. - 영구 스토리지: Railway Volume을 사용해 설정과 데이터를 보존하므로 재배포 시에도 데이터가 손실되지 않습니다.
- 저렴한 비용: 무료 요금제는 초기 테스트에 충분하며, 트래픽에 따라 Hobby 플랜은 월 약 $5부터 시작합니다.
사전 준비 사항
시작하기 전에 다음 항목이 필요합니다:
| 항목 | 설명 |
|---|---|
| Railway 계정 | 에 가입하세요. GitHub 계정으로 로그인하는 것을 강력히 권장합니다. 무료 요금제는 신용카드 등록 없이 사용할 수 있습니다. |
| AI 제공자 API Key | 최소 하나 필요: Anthropic(Claude), OpenAI(GPT), Google Gemini, 또는 OpenRouter(무료 크레딧 제공 및 저렴한 모델 전환이 가능해 초보자에게 권장됨). |
| 채팅 채널 Token(선택) | Telegram Bot Token(BotFather에서 획득, 가장 쉬움), Discord Bot Token, Slack App Token 등. |
전체 배포 단계 (약 5–12분 소요)
1단계: 원클릭 배포 템플릿 클릭
현재 가장 많이 사용되고 권장되는 템플릿의 경로는 다음과 같습니다:
- 공식 문서 링크 (권장):
https://railway.com/new/template/openclaw-railway-template에 접속하여 페이지의 "Deploy on Railway" 버튼을 클릭합니다. - 인기 커뮤니티 템플릿: Railway 템플릿 마켓플레이스에서 "OpenClaw" 또는 "Clawdbot"을 검색하여, 배포 횟수가 많고 유지 보수가 활발한 템플릿을 선택합니다.
클릭하면 Railway 인터페이스로 리디렉션됩니다. "Deploy Now"를 눌러 시작하세요.
2단계: 환경 변수 설정
Railway는 필수 및 권장 환경 변수를 입력하라는 메시지를 표시합니다. 템플릿에 안내가 포함되어 있으니 가이드라인을 따르세요:
| 변수명 | 권장 값 / 설명 | 필수 여부 |
|---|---|---|
SETUP_PASSWORD | 강력한 암호를 설정하세요 (8~20자, /setup 마법사 로그인에 사용되므로 반드시 기억하십시오) | 필수 |
OPENCLAW_GATEWAY_TOKEN | 안전한 문자열 (32자 이상, 암호 관리자 등으로 생성 권장; 앱과 Gateway를 연결하는 인증 키입니다) | 필수 |
PORT | 8080 (대부분의 템플릿에 미리 설정되어 있으며, 비워두거나 8080 입력) | 권장 |
OPENCLAW_STATE_DIR | /data/.openclaw (구성 파일과 자격 증명을 위한 영구 경로) | 권장 |
OPENCLAW_WORKSPACE_DIR | /data/workspace (워크스페이스를 위한 영구 경로) | 권장 |
ENABLE_WEB_TUI | true (디버깅을 쉽게 할 수 있도록 웹 터미널 UI를 활성화) | 선택 |
팁:
OPENAI_API_KEY,ANTHROPIC_API_KEY,GEMINI_API_KEY와 같은 다른 변수들은 나중에 Setup 마법사에서 입력할 수 있습니다. 지금은 이 단계를 건너뛰어도 좋습니다.
3단계: Volume 추가 (영구 스토리지, 절대 잊지 마세요!)
이 단계는 아주 중요합니다. Railway의 컨테이너 파일 시스템은 일시적(ephemeral)이므로, 재시작 및 재배포 시 데이터가 유지되려면 반드시 Volume을 추가해야 합니다.
방법은 다음과 같습니다:
- 배포가 완료된 후, Service 페이지로 이동합니다.
- Volumes 섹션을 찾아 + New Volume을 클릭합니다.
- Mount Path는 반드시
/data로 설정해야 합니다. 이곳에 설정 파일, 장기 기억 기록, 기기 페어링 정보가 저장됩니다. - 개인 사용용으로는 5GB 정도의 공간을 할당하는 것을 권장합니다 (충분함).
- 볼륨 생성 후 Redeploy를 클릭하여 볼륨을 적용합니다.
경고: Volume을 연결하지 않으면, 매번 다시 시작하거나 Redeploy할 때마다 모든 설정이 초기화되어 처음부터 다시 시작해야 합니다.
4단계: 퍼블릭 네트워킹(Public Networking) 활성화
Service 설정 내에서 다음을 수행:
- Settings → Public Networking으로 이동.
- HTTP Proxy를 활성화하고 포트를
8080으로 설정. - Railway가 자동으로 도메인을 부여합니다 (예:
https://<project-name>-production.up.railway.app). 원할 경우 이곳에 호스팅할 도메인을 연결할 수 있습니다.
다음 단계에서 필요하니 부여된 Public URL을 복사하여 보관하세요.
5단계: 배포 완료 대기하기
빌드 및 배포 프로세스에는 보통 2~5분 정도 소요됩니다. Railway의 Deployments → View Logs에서 로그를 확인할 수 있습니다. 다음과 같은 메시지가 나타나면 정상적으로 구동되고 있는 것입니다:
6단계: Setup 마법사 접속하기 (가장 중요한 단계)
브라우저를 열고 다음 URL로 이동하세요:
시스템이 HTTP Basic 인증 화면을 띄울 것입니다:
- 사용자 이름(Username): 아무 문자나 입력하세요(예:
admin). 이 항목은 실제로는 무시됩니다. - 비밀번호(Password): 2단계에서 설정한
SETUP_PASSWORD를 입력합니다.
로그인하면 설정 마법사로 진입합니다. 화면의 안내에 따라 구성을 완료하세요:
- LLM 공급자 선택: OpenRouter (테스트용 무료 티어), Anthropic, Google Gemini, 또는 OpenAI를 권장합니다.
- API Key 입력: 공급자의 API 키를 붙여넣습니다. 아직 없다면 에 가입하여 무료 크레딧을 얻어 Claude, Gemini, Llama 등 다양한 모델을 테스트해 보세요.
- 채팅 채널 바인딩(권장 사항): Telegram이 가장 편합니다(BotFather에서 Bot Token 획득). Discord를 사용할 경우 OAuth2 URL Generator에서
bot과applications.commands권한을 체크한 뒤 봇을 서버에 초대해야 합니다. - Gateway Token 입력: 2단계에서 설정한
OPENCLAW_GATEWAY_TOKEN을 입력합니다. - 추가 옵션: 브라우저 도구, 파일시스템 접근 등에 대한 옵션은 현재의 기본값으로 두어도 괜찮습니다.
- Run Setup / Save 클릭. 대략 10~30초 후 성공(Success) 메시지가 나오기까지 대기합니다.
7단계: 기기 페어링 및 사용 시작
- Telegram (또는 다른 설정된 앱)을 이용해 본인의 봇(Bot)을 찾아 아무 메시지(예:
hi또는/start)를 보냅니다. - 봇이 **"Pairing Required"**라고 답변할 것입니다.
- 다시 브라우저로 돌아와
https://당신의Railway도메인/openclaw로 접속합니다 (또는 루트 URL 이동). - Control UI 내의 Pending Devices 목록을 확인한 뒤 Approve를 클릭합니다.
- 이제 다시 메시지를 보내면 문제없이 AI 비서와 소통할 수 있습니다!
배포 이후 유용한 주소 모음
| URL 주소 | 목적 |
|---|---|
https://당신의도메인/setup | 설정 및 변경, 백업 기능 제공 (비밀번호 보안) |
https://당신의도메인/openclaw | 기기 관리와 채팅 로그 확인용 Control UI 대시보드 |
https://당신의도메인/tui | 웹 터미널 UI (ENABLE_WEB_TUI=true 설정 필요) |
일반적인 문제와 트러블슈팅 안내
"Internal error" 또는 "Gateway did not become ready"
1~2분 정도 대기 후 다시 시도해 보세요. 그래도 해결되지 않으면 Railway 안에서 Redeploy를 클릭합니다. 로그(Logs)를 확인하여 API 키의 유효성 등 문제의 형태를 점검하세요.
Control UI 화면의 "gateway disconnected" 또는 인증 에러
처음부터 /openclaw에 직접 방문해서 나타날 수 있는 에러입니다. 반드시 /setup 페이지를 먼저 열고 "Open OpenClaw UI" 버튼을 통해 이동하세요. 그래야 UI에 인증 토큰이 정상적으로 넘어갑니다.
"Pairing required" 또는 "Disconnected (1008)"
https://당신의도메인/setup으로 접속하여 Devices 위치에서 "Manage Devices"나 "Approve Latest Request"를 수동으로 클릭해 주세요. 이때 Gateway Token이 올바로(대소문자 구별하여) 입력되어 있는지 확인하세요.
AI 모델 변경하는 방법
OpenClaw CLI를 사용해 모델을 변경할 수 있습니다. Web TUI가 켜져 있다면 /tui에서 다음과 같이 실행하세요:
또는 /setup으로 다시 돌아와 공급자와 API Key를 갱신하고 다시 Setup을 적용(Run)하셔도 됩니다.
구성이 손상되었거나 이상 설정 오류가 발생하는 경우
/setup으로 가서 "Run Doctor" 버튼을 클릭합니다. 내부적으로 openclaw doctor --repair 명령을 자동 실행하여 파일 상태 점검, 설정 백업, 비정상적이고 깨진 데이터의 정리를 실시해 줍니다.
요금 예상 안내
| 항목 | 요금 수준 |
|---|---|
| Railway | 초기 테스트에는 무료 리소스로 충분합니다. 트래픽이나 사용에 따라 Hobby 요금제(약 5$/월)가 청구될 수 있습니다. |
| LLM 추론 | OpenRouter 무료 모델을 쓴다면 0부터 사용 가능하며, Claude Sonnet 등 프리미엄 모델 이용 시 이용량으로 청구됩니다. |
고급 조작법
컨테이너 쉘 접근 방법
가끔 직접 명령어 실행이 필요하다면:
- Web TUI:
ENABLE_WEB_TUI=true로 구성하고 다시 배포한 뒤/tui로 접속합니다. - Railway CLI: PC에 Railway CLI 프로그램을 설치한 뒤,
railway link로 프로젝트에 접근해railway shell을 치면 컨테이너로 이동됩니다.
데이터 백업과 마이그레이션 안내
- 수동 백업:
/setup페이지 내의 "Export Backup"을 통해.zip파일 형태로 다운로드 받으실 수 있습니다. 이렇게 생성된 파일은 어느 플랫폼에서나 복원이 가능합니다(VPS, Docker, 홈 서버 등). - 자동 백업:
rclone을 이용해 주기적으로/data의 디렉토리 전체를 클라우드로 보내도록 스크립팅하세요. - 플랫폼 이전하기: 백업을 담은 ZIP 파일을 내보낸 뒤 새로운 곳(클라우드나 머신)에 새로 배포한 상태에서 해당 백업 파일을 다시 가져오기만 하면 됩니다. Railway 안에 영원히 묶여있지 않습니다.
다중 인스턴스 배포하기
Railway에 위 템플릿을 여러 개 자유롭게 배포할 수 있습니다. 각 인스턴스는 각자의 개별 도메인, Volume, 구성을 소유하므로 개인 용도와 업무 용도를 깔끔하게 나누어 관리하기 용이합니다.
마치며
OpenClaw를 Railway에 구축하는 방식의 핵심은 다음의 다섯 단계입니다: 원클릭 템플릿 → 환경 변수 세팅 → Volume 적용 → Public Networking 활성화 → Setup 마법사 완료. 모든 과정은 브라우저 공간 안에서 한 번에 통과됩니다. 과정 중에 문제가 막힌다 싶으면 Railway의 배포 로그가 대개 핵심 원인을 지적해주므로 그곳을 참고하십시오. *