URL에서 작업 생성

octoparse detect는 Octoparse 확장 브라우저를 열어 페이지를 검사하고 로컬 작업 파일을 생성합니다. Octoparse 데스크톱 앱 없이 URL에서 작업을 만들 때 사용하세요.

v0.1.32부터 detect는 작업을 생성하기 전에 CAPTCHA, 접근 제한, 보안 확인 및 서비스 오류 페이지를 거부합니다. 후보 순위 지정도 적합하지 않은 영역과 페이지 전체 탐색 셸을 더 엄격하게 제외합니다. 복잡한 페이지와 로그인 흐름은 여전히 수동 검토가 필요할 수 있습니다.

세 가지 모드를 사용할 수 있습니다.

모드	사용 시점
`--auto`	CLI가 최적의 데이터 영역을 자동으로 선택하게 할 때
`--manual`	로그인, 유료 결제 벽 닫기 또는 직접 영역 선택이 필요할 때
AI 에이전트(`--agent`)	LLM 또는 자동화 도구가 워크플로를 구동할 때

AI 에이전트에는 --auto 대신 --agent 또는 준비/미리보기/적용 워크플로를 사용하세요. 자동 모드는 CLI가 직접 선택하는 용도입니다.

detect에는 유효한 Octoparse 계정과 자격 증명, 로컬 Chrome이 필요합니다. Linux arm64는 지원하지 않습니다. 플랫폼 요구 사항은 설치를 참고하세요.

자동 모드

CLI가 최적의 후보 데이터 영역을 선택해 작업 파일을 생성합니다.

octoparse detect <url> --auto --output task.json

추출할 내용을 자연어로 설명해 전달할 수 있습니다.

octoparse detect <url> --auto --goal "Extract product titles and prices" --output task.json

검색 결과 페이지에서는 감지 전에 키워드를 검색할 수 있습니다.

octoparse detect <url> --auto --query "keyword" --goal "Extract search results" --output task.json

구조화된 응답에는 --json을 사용하세요.

octoparse detect <url> --auto --goal "..." --output task.json --json

--output을 생략하면 detected_<host>.json 파일이 자동으로 생성됩니다.

브라우저 모드 선택

독립 실행형 Chrome for Testing을 사용하거나 로그인된 시스템 브라우저 프로필을 재사용하세요.

octoparse detect <url> --browser independent --auto
octoparse detect <url> --browser user --browser-id chrome --profile "Default" --manual

브라우저 모드는 octoparse browser --help에 설명된 공통 우선순위를 따릅니다. 명령어 플래그, OCTOPARSE_BROWSER, 저장된 octoparse browser use 설정, independent 순입니다. 사용자 모드는 Windows와 macOS에서 사용할 수 있습니다.

수동 모드

수동 모드는 로그인하고 팝업을 닫으며 데이터 영역을 직접 선택할 수 있는 브라우저 오버레이를 엽니다.

octoparse detect <url> --manual
octoparse detect <url> --manual --goal "Get article titles and links"

로그인이 필요한 사이트에서는 --save-session으로 쿠키를 저장해 향후 로컬 실행에서 세션을 재현할 수 있습니다.

octoparse detect <url> --manual --save-session --session-name my-session --output task.json

쿠키 세션은 모든 사이트에 적용되지 않습니다. 특히 localStorage, 기기 바인딩 또는 새로운 인증이 필요한 페이지에서는 제한될 수 있습니다.

생성된 작업 검증

작업 파일을 생성한 뒤 실행 전에 검증하세요.

octoparse task validate <taskId> --task-file task.json

그런 다음 로컬 샘플을 실행하세요.

octoparse run <taskId> --task-file task.json --max-rows 10 --headless

샘플 결과를 내보냅니다.

octoparse data export <taskId> --source local --format xlsx

AI 에이전트 워크플로

LLM 기반 또는 자동화된 워크플로에는 --auto 대신 에이전트 계약을 사용하세요. 먼저 기능 정보를 조회합니다.

octoparse capabilities --json

응답에는 에이전트 권장 워크플로인 machineContract.recipes.createTaskFromUrlWithAgent가 포함됩니다.

