options 객체에서 구성을 읽습니다. 이 페이지에서는 options 객체를 작성하는 방법과 어떤 설정 파일 및 환경 변수가 제어하는지 보여줍니다.
모든 옵션의 타입과 기본값은 Options (TypeScript) 및 ClaudeAgentOptions (Python) 참조를 확인하세요.
세션에 옵션 전달
모든query() 호출은 옵션 객체를 허용합니다: TypeScript에서는 Options, Python에서는 ClaudeAgentOptions. 각 필드는 선택 사항이며, 옵션 없이 시작된 세션은 SDK의 기본값으로 실행됩니다. 아래 예제는 프로젝트의 열린 TODO를 요약하는 읽기 전용 세션을 구성합니다. 쌍은 철자가 다른 경우 TypeScript / Python로 읽습니다:
model: 모델을 선택합니다allowedTools/allowed_tools: 읽기 전용 도구 목록을 사전 승인합니다maxTurns/max_turns: 턴 수를 제한합니다cwd: 작업 디렉토리를 설정합니다
cwd를 자신의 프로젝트 중 하나로 지정하고 예제를 실행하세요. 해당 프로젝트의 열린 TODO 요약이 결과 메시지가 도착할 때 출력됩니다.
allowedTools (TypeScript) 또는 allowed_tools (Python)는 나열된 도구를 사전 승인하므로 이들에 대한 호출은 승인을 기다리지 않고 실행됩니다. 목록 외의 도구는 계속 사용 가능합니다. Claude가 나열되지 않은 도구를 호출할 때 권한 모드는 호출 실행 여부를 결정합니다. 자세한 내용은 허용 및 거부 규칙을 참조하세요.
설정 파일 로드
설정 파일은 옵션 객체 이상의 구성을 제공합니다. 두 가지 옵션이 로드 방식을 제어합니다:settingSources/setting_sources: 로드할 파일 시스템 소스를 제어합니다: 사용자, 프로젝트 및 로컬. 설정 파일 및 CLAUDE.md 파일은 이러한 소스를 통해 도착합니다.settings: 설정 파일 경로 또는 두 언어의 인라인 JSON 문자열을 로드하며, TypeScript는 설정 객체도 허용합니다. 전달하는 형식이 무엇이든 사용자, 프로젝트 및 로컬 파일 시스템 설정을 재정의합니다. 관리되는 정책 설정만 더 높은 순위를 가집니다. 참조는 TypeScript의 설정 우선순위 및 Python의 설정 우선순위에서 전체 우선순위 순서를 문서화합니다.
[]를 전달하세요. 자세한 내용은 SDK에서 Claude Code 기능 사용을 참조하세요.
모델 선택
model 옵션, 설정 또는 환경이 모델을 선택하지 않으면 새 세션이 Claude Code의 기본 모델에서 시작됩니다. 이러한 소스의 순서는 모델 설정을 참조하세요. 특정 모델을 고정하거나 더 빠르고 저렴한 에이전트를 위해 더 작은 모델을 선택하려면 model을 설정하세요. 값은 모델 별칭 또는 전체 모델 이름을 사용합니다. 별칭 및 이들이 해석되는 버전은 모델 별칭에 나열되어 있습니다.
백업 모델을 지정하려면 fallbackModel (TypeScript) 또는 fallback_model (Python)을 설정하세요. 주 모델이 과부하 상태이거나 사용 불가능할 때 세션이 백업으로 전환됩니다. 주 모델은 각 사용자 턴의 시작 부분에서 다시 시도되므로 중단이 해결되면 세션이 주 모델로 돌아갑니다.
두 언어 모두에서 옵션은 단일 모델 또는 쉼표로 구분된 백업 목록을 허용합니다. 순서 및 체인 상한은 폴백 모델 체인을 참조하세요. TypeScript에서 model과 같은 폴백은 시작 시 오류를 발생시킵니다.
아래 예제는 TypeScript의 폴백 목록과 Python의 단일 폴백을 보여줍니다:
Messages API 요청 매개변수
temperature, top_p 및 max_tokens는 두 언어 모두에서 옵션 객체에 필드가 없습니다. 대신 노력 수준 또는 지출 상한을 설정하거나, 이러한 매개변수가 필요할 때 Messages API를 호출하세요.환경 변수 설정
env 옵션은 세션을 실행하는 Claude Code 프로세스에 대한 환경 변수를 설정합니다. 값이 상속된 환경을 대체하는지 병합하는지는 언어에 따라 다릅니다:
- TypeScript:
env는 서브프로세스 환경을 대체합니다 - Python: SDK는 값을 상속된 환경에 병합하고 값이 상속된 값을 재정의합니다
process.env를 env에 전개하여 PATH, HOME 및 ANTHROPIC_API_KEY와 같은 상속된 변수를 유지하세요. env를 설정하지 않으면 서브프로세스는 두 언어 모두에서 환경을 상속합니다.
예제는 ANTHROPIC_BASE_URL을 설정하여 API 트래픽을 게이트웨이를 통해 라우팅합니다.
작업 디렉토리 설정
cwd를 설정하여 특정 디렉토리에서 세션을 실행하세요. cwd를 설정하지 않으면 세션이 프로세스의 작업 디렉토리에서 실행됩니다. 두 SDK 모두 cwd에 대한 설정자가 없습니다. 다른 디렉토리에서 실행하려면 해당 cwd로 다른 세션을 시작하세요.
Claude Code는 작업 디렉토리를 읽어 다음을 결정합니다:
- 프로젝트 설정 및 훅: 어느 프로젝트의 설정 및 훅이 로드되는지
- 스킬: 세션 스킬이 발견되는 위치
- 세션 저장소: 저장된 세션이 어느 프로젝트에 속하는지
additionalDirectories (TypeScript) 또는 add_dirs (Python)로 경로를 추가하세요. 해당 권한의 범위는 추가 디렉토리는 파일 액세스를 부여하며 구성은 아님을 참조하세요.
턴 및 지출 제한
maxTurns / max_turns 및 maxBudgetUsd / max_budget_usd로 턴 및 지출을 제한하세요. 두 상한 모두 설정하지 않으면 꺼져 있습니다. 세션이 상한에 도달하면 실행이 서브타입이 상한을 지정하는 결과 메시지로 끝납니다: error_max_turns 또는 error_max_budget_usd. 다음에 일어나는 일은 입력 모드에 따라 다릅니다:
- 단일 샷
query(): SDK는 상한 결과를 생성한 다음 발생시키므로 루프를 try 블록으로 래핑하여 오류를 지나 계속하세요 - 스트리밍 입력: 세션은 상한 결과를 지나 살아있으며 최대 턴 수는 각 대기 중인 메시지에 대해 다시 시작됩니다. 예산 합계는 메시지 전체에 누적되며 지출이 상한에 도달하면 같은 대화의 나중 메시지는 같은 예산 결과로 끝납니다.
/clear는 예산을 다시 시작합니다
0을 다르게 처리합니다:
maxTurns/max_turns:0은 턴 제한 없이 세션을 실행하며, 옵션을 설정하지 않은 것과 같습니다maxBudgetUsd/max_budget_usd: CLI는 시작 시0을 유효하지 않은 금액으로 거부하며 세션은 실행되지 않습니다
세션 중 구성 변경
스트리밍 입력으로 세션을 시작할 때 실행 중에 모델 및 권한 모드를 전환할 수 있습니다. 설정자를 호출하는 위치는 언어에 따라 다릅니다:- TypeScript:
query()가 반환하는 객체의 메서드 - Python:
ClaudeSDKClient의 메서드,query()는 제어 메서드 없이 일반 반복자를 반환하기 때문입니다
setModel()/set_model(): 모델을 전환합니다. 옵션에서 전달한model대신 Claude Code의 기본 모델로 전환하려면 모델 없이 호출하세요.setPermissionMode()/set_permission_mode(): 권한 모드를 전환합니다
applyFlagSettings() 및 updateSettings()를 가집니다:
applyFlagSettings():await session.applyFlagSettings({ effortLevel: "high" })처럼 런타임에 설정을 적용합니다. 메서드는 옵션 필드가 아닌 설정 파일 키를 사용하므로 스키마 및 어떤 키가 세션 중에 적용되는지applyFlagSettings()참조를 확인하세요.updateSettings():await session.updateSettings("localSettings", { outputStyle: "Explanatory" })처럼 프로젝트의 로컬 설정 파일에 허용 목록에 있는 키 집합을 씁니다. 작성된 키는 세션의 다음 요청에서 적용되고local설정을 로드하는 나중 세션에 대해 지속됩니다. 메서드의 행은 메서드 테이블에서 허용 목록에 있는 키 및 버전 하한을 지정합니다.
First turn model: claude-sonnet-5를 출력한 다음 전환 후 Second turn model: claude-opus-5를 출력합니다.
각 모델은 자체 프롬프트 캐시를 가지므로 세션 중 전환 후 다음 요청은 새 모델의 요금으로 전체 대화를 캐시되지 않은 상태로 다시 계산합니다. 자세한 내용은 모델 전환을 참조하세요.