Claude Code restricted 모드 사용법, Bash와 외부 파일 접근 직접 확인

Claude Code 2.1.248에 --restricted 옵션이 추가됐습니다. 이름만 보면 권한 확인을 조금 강화하는 기능처럼 보이지만, 실제로는 실행 가능한 도구를 시작 단계에서 줄이고 파일 접근 범위도 작업 폴더 안으로 제한합니다.

공식 설명만 옮기지 않고 Ubuntu 24.04, Node.js 22.22.2 환경에서 2.1.248을 따로 실행해 일반 모드와 비교했습니다. 테스트에 사용한 폴더에는 내용이 safe fixture인 파일 하나만 넣었습니다.

restricted 모드가 필요한 경우

이 옵션은 평가용 하네스나 공유 서버처럼 Claude Code가 명령을 실행하거나 사용자 설정을 읽으면 안 되는 환경을 위해 만들어졌습니다. 평소 개발 작업에서 모든 권한을 없애는 기능이라기보다, 읽기와 편집은 허용하면서 명령 실행과 작업 폴더 밖 접근을 줄이는 실행 경계에 가깝습니다.

최소 버전은 2.1.248입니다. 설치된 버전은 다음 명령으로 확인할 수 있습니다.

claude --version

이번 테스트에서는 기존 설치를 건드리지 않기 위해 아래처럼 특정 버전만 임시 실행했습니다.

npm exec --yes --package=@anthropic-ai/claude-code@2.1.248 -- claude --version
# 2.1.248 (Claude Code)

일반 모드와 도구 목록 비교

같은 요청을 일반 모드와 restricted 모드에 각각 넣고 초기화 이벤트의 도구 목록을 비교했습니다. 일반 모드에는 Bash와 WebFetch가 있었지만 restricted 모드 목록에서는 빠졌습니다. 두 모드 모두 작업 폴더의 파일은 Read로 읽을 수 있었습니다.

확인 항목	일반 모드	restricted 모드
Bash	목록에 있음	목록에서 빠짐
WebFetch	목록에 있음	목록에서 빠짐
작업 폴더의 파일 읽기	성공	성공

restricted 모드에서 사용한 명령은 다음과 같습니다.

claude --restricted -p \
  "Read fixture.txt and reply only with its exact content."

# tool_uses=Read
# result=safe fixture
# is_error=False

작업 폴더 밖 파일 접근 결과

작업 폴더는 /tmp/foliyo-claude-restricted-test로 지정한 뒤 /etc/hostname을 읽도록 요청했습니다. Claude Code는 Read를 호출했지만 작업 폴더 밖이라는 이유로 내용을 반환하지 않았습니다.

I can't read that file. This session is running in restricted mode,
which confines file access to the working directory.

공식 문서의 설명과 실제 동작이 일치했습니다. 공유 머신에서 다른 프로젝트나 시스템 파일을 실수로 읽는 상황을 줄이는 데 사용할 수 있습니다.

bypassPermissions와 함께 실행한 결과

--restricted와 --permission-mode bypassPermissions를 동시에 지정하면 세션이 시작되지 않았습니다.

claude --restricted --permission-mode bypassPermissions -p "Return OK"

# exit=1
# Error: bypassPermissions not supported in restricted mode

restricted 모드 안에서 다시 모든 권한을 허용하는 조합을 막아 둔 것입니다. 환경변수 방식도 동일하게 작동했습니다.

CLAUDE_CODE_RESTRICTED=1 claude -p \
  "Read fixture.txt and reply only with its exact content."

사용할 때 놓치기 쉬운 부분

--restricted는 Claude Code 2.1.248 이상에서만 사용할 수 있습니다.
명령 실행 도구와 WebFetch는 기본 목록에서 빠지지만, --tools에 개별 도구를 지정하면 사용할 수 있습니다.
사용자, 프로젝트, 로컬 설정 파일은 읽지 않고 관리형 설정과 --settings로 전달한 설정만 사용합니다.
일반적인 로컬 개발에서는 Manual, Plan, Auto 같은 권한 모드가 더 편할 수 있습니다. restricted 모드는 공유 환경이나 자동 평가처럼 실행 범위를 고정해야 할 때 맞습니다.

확인에 사용한 공식 자료

테스트 날짜: 2026년 8월 28일. 실행 환경: Ubuntu 24.04, Node.js 22.22.2, Claude Code 2.1.248. 이후 버전에서는 도구 구성이나 동작이 달라질 수 있습니다.