OpenClaw에서 Brave Search 쓰는 법: 완전 설정 가이드

갓 설치한 OpenClaw는 생각은 할 줄 알지만 찾아보는 건 못 해요. 웹 검색 공급자가 빠진 채로 출고되기 때문에, 모델의 학습 데이터보다 새로운 걸 물어보면 솔직하게 모른다고 하거나 슬쩍 지어내죠. 해결책은 5분이면 돼요. Brave Search API를 연결하는 거예요. 저희는 PlusAgents에서 OpenClaw 호스팅을 업으로 하고 있는데, 사람들이 가장 많이 설정하는 검색 공급자가 바로 Brave예요. 이 가이드에서 설정의 전 과정을 다룰게요. 키 발급, 설정, 테스트, 튜닝, 그리고 파워 유저를 위한 새 Brave 스킬까지.

왜 다들 Brave부터 찾을까

OpenClaw는 검색 공급자를 여럿 지원하지만(Perplexity, Exa, Firecrawl, DuckDuckGo 등등), 설정 마법사가 제일 먼저 권하는 것도, 커뮤니티가 실제로 쓰는 것도 Brave예요. 이유는 세 가지예요. 첫째, Brave는 Google이나 Bing 결과를 되파는 대신 자체 독립 웹 인덱스를 운영해요. 그만큼 SEO 장난질에 덜 오염됐고 프라이버시도 진지하게 지켜요. 둘째, 처음부터 AI 에이전트용 API로 설계됐어요. 뒤에서 다룰 LLM 친화적인 컨텍스트 모드도 있고요. 셋째, 가격에 토를 달기 어려워요. 모든 플랜에 매달 갱신되는 $5 무료 크레딧이 들어 있고, Search 플랜은 요청 1,000건당 $5예요. 대략 월 1,000회 쿼리가 공짜라는 뜻이니, 개인 비서의 하루 일과에는 넉넉하고도 남아요.

얼리어답터를 위한 각주 하나. Brave의 예전 무료 플랜(월 2,000회 쿼리)을 아직 갖고 있다면 계속 작동하긴 하지만, LLM Context 엔드포인트 같은 최신 기능은 안 들어 있어요. 새로 시작한다면 Search 플랜을 쓰세요.

1단계: Brave API 키 발급받기

1. Brave Search API 대시보드에서 계정을 만드세요. 이메일과 비밀번호면 끝, 별다른 절차는 없어요.
2. "My subscriptions"에서 Search 플랜을 구독하세요. $5 월 크레딧은 자동으로 적용돼요.
3. 대시보드에서 사용량 한도를 걸어 두세요. 필수는 아니지만 현명한 선택이에요. 한도를 $5로 잡아 두면 영원히 무료로 쓰는 셈이고, 폭주한 에이전트가 카드 명세서를 놀라게 할 일도 없어요.
4. "API Keys" 섹션에서 키를 생성하고 안전한 곳에 복사해 두세요.

2단계: OpenClaw에 키 알려 주기

키를 OpenClaw에 넘기는 방법은 세 가지예요. 도착지는 전부 같으니, 성향에 맞는 걸 고르세요.

마법사 (추천)

openclaw configure --section web

OpenClaw의 대화형 마법사가 어떤 웹 검색 공급자를 쓸지 묻고, 키를 입력받고, 검증하고, 설정의 올바른 자리에 적어 줘요. JSON도, 오타도, 옛날 블로그에서 주워들은 민간요법도 필요 없어요.

설정 파일

설정을 직접 고치는 쪽이 좋다면(혹은 배포를 스크립트로 처리한다면) ~/.openclaw/openclaw.json을 여세요. 키의 표준 자리는 plugins.entries.brave.config.webSearch.apiKey이고, 공급자 스위치는 tools.web.search 아래에 있어요:

