샌드박스를 켰는데 안 켜졌을 수 있습니다 — 기본값이 그렇게 되어 있습니다

에이전트 격리 · 샌드박스

못 뜨면 경고만 하고
그냥 실행됩니다.

샌드박스를 켜뒀는데 시작할 수 없는 상황이면 어떻게 될까요. 문서에 적혀 있습니다 — 경고를 보여주고 샌드박스 없이 명령을 실행합니다. 그게 기본 동작입니다.

에이전트 권한 글을 쓰면서 "샌드박싱 문서는 확인하지 못했다"고 각주에 적어뒀습니다. 그 문서를 열었습니다. 권한을 좁히는 것과 격리하는 것은 다른 이야기인데, 격리 쪽에 알아둘 게 꽤 있었습니다.

📌 30초 요약

• 샌드박스는 파일과 네트워크를 운영체제 수준에서 막습니다.
• ⚠️ 네이티브 윈도우는 지원 대상이 아닙니다. WSL2 안에서 돌려야 합니다.
• ⚠️ 샌드박스가 못 뜨면 경고만 하고 그냥 실행됩니다. 이게 기본값입니다.
• 샌드박스에서 실패한 명령이 밖에서 다시 실행되는 통로도 기본으로 열려 있습니다.
• 문서가 자기 한계를 다섯 가지 적어뒀습니다. 그중 몇 개는 설정 하나로 격리가 무력해집니다.

① 샌드박스가 하는 일

권한 설정이 "이 명령을 해도 되나"를 매번 묻는 방식이라면, 샌드박스는 "어디까지 손댈 수 있나"를 미리 정해두고 운영체제가 강제하는 방식입니다. 그래서 일일이 승인하지 않아도 됩니다.

📦 기본 경계

기본값으로 샌드박스 안의 명령은 작업 디렉터리와 세션 임시 디렉터리에만 쓸 수 있습니다. 네트워크는 새 도메인에 처음 접속할 때 승인을 묻습니다. 그리고 샌드박스로 돌릴 수 없는 명령은 원래의 승인 절차로 돌아갑니다.

🖥 운영체제별로 다릅니다

macOS — 내장 기능을 쓰므로 설치할 게 없습니다.
리눅스·WSL2 — 패키지 두 개(bubblewrap, socat)가 필요합니다.

네이티브 윈도우와 WSL1은 지원하지 않습니다. 윈도우에서는 WSL2 안에서 실행해야 한다고 문서가 명시합니다.

② 여기가 핵심입니다 — 못 뜨면 그냥 돕니다

📄 원문

"By default, if the sandbox cannot start because dependencies are missing or the platform is unsupported, Claude Code shows a warning and runs commands without sandboxing. To make this a hard failure instead…"

→ 의존 패키지가 없거나 플랫폼이 미지원이면, 경고를 띄우고 샌드박스 없이 실행합니다. 이걸 실패로 처리하려면 따로 설정해야 한다고 이어집니다.

두 조건이 한국 사용자에게 특히 잘 걸립니다. 윈도우에서 그냥 돌리면 플랫폼 미지원에 해당하고, 리눅스나 WSL2라도 패키지 두 개를 안 깔았으면 의존성 누락입니다. 둘 다 "경고 후 그냥 실행"으로 처리됩니다.

🔍 이런 구조를 전에도 봤습니다

프롬프트 캐싱도 최소 길이에 못 미치면 에러 없이 조용히 안 걸렸습니다. 이번 것도 경고는 뜨지만 멈추지는 않습니다. 켜뒀다고 생각하고 넘어가기 좋은 형태입니다 — 안전장치일수록 "실패했을 때 어떻게 되는지"를 먼저 봐야 합니다.

🚪 탈출구가 하나 더 있습니다

샌드박스 안에서 실패한 명령을 샌드박스 밖에서 다시 실행하도록 하는 설정이 있고, 기본으로 열려 있습니다. 이걸 끄면 문서가 엄격 모드라고 부르는 상태가 됩니다.

편의를 위한 장치입니다. 다만 "샌드박스를 켰다"와 "모든 명령이 샌드박스 안에서 돈다"가 같은 말이 아니라는 것은 알고 계셔야 합니다.

③ 문서가 스스로 적어둔 한계

이 문서의 좋은 점은 「보안 한계」라는 절을 따로 두고 약한 곳을 직접 나열한다는 겁니다. 요약해 옮깁니다.

항목	문서가 밝힌 내용
네트워크 필터링	기본 프록시는 암호화 트래픽 내용을 검사하지 않습니다. 넓은 도메인을 허용하면 데이터가 빠져나갈 경로가 생길 수 있습니다
유닉스 소켓	특정 소켓을 열어주면 호스트 전체에 접근하게 될 수 있다고 예까지 들어 경고합니다
파일 쓰기 범위	실행 파일이 있는 폴더나 셸 설정 파일에 쓰기를 허용하면 권한 상승으로 이어질 수 있습니다
리눅스 약화 모드	도커 안 등에서 쓰라고 열어둔 옵션인데 보안을 상당히 약화시킨다고 문서가 직접 적었습니다
맥 이벤트 허용	켜면 코드 실행 격리가 사라집니다. 샌드박스 안 명령이 다른 앱을 샌드박스 밖에서 띄울 수 있습니다

