English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Tools

브라우저 문제 해결

문제: "포트 18800에서 Chrome CDP를 시작하지 못함"

OpenClaw의 브라우저 제어 서버가 다음 오류와 함께 Chrome/Brave/Edge/Chromium 실행에 실패합니다.

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

근본 원인

Ubuntu 및 많은 Linux 배포판에서 기본 Chromium 설치는 snap 패키지입니다. Snap의 AppArmor 격리가 OpenClaw가 브라우저 프로세스를 생성하고 모니터링하는 방식과 충돌합니다.

apt install chromium 명령은 snap으로 리디렉션하는 스텁 패키지를 설치합니다.

Note, selecting 'chromium-browser' instead of 'chromium'
chromium-browser is already the newest version (2:1snap1-0ubuntu2).

이것은 실제 브라우저가 아닙니다. 단순한 래퍼일 뿐입니다.

기타 일반적인 Linux 실행 실패:

  • The profile appears to be in use by another Chromium process는 Chrome이 관리 프로필 디렉터리에서 오래된 Singleton* 잠금 파일을 찾았다는 뜻입니다. OpenClaw는 해당 잠금이 종료된 프로세스 또는 다른 호스트의 프로세스를 가리키는 경우 잠금을 제거하고 한 번 다시 시도합니다.
  • Missing X server or $DISPLAY는 데스크톱 세션이 없는 호스트에서 표시 가능한 브라우저가 명시적으로 요청되었다는 뜻입니다. 기본적으로 로컬 관리 프로필은 Linux에서 DISPLAY와 WAYLAND_DISPLAY가 모두 설정되지 않은 경우 이제 headless 모드로 대체됩니다. OPENCLAW_BROWSER_HEADLESS=0, browser.headless: false 또는 browser.profiles.<name>.headless: false를 설정했다면, 해당 headed 재정의를 제거하거나, OPENCLAW_BROWSER_HEADLESS=1을 설정하거나, Xvfb를 시작하거나, 일회성 관리 실행을 위해 openclaw browser start --headless를 실행하거나, 실제 데스크톱 세션에서 OpenClaw를 실행하세요.

해결 방법 1: Google Chrome 설치(권장)

snap으로 샌드박싱되지 않는 공식 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  # if there are dependency errors

그런 다음 OpenClaw 설정(~/.openclaw/openclaw.json)을 업데이트하세요.

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

해결 방법 2: 연결 전용 모드로 Snap Chromium 사용

snap Chromium을 반드시 사용해야 한다면, 수동으로 시작한 브라우저에 연결하도록 OpenClaw를 구성하세요.

  1. 설정을 업데이트합니다.
{
  "browser": {
    "enabled": true,
    "attachOnly": true,
    "headless": true,
    "noSandbox": true
  }
}
  1. Chromium을 수동으로 시작합니다.
chromium-browser --headless --no-sandbox --disable-gpu \
  --remote-debugging-port=18800 \
  --user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
  about:blank &
  1. 선택적으로 Chrome을 자동 시작하도록 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

브라우저 작동 확인

상태를 확인합니다.

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

설정 참고

옵션 설명 기본값
browser.enabled 브라우저 제어 활성화 true
browser.executablePath Chromium 기반 브라우저 바이너리 경로(Chrome/Brave/Edge/Chromium) 자동 감지됨(Chromium 기반인 경우 기본 브라우저를 선호)
browser.headless GUI 없이 실행 false
OPENCLAW_BROWSER_HEADLESS 로컬 관리 브라우저 headless 모드에 대한 프로세스별 재정의 설정되지 않음
browser.noSandbox --no-sandbox 플래그 추가(일부 Linux 설정에 필요) false
browser.attachOnly 브라우저를 실행하지 않고 기존 브라우저에만 연결 false
browser.cdpPort Chrome DevTools Protocol 포트 18800
browser.localLaunchTimeoutMs 로컬 관리 Chrome 검색 제한 시간 15000
browser.localCdpReadyTimeoutMs 로컬 관리 실행 후 CDP 준비 제한 시간 8000

Raspberry Pi, 오래된 VPS 호스트 또는 느린 스토리지에서는 Chrome이 CDP HTTP 엔드포인트를 노출하는 데 더 많은 시간이 필요할 때 browser.localLaunchTimeoutMs를 늘리세요. 실행은 성공하지만 openclaw browser start가 여전히 not reachable after start를 보고할 때는 browser.localCdpReadyTimeoutMs를 늘리세요. 값은 120000ms 이하의 양의 정수여야 하며, 유효하지 않은 설정 값은 거부됩니다.

문제: "profile="user"에 대한 Chrome 탭을 찾을 수 없음"

existing-session / Chrome MCP 프로필을 사용 중입니다. OpenClaw가 로컬 Chrome을 볼 수 있지만, 연결할 수 있는 열린 탭이 없습니다.

수정 옵션:

  1. 관리 브라우저 사용: openclaw browser start --browser-profile openclaw 또는 browser.defaultProfile: "openclaw"를 설정합니다.
  2. Chrome MCP 사용: 로컬 Chrome이 최소 하나의 열린 탭으로 실행 중인지 확인한 다음 --browser-profile user로 다시 시도합니다.

참고:

  • user는 호스트 전용입니다. Linux 서버, 컨테이너 또는 원격 호스트의 경우 CDP 프로필을 선호하세요.
  • user / 기타 existing-session 프로필은 현재 Chrome MCP 제한을 유지합니다. ref 기반 작업, 단일 파일 업로드 훅, 대화 상자 제한 시간 재정의 없음, wait --load networkidle 없음, 그리고 responsebody, PDF 내보내기, 다운로드 가로채기 또는 배치 작업 없음.
  • 로컬 openclaw 프로필은 cdpPort/cdpUrl을 자동 할당합니다. 원격 CDP에만 이를 설정하세요.
  • 원격 CDP 프로필은 http://, https://, ws://, wss://를 허용합니다. /json/version 검색에는 HTTP(S)를 사용하고, 브라우저 서비스가 직접 DevTools 소켓 URL을 제공하는 경우 WS(S)를 사용하세요.

관련 항목