Claude Agent SDK의 PermissionMode 설정: bypassPermissions vs dontAsk

커뮤니티 반응

작성자가 초기에 bypassPermissions를 제안했으나, 다른 사용자가 공식 문서를 근거로 dontAsk의 존재와 보안상 이점을 지적하며 의견이 수렴되었다.

주요 논점

01찬성다수

보안을 위해 dontAsk 모드를 사용하여 승인되지 않은 모든 도구 호출을 엄격히 차단해야 한다.

02중립소수

도구가 없는 경우 bypassPermissions를 써도 무방하지만, 논리적으로는 dontAsk가 더 적절하다.

합의점 vs 논쟁점

합의점

allowed_tools=[] 설정 시 SDK의 기본 도구 부여가 차단된다.
dontAsk 모드는 승인되지 않은 요청을 묻지 않고 거부하는 가장 엄격한 모드이다.

논쟁점

초기에는 dontAsk 모드가 공식 문서에 명확히 기재되어 있지 않거나 인지되지 못했다.

실용적 조언

보안이 중요한 에이전트 환경에서는 permission_mode='dontAsk'를 기본으로 사용하라.
에이전트에게 최소 권한만 부여하기 위해 allowed_tools 리스트를 항상 명시적으로 관리하라.

섹션별 상세

allowed_tools=[] 설정은 에이전트에게 파일 접근이나 웹 검색 같은 도구 권한을 부여하지 않기 위해 사용한다. SDK가 기본적으로 제공할 수 있는 도구들을 명시적으로 차단하여 에이전트의 기능을 제한하는 역할을 수행한다. 빈 리스트를 전달함으로써 비동기 루프에서 발생할 수 있는 불필요한 도구 호출을 방지한다.

bypassPermissions 모드는 모든 권한 확인 절차를 생략하고 작업을 실행한다. 이는 사용자 승인 대기로 인한 실행 중단을 막아주지만, 보안 검사를 완전히 우회한다는 위험이 존재한다. 도구가 없는 상황에서는 동작상 차이가 없으나 논리적으로는 모든 접근을 허용하는 상태가 된다.

dontAsk 모드는 사전 승인되지 않은 모든 도구 실행 시도를 사용자에게 묻지 않고 즉시 거부한다. allowed_tools=[]와 함께 사용하면 승인된 도구가 하나도 없으므로, 예상치 못한 도구 사용 시도가 발생할 때 이를 엄격하게 차단하는 보안 계층을 형성한다.

Claude Agent SDK는 default, acceptEdits, plan, dontAsk, bypassPermissions의 5가지 권한 모드를 지원한다. 각 모드는 위험한 작업에 대한 프롬프트 출력 여부나 파일 수정 자동 승인 여부에 따라 에이전트의 자율성을 다르게 제어한다.

python

PermissionMode = Literal[
    "default",         # Standard permission behavior
    "acceptEdits",     # Auto-accept file edits
    "plan",            # Planning mode - no execution
    "dontAsk",         # Deny anything not pre-approved instead of prompting
    "bypassPermissions", # Bypass all permission checks (use with caution)
]

Claude Agent SDK에서 지원하는 5가지 PermissionMode 정의

용어 해설

권한 모드(Permission Mode): — AI 에이전트가 도구를 실행하거나 파일을 수정할 때 사용자에게 승인을 요청하는 방식을 결정하는 설정값이다. 보안과 자동화 수준 사이의 균형을 조절하며, 'dontAsk'나 'bypassPermissions' 등의 옵션을 통해 에이전트의 자율성을 제어한다.
에이전트 SDK(Agent SDK): — AI 모델이 외부 도구를 사용하고 환경과 상호작용하는 '에이전트'를 개발하기 위해 제공되는 소프트웨어 개발 키트이다. Anthropic의 Claude 모델을 활용해 복잡한 워크플로를 자동화하는 애플리케이션을 구축할 때 사용된다.
권한 우회(Bypass Permissions): — 모든 보안 및 권한 확인 절차를 생략하고 에이전트의 작업을 즉시 실행하는 모드이다. 사용자 개입 없이 빠른 실행이 가능하지만, 예상치 못한 도구 실행이나 파일 수정을 차단하지 못하는 보안상 취약점이 존재한다.

언급된 도구

Claude Agent SDK추천

AI 에이전트 개발 및 도구 연동

언급된 리소스

API DocsClaude Agent SDK Python Documentation