브라우저 및 웹 도구

브라우저 자동화, 텍스트 브라우저, 웹 페치, 웹 검색, 그리고 도메인 허용 목록이 적용된 HTTP 요청.

Revka는 에이전트가 웹에 접근하는 여러 방법을 제공합니다. 클릭 한 번으로 페이지를 여는 단순한 동작부터 전체 DOM 자동화, 임의의 HTTP 호출까지 다양합니다. 이 페이지는 browser, browser_open, browser_delegate, text_browser, web_fetch, web_search_tool, http_request 도구와 이를 제어하는 [browser], [web_fetch], [web_search], [http_request] 설정 섹션에 대한 참조 문서입니다.

작업에 가장 가벼운 도구를 선택하세요. 정적 페이지를 읽을 때는 web_fetch나 text_browser가 실제 브라우저를 구동하는 것보다 빠르고 비용이 적게 듭니다. JavaScript 렌더링, 로그인, 또는 상호작용이 필요한 페이지에만 browser를 사용하세요. 브라우저 백엔드 단계별 설정, VNC 디버깅, agent-browser 설치 방법은 브라우저 자동화를 참조하세요. 이 페이지는 도구 인터페이스와 설정 키에 집중합니다.

도구 선택 가이드

도구	용도	상호작용	설정 게이트
`browser_open`	승인된 HTTPS URL을 시스템 브라우저에서 열기	없음 (열기만)	`[browser]`
`browser`	전체 DOM 및 OS 수준 자동화	클릭, 폼 입력, 타이핑, 스크린샷, 스크롤 등	`[browser]`
`browser_delegate`	외부 CLI를 통한 기업용 웹 앱	자연어 태스크	`[browser_delegate]`
`text_browser`	headless/SSH 환경에서 페이지를 일반 텍스트로 렌더링	없음 (읽기 전용)	`[text_browser]`
`web_fetch`	페이지를 깔끔한 일반 텍스트로 가져오기 (GET 전용)	없음 (읽기 전용)	`[web_fetch]`
`web_search_tool`	웹 검색으로 제목, URL, 설명 가져오기	없음	`[web_search]`
`http_request`	외부 API에 임의 HTTP 요청	모든 HTTP 메서드	`[http_request]`

browser_open

승인된 HTTPS URL을 시스템 브라우저에서 엽니다. 스크래핑이나 상호작용은 없으며 단순히 페이지를 시작합니다. 내비게이션은 [browser].allowed_domains 허용 목록, HTTPS 전용으로 제한되며 로컬/사설 호스트는 거부됩니다.

{"url": "https://docs.example.com"}

파라미터	타입	필수	의미
`url`	string	예	열 HTTPS URL

browser_open은 전체 browser 도구와 [browser] 설정 섹션 및 allowed_domains 허용 목록을 공유합니다. 둘 다 [browser].enabled로 활성화됩니다.

browser

세 가지 플러그형 백엔드를 지원하는 완전한 웹 자동화 도구입니다. browser 도구는 DOM 액션과 선택적 OS 수준 액션(computer_use 백엔드 전용)을 제공합니다.

{"action": "open", "url": "https://example.com"}
{"action": "snapshot"}
{"action": "click", "selector": "@e3"}

액션

DOM 액션: open, snapshot, click, fill, type, get_text, get_title, get_url, screenshot, wait, press, hover, scroll, is_visible, close, find
OS 수준 액션 (computer_use 백엔드 전용): mouse_move, mouse_click, mouse_drag, key_type, key_press, screen_capture

파라미터

파라미터	타입	의미
`action`	string	위 액션 중 하나 (필수)
`url`	string	내비게이션할 URL (`open`에 사용)
`selector`	string	요소 선택자: `@ref`, CSS, 또는 `text=...`
`value`	string	입력할 값
`text`	string	타이핑하거나 기다릴 텍스트
`key`	string	누를 키 (Enter, Tab, Escape 등)
`x`, `y`	integer	`computer_use` 마우스 액션의 화면 좌표
`from_x`, `from_y`, `to_x`, `to_y`	integer	드래그 시작/종료 좌표
`button`	string	`left`, `right`, 또는 `middle`
`backend`	string	호출별 백엔드 재정의: `agent_browser`, `native`, 또는 `computer_use`

@ref 선택자 모델

