이 페이지의 목차
확인 2026-10-21근거 자료 3건갱신 2026-10-21언급 17곳
이 페이지의 목차
확인 날짜 안내

공식 문서 Claude Code 권한 설정(본문 날짜 없음, 서버 Last-Modified 2026-10-20, 수집 2026-10-21) 기준이다. 훅·서브에이전트·스킬 문서가 각자 적은 신뢰 규칙(버전 조건 포함)은 해당 페이지에 있고, 여기서는 권한 문서가 한 표로 모은 기준을 중심에 둔다.

정의#

작업 공간 신뢰(workspace trust)는 Claude Code가 처음 보는 폴더에서 저장소가 주는 설정 중 능력을 주는 것을, 사용자가 그 폴더의 신뢰 대화상자를 수락한 뒤에만 적용하는 단계다. 프로젝트 .claude/settings.json의 permissions.allow 규칙(묻지 않고 쓰게 허용하는 규칙, 용어 사전)과 permissions.additionalDirectories 항목이 대표다. 대화상자는 그 폴더가 줄 규칙과 디렉터리를 나열해 먼저 검토하게 한다. 제한만 하는 deny·ask 규칙은 신뢰와 상관없이 바로 적용된다. Claude Code 권한 설정

편집자 해석: 그래서 신뢰 단계는 "저장소를 클론했다는 이유만으로 그 저장소가 스스로에게 권한을 주지 못하게 하는 장치"로 볼 수 있다. 근거는 원본의 "grant capability, so Claude Code applies them only after you accept the workspace trust dialog" 문장이다. 다만 아래 표처럼 신뢰 전에도 쓰이는 저장소 내용이 있어, 신뢰 단계가 저장소의 모든 실행을 막는 것은 아니다.

신뢰가 저장되는 기준#

Claude Code 권한 설정

  • 저장소 안에서 시작: git 저장소 루트를 기준으로 신뢰를 저장하고, 신뢰는 저장소 전체에 미친다. 단 안에 중첩된 git 저장소(서브모듈 등)는 빠진다. worktree는 메인 체크아웃 루트를 쓴다.
  • 저장소 밖에서 시작: 시작한 디렉터리를 기준으로 저장하고, 그 아래 하위 디렉터리에도 미친다(중첩된 git 저장소, 예컨대 클론은 빠진다). 덮인 하위 디렉터리는 "상위 폴더를 신뢰한 폴더"로 친다.
  • 홈 디렉터리에서 시작: 신뢰를 그 세션에만 두고 디스크에 쓰지 않는다.
  • 손으로 신뢰하기: ~/.claude.json의 projects["<path>"].hasTrustDialogAccepted를 true로 둔다. <path>는 저장소 루트, 저장소 밖이면 그 폴더다. 건너뛴 서브에이전트 훅·인라인 MCP 서버의 디버그 로그 줄, 건너뛴 allow 규칙의 stderr 경고, headersHelper not run 줄에 정확한 키가 찍힌다.

대화상자가 뜨는 곳과 뜨지 않는 곳#

  • 대화상자는 대화형 세션에서만 뜬다. claude -p 실행과 SDK 세션은 절대 띄우지 않고, 상위 폴더 신뢰도 이 규칙들에는 치지 않는다. Claude Code 권한 설정
  • 백그라운드 세션: 시작·재시작 전에 그 세션이 돌 디렉터리의 신뢰를 확인한다. 신뢰하지 않은 디렉터리의 터미널에서 claude --bg를 돌리면 대화상자가 먼저 뜨고 수락하면 세션이 시작된다. 스크립트처럼 대화상자를 띄울 수 없으면 Workspace not trusted 오류로 끝난다. Claude Code 권한 설정 → Claude Code CLI 플래그
  • /cd로 옮길 때: 처음 일하는 디렉터리면 신뢰를 묻고, 그 디렉터리 설정이 활성화할 allow 규칙·추가 디렉터리·훅·헬퍼 명령을 대화상자에 나열한다. 거절하면 세션은 제자리에 남는다. v2.1.246 전에는 /cd가 새 디렉터리의 설정·훅·MCP 서버·스킬을 재개할 때까지 적용하지 않았고 대화상자도 활성화될 것을 나열하지 않았다. Claude Code 권한 설정

신뢰 전에도 도는 것 (원본 표)#

각 행은 저장소가 줄 수 있는 내용, 두 열은 그 폴더 자체를 신뢰하지 않은 두 상황이다. 중첩 저장소 안에서는 상위 폴더 열이 적용되지 않는다(대화형이면 그 저장소의 대화상자가 뜨고, -p·SDK는 오른쪽 열을 따른다). Claude Code 권한 설정