💡 다섯 개를 관통하는 한 문장

넓게 열어주는 설정 하나가 격리를 통째로 무력화합니다. 샌드박스는 기본값이 좁아서 안전한 것이고, 편하려고 하나씩 넓히다 보면 켜둔 의미가 사라집니다. 문서가 "허용할 도메인은 당신 책임"이라고 못박아둔 것도 같은 맥락입니다.

④ 켜져 있는지 확인하는 법

1. 전용 명령으로 상태 창을 엽니다. 문서에 /sandbox라고 나옵니다. 모드·예외·현재 설정을 볼 수 있고, 필요한 패키지가 빠져 있으면 그것만 표시되는 탭이 뜹니다.

2. 윈도우라면 어디서 돌고 있는지부터. 네이티브 윈도우면 애초에 대상이 아닙니다. WSL2인지 확인하세요 — WSL1도 안 됩니다.

3. 못 떴을 때 멈추게 할지 정하세요. 기본은 경고 후 실행입니다. 중요한 작업이라면 실패로 처리하는 쪽이 맞습니다.

4. 팀이라면 개인 설정에 맡기지 마세요. 조직 차원에서 강제하는 방법이 문서에 따로 있습니다. 각자 켜기를 기대하면 안 켠 사람이 반드시 생깁니다.

🚫 이 글이 확인하지 못한 것

저는 샌드박스를 실제로 켜서 시험해보지 않았습니다. 이 글은 문서에 무엇이 적혀 있나까지입니다. 설정 이름과 정확한 값은 버전에 따라 다를 수 있어 본문에서 일부러 최소한만 적었습니다 — 쓰실 때는 해당 버전 문서를 여세요.

그리고 이건 한 도구의 샌드박스입니다. 다른 에이전트 도구의 격리 방식은 확인하지 않았습니다. 다만 "안 뜨면 어떻게 되나"라는 질문은 어느 도구에나 그대로 쓰실 수 있습니다.

자주 묻는 것

Q. 샌드박스만 켜면 안심해도 되나요?

문서가 아니라고 적어뒀습니다. 위 다섯 가지 한계가 그 답입니다. 특히 네트워크는 내용을 검사하지 않으니 허용 도메인을 넓게 잡으면 격리의 의미가 줄어듭니다.

Q. 승인 프롬프트가 줄어드는 게 목적인가요?

그게 문서가 내세우는 이점 중 하나입니다 — 매번 묻는 대신 경계를 미리 정하는 방식이니까요. 다만 승인 창이 줄었다고 위험이 줄어든 건 아닙니다. 경계를 어떻게 잡았느냐에 달렸습니다.

Q. 계정 로그인을 넘기는 봇에도 적용되나요?

다른 이야기입니다. 이 샌드박스는 내 컴퓨터에서 도는 명령의 경계를 정하는 것이고, 클라우드에서 내 계정으로 로그인하는 봇은 애초에 권한을 쪼갤 자리가 없는 구조입니다. 격리로 막을 수 있는 문제가 아닙니다.

✨ 정리하면

샌드박스는 운영체제가 강제하는 경계라 승인 창을 줄여줍니다. 기본 범위는 작업 디렉터리와 임시 폴더뿐입니다.

그런데 못 뜨면 경고만 하고 그냥 실행되고, 네이티브 윈도우는 대상이 아닙니다. 켰다고 켜진 게 아닐 수 있습니다.

상태 창을 한 번 열어보세요. 그리고 못 떴을 때 멈출지 그냥 갈지는 직접 정하셔야 합니다.

🧭 AI 도입 전체 그림

권한·격리·비용은 같이 옵니다. 개인·개발자·회사별로 묶어둔 허브가 있습니다 → AI에 쓰는 돈 총정리 — 숨은 비용 7가지

🔗 같이 보면 좋은 글

• 에이전트 권한 — 디렉터리에 있다고 감사를 받은 건 아닙니다
• 봇에게 내 계정 로그인을 넘기기 전에
• 캐싱은 조용히 실패합니다 — 같은 구조의 함정
• 에이전트를 여러 개 돌릴 때의 바닥 — 작업 폴더를 나누는 방법

---

확인 시점 — 2026년 8월 14일. ✅ 1차 확인 : Claude Code 공식 문서의 샌드박스 설정 페이지 원문 직접 열람(약 66,000자) — 기본 파일·네트워크 경계, 운영체제별 구현과 지원 범위, 상태 확인 명령, 샌드박스 미기동 시의 기본 동작, 미샌드박스 재실행 설정과 엄격 모드, 「보안 한계」 절의 다섯 항목. 인용한 영문은 원문 그대로입니다. 확인하지 않은 것 : 실제로 샌드박스를 켜서 동작을 검증한 결과 · 버전별 설정값 차이(그래서 본문에 설정 이름을 최소한만 적었습니다) · 다른 에이전트 도구의 격리 방식 · 조직 강제 설정의 실제 적용 절차. 본문 ③의 표는 문서의 한계 항목을 우리말로 요약한 것이며, 정확한 설정 이름과 조건은 원문을 보셔야 합니다. 도구와 문서는 자주 바뀝니다. 제휴·협찬 없습니다.