open 후 snapshot을 호출하면 상호작용 가능한 요소가 안정적인 ref(@e1, @e2, @e3)에 매핑됩니다. 이 ref를 click, fill, hover 등의 액션에 전달하세요. 선택자는 CSS(button.submit)와 텍스트 매처(text=Accept)도 지원합니다. 페이지 변경 후에는 snapshot을 다시 실행하세요. ref는 매번 다시 계산됩니다.

백엔드

[browser].backend에서 기본 백엔드를 설정하거나 backend 파라미터로 호출별로 재정의할 수 있습니다.

agent_browser (기본값) — agent-browser CLI를 통해 Chrome for Testing을 구동합니다. 서버나 컨테이너에서 가장 쉬운 방법입니다.
rust_native — 내장 WebDriver 백엔드입니다. 빌드에 browser-native Cargo 기능이 컴파일되어 있어야 합니다.
computer_use — 진정한 OS 수준의 마우스, 키보드, 스크린샷 액션을 위해 HTTP를 통해 computer-use 사이드카에 위임합니다.
auto — Revka가 사용 가능한 백엔드를 자동으로 선택합니다.

백엔드 설치 및 디버깅 방법은 브라우저 자동화를 참조하세요.

browser_delegate

자연어 브라우저 태스크를 외부 브라우저 지원 CLI 서브프로세스(예: claude-in-chrome MCP가 적용된 Claude Code)에 위임합니다. 직접 API가 없고 headless 백엔드로는 처리하기 어려운 기업용 웹 앱(Teams, Outlook, Jira, Confluence 등)을 위해 설계되었습니다. 영구 Chrome 프로필을 설정하면 SSO 세션이 실행 간에 유지됩니다.

{"task": "Check my unread Teams messages"}

파라미터	타입	필수	의미
`task`	string	예	자연어 태스크 설명

text_browser

설치된 텍스트 기반 브라우저(lynx, links, 또는 w3m)를 사용하여 웹 페이지를 일반 텍스트로 렌더링합니다. 그래픽 브라우저가 없는 headless 및 SSH 환경에 적합하며, 단순한 HTML 페이지에 가장 효과적입니다. JavaScript 중심의 사이트는 일반적으로 Firecrawl 폴백이 적용된 web_fetch가 필요합니다.

{"url": "https://example.com"}

파라미터	타입	필수	의미
`url`	string	예	가져와서 텍스트로 렌더링할 URL

[text_browser].preferred_browser가 설정되지 않으면 Revka가 설치된 lynx, links, w3m 중 하나를 자동으로 감지합니다.

web_fetch

웹 페이지를 가져와 깔끔한 일반 텍스트로 반환합니다. HTML은 읽기 쉬운 텍스트로 변환되고, JSON과 일반 텍스트는 그대로 반환됩니다. GET 전용이며 리다이렉트를 따릅니다. 표준 페치가 실패할 경우(HTTP 오류, 빈 본문, 또는 100자 미만의 본문으로 JavaScript 전용 페이지가 의심될 때) Firecrawl이 활성화되어 있다면 스텔스 콘텐츠 추출을 위해 Firecrawl API로 폴백할 수 있습니다.

{"url": "https://docs.anthropic.com/en/api/getting-started"}

파라미터	타입	필수	의미
`url`	string	예	가져올 HTTPS URL

web_fetch는 GET 전용이며 출력을 텍스트로 정규화합니다. 다른 HTTP 메서드, 커스텀 헤더, 또는 요청 본문이 필요한 경우 http_request를 사용하세요.

web_search_tool

웹을 검색하여 관련 결과의 제목, URL, 설명을 반환합니다. 폴백 라우팅이 적용된 여러 프로바이더 백엔드를 지원합니다. 기본적으로 API 키가 필요 없는 DuckDuckGo를 사용하며, Brave(API 키 필요)나 자체 호스팅 SearXNG 인스턴스로 전환할 수 있습니다.

{"query": "Rust async runtime comparison 2026"}

파라미터	타입	필수	의미
`query`	string	예	검색 쿼리

http_request

외부 API에 임의 HTTP 요청을 수행합니다. GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS를 지원합니다. 내비게이션은 [http_request].allowed_domains 허용 목록으로 제한되며, 명시적으로 허용하지 않는 한 로컬/사설 호스트는 거부됩니다.

