Claude Code 설정 키 정리 — 파일별 적용 범위·폐기 키·기업 제한

Claude Code 설정을 만지다 보면 분명히 적었는데 안 먹는 경험을 하게 됩니다. 우선순위 때문이겠거니 하고 위 단계에 다시 적어 봐도 그대로일 때가 있고요. 최근에 설정 키 전체 참조 문서가 새로 나왔는데, 그걸 훑어 보면 원인이 하나 더 있다는 게 보입니다.

키마다 놓을 수 있는 파일이 정해져 있습니다. 우선순위 이전의 문제입니다 — 애초에 그 파일에서 읽지 않는 키라면, 몇 층에 적든 안 먹습니다.

📌 30초 요약

• 키마다 허용 범위가 다릅니다. 아무 데나 · 사용자 전용 · 관리형 전용 · 전역 파일 전용 등으로 갈립니다.
• 전역 파일에서만 읽는 키가 따로 있습니다. 프로젝트 설정에 적으면 무시됩니다.
• 폐기된 키 넷 — 그중 하나는 애초에 효과가 없었다고 문서가 밝힙니다.
• 한 번 끄면 어느 파일로도 못 켜는 키가 있습니다.
• 기업은 버전까지 잠글 수 있습니다. 범위 밖이면 아예 시작을 거부합니다.

① 같은 설정 파일이라도 안 먹는 키가 있습니다

설정 파일이 여러 층으로 겹치고 그 값들이 합쳐진다는 건 이미 정리한 적이 있습니다(덮어쓰기가 아니라 합치기). 이번 참조 문서에서 새로 드러나는 건 그 이전 단계입니다 — 어떤 키는 특정 파일에서만 읽힙니다.

허용 범위	어디에 둘 수 있나
아무 파일	사용자·프로젝트·프로젝트 로컬·관리형 전부
사용자 또는 관리형	프로젝트 쪽엔 못 둠
사용자·로컬·관리형	프로젝트 공유 설정만 제외
관리형 전용	조직이 배포하는 경로에만
전역 설정 파일 전용	홈 폴더의 전역 파일에만 — 설정 파일들에는 못 둠

마지막 줄이 가장 헷갈리는 자리입니다. 우리가 흔히 쓰는 설정 파일들과, 홈 폴더에 따로 있는 전역 설정 파일은 서로 다른 파일입니다. 여기에만 쓰는 키가 있는데, 대표적으로 차이 보기 도구 지정, IDE 자동 연결, IDE 확장 자동 설치가 그렇습니다.

즉 「차이 보기 도구를 프로젝트마다 다르게 쓰고 싶다」는 시도는 애초에 안 됩니다. 프로젝트 설정에 적어도 읽히지 않습니다. 우선순위 문제가 아니라 범위 문제라, 상위 층에 적어 봐야 똑같습니다. 설정이 안 먹을 때 파일 위치부터 의심하시라는 이야기이기도 합니다(설정이 안 먹힐 때).

② 폐기된 키 넷 — 하나는 애초에 효과가 없었습니다

참조 문서에는 더는 쓰지 말라고 표시된 키가 함께 실려 있습니다. 오래된 블로그 글이나 사내 문서를 보고 그대로 복사해 두신 게 있다면 확인해 보실 만합니다.

폐기된 키	어떻게 됐나
산출물 끄기	켜기 키에 거짓을 주는 방식으로 대체
공동 작성자 표기 넣기	표기 설정으로 커밋·PR을 따로 제어
단축키 방식 선택	효과가 없음 — 단어 편집 단축키는 항상 같은 관례를 따름
권한 설명 표시	특정 판올림에서 제거됨

세 번째가 흥미롭습니다. 단축키 방식을 고르는 키는 폐기 표시와 함께 「효과가 없다」고 적혀 있습니다. 없앤 게 아니라 원래부터 아무 일도 안 했다는 뜻입니다. 이 값을 넣어 두고 「내 단축키가 이렇게 설정돼 있다」고 믿고 계셨다면 그 전제가 틀린 겁니다.

⚠️ 한 번 끄면 어느 파일로도 못 켜는 키

산출물 기능은 켜기 키에 거짓을 주면 전역으로 꺼지고, 그다음엔 어떤 파일에서도 다시 켤 수 없습니다. 대부분의 설정이 「아래 층에서 덮어쓰기」로 되돌릴 수 있는 것과 다른 동작입니다. 조직 차원에서 끄는 용도로 만들어진 방향성인데, 개인 설정에 무심코 넣으면 되돌리기가 까다로워집니다.

③ 기업이 잠글 수 있는 것들

관리형 전용 키 중에는 개인 설정으로는 손댈 수 없는 통제가 몇 가지 있습니다. 회사 노트북에서 뭔가 막혀 있다면 여기 있을 가능성이 큽니다.

• 버전 하한·상한 강제 — 정해 둔 범위를 벗어나면 아예 시작을 거부합니다. 최신판으로 올렸다가 실행이 안 되면 이걸 의심해 보세요.
• 명령줄 곁들이기 차단 — 플러그인·하위 에이전트·MCP 서버를 명령줄 플래그로 얹는 걸 거부합니다.
• 플러그인 외 확장 전면 차단 — 스킬·에이전트·훅·MCP를 사용자·프로젝트 출처에서 아예 못 가져오게 막습니다. 승인된 플러그인만 남습니다.
• 관리형 MCP만 허용 — 조직이 배포한 것 외의 연결을 막습니다.
• 로그인 경로 강제·접속 대상 허용 목록 — 어디로 로그인하고 어디에 붙을 수 있는지를 조직이 정합니다.