{
  "plugins": {
    "entries": {
      "brave": {
        "config": {
          "webSearch": {
            "apiKey": "YOUR_BRAVE_API_KEY"
          }
        }
      }
    }
  },
  "tools": {
    "web": {
      "search": {
        "provider": "brave",
        "maxResults": 5,
        "timeoutSeconds": 30
      }
    }
  }
}

키를 tools.web.search.apiKey에 두라는 옛날 가이드도 보일 거예요. 그 경로도 호환 심을 통해 여전히 로드되긴 하지만 어디까지나 레거시예요. Brave 플러그인은 plugins 경로를 먼저 읽으니, 새로 설정한다면 표준 경로를 써서 나중에 헷갈릴 오후를 미리 아끼세요.

환경 변수

export BRAVE_API_KEY="your-key-here"

OpenClaw는 폴백으로 Gateway 환경 변수에서 BRAVE_API_KEY를 읽어요. 설정 파일보다 환경 변수가 편한 Docker 같은 컨테이너 환경에서는 이쪽이 자연스러운 길이에요.

어느 길을 택했든, 변경 사항이 반영되게 Gateway를 재시작하세요:

openclaw gateway restart

3단계: 진짜 되는지 확인하기

모델이 도저히 알 리 없는 걸 에이전트에게 물어보세요. "이번 주에 나온 OpenClaw 최신 릴리스에 뭐가 들어갔어?"라든가 "지금 서울 날씨 어때?" 같은 거요. 에이전트가 web_search 도구를 호출하고, 5초 전에는 갖고 있지도 않던 답을 출처와 URL까지 곁들여 들고 오는 걸 지켜보세요. 테스트는 그게 전부예요. 검색 대신 기억으로 대답한다면 웹을 검색하라고 콕 집어 말해 주고, 도구가 에러를 낸다면 아래 문제 해결 섹션으로 건너뛰세요(스포일러: 거의 항상 재시작이 답이에요).

튜닝: 진짜 중요한 설정들

• maxResults. 검색이 돌려주는 결과 수로, 1에서 10 사이예요(기본값 5). 결과가 많을수록 컨텍스트도 토큰도 늘어나요. 5가 무난한 기본값이에요.
• 최신성과 날짜 필터. 에이전트가 결과를 최근 하루, 일주일, 한 달, 1년으로 좁히거나 정확한 날짜 범위를 지정할 수 있어요. 낡은 결과가 없느니만 못한 "그 뒤로 뭐가 바뀌었지..." 류의 질문에 유용해요.
• 국가와 언어. 검색을 지역화할 수 있어요. 예를 들어 국가 DE에 언어 de를 지정하면 독일어 결과가 나와요. 여러 언어로 일한다면 에이전트가 조용히 덕을 봐요.
• llm-context 모드. plugins 설정에서 webSearch.mode를 "llm-context"로 바꾸면, 클래식 결과(제목, URL, 스니펫) 대신 Brave의 LLM Context API를 써요. 그라운딩에 바로 쓸 수 있게 미리 추출된 텍스트 조각이 돌아오죠. 페이지를 추가로 여는 횟수는 줄고, 리서치가 많은 작업에서 답의 질은 올라가요.
• 캐싱. 동일한 검색은 기본 15분 동안 캐시돼요(cacheTtlMinutes로 조절 가능). 의욕 넘치는 에이전트가 같은 질문을 반복하며 쿼터를 태우는 일을 막아 줘요.

파워 유저의 길: Brave의 bx CLI를 스킬로

2026년, Brave는 bx를 내놨어요. AI 에이전트를 위해 특별히 만든 의존성 제로의 Search API 명령줄 클라이언트로, 에이전트에게 사용법을 가르치는 공식 OpenClaw 스킬도 함께 나왔어요. 내장 공급자와 비교하면 고급 엔드포인트가 손에 들어와요. bx context는 토큰 예산에 맞춰 미리 추출한 웹 콘텐츠를 호출 한 번으로 돌려주고, Goggles를 쓰면 커스텀 규칙으로 결과를 재정렬할 수 있어요(문서는 위로, SEO 스팸은 아래로). 내장 공급자가 검색창이라면, bx는 리서치 조수예요.

