01. 세 가지 통증: 빈 도구 목록, 키/쿼터, 업그레이드 후 기능 소실

1) 도구 팔레트에 web_search가 없음: 대개 모델 문제가 아니라 에이전트 프로필/플레인 기능 번들이 웹 조회를 노출하지 않거나 스킬을 받았지만 게이트웨이 재시작 후 재등록되지 않은 경우입니다. Skills 3.24 콘솔 분류의 레이어를 따르고 JSON을 고치기 전에 UI·플러그인 매니페스트·런타임 도구 표를 캡처하세요.

2) 도구는 있는데 401/403/429로 실패: Brave Search와 Tavily는 회전 가능한 API 키와 명확한 이그레스 경로를 가정합니다. 기업 프록시가 api.search.brave.com이나 Tavily를 MITM하면 모호한 타임아웃처럼 보일 수 있습니다. openclaw.json을 다시 쓰기 전에 게이트웨이와 동일한 Unix 사용자로 최소 curl 프로브를 실행하세요.

3) 패치 후 “어제는 검색됐다”: 도구 등록과 플러그인 ABI가 Node 마이너나 오래된 캐시와 어긋날 수 있습니다. v2026.4.5 설치 글에 따라 단일 설치 체인을 고정하고 깨끗이 재시작한 뒤, 여전히 실패하면 태그를 고정하세요. 분류 중에는 호스트 npm 게이트웨이와 컨테이너를 섞지 마세요.

02. Brave / Tavily / 자체 SearXNG 프로바이더 비교

이 표로 10분 안에 검색 공급망을 고르는 틀을 잡습니다. 필드 이름은 릴리스 노트를 따르고, 여기서는 운영 경계에 집중합니다. 도구가 승인 경계를 넘을 때는 MCP 연동·승인 보안도 이어서 읽으세요.

차원	Brave Search API	Tavily 스타일 API	자체 호스팅 SearXNG
온보딩·과금	대시보드 키; 무료 티어는 보통 월 ~2,000쿼리 부근(콘솔에서 확인)	호출당 티어; 버스트 실험에 적합	초기 구축 비용은 높으나 장기 상각
컴플라이언스·데이터 상주	ToS/로그 검토; 쿼리가 네트워크 밖으로 나갈 수 있음	프롬프트에 인트라넷 호스트명이 있으면 동일 주의	VPC 안에 쿼리를 가둘 수 있음
OpenClaw 결합	`tools.web.search` provider 문자열 + 키 로테이션	유사; 모델 temperature가 높으면 QPS 증가	MCP나 커스텀 HTTP 래퍼가 필요한 경우가 많음
일일 Mac과 궁합	“키는 되는데 게이트웨이가 못 부른다” 재현에 좋음	쿼터/브레이커 드릴에 유용	내부 DNS/인증서 문제 시뮬레이션

03. 증상 분류: UI·로그·HTTP 오류

“브라우징 불가”를 안 보임 / 보이지만 깨짐 / 들쭉날쭉으로 나눠 JSON을 끝없이 돌리지 않게 합니다. 공개 게이트웨이는 키와 쿼리 텍스트가 모두 새기 쉬우므로 프로덕션에서 분류하기 전에 게이트웨이 Token·SecretRef를 읽으세요.

증상	먼저 확인	추가 읽을거리
UI에 web_search 없음	에이전트 기능 허용 목록, 스킬 토글, 오래된 게이트웨이 PID	Skills 콘솔 분류
도구 호출 401/403	올바른 env에 키 주입, 시계 오차, 계정 혼선	명령 오류 FAQ
429 또는 간헐 타임아웃	쿼터, 프록시, DNS, 동시 도구 폭주	사용량·라우팅 거버넌스

04. 다섯 단계: doctor에서 E2E 검색 스모크까지

버전·설치 체인 고정: openclaw --version, Node 메이저, systemd/launchd/Docker 중 무엇이 게이트웨이를 띄우는지 기록합니다. v2026.4.5 설치 글과 맞추고 분류 중 npm↔컨테이너를 오가지 마세요.
doctor 실행·스니펫 보관: 출력을 티켓에 붙입니다. doctor가 TLS를 지적하면 OpenClaw 밖에서 curl로 검증하고 명령 FAQ 문자열과 매칭하세요.
최소 tools.web.search 블록 작성: 프로바이더와 키는 하나씩. 파일 권한은 게이트웨이 사용자만 읽게 하세요. 채팅 로그에 비밀을 붙이지 마세요.
게이트웨이 재시작·단일 턴 스모크: 무거운 스킬은 끄고 검색 관련 도구만 남기고 사실 조회가 필요한 질문을 던집니다.
이분 탐색 롤백: 마지막으로 동작한 태그를 고정하고 플러그인 목록·설정을 diff합니다. 감사용으로 업그레이드·마이그레이션·롤백에 순서를 기록하세요.

# 최소 진단(경로는 환경에 맞게)
openclaw --version
openclaw doctor
grep -n "web" ~/.openclaw/openclaw.json
curl -sS -o /dev/null -w "%{http_code}\n" "https://api.search.brave.com/res/v1/web/search?q=test"
lsof -i :18789 | head

