[Claude Code] Claude Code 권한 설정: settings.json으로 확인 창 줄이기

안녕하세요, muaco입니다.

이 글로 할 수 있는 일

Claude Code를 쓰다 보면 명령을 하나 돌릴 때마다 실행해도 되는지 묻는 창이 뜹니다. 처음에는 안심이 되지만 하루에 수십 번 누르다 보면 확인이 습관이 되어 버립니다. 이 글에서는 설정 파일 settings.json에 권한 규칙을 적어 자주 쓰는 안전한 명령은 묻지 않고 지나가게 하고 되돌리기 어려운 명령은 아예 막습니다. 규칙을 넣을 파일 위치, 규칙 문법, 잘못 적었을 때 나타나는 증상까지 다룹니다.

준비물

• Claude Code가 설치되어 있고 로그인이 끝난 상태. 터미널(컴퓨터에 명령을 글자로 쳐서 시키는 창)에서 claude를 입력했을 때 대화 화면이 뜨면 됩니다.
• 텍스트 편집기. 설정 파일은 JSON(중괄호와 따옴표로 값을 적는 형식)이라 메모장 수준으로도 충분합니다.
• 비교적 최근 버전. 아래 내용 중 일부는 버전을 탑니다. 예를 들어 Manual이라는 이름표와 manual 별칭은 v2.1.200 이상에서만 쓸 수 있습니다. 설정이 실제로 어떻게 읽혔는지는 claude doctor로 확인합니다.

권한 규칙을 넣을 파일은 세 곳입니다. 세 파일 모두 permissions 항목을 읽습니다.

• ~/.claude/settings.json: 내 계정 전체에 적용됩니다. 모든 프로젝트에서 같은 규칙을 쓰고 싶을 때 여기에 넣습니다.
• .claude/settings.json: 프로젝트 폴더에 두고 팀과 공유합니다. 다만 이 파일의 allow 규칙과 추가 디렉터리는 해당 폴더를 신뢰한다고 승인한 뒤에야 적용됩니다.
• .claude/settings.local.json: 나만 쓰는 파일입니다. 확인 창에서 다시 묻지 않기를 고르면 Claude Code가 규칙을 여기에 저장합니다.

따라 하기

준비: 지금 상태 확인

1. 현재 규칙을 봅니다. 대화 화면에서 /permissions를 입력합니다. 지금 무슨 규칙이 있는지 모르면 같은 규칙을 두 번 적거나 이미 막혀 있는 명령을 다시 막게 됩니다. 목록에 규칙과 그 규칙이 담긴 settings.json 파일이 함께 뜨면 제대로 열린 상태입니다.
2. 지금 권한 모드를 봅니다. 화면 아래 상태 표시줄에 ⏸ manual mode on, ⏵⏵ accept edits on, ⏸ plan mode on, ⏵⏵ auto mode on 같은 문구가 보입니다. Shift+Tab을 누르면 모드가 차례로 바뀝니다. 규칙과 모드는 층이 다릅니다. 모드가 바닥을 정하고 규칙이 그 위에 개별 예외를 얹습니다.

설정: 규칙 적기

3. 막을 명령부터 deny에 적습니다. 규칙은 deny, ask, allow 순으로 검사하고 먼저 맞는 규칙이 결과를 정합니다. 그래서 어느 파일에 적힌 deny든 다른 파일의 allow를 이깁니다. 아래를 ~/.claude/settings.json에 넣습니다.

   {
     "permissions": {
       "deny": [
         "Bash(git push *)",
         "Read(.env)",
         "Read(./secrets/**)"
       ]
     }
   }

   제대로 됐는지는 Claude에게 원격 저장소로 밀어 달라고 시켜 보면 압니다. 거부 메시지가 나오면 성공입니다. 한 가지 주의할 점이 있습니다. deny 안에는 예외를 넣지 못합니다. Bash(aws *)를 막으면 Bash(aws s3 ls)를 허용해 두어도 함께 막힙니다.
4. 자주 쓰는 명령을 allow에 풉니다. 여기가 확인 창이 줄어드는 지점입니다. 매번 예를 누르던 명령을 적고 달라지는 부분만 별표로 바꿉니다.

   {
     "permissions": {
       "allow": [
         "Bash(npm run *)",
         "Bash(git commit *)"
       ]
     }
   }

   별표는 하위 명령 뒤에 둡니다. Bash(git log *)는 git log 계열만 허용하지만 Bash(git *)는 모든 git 명령을 허용합니다. allow 규칙에서 하위 명령 앞에 별표를 둔 형태, 예를 들어 Bash(git * main)은 시작할 때 경고가 붙습니다. deny와 ask는 넓게 잡는 쓰임이 있어 이 경고 대상이 아닙니다. 공백도 규칙의 일부입니다. Bash(ls *)는 ls에는 걸리고 lsof에는 걸리지 않지만 공백이 없는 Bash(ls*)는 lsof까지 걸립니다.
5. 눈으로 보고 싶은 명령은 ask에 둡니다. 막기는 아깝고 그냥 통과시키기는 불안한 명령이 있습니다.

   {
     "permissions": {
       "ask": ["Bash(git clean *)"]
     }
   }

   ask 규칙은 auto 모드에서도 창을 띄웁니다. 여러 명령을 &&나 ;로 이어 붙여도 조각 하나가 걸리면 물어봅니다.