먼저, 공식 스크립트로 CLI를 설치하세요(바이너리가 어디에 설치됐는지 출력해 줘요, 보통은 ~/.local/bin이에요):

curl -fsSL https://raw.githubusercontent.com/brave/brave-search-cli/main/scripts/install.sh | sh

다음으로, 인자 없이 bx config set-key를 실행해 키를 설정하세요. 대화형으로 물어보기 때문에 키가 셸 히스토리에 남지 않아요. 그다음, OpenClaw가 바이너리를 찾을 수 있게 해 주고 Gateway를 재시작하세요:

openclaw config set tools.exec.pathPrepend '["/home/you/.local/bin"]'
openclaw gateway restart

마지막으로, ClawHub에서 스킬을 설치하세요:

openclaw skills install bx-search

이제부터 에이전트는 웹 리서치에 bx를 먼저 집어 들어요. /skill bx-search "질문 내용"처럼 명시적으로 부를 수도 있는데, 에이전트가 고집스럽게 내장 도구만 찾을 때 유용해요. 두 방식은 사이좋게 공존해요. 내장 Brave 공급자가 든든한 기본기라면, 스킬은 업그레이드예요.

PlusAgents에서는 채팅에 키 붙여 넣기

OpenClaw를 PlusAgents에서 돌리고 있다면 터미널도 파일 편집도 등장할 일이 없어요. 에이전트가 자기 설정에 완전히 접근할 수 있어서, 설정 전체가 채팅 메시지 하나로 끝나요. "여기 내 Brave Search API 키야: BSA... 웹 검색에 Brave를 쓰도록 스스로 설정하고, Gateway 재시작해 줘." 그러면 에이전트가 키를 표준 설정 경로에 적고, 재시작하고, 확인까지 해 줘요. 소프트웨어에게 스스로를 재설정하라고 부탁하는 건 처음엔 묘한 기분인데, 사실 그게 에이전트를 돌리는 이유의 전부죠.

아직 에이전트가 없다면 무료 플랜으로 1분 정도 만에 진짜 OpenClaw 인스턴스를 받을 수 있어요. LLM 크레딧도 포함이에요. 그 밖의 실행 방법이 궁금하다면 배포 가이드에서 전부 비교해 뒀어요.

문제 해결과 안전하게 쓰기

• 설정을 바꿨는데 아무 일도 안 일어난다면? Gateway를 재시작하세요. "안 돼요" 신고의 부동의 1위이고, openclaw gateway restart가 처방이에요.
• 에러가 나거나 결과가 비어 있다면? Brave 대시보드에서 구독이 활성 상태인지, 키가 내가 생각하는 그 키가 맞는지 확인하세요. 삭제된 구독의 키는 조용히 실패해요.
• 한도에 자꾸 부딪힌다면? 무료 크레딧은 월 1,000회 쿼리 정도를 커버해요. 리서치가 많은 에이전트는 이걸 금방 태울 수 있으니, 대시보드의 사용량 그래프를 지켜보고 한도는 얼떨결에가 아니라 의도적으로 올리세요.
• 제대로 된 진단이 필요하다면? brave.http 진단 플래그를 켜면 OpenClaw가 요청 URL, 응답 시간, 캐시 적중 여부를 로그로 남겨요. API 키는 절대 로그에 남기지 않아요.
• 키 위생. 사용량 한도를 걸고, 키를 명령줄 플래그로 넘기지 말고(셸 히스토리에 남아요), 유출이 의심되는 순간 대시보드에서 폐기하세요.

이게 다예요. 이제 에이전트는 자신만만하게 기억을 더듬는 대신 진짜로 조사할 수 있어요. OpenClaw 여정이 아직 초반이라면 OpenClaw 사용법 가이드가 갓 설치한 인스턴스를 일주일 만에 일상 비서로 바꿔 줄 거예요. OpenClaw가 뭔지부터 궁금하다면 여기서 시작하세요.