이미 원격 Mac에서 OpenClaw를 돌리지만 답이 여전히 「오프라인 같다」면 내장 웹 검색 배선이 빠졌을 가능성이 큽니다. 2026 스택은 web_search로 넓게, web_fetch로 단일 URL, 필요 시 Firecrawl류로 JS·봇 대응을 보완합니다. 글은 v2026.3.28 플러그인 승인·브라우저 MCP와 구분해 공급자 선택, 활성화 순서, 키, 허용 목록, /approve, 429/빈 결과, 로그와 VNC 체크리스트만 다룹니다. 검색은 되는데 응답이 없으면 무응답 분석·launchd 데몬을 보세요.
문서만 붙여 넣기, 데모 직후 429, .env에 키가 있는데도 disabled 같은 문제는 한 스위치가 아니라 순서(doctor→configure→launchd 환경→allowlist→채널 테스트→승인→부하 단계적 감소)로 풉니다.
독자와 경계
macOS에서 OpenClaw를 운영 중이고 공개 웹 검색을 안정화하려는 독자용입니다. 설치 입문서가 아닙니다.
검색이 크리티컬 패스에 올라가면 설정 버전 관리, 현재 활성 에이전트 프로필 기록, 사고 시 allowlist를 좁히는 롤백 절차까지 포함해 설계하세요.
통증 포인트와 경계
- 도구 혼동: 브라우저 MCP는 실제 Chrome, 내장 검색은 공급자 API입니다. 경계 없으면 비용·인용이 이중화됩니다.
- 허용 목록 드리프트: 업그레이드 후에도
web_search/group:web가 없으면 환각이 늘 수 있습니다. - 비밀 배치: 대화형 셸 export만으로는 launchd Gateway에 안 들어갈 수 있습니다.
- 승인 교착:
requireApproval이 검색을 멈출 수 있습니다. 채널별 /approve는 승인 글 참고. - 쿼터 형태: 429는 병렬 서브에이전트·재시도가 흔한 원인입니다.
- 빈 결과: 필터가 빡세면 HTTP 200인데 행이 0일 수 있습니다.
- 관측 가능성 공백: 모델 대화만 있고 도구 메타데이터가 없으면 공급자 HTTP 상태를 못 봅니다. 벤더 교체 전에 프로바이더 이름·지연·상태 코드가 남는 Gateway/도구 트레이스를 켜세요.
- 멀티테넌트 키 혼용: 스테이징과 프로덕션이 같은 API 키를 쓰면 429 원인을 나눌 수 없습니다. 환경별 키 분리와 카나리아 라벨을 쓰세요.
로그, 정책, 업그레이드를 견디는 런북
web_search·web_fetch·크롤 폴백을 분리해 보기
「검색이 고장」이라고 해도 실제로는 단일 URL 페치 타임아웃, TLS 검사, Firecrawl 쿼터일 수 있습니다. 대화 ID나 요청 ID 하나를 잡고 프로바이더명·HTTP 코드·재시도·모델 병렬 재시도까지 한 줄로 추적하세요. 여러 서브에이전트 로그를 섞으면 429를 인증 문제로 오해하기 쉽습니다.
기업 출구·DNS가 쿼터처럼 보일 때
스플릿 DNS, 캡티브 포털, TLS 인스펙션은 HTTP 200에 빈 본문이나 극단적 지연을 만들어 레이트리밋처럼 보입니다. Gateway 호스트의 이그레스 경로를 공급자 매트릭스와 함께 문서화하고, VNC에서 Safari나 서비스와 동일 사용자 맥락의 curl로 도달성을 확인하세요. 대화형 SSH와 launchd는 프록시/환경이 다를 수 있습니다.
런북 순서: PID 환경 → allowlist diff → 최소 재현 → 병렬
실행 중인 Gateway PID에 보이는 환경 변수를 먼저 확인하고, 릴리스 노트와 유효 allowlist를 대조한 뒤 정책이 허용하면 LLM 밖에서 최소 쿼리를 재현하고, 마지막에 도구 병렬과 서브에이전트를 줄입니다. 업그레이드 후 group:web만 빠졌는데 키만 돌리는 패턴이 시간을 가장 태웁니다.
대시보드 너머 비용·안전 가드레일
콘솔은 월 합계를 보여 주지만 에이전트는 버스트를 만듭니다. 공급자 상한 외에 대화당 최대 병렬 검색, 유사 쿼리 중복 제거, 민감 채널용 「검색 끄기」 모드를 오케스트레이션에 두세요. 이유는 SOUL/MEMORY에 남겨 6개월 뒤에도 왜 allowlist가 빡센지 알 수 있게 합니다.
검색 공급자 판단표(참고)
| 패턴 | 적합 | 주의 |
|---|---|---|
| Brave Search(흔한 기본값) | 일반 검색·프라이버시 | 월 한도·인용 정책 |
| Tavily 등 AI API | 에이전트용 JSON 스니펫 | 유료·include_domains |
| Perplexity류 | 링크 있는 요약 | 비용·컴플라이언스 |
| Gemini/Google 키 | Google AI 과금 통합 | SecretRef 로테이션 |
| fetch 측 Firecrawl | 단일 URL·봇 페이지 | 검색과 쿼터 분리 |
| Bing/넓은 SERP API | 전통 블루링크·지역 SERP | 컴플라이언스·캐시; 원시 SERP 장기 저장 금지일 수 있음 |
| 자체 검색/인트라넷 인덱스 | 공개 검색이 정책상 불가·오프라인 | 신선도·SLO·임베딩 파이프라인까지 자체 책임 |
9단계 활성화·검증
doctor 베이스라인
openclaw doctor에서 web/search/tools 언급 줄을 버전과 함께 보관.
web 설정 마법사
openclaw configure --section web 또는 tools.web.search JSON. 키는 커밋 금지.
데몬과 동일 경로로 키
plist/서비스가 읽는 환경에 TAVILY_API_KEY 등. 재부팅 테스트.
allowlist 정합
web_search·필요 시 web_fetch.
실제 채널 카나리아
공개 웹 사실 질문으로 로그 지연·에러 확인.
승인 게이트
before_tool_call이면 채널 UI로 승인 후 재실행.
순서대로 분석
401/403→키·ACL; 429→백오프·병렬; timeout→경로; 빈 JSON→필터 완화.
재현 패키지 보관
마스킹된 로그, 비밀 없는 tools.web 조각, allowlist 요약을 사건별로 저장해 업그레이드 후와 비교.
성능 저하 모드 사전 정의
검색 읽기 전용/저빈도 안내 문구, 서브에이전트 중단, 정책 허용 시 소형 모델 전환을 문서화. 당일 즉흥이 아니라 절차로.
인용 가능 운영 메모
티켓 전 체크
- Doctor output archived with version
- Provider block present in JSON or wizard transcript
- Effective allowlist contains web tools
- Secrets visible to the running Gateway process
- Canary query reproduced from the same channel users rely on
VNC 원격 Mac: 콘솔·권한
원격 Mac에서 Gateway UI를 열고 SSH로 로그 tail. 시간 동기·MITM·메뉴바 동반 앱 확인. 시스템 동의는 GUI 세션에서 처리해야 합니다.
그래픽 세션에서 키체인이나 시크릿 UI를 열어 plist가 가리키는 자격 증명이 실제로 있고 만료되지 않았는지 확인하세요. 로컬 터미널 테스트와 프로덕션 서비스를 섞으면 운영자 계정과 서비스 계정에 가까운 두 브라우저 맥락으로 나눠 잘못된 「연결 확인」을 피하세요.
관련 글
승인: 플러그인 승인. 브라우저: Chrome MCP. 침묵: 무응답. 상주: launchd.
FAQ
- UI가 여전히 disabled? allowlist·provider·Gateway 환경. env 수정 후 doctor.
- 검색 되는데 Firecrawl?
web_fetch보조. 예산은 검색과 분리. - 429에 벤더 유지? 병렬·지수 백오프·캐시부터.
- MCP가 더 안전? 위협 모델이 다름. SOUL/MEMORY에 기록.
- 노트북과 원격 Mac 결과가 다른 이유? DNS, PAC, 시스템 언어/지역, IPv6 선호가 SERP를 바꿉니다. 반드시 Gateway 호스트에서 재현하세요.
- 검색 결과를 워크스페이스에 캐시해도 되나요? 컴플라이언스와 보존 정책이 허용할 때만. SERP는 빨리 낡으니 짧은 TTL과 프로바이더 메타데이터 보관을 권장.
맺음말
리눅스 VM·헤드리스만으로는 동의·콘솔 단서가 숨고, 잘못된 사용자 맥락에서 한 「연결 확인」도 생깁니다. VNC로 실제 macOS 데스크톱을 보면 키 로드부터 Gateway 오버레이까지 한 줄로 추적할 수 있고, 승인·키체인·브라우저 인접 디버깅이 섞일 때 특히 유리합니다. 짧은 실험이면 VNCMac의 VNC Mac과 사이트 체크리스트가 부적절한 호스트에서 로그 조각만 쫓는 것보다 시간을 아낄 때가 많습니다.