메인 콘텐츠로 건너뛰기

​
인증 방법

Claude Code를 설정하려면 Anthropic 모델에 대한 접근이 필요합니다. 팀의 경우 다음 세 가지 방법 중 하나로 Claude Code 접근을 설정할 수 있습니다:
  • Claude API(Claude Console을 통해)
  • Amazon Bedrock
  • Google Vertex AI

​
Claude API 인증

Claude API를 통해 팀을 위한 Claude Code 접근을 설정하려면:
  1. 기존 Claude Console 계정을 사용하거나 새로운 Claude Console 계정을 만듭니다
  2. 다음 방법 중 하나를 통해 사용자를 추가할 수 있습니다:
    • Console 내에서 사용자를 일괄 초대합니다(Console -> Settings -> Members -> Invite)
    • SSO 설정
  3. 사용자를 초대할 때 다음 역할 중 하나가 필요합니다:
    • “Claude Code” 역할은 사용자가 Claude Code API 키만 만들 수 있음을 의미합니다
    • “Developer” 역할은 사용자가 모든 종류의 API 키를 만들 수 있음을 의미합니다
  4. 초대된 각 사용자는 다음 단계를 완료해야 합니다:

​
클라우드 제공자 인증

Bedrock 또는 Vertex를 통해 팀을 위한 Claude Code 접근을 설정하려면:
  1. Bedrock 문서 또는 Vertex 문서를 따릅니다
  2. 환경 변수와 클라우드 자격증명 생성 지침을 사용자에게 배포합니다. 여기서 구성 관리 방법에 대해 자세히 알아봅니다.
  3. 사용자가 Claude Code를 설치할 수 있습니다

​
접근 제어 및 권한

세밀한 권한을 지원하므로 에이전트가 수행할 수 있는 작업(예: 테스트 실행, 린터 실행)과 수행할 수 없는 작업(예: 클라우드 인프라 업데이트)을 정확히 지정할 수 있습니다. 이러한 권한 설정은 버전 제어에 체크인할 수 있으며 조직의 모든 개발자에게 배포할 수 있을 뿐만 아니라 개별 개발자가 사용자 정의할 수 있습니다.

​
권한 시스템

Claude Code는 전력과 안전성의 균형을 맞추기 위해 계층화된 권한 시스템을 사용합니다:
도구 유형예시승인 필요”Yes, don’t ask again” 동작
읽기 전용파일 읽기, LS, Grep아니오N/A
Bash 명령셸 실행예프로젝트 디렉토리 및 명령당 영구적
파일 수정파일 편집/쓰기예세션 종료까지

​
권한 구성

/permissions를 사용하여 Claude Code의 도구 권한을 보고 관리할 수 있습니다. 이 UI는 모든 권한 규칙과 이들이 소싱되는 settings.json 파일을 나열합니다.
  • Allow 규칙은 Claude Code가 추가 수동 승인 없이 지정된 도구를 사용하도록 허용합니다.
  • Ask 규칙은 Claude Code가 지정된 도구를 사용하려고 할 때마다 사용자에게 확인을 요청합니다. Ask 규칙은 allow 규칙보다 우선합니다.
  • Deny 규칙은 Claude Code가 지정된 도구를 사용하지 못하도록 방지합니다. Deny 규칙은 allow 및 ask 규칙보다 우선합니다.
  • Additional directories는 Claude의 파일 접근을 초기 작업 디렉토리 이상으로 확장합니다.
  • Default mode는 새로운 요청을 만날 때 Claude의 권한 동작을 제어합니다.
권한 규칙은 다음 형식을 사용합니다: Tool 또는 Tool(optional-specifier) 도구 이름만 있는 규칙은 해당 도구의 모든 사용과 일치합니다. 예를 들어, allow 규칙 목록에 Bash를 추가하면 Claude Code가 사용자 승인을 요구하지 않고 Bash 도구를 사용하도록 허용합니다.