{
  "url": "https://api.example.com/v1/data",
  "method": "POST",
  "headers": {"Authorization": "Bearer REPLACE_WITH_TOKEN"},
  "body": "{\"key\": \"value\"}"
}

파라미터	타입	필수	기본값	의미
`url`	string	예	—	대상 URL
`method`	string	아니오	`GET`	HTTP 메서드
`headers`	object	아니오	`{}`	키-값 HTTP 헤더
`body`	string	아니오	—	POST/PUT/PATCH의 요청 본문

설정

이 모든 도구는 ~/.revka/config.toml에서 설정합니다. 전체 키 참조는 설정: 채널, 도구 & 통합을 확인하세요.

도메인 허용 목록

모든 웹 도구는 동일한 방식의 도메인 허용 목록을 적용합니다.

["*"]는 모든 공개 도메인을 허용하지만 SSRF 보호를 위해 로컬 및 사설 호스트(RFC 1918, 루프백, 링크-로컬, .local)는 여전히 차단됩니다.
web_fetch와 http_request에서 빈 목록([])은 모든 요청을 거부합니다(기본 거부).
특정 항목은 정확한 일치 또는 서브도메인 일치를 사용합니다.
web_fetch와 browser_delegate의 경우 blocked_domains는 항상 allowed_domains보다 우선합니다.

사설 또는 내부 호스트에 접근하려면 web_fetch.allowed_private_hosts에 추가하거나 http_request.allow_private_hosts = true를 설정하세요.

`[browser]`

browser와 browser_open 모두를 제어합니다.

