Claude Code settings.json 위치와 설정법 — 설정이 안 먹힐 때 확인할 것

클로드 코드(Claude Code)의 설정은 settings.json이라는 JSON 파일에 들어가요. 문제는 이 파일이 한 곳이 아니라 여러 곳에 있을 수 있다는 점이에요. 이 글을 읽으면 어느 파일에 무엇을 넣을지, 설정이 안 먹힐 때 어디를 볼지 알 수 있어요.

Claude Code settings.json은 어디에 있나요?

직접 고칠 수 있는 파일은 세 개예요 (2026년 10월 기준).

~/.claude는 홈 폴더 안의 .claude 폴더예요. Windows에서는 %USERPROFILE%\.claude예요. 앞에 ~가 없는 .claude는 프로젝트 폴더 안에 있어요.

처음 설치하면 이 파일들은 아직 없어요. 폴더를 찾아도 안 보이는 게 정상이에요. 직접 만들어도 되고, Claude Code가 필요할 때 만들어 주기도 해요.

• /config 메뉴에서 테마 같은 옵션을 바꾸면 ~/.claude/settings.json이 생겨요.
• 권한 질문에 "Yes, and don't ask again"을 고르면 .claude/settings.local.json이 생겨요.

회사에서 관리하는 계정이라면 관리자가 내려보내는 관리 설정(managed settings)도 있어요. 이건 내가 고칠 수 없어요.

홈 폴더에 있는 ~/.claude.json은 이름이 비슷하지만 다른 파일이에요. 계정 정보와 MCP 서버 설정을 Claude Code가 직접 기록하는 곳이라 손댈 필요가 없어요.

settings.json은 어떻게 고치나요?

가장 쉬운 방법은 Claude Code 안에서 /config를 실행하는 거예요. 다만 이 메뉴에는 테마, 편집 모드 같은 일부 옵션만 있어요.

나머지는 파일을 직접 열어 고쳐요. 예를 들어 테스트 명령은 묻지 않고 실행하고, .env 파일은 읽지 못하게 하려면 이렇게 써요.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

첫 줄의 $schema는 편집기에서 자동 완성과 오류 표시를 켜 주는 줄이에요. VS Code나 Cursor에서 쓰면 편해요.

주의할 점이 두 가지 있어요.

1. 이 파일은 엄격한 JSON이에요. // 주석이나 마지막 쉼표가 있으면 오류가 나요.
2. 대부분의 수정은 저장하면 바로 적용돼요. 하지만 model처럼 시작할 때만 읽는 값도 있어요. 이때는 /model로 바꾸거나 새로 시작해요.

저는 처음엔 /config로 시작하고, 권한 규칙이 필요해질 때 파일을 여는 게 맞다고 봐요. 권한 규칙 문법이 처음이라면 Claude Code Auto 모드 가이드의 allow·deny 설명을 같이 보면 좋아요.

같은 설정이 여러 파일에 있으면 무엇이 이기나요?

위에 있을수록 우선이에요.

1. 관리 설정 (회사가 내려보낸 것)
2. 실행할 때 붙인 --settings 옵션
3. .claude/settings.local.json
4. .claude/settings.json
5. ~/.claude/settings.json

즉 내 홈 폴더 설정이 가장 약해요. 팀 파일이 같은 값을 정하면 그 프로젝트에서는 팀 값이 적용돼요. 그 프로젝트에서만 내 값을 쓰고 싶다면 .claude/settings.local.json에 다시 적으면 돼요.

예외도 있어요. permissions.allow 같은 목록은 하나를 고르지 않고 모든 파일의 목록을 합쳐요. 그래서 팀 규칙과 내 규칙이 함께 적용돼요.

환경 변수도 따로 봐야 해요. 예를 들어 셸에 ANTHROPIC_MODEL이 있으면 어느 파일의 model보다 이게 먼저예요. 구독을 샀는데 API 요금이 나온다면 ANTHROPIC_API_KEY 변수부터 보세요. 이 내용은 Claude Code 요금제 가격 차이 글에 정리해 뒀어요.

설정이 안 먹힐 때는 무엇부터 확인하나요?

순서대로 확인해 보세요.

1. /status를 실행해요. Setting sources 줄에 Claude Code가 읽은 파일 목록이 나와요. 내 파일이 없으면 아예 읽지 못한 거예요.
2. claude doctor를 실행해요. 잘못 적어서 건너뛴 항목을 알려 줘요.
3. 더 위의 파일이 같은 값을 정했는지 봐요. 위 우선순위 목록을 떠올리면 돼요.
4. 그 파일에 넣을 수 없는 값인지 봐요. 예를 들어 permissions.defaultMode의 auto는 프로젝트 파일에 넣어도 적용되지 않아요. ~/.claude/settings.json에 넣어야 해요.
5. 폴더를 신뢰했는지 봐요. 팀 파일의 allow 규칙은 각자 그 폴더를 신뢰(trust)한 뒤에 적용돼요. deny 규칙은 바로 적용돼요.

Codex도 쓴다면 Codex config.toml 위치와 설정 정리와 비교해 보세요. 저는 두 도구 모두 "개인 파일 하나 + 프로젝트 파일 하나"만 기억하면 대부분 해결된다고 봐요.

자주 묻는 질문

settings.local.json을 git에 올려도 되나요?

올리지 않는 게 맞아요. Claude Code가 이 파일을 만들 때 git 제외 목록에 자동으로 넣어요. 직접 만들었다면 .gitignore에 직접 추가해 주세요.

한 번만 다른 설정으로 실행할 수 있나요?

돼요. claude --settings '{"model": "claude-opus-5-5"}'처럼 실행하면 그 세션에만 적용되고 파일은 바뀌지 않아요.

설정 파일 위치를 옮길 수 있나요?

CLAUDE_CONFIG_DIR 환경 변수를 정하면 홈 폴더 대신 그 위치에 설정과 기록을 저장해요.

CLAUDE.md와 settings.json은 무엇이 다른가요?

settings.json은 모델, 권한 같은 동작 설정이에요. Claude에게 주는 작업 지시는 CLAUDE.md에 써요.

참고 문서: Claude Code Settings files and precedence