6. 세션 시작 모드를 정합니다. permissions.defaultMode에 넣습니다. 값은 default(화면에는 Manual), acceptEdits, plan, auto, dontAsk, bypassPermissions입니다. 민감한 작업이라면 default가 안전합니다.

   {
     "permissions": {
       "defaultMode": "default"
     }
   }

   이 값은 세션이 어떤 모드로 시작할지를 정합니다. 그래서 지금 열려 있는 세션은 그대로고 다음에 새로 여는 세션부터 바뀝니다. 저장하고도 상태 표시줄이 그대로라면 세션을 한 번 닫았다 엽니다. 참고로 Pro, Max, Team 요금제의 터미널 세션은 기본 시작 모드가 auto입니다(macOS, Linux, WSL은 v2.1.228 이상, 윈도우는 v2.1.233 이상 기준).
7. 네 덩어리를 파일 하나로 합칩니다. 위 예시들은 설명을 위해 따로 떼어 놓은 조각입니다. 그대로 차례차례 붙여 넣으면 중괄호 묶음이 여러 개가 되어 파일이 읽히지 않습니다. 최상위 중괄호는 하나, 그 안의 permissions도 하나여야 합니다. 아래가 앞의 넷을 합친 ~/.claude/settings.json 전문입니다. 파일을 통째로 이걸로 바꾸고 목록만 내 명령으로 손보면 됩니다.

   {
     "permissions": {
       "defaultMode": "default",
       "deny": [
         "Bash(git push *)",
         "Read(.env)",
         "Read(./secrets/**)"
       ],
       "ask": [
         "Bash(git clean *)"
       ],
       "allow": [
         "Bash(npm run *)",
         "Bash(git commit *)"
       ]
     }
   }

   쉼표는 항목 사이에만 찍고 마지막 항목 뒤에는 찍지 않습니다. 이미 다른 설정이 들어 있는 파일이라면 permissions 한 덩어리만 기존 중괄호 안에 넣고 앞 항목 끝에 쉼표를 더합니다.

확인: 규칙이 실제로 도는지 보기

8. /permissions를 다시 엽니다. 방금 넣은 규칙이 목록에 보이고 옆에 내가 저장한 파일 이름이 붙어 있어야 합니다. 안 보이면 JSON 문법이 깨졌을 가능성이 큽니다.
9. 허용한 명령과 막은 명령을 한 번씩 시켜 봅니다. 허용한 쪽은 창 없이 실행되고 막은 쪽은 거부 메시지가 돌아옵니다. 두 반응이 다 확인되면 설정이 살아 있습니다.

막히기 쉬운 곳

• 경로 규칙의 기준점이 다릅니다. 슬래시 하나로 시작하는 Read(/secrets/**)는 파일시스템 뿌리가 아니라 그 규칙이 적힌 설정 파일 자리를 기준으로 잡습니다. 사용자 설정에 적으면 ~/.claude/secrets/**를 막습니다. 진짜 절대 경로는 슬래시 둘로 시작하고 홈 폴더 기준은 물결표를 씁니다.
• 도구 이름을 잘못 고르면 규칙이 무시됩니다. 파일 경로 규칙은 Edit와 Read에만 걸립니다. Write(docs/**)나 Glob(docs/**)로 적으면 Claude Code가 받아만 두고 참조하지 않으며 시작할 때 경고를 냅니다. 다만 --allowedTools로 넘긴 Glob 규칙은 이 경고에서 빠집니다. 설정 파일에는 Edit(docs/**), Read(docs/**)로 바꿔 적습니다.
• deny가 모든 경로를 막지는 않습니다. Read와 Edit의 deny는 Claude의 파일 도구, cat이나 sed처럼 인식되는 bash 명령, 그리고 출력을 파일로 보내는 리다이렉션 대상에 적용됩니다. 파이썬 스크립트가 스스로 파일을 여는 경우까지는 막지 못합니다. 프로세스 단위로 차단하려면 샌드박스를 켜야 합니다.
• 주소로 걸러 보려는 규칙은 잘 새어 나갑니다. Bash(curl http://github.com/ *)는 옵션 순서가 바뀌거나 https를 쓰거나 리다이렉트를 거치면 맞지 않습니다. curl과 wget을 deny로 막고 필요한 도메인만 WebFetch(domain:github.com)로 여는 편이 낫습니다.
• auto 모드를 프로젝트 파일에 적으면 먹지 않습니다. defaultMode를 auto나 bypassPermissions로 두었는데 Manual로 시작한다면, 값이 .claude/settings.json이나 .claude/settings.local.json에 있을 가능성이 큽니다. ~/.claude/settings.json으로 옮깁니다.

여기서 더 나아가려면

권한 규칙은 Claude가 무엇을 시도할지 걸러 주지만 실행된 명령이 어디까지 닿는지는 정하지 않습니다. 그 층은 /sandbox로 켜는 샌드박스가 맡아 bash 명령의 파일과 네트워크 범위를 운영체제 수준에서 좁힙니다. 조직 전체에 같은 금지 목록을 강제하려면 관리자 배포용 설정을 쓰고 팀 저장소라면 승인된 규칙 파일을 버전 관리에 함께 넣어 공유하면 됩니다.

이상으로 글 마치겠습니다.

출처

• Claude Code 공식 문서, Configure permissions
• Claude Code 공식 문서, Choose a permission mode
• Claude Code 공식 문서, Security