권한 구성

Claude Agent SDK는 Claude가 도구를 사용하는 방식을 관리하기 위한 권한 제어 기능을 제공합니다. 권한 모드와 규칙을 사용하여 자동으로 허용되는 항목을 정의하고, canUseTool 콜백을 사용하여 런타임에 나머지를 처리합니다.

이 페이지는 권한 모드와 규칙을 다룹니다. 사용자가 런타임에 도구 요청을 승인하거나 거부하는 대화형 승인 흐름을 구축하려면 승인 및 사용자 입력 처리를 참조하세요.

권한 평가 방식

Claude가 도구를 요청하면 SDK는 다음 순서로 권한을 확인합니다:

훅
훅을 먼저 실행하여 허용, 거부 또는 다음 단계로 진행할 수 있습니다
권한 규칙
settings.json에 정의된 규칙을 다음 순서로 확인합니다: deny 규칙 먼저(다른 규칙에 관계없이 차단), 그다음 allow 규칙(일치하면 허용), 그다음 ask 규칙(승인 요청). 이러한 선언적 규칙을 사용하면 코드를 작성하지 않고도 특정 도구를 사전 승인, 차단 또는 승인 요구할 수 있습니다.
권한 모드
활성 권한 모드(bypassPermissions, acceptEdits, dontAsk 등)를 적용합니다
canUseTool 콜백
규칙이나 모드로 해결되지 않으면 canUseTool 콜백을 호출하여 결정합니다

이 페이지는 기본 동작을 제어하는 정적 구성인 권한 모드(3단계)에 초점을 맞춥니다. 다른 단계에 대해서는:

훅: 도구 요청을 허용, 거부 또는 수정하는 사용자 정의 코드를 실행합니다. 훅으로 실행 제어를 참조하세요.
권한 규칙: settings.json에서 선언적 허용/거부 규칙을 구성합니다. 권한 설정을 참조하세요.
canUseTool 콜백: 런타임에 사용자에게 승인을 요청합니다. 승인 및 사용자 입력 처리를 참조하세요.

권한 모드

권한 모드는 Claude가 도구를 사용하는 방식에 대한 전역 제어를 제공합니다. query()를 호출할 때 권한 모드를 설정하거나 스트리밍 세션 중에 동적으로 변경할 수 있습니다.

사용 가능한 모드

SDK는 다음 권한 모드를 지원합니다:

모드	설명	도구 동작
`default`	표준 권한 동작	자동 승인 없음; 일치하지 않는 도구는 `canUseTool` 콜백을 트리거합니다
`acceptEdits`	파일 편집 자동 수락	파일 편집 및 파일시스템 작업(`mkdir`, `rm`, `mv` 등)이 자동으로 승인됩니다
`bypassPermissions`	모든 권한 검사 우회	모든 도구가 권한 프롬프트 없이 실행됩니다(주의하여 사용)
`plan`	계획 모드	도구 실행 없음; Claude가 변경 없이 계획만 수립합니다

하위 에이전트 상속: bypassPermissions를 사용할 때 모든 하위 에이전트가 이 모드를 상속하며 재정의할 수 없습니다. 하위 에이전트는 메인 에이전트와 다른 시스템 프롬프트를 가질 수 있으며 덜 제한된 동작을 할 수 있습니다. bypassPermissions를 활성화하면 승인 프롬프트 없이 전체적이고 자율적인 시스템 접근 권한이 부여됩니다.

권한 모드 설정

쿼리를 시작할 때 권한 모드를 한 번 설정하거나, 세션이 활성화된 동안 동적으로 변경할 수 있습니다.

모드 세부 정보

편집 수락 모드 (`acceptEdits`)

Claude가 프롬프트 없이 코드를 편집할 수 있도록 파일 작업을 자동 승인합니다. 다른 도구(파일시스템 작업이 아닌 Bash 명령 등)는 여전히 일반 권한이 필요합니다.

자동 승인되는 작업:

파일 편집 (Edit, Write 도구)
파일시스템 명령: mkdir, touch, rm, mv, cp

사용 시기: Claude의 편집을 신뢰하고 더 빠른 반복을 원할 때, 예를 들어 프로토타이핑 중이거나 격리된 디렉토리에서 작업할 때 사용합니다.

권한 우회 모드 (`bypassPermissions`)

프롬프트 없이 모든 도구 사용을 자동 승인합니다. 훅은 여전히 실행되며 필요한 경우 작업을 차단할 수 있습니다.

극도로 주의하여 사용하세요. 이 모드에서 Claude는 전체 시스템 접근 권한을 가집니다. 모든 가능한 작업을 신뢰할 수 있는 통제된 환경에서만 사용하세요.

계획 모드 (`plan`)

도구 실행을 완전히 방지합니다. Claude는 코드를 분석하고 계획을 수립할 수 있지만 변경할 수는 없습니다. Claude는 계획을 확정하기 전에 요구 사항을 명확히 하기 위해 AskUserQuestion을 사용할 수 있습니다. 이러한 프롬프트 처리에 대해서는 승인 및 사용자 입력 처리를 참조하세요.

사용 시기: Claude가 변경을 실행하지 않고 제안만 하기를 원할 때, 예를 들어 코드 리뷰 중이거나 변경 사항이 적용되기 전에 승인해야 할 때 사용합니다.

권한 평가 방식

권한 모드

사용 가능한 모드

권한 모드 설정

모드 세부 정보

편집 수락 모드 (acceptEdits)

권한 우회 모드 (bypassPermissions)

계획 모드 (plan)

관련 리소스

편집 수락 모드 (`acceptEdits`)

권한 우회 모드 (`bypassPermissions`)

계획 모드 (`plan`)