​
권한 모드

Claude Code는 설정 파일에서 defaultMode로 설정할 수 있는 여러 권한 모드를 지원합니다:
모드설명
default표준 동작 - 각 도구의 첫 사용 시 권한 요청
acceptEdits세션에 대해 파일 편집 권한을 자동으로 수락합니다
plan계획 모드 - Claude는 파일을 분석할 수 있지만 수정하거나 명령을 실행할 수 없습니다
bypassPermissions모든 권한 프롬프트를 건너뜁니다(안전한 환경 필요 - 아래 경고 참조)

​
작업 디렉토리

기본적으로 Claude는 실행된 디렉토리의 파일에 접근할 수 있습니다. 이 접근을 확장할 수 있습니다:
  • 시작 중: --add-dir <path> CLI 인수 사용
  • 세션 중: /add-dir 슬래시 명령 사용
  • 영구 구성: 설정 파일의 additionalDirectories에 추가
추가 디렉토리의 파일은 원래 작업 디렉토리와 동일한 권한 규칙을 따릅니다. 프롬프트 없이 읽을 수 있게 되며, 파일 편집 권한은 현재 권한 모드를 따릅니다.

​
도구별 권한 규칙

일부 도구는 더 세밀한 권한 제어를 지원합니다: Bash
  • Bash(npm run build) 정확한 Bash 명령 npm run build와 일치합니다
  • Bash(npm run test:*) npm run test로 시작하는 Bash 명령과 일치합니다
  • Bash(curl http://site.com/:*) 정확히 curl http://site.com/로 시작하는 curl 명령과 일치합니다
Claude Code는 셸 연산자(예: &&)를 인식하므로 Bash(safe-cmd:*)와 같은 접두사 일치 규칙은 safe-cmd && other-cmd 명령을 실행할 권한을 주지 않습니다
Bash 권한 패턴의 중요한 제한사항:
  1. 이 도구는 접두사 일치를 사용하며, regex 또는 glob 패턴이 아닙니다
  2. 와일드카드 :*는 패턴 끝에서만 작동하여 모든 연속을 일치시킵니다
  3. Bash(curl http://github.com/:*)와 같은 패턴은 많은 방식으로 우회될 수 있습니다:
    • URL 앞의 옵션: curl -X GET http://github.com/...는 일치하지 않습니다
    • 다른 프로토콜: curl https://github.com/...는 일치하지 않습니다
    • 리다이렉트: curl -L http://bit.ly/xyz(github로 리다이렉트)
    • 변수: URL=http://github.com && curl $URL는 일치하지 않습니다
    • 추가 공백: curl http://github.com는 일치하지 않습니다
더 안정적인 URL 필터링을 위해 다음을 고려하세요:
  • WebFetch(domain:github.com) 권한으로 WebFetch 도구 사용
  • CLAUDE.md를 통해 Claude Code에 허용된 curl 패턴에 대해 지시
  • 사용자 정의 권한 검증을 위해 훅 사용
Read & Edit Edit 규칙은 파일을 편집하는 모든 기본 제공 도구에 적용됩니다. Claude는 Grep, Glob 및 LS와 같이 파일을 읽는 모든 기본 제공 도구에 Read 규칙을 적용하기 위해 최선의 노력을 기울입니다. Read & Edit 규칙은 모두 gitignore 사양을 따르며 네 가지 고유한 패턴 유형이 있습니다:
패턴의미예시일치
//path파일 시스템 루트의 절대 경로Read(//Users/alice/secrets/**)/Users/alice/secrets/**
~/path홈 디렉토리의 경로Read(~/Documents/*.pdf)/Users/alice/Documents/*.pdf
/path설정 파일에 상대적인 경로Edit(/src/**/*.ts)<settings file path>/src/**/*.ts
path 또는 ./path현재 디렉토리에 상대적인 경로Read(*.env)<cwd>/*.env
/Users/alice/file과 같은 패턴은 절대 경로가 아닙니다. 설정 파일에 상대적입니다! 절대 경로에는 //Users/alice/file을 사용하세요.
  • Edit(/docs/**) - <project>/docs/의 편집 (NOT /docs/!)
  • Read(~/.zshrc) - 홈 디렉토리의 .zshrc 읽기
  • Edit(//tmp/scratch.txt) - 절대 경로 /tmp/scratch.txt 편집
  • Read(src/**) - <current-directory>/src/에서 읽기
WebFetch
  • WebFetch(domain:example.com) example.com에 대한 fetch 요청과 일치합니다
MCP
  • mcp__puppeteer puppeteer 서버에서 제공하는 모든 도구와 일치합니다(Claude Code에서 구성된 이름)
  • mcp__puppeteer__puppeteer_navigate puppeteer 서버에서 제공하는 puppeteer_navigate 도구와 일치합니다
다른 권한 유형과 달리 MCP 권한은 와일드카드(*)를 지원하지 않습니다.MCP 서버의 모든 도구를 승인하려면:
  • ✅ 사용: mcp__github(모든 GitHub 도구 승인)
  • ❌ 사용하지 마세요: mcp__github__*(와일드카드는 지원되지 않음)
특정 도구만 승인하려면 각각을 나열하세요:
  • ✅ 사용: mcp__github__get_issue
  • ✅ 사용: mcp__github__list_issues

​
훅을 사용한 추가 권한 제어

Claude Code 훅은 런타임에 권한 평가를 수행하기 위해 사용자 정의 셸 명령을 등록하는 방법을 제공합니다. Claude Code가 도구 호출을 할 때 PreToolUse 훅은 권한 시스템이 실행되기 전에 실행되며, 훅 출력은 권한 시스템 대신 도구 호출을 승인하거나 거부할지 여부를 결정할 수 있습니다.

​
엔터프라이즈 관리 정책 설정

Claude Code의 엔터프라이즈 배포의 경우 사용자 및 프로젝트 설정보다 우선하는 엔터프라이즈 관리 정책 설정을 지원합니다. 이를 통해 시스템 관리자는 사용자가 재정의할 수 없는 보안 정책을 적용할 수 있습니다. 시스템 관리자는 다음에 정책을 배포할 수 있습니다:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux 및 WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json
이러한 정책 파일은 일반 설정 파일과 동일한 형식을 따르지만 사용자 또는 프로젝트 설정으로 재정의될 수 없습니다. 이는 조직 전체에서 일관된 보안 정책을 보장합니다.

​
설정 우선순위

여러 설정 소스가 존재할 때 다음 순서(가장 높은 우선순위에서 가장 낮은 우선순위)로 적용됩니다:
  1. 엔터프라이즈 정책
  2. 명령줄 인수
  3. 로컬 프로젝트 설정(.claude/settings.local.json)
  4. 공유 프로젝트 설정(.claude/settings.json)
  5. 사용자 설정(~/.claude/settings.json)
이 계층 구조는 조직 정책이 항상 적용되도록 하면서도 적절한 경우 프로젝트 및 사용자 수준에서 유연성을 허용합니다.

​
자격증명 관리

Claude Code는 인증 자격증명을 안전하게 관리합니다:
  • 저장 위치: macOS에서 API 키, OAuth 토큰 및 기타 자격증명은 암호화된 macOS Keychain에 저장됩니다.
  • 지원되는 인증 유형: Claude.ai 자격증명, Claude API 자격증명, Bedrock 인증 및 Vertex 인증.
  • 사용자 정의 자격증명 스크립트: apiKeyHelper 설정은 API 키를 반환하는 셸 스크립트를 실행하도록 구성할 수 있습니다.
  • 새로고침 간격: 기본적으로 apiKeyHelper는 5분 후 또는 HTTP 401 응답 시 호출됩니다. 사용자 정의 새로고침 간격을 위해 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 환경 변수를 설정하세요.