Linux 환경에서 OpenClaw 브라우저 오류 해결하기

리눅스 환경에서 개발 도구를 세팅하다 보면 브라우저 제어 단계에서 예상치 못한 오류를 마주하곤 해요. 분명 가이드대로 설치했는데 브라우저 프로세스가 실행되지 않거나, 권한 문제로 연결이 끊기면 정말 답답하죠. 특히 샌드박스 보안 정책이 까다로운 배포판을 사용 중이라면 이런 설정 오류는 흔히 발생하는 일이에요.

필요한 것

• Ubuntu 또는 Chromium 기반 브라우저가 설치된 Linux 배포판
• OpenClaw 설정 파일 (~/.openclaw/openclaw.json) 수정 권한

빠른 시작

가장 빠르고 확실한 해결책은 Snap 패키지의 간섭을 받지 않는 공식 Google Chrome을 설치하는 거예요. 5분 안에 설정을 끝낼 수 있어요.

1. Google Chrome 설치: 터미널에서 아래 명령어를 실행해서 공식 .deb 패키지를 설치하세요.

   wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
   sudo dpkg -i google-chrome-stable_current_amd64.deb
   sudo apt --fix-broken install -y  # 의존성 오류 발생 시 실행

2. OpenClaw 설정 업데이트: ~/.openclaw/openclaw.json 파일을 열고 브라우저 경로를 지정하세요.

   {
     "browser": {
       "enabled": true,
       "executablePath": "/usr/bin/google-chrome-stable",
       "headless": true,
       "noSandbox": true
     }
   }

문제 해결

문제 1: “Failed to start Chrome CDP on port 18800”

OpenClaw가 Chrome/Brave/Edge/Chromium을 실행하려고 할 때 아래와 같은 오류가 발생하는 경우예요.

{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"openclaw\"."}

원인 Ubuntu를 포함한 많은 리눅스 배포판에서 apt install chromium으로 설치되는 Chromium은 실제로는 Snap 패키지예요. Snap의 AppArmor 보안 격리 기능이 OpenClaw가 브라우저 프로세스를 실행하고 모니터링하는 작업을 차단하기 때문에 발생해요.

해결 방법: Snap Chromium 수동 연결 (Attach-Only Mode) 공식 Chrome을 설치할 수 없는 상황이라면, 브라우저를 수동으로 실행하고 OpenClaw를 여기에 연결해야 해요.

1. openclaw.json 설정 변경:

   {
     "browser": {
       "enabled": true,
       "attachOnly": true,
       "headless": true,
       "noSandbox": true
     }
   }

2. 터미널에서 Chromium 수동 실행:

   chromium-browser --headless --no-sandbox --disable-gpu \
     --remote-debugging-port=18800 \
     --user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
     about:blank &

3. (선택 사항) systemd 서비스 등록: 브라우저가 자동으로 실행되도록 ~/.config/systemd/user/openclaw-browser.service 파일을 만드세요.

   [Unit]
   Description=OpenClaw Browser (Chrome CDP)
   After=network.target
   
   [Service]
   ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.openclaw/browser/openclaw/user-data about:blank
   Restart=on-failure
   RestartSec=5
   
   [Install]
   WantedBy=default.target

   이후 systemctl --user enable --now openclaw-browser.service 명령어로 활성화하세요.

문제 2: “Chrome extension relay is running, but no tab is connected”

chrome 프로필(확장 프로그램 릴레이)을 사용 중일 때 발생하는 오류예요. OpenClaw 확장 프로그램이 활성화된 탭을 찾지 못했다는 뜻이에요.

해결 방법

1. 관리형 브라우저 사용: openclaw browser start --browser-profile openclaw 명령어를 실행하거나, 설정에서 browser.defaultProfile을 "openclaw"로 변경하세요.
2. 확장 프로그램 수동 연결: 브라우저에서 탭을 하나 열고, OpenClaw 확장 프로그램 아이콘을 직접 클릭해서 연결을 활성화하세요.

브라우저 작동 확인하기

설정을 마쳤다면 아래 명령어로 상태를 확인해 보세요.

# 상태 확인
curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'

# 브라우징 테스트
curl -s -X POST http://127.0.0.1:18791/start
curl -s http://127.0.0.1:18791/tabs

Config Reference

옵션	설명	기본값
browser.enabled	브라우저 제어 활성화 여부	true
browser.executablePath	브라우저 실행 파일 경로 (Chrome/Brave/Edge/Chromium)	자동 감지
browser.headless	GUI 없이 실행 여부	false
browser.noSandbox	--no-sandbox 플래그 추가 (일부 리눅스 환경에서 필요)	false
browser.attachOnly	브라우저를 직접 실행하지 않고 기존 프로세스에 연결	false
browser.cdpPort	Chrome DevTools Protocol 포트	18800

설정 과정에서 어려움이 있다면 AI Setup Assistant에게 물어보세요!

What’s Next

• Browser Configuration 상세 가이드
• OpenClaw 확장 프로그램 설치하기