Tools
웹 가져오기
web_fetch는 일반 HTTP GET을 수행하고 읽기 가능한 콘텐츠(HTML을
Markdown 또는 텍스트로 변환)를 추출합니다. JavaScript는 실행하지 않습니다. JS 의존도가 높은 사이트나
로그인으로 보호된 페이지에는 대신 웹 브라우저를 사용하세요.
빠른 시작
기본적으로 활성화되어 있으며 구성이 필요하지 않습니다.
await web_fetch({ url: "https://example.com/article" });도구 매개변수
urlstringrequired가져올 URL입니다. http(s)만 지원합니다.
extractMode'markdown' | 'text'default: markdown주요 콘텐츠 추출 후의 출력 형식입니다.
maxCharsnumber출력을 지정한 문자 수로 자릅니다. tools.web.fetch.maxCharsCap 범위로 제한됩니다.
작동 방식
가져오기
Chrome과 유사한 User-Agent 및 Accept-Language 헤더로 HTTP GET을
전송합니다. 비공개/내부 호스트 이름을 차단하고 리디렉션을 다시 검사합니다.
추출
HTML 응답에 Readability(주요 콘텐츠 추출)를 실행합니다.
대체 처리(선택 사항)
Readability가 실패하고 가져오기 제공자를 사용할 수 있으면 해당 제공자를 통해 다시 시도합니다(예: Firecrawl의 봇 우회 모드).
캐시
동일한 URL의 반복적인 가져오기를 줄이기 위해 결과를 15분 동안 캐시합니다 (구성 가능).
진행 상황 업데이트
web_fetch는 5초 후에도 가져오기가 대기 중인 경우에만 공개 진행 상황 줄을
출력합니다.
페이지 콘텐츠를 가져오는 중...빠른 캐시 적중과 신속한 네트워크 응답은 타이머가 실행되기 전에 완료되므로 진행 상황 줄이 표시되지 않습니다. 호출을 취소하면 타이머가 해제됩니다. 진행 상황 줄은 채널 UI 상태일 뿐이며 가져온 페이지 콘텐츠를 절대 포함하지 않습니다.
구성
{ tools: { web: { fetch: { enabled: true, // 기본값: true provider: "firecrawl", // 선택 사항. 자동 감지하려면 생략 maxChars: 20000, // 기본 출력 문자 수. maxCharsCap으로 제한됨 maxCharsCap: 20000, // maxChars 매개변수의 상한 maxResponseBytes: 750000, // 잘라내기 전 최대 다운로드 크기(32000~10000000) timeoutSeconds: 30, cacheTtlMinutes: 15, maxRedirects: 3, useTrustedEnvProxy: false, // 신뢰할 수 있는 HTTP(S) 환경 프록시가 DNS를 확인하도록 허용 readability: true, // Readability 추출 사용 userAgent: "Mozilla/5.0 ...", // User-Agent 재정의 ssrfPolicy: { allowRfc2544BenchmarkRange: true, // 198.18.0.0/15를 사용하는 신뢰할 수 있는 가상 IP 프록시를 위한 명시적 허용 allowIpv6UniqueLocalRange: true, // fc00::/7을 사용하는 신뢰할 수 있는 가상 IP 프록시를 위한 명시적 허용 }, }, }, },}Firecrawl 대체 처리
Readability 추출이 실패하면 web_fetch는 봇 우회와 향상된 추출을 위해
Firecrawl을 대체 수단으로 사용할 수 있습니다.
{ tools: { web: { fetch: { provider: "firecrawl", // 선택 사항. 사용 가능한 자격 증명에서 자동 감지하려면 생략 }, }, }, plugins: { entries: { firecrawl: { enabled: true, config: { webFetch: { // apiKey: "fc-...", // 선택 사항. 키 없는 스타터 액세스를 사용하려면 생략 baseUrl: "https://api.firecrawl.dev", onlyMainContent: true, maxAgeMs: 172800000, // 캐시 기간(2일) timeoutSeconds: 60, }, }, }, }, },}plugins.entries.firecrawl.config.webFetch.apiKey는 선택 사항이며 SecretRef 객체를 지원합니다.
레거시 tools.web.fetch.firecrawl.* 구성은 openclaw doctor --fix를 통해
plugins.entries.firecrawl.config.webFetch로 자동 마이그레이션됩니다.
현재 런타임 동작:
tools.web.fetch.provider는 가져오기 대체 제공자를 명시적으로 선택합니다.provider를 생략하면 OpenClaw는 구성된 자격 증명에서 준비된 첫 번째 웹 가져오기 제공자를 자동 감지합니다. 샌드박스 외부의web_fetch는contracts.webFetchProviders를 선언하고 런타임에 일치하는 제공자를 등록하는 설치된 Plugin을 사용할 수 있습니다. 현재 공식 Firecrawl Plugin이 이 대체 기능을 제공합니다.- 샌드박스의
web_fetch호출은 번들 제공자와 공식 npm 또는 ClawHub 출처가 확인된 설치 제공자를 허용합니다. 현재는 공식 Firecrawl Plugin이 허용되며, 서드 파티 외부 가져오기 Plugin은 계속 제외됩니다. - Readability가 비활성화된 경우
web_fetch는 선택된 제공자 대체 처리로 바로 넘어갑니다. 사용 가능한 제공자가 없으면 안전하게 실패합니다.
신뢰할 수 있는 환경 프록시
배포 환경에서 web_fetch가 신뢰할 수 있는 아웃바운드 HTTP(S) 프록시를
통과해야 하는 경우 tools.web.fetch.useTrustedEnvProxy: true를 설정하세요.
이 모드에서도 OpenClaw는 요청을 보내기 전에 호스트 이름 기반 SSRF 검사를 적용하지만, 로컬 DNS 고정 대신 프록시가 DNS를 확인하도록 허용합니다. 프록시가 운영자의 통제하에 있고 DNS 확인 후에도 아웃바운드 정책을 적용하는 경우에만 이를 활성화하세요.
제한 및 안전성
maxChars는tools.web.fetch.maxCharsCap(기본값20000) 범위로 제한됩니다.- 응답 본문은 구문 분석 전에
maxResponseBytes(기본값750000, 32000~10000000으로 제한됨)로 제한되며, 크기를 초과한 응답은 경고와 함께 잘립니다. - 비공개/내부 호스트 이름은 차단됩니다.
tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange및tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange는 신뢰할 수 있는 가상 IP 프록시 스택만을 위한 제한적인 명시적 허용입니다. 프록시가 해당 합성 범위를 소유하고 자체 대상 정책을 적용하지 않는 한 설정하지 마세요.- 리디렉션은 검사되며
maxRedirects(기본값3)로 제한됩니다. useTrustedEnvProxy는 명시적으로 활성화해야 하며, DNS 확인 후에도 아웃바운드 정책을 적용하는 운영자 통제 프록시에만 활성화해야 합니다.web_fetch는 최선형 기능입니다. 일부 사이트에는 웹 브라우저가 필요합니다.
도구 프로필
도구 프로필이나 허용 목록을 사용하는 경우 web_fetch 또는 group:web을 추가하세요.
{ tools: { allow: ["web_fetch"], // 또는: allow: ["group:web"] (web_fetch, web_search 및 x_search 포함) },}