Linux에서는 리스너 확인에 ss -lntp를 쓰고, Windows는 WSL vs PowerShell 홈 분할을 Windows doctor 글에서 확인하세요.

05. 지표, 키 위생, 흔한 오해

지표 1: 2026년 샘플 스레드에서 “도구 고장”의 약 40~55%는 실제로 설정 미재로드·게이트웨이 미재시작·PATH 분리였습니다. 모델을 만지기 전 최소 스모크를 돌리세요.
지표 2: Brave 일반 무료 티어는 월 약 이천 쿼리 수준(대시보드 확인). 재질의가 공격적인 에이전트는 수 분 안에 429에 걸리고 401이 아닐 수 있습니다.
지표 3: 프로덕션 검색 키를 일일·단기 macOS 사용자에만 두고 노트북에는 Brave/Tavily 비밀을 두지 않으면, 장기 로컬 디버깅 대비 셸 기록·화면 캡처·공유 VNC 등 사이드채널 유출을 대략 한 자릿수 줄인다는 보안 프레이밍이 흔합니다(법적 보증 아님).

오해 A: “강한 모델이면 web_search 불필요”—닫힌 가중치도 변동 사실을 환각합니다. 오해 B: “키를 글로벌 export하면 launchd가 고쳐진다”—비대화형 서비스는 셸 env를 못 읽습니다. 오해 C: “Docker는 항상 비밀을 격리”—잘못된 볼륨 마운트가 호스트 .env를 로그로 새게 합니다.

연결은 SSH/VNC FAQ, 하드웨어 단계는 베어 메탈 macOS 요금, 원격 패턴은 macOS 원격 접속 가이드를 보세요.

tools.web.search + Skills: 네이티브 검색과 ClawHub 웹 검색 스킬을 동시에 켜면 이중 등록·별칭 불일치가 나기 쉽습니다. 모델은 web_search를 보는데 설정은 다른 곳에 있습니다. 공급망 하나로 시작하고 지연·HTTP 코드를 로깅한 뒤 둘째를 추가하세요. 자동 승인은 MCP 연동에 맞춥니다.

키 로테이션: DB 비밀번호를 돌리는 날과 같은 날 누가 키를 만들고·돌리고·폐기하는지 문서화합니다. 이미 SecretRef·지출 상한을 쓰면 검색 QPS를 예산 알림에 넣어 야간 자동화가 쿼터를 못 비우게 하세요.

기업 TLS 검사: Node 신뢰 저장소에 기업 루트가 없으면 불투명한 TLS 오류로 보입니다. 게이트웨이 사용자로 curl/node를 시험하고 컨테이너 vs 호스트 신뢰 번들을 비교하며, 프라이빗 기업 루트를 렌탈 머신에 가져오지 마세요.

429 백오프: temperature를 올려 모델이 “다르게 묻게” 하는 대신 지수 백오프와 동시성 상한을 구현합니다. 실패는 거버넌스 글의 라우팅 폴백과 짝을 이룹니다.

Windows/WSL 분열: Windows에서 openclaw.json을 고치는데 게이트웨이가 WSL 사본을 읽는 전형적인 “파일은 바뀌었는데 프로세스는 안 읽었다” 버그입니다. Windows doctor 가이드로 홈을 하나로 정리하세요.

일일 리허설: 렌탈 → 단일 사용자 설치 체인 → doctor → 최소 검색 설정 → 스모크 → 민감정보를 제거한 로그 저장 → 전원 off. 일일 함정과 함께 공유 VNC 클립보드에 키를 두지 마세요.

분류 순서: 가시성 → 인증(401/403) → 쿼터/네트워크(429/타임아웃) → 버전/플러그인 ABI. 항상 doctor+게이트웨이 로그를 첨부해 명령 FAQ 문자열 매칭에 넘기세요.

06. 헤드리스 Linux·Windows 한계 vs Mac 렌탈

순수 헤드리스 Linux나 Docker Desktop 의존이 큰 Windows 노트북은 CI 프로브에는 쓸 수 있지만 홈 분리, 신뢰 저장소 불일치, 브라우저 콘솔과 게이트웨이 로그 정렬 지연을 자주 만듭니다. 여러 프로덕션 검색 키의 유일한 거처로 삼지 말고 짧은 검증면으로 취급하세요.

Apple과 동일한 TLS·툴체인이 필요하고 자격 증명 리스크를 시간 박스로 묶으려면 먼저 네이티브 macOS에서 검색 스모크를 통과시킨 뒤 Linux/Windows 장기 호스트 여부를 결정하세요. 일일 Mac은 콘솔 패리티를 유지하고 임대 종료 시 환경을 폐기합니다. 렌탈 vs 로컬 비용 시험과 배포 함정을 함께 읽고 런북에 결과를 적으세요.

2026 OpenClaw 웹 검색 플레이북:
web_search 누락, Brave/Tavily 설정·doctor 분류

목차