저장소가 주는 것상위 폴더만 신뢰함claude -p나 SDK, 폴더를 신뢰한 적 없음
settings 파일의 훅, env 블록, apiKeyHelper 같은 헬퍼 명령, 프로젝트 스킬의 훅과 allowed-tools쓰인다쓰인다. 스킬의 allowed-tools는 어떤 세션에서도 신뢰가 막지 않는다
.claude/settings.json의 permissions.allow와 additionalDirectories신뢰 대화상자를 수락할 때까지 안 쓰인다(대화상자가 이것들을 나열하며 다시 뜬다)안 쓰인다. stderr에 this workspace has not been trusted 경고
프로젝트 서브에이전트의 frontmatter 훅, 프로젝트 @skills-dir 플러그인, 저장소나 --add-dir 디렉터리의 extraKnownMarketplaces안 쓰이고 대화상자도 없다안 쓰인다
저장소나 --add-dir 디렉터리의 서브에이전트 frontmatter 인라인 mcpServers안 쓰이고 대화상자도 없다안 쓰인다
.mcp.json의 서버(저장소가 자기 설정에서 승인한 것 포함)연결 전에 묻는다. 저장소 자신의 승인은 치지 않는다승인 여부와 상관없이 묻지 않고 연결한다. SDK는 settingSources에 project가 있을 때만 로드. 같은 폴더의 claude mcp list는 여전히 대기(pending)로 보인다
.mcp.json 서버의 headersHelper신뢰 대화상자를 수락할 때까지 실행하지 않고(헬퍼가 선언된 곳을 밝히며 다시 뜬다), 그동안 정적 headers만으로 연결실행하지 않고 정적 headers만으로 연결하며 서버마다 stderr에 headersHelper not run

편집자 해석: 이 표에서 -p·SDK 세션은 훅·env·헬퍼·.mcp.json 서버는 신뢰한 것처럼 쓰고, allow 규칙과 서브에이전트 frontmatter 훅·인라인 서버는 쓰지 않는다. 그래서 "-p는 폴더를 신뢰한 것으로 다룬다"는 훅 문서의 설명(훅)은 훅에 대한 말로 읽고, 권한 규칙까지 넓히지 않는 편이 맞다고 볼 수 있다. 근거는 위 표의 둘째 행("Not used")과 첫째 행("Used")이다.

env는 언제 신뢰를 기다리나 (2026-10-21 기준)#

같은 날 수집한 세 공식 문서가 env를 다르게 적는다. 나란히 둔다.

  • Settings 문서: permissions.allow, permissions.additionalDirectories, extraKnownMarketplaces와 "대부분의 env 값"은 팀원 각자가 폴더를 신뢰한 뒤에만 적용된다. Claude Code 설정 파일과 우선순위 → Claude Code 설정 파일
  • 권한 문서(위 표 첫째 행): 상위 폴더만 신뢰했을 때도, -p·SDK로 돌릴 때도 env 블록은 쓰인다. Claude Code 권한 설정
  • settings reference: project·local 설정의 env 값은 "after you trust the workspace, or at startup in -p mode, which never shows the trust dialog"에 적용된다. 모델 선택·시간 제한·기능 토글처럼 Claude Code가 안전하다고 분류한 변수는 모든 설정 파일에서 시작 때 적용된다(project·local이 둘 수 없는 변수는 제외). Claude Code 설정 키 전체 레퍼런스 → Claude Code 설정 키 레퍼런스

편집자 해석: settings reference 문장으로 보면, Settings 문서의 "대부분"은 안전한 변수로 분류된 것을 뺀 나머지이고 "신뢰한 뒤"는 대화형 세션 기준이며, -p·SDK는 권한 문서 표처럼 시작 때 적용되는 예외로 읽을 수 있다. 근거는 settings reference의 "or at startup in -p mode" 문장이다. 상위 폴더만 신뢰한 경우는 이 해석으로 정리되지 않아, 이 상황을 직접 다루는 권한 문서 표를 기준으로 정했다(아래 ‘원본끼리 달랐던 점’ 상자): 상위 폴더만 신뢰한 대화형 세션에서도 저장소의 env 블록은 쓰인다. 단 중첩 저장소 안에서는 이 열이 적용되지 않고 대화형 세션은 그 저장소의 신뢰 대화상자를 띄운다. Claude Code 권한 설정

