> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# URL에서 작업 생성

> octoparse detect로 URL을 검사하고 데이터 영역을 선택해 로컬 작업 파일을 생성하세요. 자동, 수동 및 AI 에이전트 워크플로를 지원합니다.

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

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

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

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

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

<Note>
  `detect`에는 유효한 Octoparse 계정과 자격 증명, 로컬 Chrome이 필요합니다. Linux arm64는 지원하지 않습니다. 플랫폼 요구 사항은 [설치](../quick-start/installation#supported-platforms-for-local-extraction)를 참고하세요.
</Note>

## 자동 모드

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

```bash theme={null}
octoparse detect <url> --auto --output task.json
```

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

```bash theme={null}
octoparse detect <url> --auto --goal "Extract product titles and prices" --output task.json
```

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

```bash theme={null}
octoparse detect <url> --auto --query "keyword" --goal "Extract search results" --output task.json
```

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

```bash theme={null}
octoparse detect <url> --auto --goal "..." --output task.json --json
```

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

## 브라우저 모드 선택

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

```bash theme={null}
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에서 사용할 수 있습니다.

## 수동 모드

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

```bash theme={null}
octoparse detect <url> --manual
octoparse detect <url> --manual --goal "Get article titles and links"
```

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

```bash theme={null}
octoparse detect <url> --manual --save-session --session-name my-session --output task.json
```

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

## 생성된 작업 검증

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

```bash theme={null}
octoparse task validate <taskId> --task-file task.json
```

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

```bash theme={null}
octoparse run <taskId> --task-file task.json --max-rows 10 --headless
```

샘플 결과를 내보냅니다.

```bash theme={null}
octoparse data export <taskId> --source local --format xlsx
```

## AI 에이전트 워크플로

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

```bash theme={null}
octoparse capabilities --json
```

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

### 원샷 방식(가장 빠름)

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

```bash theme={null}
octoparse detect <url> \
  --agent \
  --agent-command "path/to/your/agent-runner" \
  --goal "Extract search results" \
  --output task.json \
  --yes \
  --run-sample 5 \
  --json
```

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

### 감사 가능한 단계별 방식

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

<Steps>
  <Step title="에이전트 컨텍스트 준비">
    에이전트 계획을 위한 웹페이지 컨텍스트를 내보냅니다.

    ```bash theme={null}
    octoparse detect <url> \
      --prepare-agent \
      --goal "Extract product titles and prices" \
      --output context.json \
      --json
    ```

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

  <Step title="계획 작성">
    `context.json`을 바탕으로 `plan.json`을 생성합니다.

    `octopus.detect.agent-plan.v1` 스키마를 사용하세요. 필드를 선택하기 전에 `context.visualArtifacts.annotatedScreenshotPath`의 주석 스크린샷을 열고 계획에 `visualReview` 근거를 포함하세요.
  </Step>

  <Step title="계획 미리보기">
    최종 작업 파일을 생성하기 전에 계획을 검증합니다.

    ```bash theme={null}
    octoparse detect \
      --preview-agent-plan plan.json \
      --agent-context context.json \
      --json
    ```

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

  <Step title="계획 적용">
    최종 로컬 작업 파일을 생성합니다.

    ```bash theme={null}
    octoparse detect \
      --apply-agent-plan plan.json \
      --agent-context context.json \
      --output task.json
    ```

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

## 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`를 확인합니다. 광고나 서로 다른 유형의 행에서 일부 필드가 누락되는 것은 흔히 정상입니다. |

## 다음 단계

<CardGroup cols={2}>
  <Card title="첫 작업 실행" href="../quick-start/run-your-first-task">
    생성된 작업을 로컬에서 실행하고 상태를 확인한 뒤 결과를 내보냅니다.
  </Card>

  <Card title="명령어 요약표" href="../reference/command-cheatsheet">
    detect, run, cloud, data, auth 명령어의 전체 레퍼런스를 확인합니다.
  </Card>
</CardGroup>