[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"
native_headless = true

키	타입	기본값	의미
`enabled`	bool	`false`	`browser`와 `browser_open`의 마스터 스위치
`allowed_domains`	array	`[]`	내비게이션 허용 목록; `"*"`는 모든 공개 도메인 허용
`session_name`	string	미설정	명명된 브라우저 세션 (인증 상태 유지)
`backend`	string	`"agent_browser"`	`agent_browser`, `rust_native`, `computer_use`, 또는 `auto`
`native_headless`	bool	`true`	rust-native 백엔드의 headless 모드
`native_webdriver_url`	string	`http://127.0.0.1:9515`	rust-native 백엔드의 WebDriver 엔드포인트
`native_chrome_path`	string	미설정	선택적 Chrome/Chromium 실행 파일 경로

[browser.computer_use] 하위 섹션은 OS 수준 사이드카를 설정합니다.

키	타입	기본값	의미
`endpoint`	string	`http://127.0.0.1:8787/v1/actions`	OS 수준 액션을 위한 사이드카 엔드포인트
`api_key`	string	미설정	선택적 베어러 토큰 (암호화 저장)
`timeout_ms`	integer	`15000`	액션별 요청 타임아웃
`allow_remote_endpoint`	bool	`false`	루프백이 아닌 엔드포인트 허용
`window_allowlist`	array	`[]`	사이드카 정책에 전달되는 창 제목/프로세스 허용 목록
`max_coordinate_x` / `max_coordinate_y`	integer	미설정	선택적 좌표 경계

`[browser_delegate]`

[browser_delegate]
enabled = true
cli_binary = "claude"
chrome_profile_dir = "~/.config/chrome-corp-profile"
allowed_domains = ["teams.microsoft.com", "outlook.office.com"]
blocked_domains = []
task_timeout_secs = 120

키	타입	기본값	의미
`enabled`	bool	`false`	`browser_delegate` 도구 활성화
`cli_binary`	string	`"claude"`	브라우저 태스크에 사용할 CLI 바이너리
`chrome_profile_dir`	string	`""`	영구 SSO 세션을 위한 Chrome 사용자 데이터 디렉터리; 비어 있으면 실행마다 새 프로필 사용
`allowed_domains`	array	`[]`	내비게이션 허용 목록; 비어 있으면 차단되지 않은 모든 도메인 허용
`blocked_domains`	array	`[]`	차단 목록; `allowed_domains`보다 우선
`task_timeout_secs`	integer	`120`	태스크별 타임아웃(초)

`[text_browser]`

[text_browser]
enabled = true
preferred_browser = "lynx"   # optional; auto-detects if unset
timeout_secs = 30

키	타입	기본값	의미
`enabled`	bool	`false`	`text_browser` 도구 활성화
`preferred_browser`	string	미설정	`lynx`, `links`, 또는 `w3m`; 미설정 시 자동 감지
`timeout_secs`	integer	`30`	요청 타임아웃(초)

`[web_fetch]`

[web_fetch]
enabled = true
allowed_domains = ["*"]
blocked_domains = []
allowed_private_hosts = []
max_response_size = 500000
timeout_secs = 30

[web_fetch.firecrawl]
enabled = false
api_key_env = "FIRECRAWL_API_KEY"
api_url = "https://api.firecrawl.dev/v1"
mode = "scrape"

키	타입	기본값	의미
`enabled`	bool	`false`	`web_fetch` 도구 활성화
`allowed_domains`	array	`["*"]`	허용 목록; `["*"]` = 모든 공개 호스트, `[]` = 모두 거부
`blocked_domains`	array	`[]`	차단 목록; 항상 `allowed_domains`보다 우선
`allowed_private_hosts`	array	`[]`	SSRF 보호를 우회할 수 있는 사설/내부 호스트
`max_response_size`	integer	`500000`	최대 응답 크기(바이트, 500 KB)
`timeout_secs`	integer	`30`	요청 타임아웃(초)

[web_fetch.firecrawl] 하위 섹션은 JavaScript/봇 차단 폴백을 활성화합니다. api_key_env(기본값: FIRECRAWL_API_KEY)에 지정된 환경 변수로 API 키를 설정하세요. 현재 mode = "scrape"만 구현되어 있으며, crawl은 향후 사용을 위해 예약되어 있습니다.

`[web_search]`

[web_search]
enabled = true
provider = "duckduckgo"   # duckduckgo (free), brave, searxng
max_results = 5
timeout_secs = 15
# brave_api_key = "REPLACE_WITH_KEY"          # required for the brave provider
# searxng_instance_url = "https://searx.example.com"   # required for searxng

키	타입	기본값	의미
`enabled`	bool	`true`	`web_search_tool` 활성화
`provider`	string	`"duckduckgo"`	`duckduckgo` (무료), `brave` (API 키), 또는 `searxng` (자체 호스팅)
`brave_api_key`	string	미설정	Brave Search API 키 (`brave` 사용 시 필수)
`searxng_instance_url`	string	미설정	SearXNG 인스턴스 URL (`searxng` 사용 시 필수)
`max_results`	integer	`5`	검색당 최대 결과 수 (1–10)
`timeout_secs`	integer	`15`	요청 타임아웃(초)

웹 검색은 API 키가 필요 없는 DuckDuckGo로 기본 활성화됩니다. 이 키들은 환경 변수로도 설정할 수 있습니다: WEB_SEARCH_ENABLED, WEB_SEARCH_PROVIDER, WEB_SEARCH_MAX_RESULTS, WEB_SEARCH_TIMEOUT_SECS, BRAVE_API_KEY, SEARXNG_INSTANCE_URL.

`[http_request]`

[http_request]
enabled = true
allowed_domains = ["api.example.com", "api.github.com"]
max_response_size = 1000000
timeout_secs = 30
allow_private_hosts = false

키	타입	기본값	의미
`enabled`	bool	`false`	`http_request` 도구 활성화
`allowed_domains`	array	`["*"]`	허용 목록; `["*"]` = 모든 공개 호스트, `[]` = 모두 거부
`max_response_size`	integer	`1000000`	최대 응답 크기(바이트, 1 MB; `0` = 무제한)
`timeout_secs`	integer	`30`	요청 타임아웃(초)
`allow_private_hosts`	bool	`false`	사설/LAN 호스트 요청 허용 (false일 때 SSRF 보호 적용)

브라우저 및 웹 도구

도구 선택 가이드

browser_open

browser

액션

파라미터

@ref 선택자 모델

백엔드

browser_delegate

text_browser

web_fetch

web_search_tool

http_request

설정

도메인 허용 목록

`[browser]`

`[browser_delegate]`

`[text_browser]`

`[web_fetch]`

`[web_search]`

`[http_request]`

관련 페이지

시작하기

핵심 개념

가이드

CLI 참조

게이트웨이 API

대시보드

채널

프로바이더 및 모델

도구

메모리

워크플로우 및 SOP

크론 및 스케줄링

보안 및 감사

배포 및 운영

하드웨어

MCP 및 확장성

에코시스템

참조