Tools
웹 가져오기
web_fetch 도구는 일반 HTTP GET을 수행하고 읽을 수 있는 콘텐츠를 추출합니다
(HTML을 markdown 또는 text로 변환). JavaScript는 실행하지 않습니다.
JS가 많은 사이트나 로그인으로 보호된 페이지에는 대신 웹 브라우저를 사용하세요.
빠른 시작
web_fetch는 기본적으로 활성화되어 있습니다 -- 설정이 필요 없습니다. 에이전트가
즉시 호출할 수 있습니다.
await web_fetch({ url: "https://example.com/article" });
도구 매개변수
urlstringrequired가져올 URL입니다. http(s)만 지원합니다.
extractMode'markdown' | 'text'주요 콘텐츠 추출 후 출력 형식입니다.
maxCharsnumber출력을 지정한 문자 수로 잘라냅니다.
작동 방식
Fetch
Chrome과 유사한 User-Agent 및 Accept-Language 헤더로 HTTP GET을
보냅니다. 비공개/내부 호스트 이름을 차단하고 리디렉션을 다시 확인합니다.
Extract
HTML 응답에서 Readability(주요 콘텐츠 추출)를 실행합니다.
Fallback (optional)
Readability가 실패하고 Firecrawl이 설정되어 있으면 봇 우회 모드로 Firecrawl API를 통해 다시 시도합니다.
Cache
동일한 URL의 반복 가져오기를 줄이기 위해 결과를 15분 동안(설정 가능) 캐시합니다.
설정
{
tools: {
web: {
fetch: {
enabled: true, // default: true
provider: "firecrawl", // optional; omit for auto-detect
maxChars: 50000, // max output chars
maxCharsCap: 50000, // hard cap for maxChars param
maxResponseBytes: 2000000, // max download size before truncation
timeoutSeconds: 30,
cacheTtlMinutes: 15,
maxRedirects: 3,
useTrustedEnvProxy: false, // let a trusted HTTP(S) env proxy resolve DNS
readability: true, // use Readability extraction
userAgent: "Mozilla/5.0 ...", // override User-Agent
ssrfPolicy: {
allowRfc2544BenchmarkRange: true, // opt-in for trusted fake-IP proxies using 198.18.0.0/15
allowIpv6UniqueLocalRange: true, // opt-in for trusted fake-IP proxies using fc00::/7
},
},
},
},
}
Firecrawl 폴백
Readability 추출이 실패하면 web_fetch는 봇 우회와 더 나은 추출을 위해
Firecrawl로 폴백할 수 있습니다.
{
tools: {
web: {
fetch: {
provider: "firecrawl", // optional; omit for auto-detect from available credentials
},
},
},
plugins: {
entries: {
firecrawl: {
enabled: true,
config: {
webFetch: {
apiKey: "fc-...", // optional if FIRECRAWL_API_KEY is set
baseUrl: "https://api.firecrawl.dev",
onlyMainContent: true,
maxAgeMs: 86400000, // cache duration (1 day)
timeoutSeconds: 60,
},
},
},
},
},
}
plugins.entries.firecrawl.config.webFetch.apiKey는 SecretRef 객체를 지원합니다.
레거시 tools.web.fetch.firecrawl.* 설정은 openclaw doctor --fix로 자동 마이그레이션됩니다.
현재 런타임 동작:
tools.web.fetch.provider는 가져오기 폴백 제공자를 명시적으로 선택합니다.provider가 생략되면 OpenClaw는 사용 가능한 자격 증명에서 준비된 첫 번째 web-fetch 제공자를 자동 감지합니다. 샌드박스가 아닌web_fetch는contracts.webFetchProviders를 선언하고 런타임에 일치하는 제공자를 등록하는 설치된 plugins를 사용할 수 있습니다. 현재 번들 제공자는 Firecrawl입니다.- 샌드박스 처리된
web_fetch호출은 번들 제공자로 제한됩니다. - Readability가 비활성화되어 있으면
web_fetch는 선택된 제공자 폴백으로 바로 건너뜁니다. 사용 가능한 제공자가 없으면 닫힌 상태로 실패합니다.
신뢰할 수 있는 env 프록시
배포에서 web_fetch가 신뢰할 수 있는 아웃바운드 HTTP(S) 프록시를 거쳐야 한다면
tools.web.fetch.useTrustedEnvProxy: true를 설정하세요.
이 모드에서도 OpenClaw는 요청을 보내기 전에 호스트 이름 기반 SSRF 검사를 적용하지만, 로컬 DNS 고정을 수행하는 대신 프록시가 DNS를 확인하도록 합니다. 프록시가 운영자가 제어하며 DNS 확인 후 아웃바운드 정책을 적용하는 경우에만 활성화하세요.
제한 및 안전성
maxChars는tools.web.fetch.maxCharsCap로 제한됩니다- 응답 본문은 파싱 전에
maxResponseBytes로 제한되며, 너무 큰 응답은 경고와 함께 잘립니다 - 비공개/내부 호스트 이름은 차단됩니다
tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange와tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange는 신뢰할 수 있는 가짜 IP 프록시 스택을 위한 좁은 옵트인입니다. 프록시가 해당 합성 범위를 소유하고 자체 대상 정책을 적용하지 않는 한 설정하지 마세요- 리디렉션은 확인되며
maxRedirects로 제한됩니다 useTrustedEnvProxy는 명시적 옵트인이며, DNS 확인 후에도 아웃바운드 정책을 적용하는 운영자 제어 프록시에만 활성화해야 합니다web_fetch는 최선 노력 방식입니다 -- 일부 사이트에는 웹 브라우저가 필요합니다
도구 프로필
도구 프로필이나 허용 목록을 사용하는 경우 web_fetch 또는 group:web을 추가하세요.
{
tools: {
allow: ["web_fetch"],
// or: allow: ["group:web"] (includes web_fetch, web_search, and x_search)
},
}