claude code sandbox — 켜는 법과 윈도우 제약
클로드 코드의 샌드박스는 세션에서 /sandbox를 치면 켭니다. 켜 두면 Bash 명령을 하나하나 승인하는 대신, 건드려도 되는 파일 경로와 접속해도 되는 도메인을 미리 정해 두고 운영체제가 그 경계를 강제합니다. 다만 먼저 알아야 할 제약이 하나 있습니다 — 네이티브 윈도우에서는 안 됩니다. macOS·리눅스·WSL2만 지원하므로, 윈도우라면 WSL2 안에서 클로드 코드를 실행해야 합니다. 아래는 Claude Code 2.1.204 기준입니다.
샌드박스가 정확히 뭘 막는가
이름만 보면 "안전 모드" 같지만, 실제로 하는 일은 두 가지로 딱 갈립니다.
- 파일 경계 — 샌드박스 안에서 도는 명령은 기본적으로 현재 작업 디렉터리, 세션 임시 디렉터리,
--add-dir로 추가한 디렉터리에만 쓸 수 있습니다. - 네트워크 경계 — 샌드박스 밖에서 도는 프록시가 도메인을 거릅니다. 기본으로 열려 있는 도메인은 하나도 없습니다.
중요한 건 이게 OS 수준에서 걸린다는 점입니다. 명령이 띄운 자식 프로세스까지 같은 경계를 받습니다. 그래서 "스크립트가 또 다른 스크립트를 부르면 어떻게 되나" 같은 걱정을 안 해도 됩니다.
켜는 법 — /sandbox 패널
세션에서 /sandbox를 치면 탭 세 개짜리 패널이 열립니다.
| 탭 | 하는 일 |
|---|---|
| Mode | 샌드박스로 도는 명령을 자동 승인할지 고릅니다 |
| Overrides | 샌드박스에서 실패한 명령이 밖에서 다시 돌 수 있는지 (allowUnsandboxedCommands) |
| Config | 지금 적용된 샌드박스 설정을 봅니다 |
리눅스에서 필요한 패키지가 빠져 있으면 Dependencies 탭이 하나 더 보입니다. 이 탭만 덩그러니 보인다면 설치가 덜 된 것입니다.
모드는 둘뿐입니다
파일·네트워크 제한은 두 모드가 똑같습니다. 차이는 오직 승인을 묻느냐입니다.
- auto-allow — 샌드박스로 돌릴 수 있는 명령은 묻지 않고 실행합니다. 못 돌리는 명령(허용 안 된 호스트가 필요한 경우 등)만 평소의 권한 흐름으로 넘어갑니다.
- regular permissions — 샌드박스로 돌더라도 평소처럼 전부 승인을 받습니다. 통제는 강하지만 손이 많이 갑니다.
auto-allow를 골라도 그대로 남는 안전장치가 있습니다.
- 명시적인 deny 규칙은 언제나 지켜집니다
- 중요 경로를 지우는
rm·rmdir은 여전히 승인을 받습니다 Bash(git push *)처럼 내용까지 지정한 ask 규칙은 샌드박스 명령에도 그대로 걸립니다
반대로 Bash나 Bash(*)처럼 통째로 물어보라는 ask 규칙은 샌드박스로 도는 명령에 한해 건너뜁니다. 단 클로드 코드 플랜 모드에서는 건너뛰지 않고 읽기 전용 명령까지 물어봅니다.
설정이 저장되는 자리
패널에서 모드를 고르면 그 프로젝트의 .claude/settings.local.json에 저장됩니다. 프로젝트마다 따로 논다는 뜻입니다. 모든 프로젝트에 걸고 싶으면 사용자 설정에 직접 씁니다.
// ~/.claude/settings.json
{
"sandbox": {
"enabled": true
}
}설정 파일을 건드리지 않고 이번 세션만 바꾸려면 시작할 때 넘깁니다.
claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'설정 파일이 여러 군데 있어 어느 게 이기는지 헷갈린다면 클로드 코드 설정 파일에 우선순위를 정리해 두었습니다.
윈도우에서는 왜 안 되나
공식 문서는 짧게 못박습니다 — "WSL1과 네이티브 윈도우는 지원하지 않는다." 빈말이 아니라 설치본 안에도 이 문장이 들어 있습니다.
Enterprise policy requires sandboxing, but sandboxing is not available on
native Windows. Shell command execution is blocked on this platform by policy.회사 정책으로 샌드박스가 강제된 환경이라면 윈도우에서 셸 명령 실행 자체가 막힌다는 뜻입니다. 개인 설정이라면 그 정도는 아니고, 기본 동작은 경고만 내고 샌드박스 없이 그냥 도는 것입니다. 이게 위험하다고 보면 하드 실패로 바꿀 수 있습니다.
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true
}
}WSL2에서 쓰려면 챙길 것
macOS는 OS에 내장된 Seatbelt를 쓰기 때문에 설치할 게 없습니다. 리눅스와 WSL2는 패키지 두 개가 필요합니다.
sudo apt-get install bubblewrap socat| 필요한 것 | 역할 | 필수인가 |
|---|---|---|
bubblewrap | 파일 격리를 실제로 거는 도구 | ✅ |
socat | 트래픽을 샌드박스 프록시로 넘기는 중계 | ✅ |
| seccomp 필터 | 유닉스 도메인 소켓까지 차단 | 선택 (npm i -g @anthropic-ai/sandbox-runtime) |
| ripgrep | — | 네이티브 바이너리에 번들돼 있음 |
뭐가 빠졌는지는 /sandbox의 Dependencies 탭이 이름으로 알려 줍니다. 설치하고 클로드 코드를 다시 띄웠는데 그 탭이 안 보이면 다 갖춰진 것입니다.
열어 줄 경로 넓히기
kubectl·terraform·npm처럼 작업 폴더 밖에 파일을 쓰는 도구가 있습니다. 이럴 때 그 도구를 샌드박스에서 빼는 것보다 경로를 열어 주는 편을 공식 문서가 권합니다.
{
"sandbox": {
"enabled": true,
"filesystem": {
"allowWrite": ["~/.kube", "/tmp/build"]
}
}
}여기서 경로 표기가 헷갈리기 쉽습니다. 권한 규칙(Read·Edit)의 표기와 다릅니다.
| 접두사 | 기준 |
|---|---|
/tmp/build | 파일시스템 루트 기준 절대경로 |
~/.kube | 홈 디렉터리 기준 |
./output (또는 접두사 없음) | 프로젝트 설정이면 프로젝트 루트, 사용자 설정이면 ~/.claude |
"allowRead": ["."]를 사용자 설정에 넣으면 프로젝트 루트가 아니라 ~/.claude가 열립니다. 프로젝트를 가리키려면 그 설정을 프로젝트의 .claude/settings.json에 둬야 합니다.
읽기 쪽은 denyRead·allowRead로 짜는데, 규칙이 겹치면 더 좁은 경로가 이깁니다.
| 규칙 | 결과 |
|---|---|
denyRead: ["~/"] + allowRead: ["~/projects"] | ~/projects만 읽히고 나머지 홈은 막힘 |
allowRead: ["~/"] + denyRead: ["~/.env"] | ~/.env만 막히고 나머지 홈은 읽힘 |
allowRead: ["~/"] + denyRead: ["~/**/.env"] | 홈 아래 모든 .env가 막힘 |
넓은 allow가 좁은 deny를 덮어쓰지 못한다는 게 핵심입니다. 비밀 파일을 실수로 다시 여는 일을 막아 줍니다.
네트워크는 기본이 전부 차단입니다
미리 열린 도메인이 하나도 없습니다. 명령이 새 도메인에 붙으려 하면 그때 승인을 묻습니다.
- Yes — 이번 세션 동안만 그 호스트를 허용합니다
- Yes, and don't ask again — 로컬 설정에
WebFetch(domain:...)허용 규칙으로 저장돼 다음 세션에도 남습니다
매번 묻는 게 싫으면 미리 적어 둡니다.
{
"sandbox": {
"enabled": true,
"network": {
"allowedDomains": ["registry.npmjs.org", "*.pythonhosted.org"],
"strictAllowlist": true
}
}
}strictAllowlist를 켜면 목록 밖 호스트는 묻지도 않고 거부합니다. 두 가지 단서가 있습니다 — v2.1.219 이상이어야 하고, 레포의 .claude/settings.json에 넣으면 안 먹습니다. 사용자 설정·관리 설정·CLI --settings에서만 적용됩니다.
빠져나가는 구멍과 그걸 막는 법
샌드박스 안에서 아예 못 도는 명령이 있습니다. 이때 클로드 코드는 작업을 실패시키는 대신 dangerouslyDisableSandbox를 붙여 다시 시도할 수 있습니다. 다시 돌 때는 샌드박스 밖이라 평소의 권한 흐름을 타고, 수동 모드라면 확인 창이 뜹니다.
이 구멍을 아예 막으려면 이렇게 합니다. 패널의 Overrides 탭에 Strict sandbox mode로 표시되는 설정입니다.
{
"sandbox": {
"enabled": true,
"allowUnsandboxedCommands": false
}
}참고로 내가 직접 !를 붙여 치는 셸 명령은 이 설정과 무관하게 샌드박스 밖에서 돕니다(백그라운드 세션 등 몇 경우는 예외). 스크립트에 물려 자동으로 돌릴 때의 이야기는 클로드 코드 자동화에 정리해 두었습니다.
샌드박스는 완전한 격리가 아닙니다
공식 문서가 직접 밝히는 한계입니다. 보안 경계로 삼기 전에 알아 둬야 합니다.
- TLS를 들여다보지 않습니다. 프록시는 클라이언트가 말한 호스트 이름만 보고 허용 여부를 정합니다. 그래서
github.com처럼 넓은 도메인을 열어 두면 데이터가 빠져나가는 경로가 될 수 있습니다. - 유닉스 소켓 허용은 특히 위험합니다.
/var/run/docker.sock을 열어 주면 사실상 호스트 전체를 내주는 셈입니다. - 쓰기 경로를 넓힐 때 조심하세요.
$PATH에 있는 실행 파일 폴더나.bashrc같은 셸 설정 파일에 쓰게 열면 다른 맥락에서 코드가 실행될 수 있습니다. - 환경 변수는 그대로 상속됩니다. 샌드박스 안 명령도 부모 프로세스의 환경을 물려받으므로 거기 든 자격증명이 같이 넘어갑니다.
sandbox.credentials로 특정 변수를 지우거나 가릴 수 있습니다.
자주 묻는 것
Q. 윈도우인데 /sandbox가 아무 일도 안 합니다.
네이티브 윈도우는 지원 대상이 아닙니다. WSL2 배포판 안에서 클로드 코드를 실행하고, 그 안에 bubblewrap과 socat을 설치하세요. WSL1은 안 됩니다.
Q. 샌드박스를 켜면 승인 창이 아예 안 뜨나요?
Bash 명령에 한해, 그것도 auto-allow 모드일 때만 그렇습니다. 파일을 고치는 Edit·Write는 여전히 권한 시스템을 타고, deny 규칙과 중요 경로 삭제는 어느 모드에서든 막힙니다.
Q. 명령이 Operation not permitted로 실패합니다.
쓰기가 막힌 경로이거나 허용 안 된 호스트일 가능성이 큽니다. 실패한 명령의 결과에 샌드박스가 막은 경로나 호스트 이름이 찍혀 나오니 그걸 보고 allowWrite나 allowedDomains에 추가하면 됩니다. 컨테이너 안이라면 bubblewrap 쪽 문제일 수도 있습니다.
Q. 서브에이전트도 샌드박스가 걸리나요?
걸립니다. 서브에이전트는 부모 세션과 같은 프로세스에서 돌고 같은 샌드박스 설정을 씁니다.
Q. 다른 AI CLI도 이런 게 있나요?
있습니다. 다만 구조가 다릅니다. Codex는 샌드박스 모드를 세 가지로 나누고 승인 정책과 짝을 지어 쓰는데, 그건 codex 샌드박스 설정에 따로 정리해 두었습니다.
마무리
정리하면 샌드박스는 "승인을 줄이는 대신 경계를 미리 그어 두는" 맞바꿈입니다. 그래서 켜기 전에 정해야 할 건 두 가지뿐입니다 — 어디에 쓸 수 있게 할지(allowWrite)와 어디에 접속할 수 있게 할지(allowedDomains). 이 둘을 좁게 잡으면 auto-allow로 두고도 마음이 놓입니다.
윈도우 사용자라면 결론은 하나입니다. WSL2로 옮기세요. 네이티브 윈도우에서는 설정을 아무리 넣어도 샌드박스가 안 붙고, 기본값에서는 경고만 뜬 채 그냥 돌아갑니다.
설정 키와 플랫폼 지원은 버전을 탑니다. 이 글은 Claude Code 2.1.204 기준이며, strictAllowlist처럼 버전이 필요한 항목은 본문에 적어 두었습니다.
📚 참고 출처 (2026년 9월 18일 확인 · Claude Code 2.1.204 · 윈도우 11에서 설치본 대조)
· Configure the sandboxed Bash tool — Claude Code 공식 문서
· Settings reference — Claude Code 공식 문서
· Permission modes — Claude Code 공식 문서
COMMENTS