구성

각 명령어마다 플래그를 반복해서 입력하는 대신, 지속적인 기본 설정을 지정하기 위해 agent-browser.json 파일을 생성하세요.

구성 파일 위치

agent-browser는 두 가지 위치를 확인하며, 우선 순위에 따라 병합됩니다:

프로젝트 수준 설정은 사용자 수준 설정을 덮어씁니다. 환경 변수는 둘 다를 오버라이드합니다. CLI 플래그는 항상 최우선입니다.

기본 위치가 아닌 특정 구성 파일을 로드하려면 --config <경로> 또는 AGENT_BROWSER_CONFIG 환경 변수를 사용하세요:

agent-browser --config ./ci-config.json open example.com
AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com

예제 구성

{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data",
  "userAgent": "my-agent/1.0",
  "ignoreHttpsErrors": true
}

모든 옵션

모든 CLI 플래그는 해당 이름의 카멜케이스 버전을 사용하여 구성 파일에서 설정할 수 있습니다:

일반적인 구성 사례

로컬 개발

{
  "headed": true,
  "profile": "./browser-data"
}

프록시 뒤에 있는 경우

{
  "proxy": "http://proxy.corp.example.com:8080",
  "proxyBypass": "localhost,*.internal.com",
  "ignoreHttpsErrors": true
}

CI / Devcontainer

{
  "args": "--no-sandbox,--disable-gpu",
  "ignoreHttpsErrors": true
}

iOS 테스트

{
  "provider": "ios",
  "device": "iPhone 16 Pro"
}

AI 에이전트 보안

{
  "contentBoundaries": true,
  "maxOutput": 50000,
  "allowedDomains": ["your-app.com", "*.your-app.com"],
  "actionPolicy": "./policy.json"
}

부울 옵션 오버라이드

부울 플래그는 구성 설정을 오버라이드하기 위해 선택적으로 true/false 값을 허용합니다:

agent-browser --headed false open example.com

플래그만 주는 경우 true를 전달한 것과 동일합니다:

agent-browser --headed open example.com       # --headed true 와 동일
agent-browser --headed true open example.com  # 명시적 지정

이 규칙은 모든 부울 플래그에 적용됩니다: --headed, --debug, --json, --ignore-https-errors, --allow-file-access, --auto-connect, --content-boundaries, --confirm-interactive, --native.

확장 기능 병합

사용자 수준 및 프로젝트 수준 구성에서 지정된 확장 기능은 재지정되지 않고 연결됩니다. 예를 들어, ~/.agent-browser/config.json이 ["/ext1"]을 지정하고 ./agent-browser.json이 ["/ext2"]을 지정하면 결과는 ["/ext1", "/ext2"]가 됩니다.

AGENT_BROWSER_EXTENSIONS 환경 변수와 CLI --extension 플래그는 표준 우선 순위 규칙을 따릅니다(환경 변수가 구성을 덮어쓰고, CLI는 뒤에 추가).

환경 변수

이 환경 변수들은 추가적인 데몬 및 런타임 동작을 구성합니다:

오류 처리

• 자동 탐지된 구성 파일 (~/.agent-browser/config.json, ./agent-browser.json)이 누락된 경우 무시됩니다.
• 누락되거나 형식이 잘못된 파일이 포함된 --config <경로>는 오류와 함께 종료됩니다.
• 자동 탐지된 파일 내 부적절한 JSON은 표준 오류에 경고를 출력하고 해당 파일 없이 계속 진행합니다.
• 알 수 없는 키는 향후 호환성을 위해 무시됩니다.

팁: 프로젝트 수준 agent-browser.json 파일에 환경별 값(경로, 프록시 등)이 포함되어 있다면, 이를 .gitignore에 추가하는 것이 좋습니다.