AI 리서치 에이전트 만들기 — OpenClaw로 자동화된 리서치 파이프라인 구축기

들어가며

AI 에이전트가 단순한 챗봇을 넘어 자율적으로 작업을 수행하는 시대가 왔다. 오늘은 OpenClaw 멀티에이전트 시스템에서 “일반 리서치 에이전트”를 구축한 과정을 공유한다. 검색 프롬프트 설계부터 다중 소스 검색, 보고서 자동 생성까지 — AI가 혼자서 리서치를 완수하는 시스템을 만들어보았다.

왜 리서치 에이전트인가?

매일 뉴스, 인물, 이슈에 대한 정보를 찾아야 하는 상황이 많다. 그때마다 여러 사이트를 돌아다니며 검색하고, 결과를 정리하고, 보고서를 쓰는 건 시간 낭비다.

목표: “이정현 사퇴에 대해 리서치해줘” 한 마디면, AI가 알아서 검색하고 보고서까지 만들어주는 시스템.

전체 아키텍처

최종 구조는 이렇다:

사용자: "○○에 대해 리서치해줘"
  → Sunny (메인 비서): researcher-general 에이전트 spawn
    → 기획 에이전트 (Sonnet 4.6): 자율 수행
      ① 프롬프트 설계 (다각도 검색 키워드)
      ② 구글검색 (Gemini CLI → exec)
      ③ 국내검색 (네이버 Open API → 스킬)
      ④ 글로벌검색 (Tavily → 스킬)
      ⑤ 결과 수합 → 보고서 작성 → 파일 저장
    ← 완료 보고 (자동 announce)
  ← Sunny: 사용자에게 결과 전달

핵심 설계 원칙:

메인 비서(Sunny)는 개입하지 않는다 — spawn만 하고 결과를 기다림
기획 에이전트가 전체 플로우를 자율 수행
3개 검색 소스를 반드시 모두 사용 (다양한 관점 확보)

Step 1: 에이전트 설정 (OpenClaw Config)

OpenClaw의 agents.list에 에이전트를 등록한다:

{
  "id": "researcher-general",
  "name": "일반리서치 (기획)",
  "model": {
    "primary": "anthropic/claude-sonnet-4-6",
    "fallbacks": ["anthropic/claude-haiku-4-5"]
  },
  "skills": ["naver-search", "naver-news", "tavily-search"],
  "tools": {
    "profile": "full",
    "allow": ["group:web", "group:memory", "group:fs",
              "group:messaging", "exec", "sessions_spawn", "subagents"]
  }
}

포인트:

tools.profile은 반드시 “full”로! “minimal”로 하면 파일 저장(write) 등 도구가 차단되어 보고서 저장이 안 된다. (이걸로 한참 삽질했다)
skills에 검색 스킬을 직접 할당하면 exec 없이 스킬 스크립트를 호출할 수 있다
Gemini CLI만 외부 바이너리이므로 exec 권한이 필요

Step 2: ROLE.md — 에이전트의 행동 규칙

에이전트가 어떻게 행동할지 agents/researcher-general/ROLE.md에 정의한다. 핵심은 전체 플로우를 명확하게 지시하는 것:

1단계: 프롬프트 설계 (다각도 키워드) 2단계: 3개 검색 소스 모두 실행 (필수!) 3단계: 결과 수합 → 보고서 작성 4단계: 파일 저장

핵심: “3개 소스 모두 필수”를 강조 표시까지 넣어야 에이전트가 하나만 쓰고 끝내지 않는다. AI도 귀찮으면 지름길을 탄다.

Step 3: 검색 소스 설정

구글검색 — Gemini CLI

gemini -m gemini-3-flash-preview -p "검색할 내용" --approval-mode yolo

Gemini CLI는 구글의 네이티브 검색을 활용하기 때문에 실시간 정보에 강하다. 반드시 exec로 호출해야 한다.

국내검색 — 네이버 Open API

네이버 개발자센터에서 발급받은 Client ID/Secret으로 직접 호출한다. 처음에는 SerpAPI(유료)를 경유하는 구조였는데, 네이버 Open API 직접 호출로 전면 교체했다. 외부 패키지 의존성 0, Python 표준 라이브러리만 사용.

지원 API: 뉴스, 웹, 쇼핑, 이미지, 블로그, 지역(장소)

Tavily 검색

AI 에이전트에 최적화된 검색 API. 무료 플랜으로 월 1,000회 호출 가능.

Step 4: 삽질의 기록 (트러블슈팅)

문제 1: 에이전트가 파일을 저장하지 않는다

증상: 텍스트 반환은 되는데, 파일 저장에서 도구를 호출하지 않고 끝남.

원인: tools.profile: “minimal” — 이 설정은 session_status만 허용한다. write 도구가 차단되어 파일 저장 불가.

해결: tools.profile: “full”로 변경. 이것 하나로 해결.

문제 2: 에이전트가 Gemini CLI를 안 쓴다

증상: ROLE.md에 3개 소스 필수라고 써놨는데, Tavily만 쓰고 끝냄.

원인: 에이전트가 “이미 충분한 결과를 얻었다”고 판단하고 나머지를 건너뜀.

해결: ROLE.md에 강한 표현과 경고 표시 추가. AI에게도 명확한 지시가 필요하다.

문제 3: 네이버 검색 401 에러

증상: 네이버 API 호출 시 401 Unauthorized.

원인: 환경변수가 게이트웨이 프로세스에 로드되지 않음. .zshrc에 등록해도 LaunchAgent로 시작되는 게이트웨이는 .zshrc를 읽지 않는다.

해결: LaunchAgent plist 파일의 EnvironmentVariables에 직접 추가.

문제 4: SerpAPI 의존성 제거

네이버 검색 스킬이 SerpAPI(유료)를 경유하는 구조였던 것을 네이버 Open API 직접 호출로 전면 재작성. 외부 패키지 0개.

실제 작동 결과

“이정현 사퇴에 대해 리서치해줘”라고 요청하면:

기획 에이전트 자동 spawn (약 2~3초)
프롬프트 설계 — 다각도 검색 키워드 자동 생성
3개 소스 병렬 검색 — 네이버 뉴스 + Tavily + Gemini 종합 분석
보고서 자동 생성 — 마크다운 형식, 출처 URL 포함
파일 자동 저장
결과 자동 보고 — 메인 비서에게 announce → 사용자에게 전달

전체 소요 시간: 약 2분 30초. 사람이 같은 작업을 하면 최소 30분은 걸린다.

배운 것들

AI 에이전트도 지름길을 탄다 — 명확하고 강한 지시가 필요하다
tools.profile이 핵심 — 도구 접근 권한을 꼼꼼히 확인해야 한다
환경변수는 프로세스 단위 — LaunchAgent와 쉘 환경은 별개다
외부 의존성은 줄일수록 좋다 — SerpAPI → 네이버 직접 호출로 간소화
ROLE.md는 에이전트의 DNA — 여기에 뭘 쓰느냐가 에이전트의 행동을 결정한다

마치며

AI 에이전트 시스템은 아직 초기 단계지만, 가능성은 무궁무진하다. “검색해서 정리해줘” 한 마디로 다중 소스 리서치 보고서가 자동 생성되는 세상. 다음에는 학술 논문 리서치 에이전트도 만들어볼 예정이다.

직접 만들어보고 싶다면 OpenClaw를 확인해보자. 오픈소스이고, 멀티에이전트 지원이 잘 되어 있다.