원본끼리 달랐던 점(정리됨)상위 폴더만 신뢰한 대화형 세션의 저장소 env
  • Claude Code 설정 파일과 우선순위 (Settings 문서, 수집 2026-10-21): "most env values apply only after each teammate trusts the folder"
  • Claude Code 권한 설정 (Permissions 문서, 수집 2026-10-21): "What runs before you trust a folder" 표의 "You trusted only a parent folder" 열에서 env 블록은 "Used"
  • 갈리는 경우: 상위 폴더만 신뢰하고 이 폴더 자체는 신뢰하지 않은 대화형 세션에서 저장소의 env가 적용되는가. 권한 문서는 이 표의 두 열을 "you haven't trusted the folder itself"인 경우라고 밝히고, Settings 문서와 settings reference는 상위 폴더 신뢰를 따로 말하지 않는다.

권한 문서 기준으로 해소로 닫는다. 이 상황을 직접 다루는 원본은 권한 문서 표뿐이다. 표는 두 열을 "the two situations in which you haven't trusted the folder itself: you trusted only a parent folder, or you ran claude -p or the SDK there"라고 정의하고, settings 파일 훅·env 블록·헬퍼 명령 행의 "You trusted only a parent folder" 열에 "Used"라고 적는다. 그래서 상위 폴더만 신뢰한 대화형 세션에서도 저장소의 env 블록은 쓰인다고 설명한다. 같은 원본의 예외도 함께 쓴다: "The parent-folder column doesn't apply inside a nested repository"(대화형 세션은 그 저장소의 신뢰 대화상자를 띄운다). 위 원본 주장과 출처는 그대로 둔다. Claude Code 권한 설정

내 local 설정 파일이 신뢰를 기다리는 경우#

Claude Code 권한 설정

  • .claude/settings.local.json은 보통 내 파일이라 allow 규칙과 추가 디렉터리를 신뢰 단계 없이 적용한다. 그러나 파일이 git에 추적되거나 .claude가 심볼릭 링크면 저장소가 준 것으로 보고 폴더를 신뢰할 때까지 보류한다.
  • 둘을 가리려고 git을 돌리는데, git은 폴더를 신뢰한 뒤에만 돌린다(그 폴더나 신뢰가 이어지는 상위 디렉터리의 대화상자를 수락했거나, 수락으로 치는 -p·SDK 세션). 그 전에는 시작 위치가 정한다:
    • 설정 홈에서 시작: git 없이 그 폴더의 local 파일을 바로 적용한다. 설정 홈은 홈 디렉터리, 또는 .claude 하위 디렉터리를 CLAUDE_CONFIG_DIR로 지정한 디렉터리다(그 디렉터리가 git 저장소 안이고 local 파일을 저장소 루트에 두는 경우는 다른 곳처럼 보류).
    • 그 밖: 프로젝트 설정처럼 보류한다. 검사가 돈 뒤에는 추적되지 않는 파일이나 git 저장소 밖 디렉터리의 파일 규칙을, 그 정확한 폴더를 신뢰하지 않았어도 적용한다.
  • 설정 홈 예외는 신뢰 단계만 건너뛴다. ~/.claude/settings.local.json은 여전히 local 범위라 홈 디렉터리 자체에서 시작한 세션에서만 읽힌다. 모든 프로젝트에 규칙을 걸려면 사용자 설정 ~/.claude/settings.json(또는 $CLAUDE_CONFIG_DIR/settings.json)에 둔다. → Claude Code 설정 파일

남의 저장소에 claude -p를 돌리기 전에#

원본이 권하는 방법이다. 내 컴퓨터에서 무엇이 돌 수 있는지 먼저 정한다. Claude Code 권한 설정

  1. --setting-sources user를 넘기거나 SDK settingSources에서 project를 빼면 프로젝트 설정 파일도 .mcp.json도 읽지 않는다.
  2. --bare로 시작하면 프로젝트의 훅, 스킬, 커스텀 명령, 서브에이전트, 플러그인, .mcp.json 서버를 읽지 않는다. 단 프로젝트 설정 파일의 env 블록과 awsAuthRefresh 같은 헬퍼는 여전히 적용되고, apiKeyHelper는 --settings에서만 읽는다.
  3. --settings '{"disableAllHooks": true}'로 그 실행의 훅을 끈다. 사용자 설정에만 두면 부족하다. 저장소의 프로젝트 설정이 사용자 설정보다 우선해 false로 되돌릴 수 있기 때문이다.
  4. disabledMcpjsonServers에 이름을 넣으면 모든 세션 종류에서 그 .mcp.json 서버를 거부한다.

편집자 해석: 2번의 --bare도 env 블록과 일부 헬퍼는 막지 못하므로, 남의 저장소를 자동화로 돌릴 때는 1번처럼 프로젝트 설정 출처 자체를 빼는 쪽이 범위가 가장 넓다고 볼 수 있다. 근거는 원본 2번 항목의 "The project's env block and helpers such as awsAuthRefresh in its settings files still apply" 문장이다. → Claude Code 차단 훅 단단하게 만들기 8단계

다른 페이지의 신뢰 규칙#