한 줄 요약: Claude Code 공식 문서 "Configure auto mode". 자동 모드 분류기에게 조직이 신뢰하는 저장소·버킷·도메인을 알려 주는 autoMode 설정 블록(environment, allow, soft_deny, hard_deny, classifyAllShell)의 형식과 적용 범위, 분류기 안의 우선순위, /auto-mode-setup으로 초안 만들기, /permissions Auto mode 탭, claude auto-mode 하위 명령, 거부된 동작을 읽고 고치는 법을 다루는 설정 레퍼런스다.
원본 정보#
- 제목: Configure auto mode
- 발행: Anthropic, Claude Code 공식 문서. 본문에 날짜 없음(원본 날짜 미상). 서버 Last-Modified 2026-10-20
- URL: https://code.claude.com/docs/en/auto-mode-config (새 창)
- 수집(fetch)일: 2026-10-21. 본문의 설정 키, 명령, 버전 조건(v2.1.228~v2.1.304)은 이 날짜 기준이다.
- 구성: 자동 모드와 이 문서의 범위 → 기본 신뢰 범위 → 흔한 경계(push·PR, 사람 확인 지점) → 분류기가 설정을 읽는 곳 → 신뢰 인프라 정의(
autoMode.environment) →/auto-mode-setup→ block·allow 규칙 재정의 →/permissions에서 편집 → 모든 셸 명령을 분류기로(classifyAllShell) → 기본값·실효 설정 확인(CLI) → 거부 검토. - 원본은 자동 모드를 모든 제공자(Anthropic API, Claude Platform on AWS, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, 로그인한 Claude apps gateway 세션)에서 모든 사용자가 쓸 수 있다고 적고, 계정에서 쓸 수 없다고 나오면 권한 모드 문서의 전체 요건(지원 모델, Team·Enterprise 플랜의 조직 단위 통제)을 확인하라고 한다(2026-10-21 기준).
- 자동 모드를 켜고 끄는 법은 이 문서가 아니라 권한 모드 문서가 다룬다고 원본이 밝힌다(→ Claude Code 권한 모드).
핵심 주장#
- 분류기는 기본으로 작업 디렉터리와 현재 저장소에 설정된 remote만 신뢰한다. 회사 소스 관리 조직으로의 push나 팀 클라우드 버킷 쓰기는
autoMode.environment에 넣기 전까지 막힌다.environment는 분류기가 "외부"가 무엇인지 정하는 기준이라, 목록에 없는 목적지는 잠재적 유출 대상으로 본다. 원본은 대부분의 조직에 필요한 필드는environment하나라고 한다. 항목은 정규식이나 도구 패턴이 아니라 자연어 문장이다. → Claude Code 자동 모드 설정하기 autoMode는 저장소 파일에서 읽지 않는다. 분류기는~/.claude/settings.json, managed settings,--settings플래그·Agent SDK의 인라인 JSON에서만autoMode를 읽고, 프로젝트의.claude/settings.json·.claude/settings.local.json에서는 읽지 않는다. 체크인된 저장소나 빌드 단계가 자기 allow 규칙을 주입하지 못하게 하려는 것이다. 범위별 항목은 합쳐진다. 개발자는 managed가 준 항목을 지우지 못하지만, allow는 분류기 안에서 soft block 규칙의 예외로 작동하므로 개발자가 더한allow가 조직의soft_deny를 넘을 수 있다. 원본 표현으로 이 합치기는 "additive, not a hard policy boundary"다. 사용자 의도나 분류기 설정과 상관없이 절대 돌면 안 되는 동작은 managed settings의permissions.deny로 막으라고 한다(분류기보다 먼저 막고 덮어쓸 수 없다). → Claude Code 관리자 권한 통제, managed settings- 분류기 안의 우선순위는 네 단계다.
hard_deny는 무조건 막고(사용자 의도·allow예외가 닿지 않음),soft_deny가 그다음 막으며,allow가 맞는soft_deny의 예외가 되고, 끝으로 사용자의 명시적 의도가 남은 soft block을 넘는다. 명시적 의도는 사용자 메시지가 Claude가 하려는 바로 그 동작을 직접·구체적으로 말할 때다. "저장소 정리해 줘"는 force push를 허락하지 않고 "이 브랜치 force-push해 줘"는 허락한다. 배열에"$defaults"를 빼면 그 섹션의 내장 목록 전체가 대체된다(soft_deny면 force push,curl | bash, 운영 배포, 자동 모드 우회 규칙까지,hard_deny면 내장 데이터 유출 규칙). → 권한 모드 - push와 PR은 기본으로 허용되지만 조건이 있다. 자동 모드는 작업 중인 저장소의 모든 브랜치(기본 브랜치 포함)로의 push와 PR 생성을 기본으로 허용한다. 단
production,release,gh-pages처럼 이름이 배포·공개 대상을 가리키는 기본 브랜치 아닌 브랜치는 이 기본에서 빠져 분류기가 따로(운영 배포로서도) 판단하고, push 내용도 검사해 force push, 비밀값이 커밋에 들어가는 것, CI나 배포 파이프라인이 돌릴 때 비밀값을 저장소 밖으로 보낼 변경은 계속 막는다. 사람 확인 지점을 두려면permissions.ask를 쓰되, 이 규칙은git push·gh pr create로 시작하는 명령만 맞추므로git -C <dir> push나git -c <key>=<value> push로 쓴 push는 확인 지점을 거치지 않는다. 명령 전체를 보는 확인 지점은PreToolUse훅이라고 원본은 말한다. → Claude Code 권한 모드 고르기 - 설정을 돕는 도구가 있다.
/auto-mode-setup은 프로젝트와 최근 세션에서environment항목(때로 규칙 항목도) 초안을 만들고, 수락하면~/.claude/settings.json에 쓴다./permissions의 Auto mode 탭에서 규칙과environment항목을 보고 고친다(v2.1.246 이상).claude auto-mode defaults·config·critique·reset으로 내장 규칙, 실제 적용 결과, 내가 쓴 규칙에 대한 AI 피드백, 초기화를 다룬다. 거부된 동작은 화면의 이유 표시로 원인을 가린 뒤environment항목,allow규칙, 다음 메시지의 의도 표명 중 하나로 고친다. → Claude Code 자동 모드 설정하기, Claude Code CLI 플래그
원본의 설정 예시 (원문 그대로, 2026-10-21 기준)#
- 사람 확인 지점:
{"permissions": {"ask": ["Bash(git push *)", "Bash(gh pr create *)"]}} - 기본값을 두고 조직 인프라 추가:
"environment": ["$defaults", "Source control: github.example.com/acme-corp and all repos under it", "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets", "Trusted internal domains: *.corp.example.com, api.internal.example.com", "Key internal services: Jenkins at ci.example.com, Artifactory at artifacts.example.com"] - 네 목록 모두 기본값 유지 + 조직 규칙 추가, 시작 템플릿(대괄호 칸 채우기),
/auto-mode-setup끄기("skillOverrides": {"auto-mode-setup": "off"}),"classifyAllShell": true
전체 JSON은 Claude Code 자동 모드 설정하기에 원문 그대로 옮겼다.
원본의 숫자·버전 조건 (2026-10-21 기준)#
/auto-mode-setup: Pro·Max·Team·Enterprise 플랜과 Claude Console API 키에서 쓴다. Pro·Max·Team은 v2.1.228 이상(네이티브 Windows v2.1.233 이상), Enterprise와 Console API 키는 v2.1.283 이상. 텔레메트리를 끈 세션, 서드파티 제공자, Claude apps gateway에서는 v2.1.304 전까지 이 명령이 없다. 클라우드 세션에서는 쓸 수 없다.- Host containment 환경 항목: v2.1.257 이상.
/permissions의 Auto mode 탭: v2.1.246 이상, 세션에서 자동 모드를 쓸 수 있을 때만 보인다.
원본에 없는 것#
- 자동 모드를 켜고 끄는 법, 분류기가 기본으로 막는 것의 목록, 반복 차단 기준: 원본은 권한 모드 문서로 넘긴다(→ Claude Code 권한 모드).
- 판정 없는 거부의 원인과 대처: 원본은 Errors 문서로 넘긴다.
- 내장 규칙 전체 목록: 원본은 잘린 JSON 예만 보여 주고
claude auto-mode defaults로 출력하라고 한다. - 조직 전체에
autoMode를 배포하는 법: 원본은 Server-managed settings 문서로 넘긴다. 기기 파일·MDM 배포는 Claude Code managed settings 배포·점검.
원본이 링크한 관련 문서#
Claude Platform on AWS, Claude apps gateway, Server-managed settings, Costs(컴팩션), Errors(판정 없음), Environment variables(설치·업그레이드 뒤 첫 세션, 기능 플래그), Setup(업데이트), Claude Code on the web, Tools reference(Monitor), Sandboxing(명령별 허용 도메인 → Claude Code 샌드박스), Interactive mode(트랜스크립트 보기). 이 사이트에서 다룬 문서: Permission modes, Permissions, Memory, Skills, Hooks, settings reference.