원샷 방식(가장 빠름)

컨텍스트 파일을 읽고 계획을 작성할 수 있는 신뢰할 수 있는 로컬 실행기와 함께 --agent를 사용하세요.

octoparse detect <url> \
  --agent \
  --agent-command "path/to/your/agent-runner" \
  --goal "Extract search results" \
  --output task.json \
  --yes \
  --run-sample 5 \
  --json

응답은 생성된 작업, 미리보기 결과 및 샘플 실행 출력을 포함하는 하나의 JSON 봉투 객체입니다.

감사 가능한 단계별 방식

감사 또는 복구가 필요한 경우 작업을 한 번에 생성하지 말고 준비/미리보기/적용 순서를 사용하세요.

에이전트 컨텍스트 준비

에이전트 계획을 위한 웹페이지 컨텍스트를 내보냅니다.

octoparse detect <url> \
  --prepare-agent \
  --goal "Extract product titles and prices" \
  --output context.json \
  --json

후보 데이터 영역, 필드 샘플, 시각적 스크린샷 및 decisionSummary가 포함된 context.json을 생성합니다.

계획 작성

context.json을 바탕으로 plan.json을 생성합니다.octopus.detect.agent-plan.v1 스키마를 사용하세요. 필드를 선택하기 전에 context.visualArtifacts.annotatedScreenshotPath의 주석 스크린샷을 열고 계획에 visualReview 근거를 포함하세요.

계획 미리보기

최종 작업 파일을 생성하기 전에 계획을 검증합니다.

octoparse detect \
  --preview-agent-plan plan.json \
  --agent-context context.json \
  --json

data.pass가 false이면 적용하기 전에 계획을 수정하세요.

계획 적용

최종 로컬 작업 파일을 생성합니다.

octoparse detect \
  --apply-agent-plan plan.json \
  --agent-context context.json \
  --output task.json

생성된 task.json은 검사 및 검증하거나 로컬 CLI 실행에 사용할 수 있습니다.

detect 문제 해결

문제	확인 사항
Chrome 실행 실패	`octoparse doctor`를 실행하고 `chrome` 항목을 확인합니다. `--chrome-path /path/to/chrome`를 사용해 보세요.
`LINUX_ARM64_UNSUPPORTED`	Linux x64 환경으로 전환하거나 클라우드 추출을 사용합니다.
`LOGIN_SESSION_REQUIRED`	`--manual`로 로그인하고 `--save-session`으로 세션을 저장합니다.
계획 미리보기가 `pass: false` 반환	`plan.json`의 `candidateId` 또는 필드 선택을 수정한 뒤 미리보기를 다시 실행합니다.
작업 결과가 비어 있거나 잘못됨	에이전트 컨텍스트의 `context.resultValidationPolicy`를 확인합니다. 광고나 서로 다른 유형의 행에서 일부 필드가 누락되는 것은 흔히 정상입니다.

다음 단계

첫 작업 실행

생성된 작업을 로컬에서 실행하고 상태를 확인한 뒤 결과를 내보냅니다.

명령어 요약표

detect, run, cloud, data, auth 명령어의 전체 레퍼런스를 확인합니다.

개요

시작하기

작업 만들기

작업 및 실행

데이터

자동화

레퍼런스

자동 모드

브라우저 모드 선택

수동 모드

생성된 작업 검증

AI 에이전트 워크플로

원샷 방식(가장 빠름)

감사 가능한 단계별 방식

detect 문제 해결

다음 단계

첫 작업 실행

명령어 요약표

​자동 모드

​브라우저 모드 선택

​수동 모드

​생성된 작업 검증

​AI 에이전트 워크플로

​원샷 방식(가장 빠름)

​감사 가능한 단계별 방식

​detect 문제 해결

​다음 단계

첫 작업 실행

명령어 요약표

자동 모드

브라우저 모드 선택

수동 모드

생성된 작업 검증

AI 에이전트 워크플로

원샷 방식(가장 빠름)

감사 가능한 단계별 방식

detect 문제 해결

다음 단계