이 키들이 관리형 전용이라는 점이 중요합니다. 사용자 설정에 같은 키를 적어도 읽히지 않습니다. 조직 정책이 어디까지 내려오고 어디는 안 내려오는지는 기능마다 다른데(조직 설정이 안 먹는 자리), 참조 문서의 범위 표시가 그 경계를 알려 주는 가장 빠른 방법입니다.

④ 하위 설정이 가장 많은 곳 — 격리 실행

참조 문서에서 하위 항목이 압도적으로 많은 묶음이 하나 있습니다. 명령을 격리해서 실행하는 샌드박스 쪽입니다.

켜고 끄는 값 외에 파일 접근 8개 남짓, 네트워크 10개 이상, 자격증명 5개의 하위 설정이 딸려 있습니다. 여기에 보조 도구 경로 지정까지 붙습니다. 세밀하게 조일 수 있다는 뜻이지만, 뒤집으면 기본값으로 두면 무엇이 열려 있는지 모르는 채로 쓰게 된다는 뜻이기도 합니다.

참조 문서가 열두 갈래 남짓으로 묶여 있는데, 실제로 손댈 만한 건 권한·기억과 맥락·훅·도구 쪽에 몰려 있습니다. 나머지는 대부분 조직이 배포하거나 한 번 정하고 안 건드리는 값들입니다. 전부 읽으실 필요는 없고, 지금 안 먹는 키 하나를 찾을 때 범위 표시만 확인하시면 됩니다.

⑤ 자주 묻는 질문 (FAQ)

Q. 설정이 안 먹을 때 뭘 먼저 보나요?

순서를 바꾸세요. 지금까지는 우선순위부터 보셨을 텐데, 그 키가 이 파일에서 읽히는지를 먼저 확인하는 게 빠릅니다. 참조 문서에 키마다 허용 범위가 붙어 있으니 거기부터 보고, 범위가 맞으면 그때 우선순위를 따지세요.

Q. 전역 설정 파일과 설정 파일은 뭐가 다른가요?

이름이 비슷해서 헷갈리는데 다른 파일입니다. 우리가 층층이 겹쳐 쓰는 건 설정 파일들이고, 홈 폴더에 하나 더 있는 게 전역 설정 파일입니다. IDE 연결이나 차이 보기 도구처럼 기기 단위로 한 번 정하는 값이 그쪽에 모여 있습니다.

Q. 회사 노트북에서 플러그인 설치가 막혔는데요?

관리형 설정에서 플러그인 외 확장을 전면 차단했을 가능성이 큽니다. 이 경우 스킬·에이전트·훅·MCP를 사용자나 프로젝트 쪽에서 가져올 수 없고 승인된 플러그인만 남습니다. 개인 설정으로는 풀 수 없으니 관리자에게 요청하는 것 말고는 방법이 없습니다.

Q. 지금 뭘 정리해 두면 좋을까요?

① 쓰고 계신 설정 파일을 열어 폐기 표시된 키가 있는지 보세요. ② 프로젝트 설정에 넣어 둔 키 중 범위가 안 맞는 것을 골라내세요 — 안 먹고 있었을 겁니다. ③ 산출물처럼 되돌리기 어려운 키는 개인 설정에 두지 마세요. ④ 격리 실행을 쓰신다면 기본값이 무엇을 열어 두는지 한 번 확인해 두세요.

✨ 정리

설정이 안 먹는 이유는 우선순위 말고 하나 더 있습니다 — 그 파일에서 아예 안 읽는 키일 수 있습니다. 새 참조 문서의 범위 표시가 그걸 바로 알려 줍니다. 겸사겸사 폐기된 키도 걷어내시고, 산출물처럼 한 번 끄면 못 켜는 키는 개인 설정에 두지 마세요. 회사에서 막힌 게 있다면 관리형 전용 키 목록을 보시면 답이 나옵니다.

더 읽을거리: AI 개발 비용·도구 총정리 허브

출처: Claude Code 공식 문서 「All settings」 전체 참조(code.claude.com, 2026년 9월 확인). 키마다 허용 범위가 다르다는 점과 다섯 갈래의 범위 구분, 전역 설정 파일에서만 읽는 키(차이 보기 도구·IDE 자동 연결·IDE 확장 자동 설치), 폐기된 키 넷과 단축키 방식 선택 키가 「효과가 없다」는 서술, 산출물 기능을 끄면 어느 파일로도 다시 켤 수 없다는 방향성, 관리형 전용 통제(버전 하한·상한 강제 시 시작 거부, 명령줄 곁들이기 차단, 플러그인 외 확장 전면 차단, 관리형 MCP 전용, 로그인 경로 강제, 접속 허용 목록), 격리 실행 묶음의 하위 설정이 가장 많다는 점은 모두 해당 문서에 담긴 내용입니다. 키 총 개수와 갈래 수는 문서 규모를 어림한 것이며 정확한 수치가 아닙니다 — 실제 목록은 공식 참조를 직접 확인하세요. 「실제로 손댈 만한 건 권한·기억과 맥락·훅·도구 쪽에 몰려 있다」는 평가와 ④절의 해석, FAQ의 점검 순서는 필자 의견입니다. 설정 키는 판올림마다 늘거나 사라지니 적용 전 최신 문서를 확인하세요.