소용량 메모리 Ubuntu/Debian VPS에서 OpenClaw Gateway는 이미 돌아가지만, Chromium이 필요한 브라우저 기능을 켜면 로그에 디스플레이 없음·실행 파일 없음·샌드박스 오류가 뜹니다. 이 글은 헤드리스 Linux를 프로덕션 Gateway로 쓰는 엔지니어를 위한 것입니다. DISPLAY / Xvfb / browser.executablePath에 대한 숨은 가정 일곱 가지, 가상 프레임버퍼와 실제 디스플레이 비용 표, 여섯 단계 재현 가능한 Runbook(의존성, Xvfb, 환경 내보내기, 설정 검증, systemd/Docker, 최소 검증)과 사이트 내 크로스 플랫폼 설치, not ready 문제 해결, 관측 글과의 역할을 나눕니다.
문서는 디스플레이 스택이 있는 머신을 가정하지만, 프로덕션에서는 헤드리스 VPS가 흔합니다. 아래 일곱 가지는 ‘Chrome만 설치하면 된다’는 논쟁을 서명 가능한 리스크 표로 모읍니다.
Gateway 프로세스가 셸의 DISPLAY를 자동 상속한다고 가정:systemd Environment=에 없으면 브라우저 자식은 빈 디스플레이에 붙을 수 있습니다.
browser.executablePath를 데스크톱 배포판 경로로 둠:컨테이너·최소 이미지는 경로가 달라 spawn ENOENT처럼 보입니다.
폰트·ICU 의존성 무시:폰트 패키지가 없으면 렌더가 조용히 실패하거나 타임아웃되어 Gateway가 ‘멈춘 것’처럼 보입니다.
브라우저 샌드박스를 root로 실행:Chromium이 샌드박스를 낮추거나 거부합니다. 전용 비특권 사용자와 보안 강화 글의 최소 권한을 맞춥니다.
Xvfb와 Gateway 기동 순서를 고정하지 않음:경쟁 상태로 첫 도구 호출이 실패하고 재시도가 ‘자가 치유’되어 재현이 어렵습니다.
브라우저 RAM과 모델 호출을 한 예산에 섞음:작은 머신에서는 LLM보다 Chromium이 먼저 OOM됩니다.
Gateway 로그만 보고 자식 종료 코드는 안 봄:브라우저 크래시는 다운스트림에서 도구 타임아웃으로 보입니다. openclaw logs와 저널로 타임라인을 맞춥니다.
공통 원인은 브라우저를 OS 의존 체인이 있는 런타임이 아니라 선택 플러그인으로 보는 것입니다. MCP 핸드셰이크 글은 도구 발견·세션, 이 글은 브라우저 바이너리 + 디스플레이 스택 최소 루프입니다.
Docker 프로덕션과 베어 메탈 systemd를 같이 쓰면 토폴로지에 DISPLAY·Xvfb를 누가 띄우는지 적어 두 오케스트레이터가 같은 디스플레이 번호를 두고 싸우지 않게 합니다.
만능은 없습니다. 재현성과 문제 조사 표면을 바꿉니다.
| 차원 | Xvfb + DISPLAY | 실제 / VNC 디스플레이 | Chromium --headless만 (Xvfb 없음) |
|---|---|---|---|
| 의존 범위 | Xvfb 프로세스·디스플레이 번호·폰트 패키지 유지 | 세션·해상도·사람 개입 창 유지 | 버전별 headless 정책에 의존, 업그레이드 후 동작이 바뀔 수 있음 |
| 재현성 | 높음: systemd·compose로 환경 변수 고정 | 중간: 데스크톱 세션·잠금 영향 | 중~높음: 배포판·샌드박스 조합에 따름 |
| 분류 신호 | 명확: DISPLAY, Xvfb 로그, Chromium stderr | 복잡: GUI 상태·권한 대화상자 | 간헐: GPU 없는 호스트에서 GPU/ANGLE 경로 |
| 전형적 용도 | 소메모리 VPS, 스크린샷·자동화만 | GUI·서명 팝업 흐름 | 해당 빌드에서 headless 단독이 검증된 툴체인 |
여기서 ‘재현 가능’이란 같은 systemd 유닛이나 compose 파일을 깨끗한 VPS에 가져가도 Xvfb + Gateway + 브라우저가 안정적으로 뜬다는 뜻입니다.
not ready 글과 함께: Gateway 프로세스가 아직 안정적으로 리슨하지 않으면 브라우저 층 조사를 겹치지 않습니다. 로그가 섞입니다.
순서는 디스플레이 스택 → Gateway → 도구입니다. 명령은 Debian/Ubuntu 예이며 다른 배포판은 패키지 이름을 바꿉니다.
Chromium·폰트 의존성 설치:apt install로 배포판 chromium 또는 google-chrome-stable과 fonts-noto 등을 넣습니다.
Xvfb 설치:Xvfb :99 -screen 0 1920x1080x24를 수동 기동해 소켓 충돌이 없는지 확인합니다.
DISPLAY 내보내기:Gateway와 같은 환경에 DISPLAY=:99. systemd는 Environment=DISPLAY=:99, Docker는 environment 블록.
browser.executablePath 기록:which chromium 또는 패키지 경로에 맞추고 변경 후 openclaw doctor를 실행합니다.
systemd 또는 compose로 기동 순서 고정:Xvfb가 먼저 Ready 후 Gateway. Xvfb에 재시작 정책·로그를 둡니다.
최소 검증:Gateway가 건강하면 about:blank만 여는 브라우저 도구를 한 번 호출해 샌드박스·디스플레이 오류가 없는지 본 뒤 트래픽을 엽니다.
# 手动验证（维护窗）： Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 chromium --no-sandbox --disable-dev-shm-usage --headless=new --dump-dom about:blank >/tmp/blank.html # 然后以相同 DISPLAY 启动/重启 Gateway（systemd 或 docker compose）
안내: --no-sandbox는 제한된 진단용입니다. 프로덕션에서는 비 root·최소 권한과 networkPolicy로 노출을 줄입니다.
관측 글과 맞춰 Xvfb·Chromium stderr를 같은 티켓 타임라인에 두어 ‘Gateway는 녹색인데 도구는 빨강’을 모델 백엔드 문제로 오인하지 않습니다.
온콜 채널용입니다. WebSocket 종료 코드가 섞이면 gateway closed (1000) 글로 넘어갑니다.
cannot open display: DISPLAY와 살아 있는 Xvfb 확인.executablePath ENOENT: 경로와 컨테이너에 같은 바이너리 마운트.zygote / sandbox: 비특권 사용자·커널 전제 확인 후 임시 진단 플래그.
주의: 느슨한 샌드박스 설정을 프로덕션에 오래 두지 마세요. 진단 후 설정을 되돌리고 변경 티켓을 남겨 감사 요구를 충족합니다.
Docker에서는 /dev/shm과 공유 메모리 크기도 확인합니다. 너무 작으면 Chromium이 간헐 종료되어 도구가 불안정합니다.
2차 라인 정렬용입니다. 외부 전송 전 비식별화합니다.
/etc/os-release, uname -r, Chromium 메이저 버전.ss -lxn | grep X11 또는 동등한 리스너 확인.dmesg에 OOM killer가 있는지.Gateway를 수면 가능한 노트북에만 묶으면 디스플레이 스택과 네트워크가 불안정합니다. 최소 VPS는 브라우저와 모델을 동시에 올리면 OOM이 잦습니다. OpenClaw와 주변 툴체인을 위해 장기 온라인·계약 가능한 macOS나 전용 연산층이 필요하면 전용 원격 Mac이 ‘얼기설기 로컬’보다 안정적인 경우가 많습니다. 산발적 자체 장비 대비 고정 SSH·명확한 디스크 단·복제 가능한 노드 프로필의 NodeMini Mac mini 클라우드 대여가 플랫폼 거버넌스에 유리합니다. 사양·가격은 Mac mini 대여 가격, 온보딩은 헬프 센터, 연재는 블로그 OpenClaw 카테고리에서 시작하세요.
브라우저 층이 안정되면 근본 원인 태그를 변경 기록에 남겨 다음 Chromium 업그레이드에서 같은 함정을 반복하지 않습니다.
DISPLAY가 리슨 중인 Xvfb를 가리키는지, browser.executablePath가 실제 바이너리와 일치하는지, systemd/Docker가 DISPLAY·폰트 의존성을 Gateway 프로세스에 주입하는지입니다. 용량 계획은 Mac mini 대여 가격과 헬프 센터를 보세요.
not ready는 포트·메모리·타임아웃·컨테이너 기동 순서입니다. 이 글은 브라우저 서브시스템과 디스플레이 스택입니다. 계속되면 not ready와 closed (1000)도 대조하세요.
블로그 OpenClaw 카테고리에서 설치·Docker·systemd·보안·관측·MCP로 이어집니다. 온보딩은 헬프 센터를 참고하세요.