지금까지 우리는 터미널, 웹 패널, 혹은 텔레그램 같은 메신저 UI를 통해 직접 AI 에이전트에게 업무를 지시해 왔습니다. 하지만 진정한 의미의 자동화란 사용자가 일일이 명령어를 입력하지 않아도 AI가 알아서 백그라운드에서 데이터를 수집하고, 분석하며, 특정 조건에 도달했을 때만 보고하는 시스템을 뜻합니다.
이번 17편에서는 눈에 보이는 채팅창이나 UI 없이 서버 백그라운드에서 24시간 묵묵히 돌아가는 openclaw headless 모드 운영법을 처음부터 끝까지 다룹니다. Python이나 서버 기초만 있다면 누구나 완벽한 백그라운드 자동화 팩토리를 완성할 수 있습니다.
지난 편(16편: OpenClaw 멀티 에이전트 — 에이전트 여러 개 동시 운영하기)에서는 단일 게이트웨이 안에서 역할이 다른 여러 에이전트를 동시에 운영하는 법을 배웠습니다. 이번 편에서는 그 팀 전체를 화면 없이 서버에서 돌리는 방법을 실습합니다.
Headless 모드란 무엇인가?
Headless(헤드리스)란 말 그대로 '머리(눈에 보이는 화면이나 UI)'가 없는 상태로 프로그램이 백그라운드에서 실행되는 모드를 의미합니다. 클라우드 서버나 개인용 VPS에 openclaw 설치를 마친 후, 게이트웨이를 Headless 상태로 띄워두면 터미널 창을 닫아도 AI는 멈추지 않습니다.
이는 사용자와 잡담을 나누기 위한 용도가 아니라 데이터베이스 백업, 시스템 에러 로그 모니터링, 야간 대규모 데이터 처리 등 사용자가 보지 않는 곳에서 실무를 처리하는 셀프호스팅 AI를 운영할 때 필수적인 아키텍처입니다.
Headless 모드가 필요한 대표적인 상황
- 야간 자동 리포트 생성: 매일 새벽 3시에 전날 데이터를 취합해 요약 보고서를 자동으로 생성하고 슬랙에 전송
- 파일 변경 감지 자동 처리: 특정 폴더에 새 파일이 생성되면 즉시 분석·분류·저장
- 서버 헬스 모니터링: 서버 상태를 5분 간격으로 체크하고, 이상 감지 시 텔레그램 경보 발송
- 주기적인 웹 스크래핑: 경쟁사 가격·뉴스·공시 데이터를 정해진 시간에 자동 수집
Docker로 Headless 환경 구축하기 — 실행 가능한 코드
Headless 배포를 구성하는 가장 깔끔하고 공식적인 방법은 Docker 컨테이너를 활용하는 것입니다. Docker를 사용하면 호스트 시스템과 완벽히 격리된 상태에서 백그라운드 데몬(Daemon)으로 에이전트를 영구 실행할 수 있습니다.
서버 터미널을 열고 아래 명령어를 실행해 보세요. -d(detach) 옵션이 UI 없이 백그라운드에서 실행하게 만드는 핵심입니다.
# 1. OpenClaw 설정 파일이 저장될 로컬 디렉토리 생성
mkdir -p ~/.openclaw
# 2. Docker를 이용해 Headless 모드로 게이트웨이 백그라운드 실행 (-d 옵션)
docker run -d \
--name openclaw-headless \
--restart unless-stopped \
-v ~/.openclaw:/root/.openclaw \
-p 18789:18789 \
openclaw/openclaw:latest gateway run
# 3. 백그라운드에서 잘 돌아가고 있는지 로그 확인
docker logs -f openclaw-headless주요 옵션 해설
-d(detach): 컨테이너를 백그라운드에서 실행합니다. 터미널을 닫거나 SSH 접속을 종료해도 AI는 계속 동작합니다.--restart unless-stopped: 서버가 재부팅되거나 컨테이너가 예기치 않게 종료되어도 자동으로 재시작합니다. 진정한 24/7 무인 운영의 핵심 옵션입니다.-v ~/.openclaw:/root/.openclaw: 호스트의 설정 폴더를 컨테이너 내부에 마운트합니다. 컨테이너를 재생성해도 설정과 데이터가 그대로 유지됩니다.docker logs -f: 실행 중인 컨테이너의 로그를 실시간으로 스트리밍합니다. Ctrl+C로 로그 보기를 중지해도 컨테이너는 계속 동작합니다.
cron + message 도구 결합 — 무인 자동화 완성하기
UI가 없는 Headless 모드의 AI는 언제, 어떻게 일을 시작할까요? 정답은 cron(스케줄링) 도구와 message(푸시 알림) 도구의 결합에 있습니다.
사용자가 잠든 심야나 새벽 등 트래픽이 적은 오프피크(off-peak) 시간에 무거운 배치(Batch) 작업이나 리포트 생성을 스케줄링해 두는 것이 이상적입니다. 예약된 시간에 스스로 깨어난 에이전트는 지정된 스크립트를 백그라운드에서 실행하고, 결과나 에러가 발생하면 message 능력을 이용해 텔레그램이나 디스코드로 "리포트 작업이 완료되었습니다"라는 푸시 알림을 보냅니다.
자동화 파이프라인 흐름 예시
- cron 스케줄 설정:
AGENTS.md또는 openclaw.json의 cron 블록에 "매일 새벽 3시에 리포트 생성" 규칙을 등록합니다. - 에이전트 자동 기동: 새벽 3시가 되면 Headless 컨테이너 안의 에이전트가 자동으로 깨어나 지정된 작업(데이터 취합, 요약, 저장)을 실행합니다.
- 결과 보고: 작업 완료 후
message도구를 통해 텔레그램 또는 디스코드로 결과 요약 메시지를 전송합니다. - 에러 발생 시 즉각 알림: 예외 상황이 발생하면
AGENTS.md의 규칙에 따라 에러 로그와 함께 긴급 알림을 발송합니다.
이것이 바로 채팅 없이도 스스로 일하는 진정한 백그라운드 AI 자동화 시스템입니다. 잠든 시간에도 쉬지 않고 일하는 무인 팩토리를 24시간 운영하는 것과 같습니다.
docker run -d --restart unless-stopped로 게이트웨이를 영구 백그라운드 실행하고, cron으로 작업 시간을 예약한 뒤 message 도구로 결과를 보고받으면 완전한 Headless 무인 자동화가 완성됩니다.
실전 팁과 주의사항
- 반드시 클라우드 서버(VPS)에서 운영하세요: Headless 모드는 터미널 창을 숨길 뿐, 프로그램이 설치된 기기의 전원은 켜져 있어야 합니다. 개인 노트북이 아닌 월 5달러 수준의 VPS(Vultr, Hetzner, DigitalOcean 등)에 배포해야 진정한 24/7 자동화가 가능합니다.
- 에러 로그 수신 규칙을 AGENTS.md에 미리 정의하세요: UI가 없으면 AI가 에러를 뿜어도 알 수가 없습니다.
AGENTS.md에 "치명적인 에러가 발생하면 즉시 내 텔레그램으로 에러 로그를 전송해"라는 규칙을 반드시 추가해 두세요. - 메신저 연동이 없어도 Headless 자동화는 작동합니다: 텔레그램·디스코드 연동이 없어도
cron이나heartbeat설정이 켜져 있다면 AI는 정해진 시간마다 로컬 파일 시스템을 읽고, 인터넷 검색·파일 수정 등 부여받은 로컬 자동화 업무를 수행합니다. - 리소스 효율도 높아집니다: 웹 UI를 렌더링하거나 실시간 웹소켓으로 타이핑 이펙트를 전달할 필요 없이 백그라운드 연산에만 집중하므로, 서버 자원이 한정된 환경에서도 더 안정적으로 동작합니다.
--restart unless-stopped 옵션을 사용하면 서버 재부팅 후에도 컨테이너가 자동 재시작됩니다. 설정 파일에 오류가 있으면 재부팅마다 에러 상태로 계속 재시작되므로, 배포 전 반드시 openclaw doctor --fix로 설정을 검증하세요.자주 묻는 질문 (FAQ)
- Headless 모드로 켜두면 제 개인 노트북이나 PC를 꺼도 에이전트가 계속 일하나요?
- 아닙니다. Headless 모드는 터미널 창(UI)을 숨기고 백그라운드에서 돌아가게 할 뿐, 프로그램이 설치된 물리적인 기기의 전원은 반드시 켜져 있어야 합니다. 그래서 24시간 켜둘 수 있는 월 5달러 수준의 클라우드 VPS에 배포하는 것을 강력히 권장합니다.
- 백그라운드에서 UI 없이 돌고 있다면 AI가 에러를 뿜을 때 어떻게 확인하나요?
- 두 가지 방법이 있습니다. 첫째는 서버 터미널에 접속해
docker logs openclaw-headless명령어로 텍스트 로그를 직접 확인하는 것입니다. 둘째는AGENTS.md에 "치명적인 에러가 발생하면 반드시 내 텔레그램 채널로 즉시 에러 로그를 전송해"라고 지시해 두어, AI가 스스로 문제를 보고하도록 만드는 것입니다. - 메신저 연동을 다 꺼둔 상태에서도 Headless 모드가 의미가 있나요?
- 물론입니다. 텔레그램이나 디스코드 연동이 없더라도,
cron이나heartbeat설정이 켜져 있다면 AI는 정해진 시간마다 로컬 파일 시스템을 읽고, 인터넷을 검색하고, 파일을 수정하는 등 부여받은 로컬 자동화 업무를 훌륭하게 수행합니다. - Headless 모드는 일반 모드보다 서버 자원(RAM, CPU)을 적게 소모하나요?
- 네, 미세하지만 이점이 있습니다. 웹 UI로 화면을 렌더링하거나 실시간 웹소켓으로 타이핑 이펙트를 사용자에게 전달할 필요 없이 백그라운드 연산에만 집중하므로, 서버 자원이 한정된 환경에서 더욱 안정적이고 효율적으로 동작합니다.
이 글이 도움이 됐다면 댓글로 여러분의 경험을 알려주세요! 🙌
Headless 환경 구축에서 막히는 부분은 댓글에 남겨주세요 — 직접 답변드립니다.
📬 새 편 알림 받기 → AI 활용 가이드 구독
댓글