8월 첫째 주에 바뀐 세 가지

2026년 8월 4일 v2.1.221에서 샌드박스 자격증명 파일에 마스킹 모드가 추가됐습니다. 8월 7일 v2.1.224에서는 값의 일부만 골라 가리는 옵션, JWT(로그인 정보가 담긴 토큰 형식)를 형식만 같은 가짜 토큰으로 바꾸는 옵션, AWS 요청에 붙는 서명을 다시 만들어 주는 옵션이 붙었습니다. 8월 8일 v2.1.225에서는 에이전트 실행 경로에도 신뢰하지 않은 디렉터리에 대한 확인 절차가 추가됐습니다. 세 변경이 가리키는 방향은 하나입니다. 에이전트에게 폴더를 열어주기 전에 무엇을 보여줄지 먼저 정하라는 것입니다.

차단과 마스킹은 목적이 다릅니다

차단은 값을 없앱니다. 안전하지만 그 키로 인증하던 도구가 함께 멈춥니다. 마스킹은 명령에게 자리표시자를 보여주고, 허용한 호스트로 요청이 나갈 때 프록시가 진짜 값으로 바꿔치기합니다. 명령이 화면에 찍거나 로그에 남기는 값은 자리표시자이지만 요청은 정상적으로 인증되는 구조입니다. 여기에 조건이 둘 붙습니다. 프록시가 요청 내용을 봐야 하므로 TLS 종료 설정이 필요하고, 이 설정 없이 마스킹을 걸면 값이 새지는 않되 자리표시자가 그대로 서버까지 가서 인증이 실패합니다.

두 번째 조건이 실무에서 더 자주 걸립니다. 마스킹은 프록시에게 진짜 키를 특정 호스트로 보내라고 허가하는 설정이라, 사용자 설정과 관리자 설정, 실행 시 지정한 설정 파일에서만 인정됩니다. 저장소 안에 커밋되는 프로젝트 설정 파일에 적으면 조용히 무시됩니다. 클라이언트 저장소마다 설정을 넣어두는 방식으로는 동작하지 않는다는 뜻입니다.

맥에서는 같은 설정이 다르게 동작합니다

공식 문서는 파일 마스킹을 플랫폼별로 나눠 설명합니다. 리눅스와 WSL2에서는 샌드박스 명령이 자리표시자가 들어간 사본을 읽고 실제 값은 나갈 때 채워집니다. 맥에서는 해당 파일을 아예 읽지 못합니다. 사본을 만들지도, 나갈 때 값을 넣지도 않으므로 그 파일로 인증하던 도구는 샌드박스 안에서 동작하지 않습니다. 결과만 놓고 보면 차단과 같습니다. 다만 맥에서 마스킹 항목으로 걸린 읽기 차단은 파일시스템 격리를 꺼도 유지된다는 점이 일반 차단 항목과 다릅니다.

확인 방법은 문서에 그대로 나와 있습니다. 샌드박스 명령으로 해당 파일을 출력해 보면 리눅스와 WSL2에서는 자리표시자가 찍히고 맥에서는 읽기가 실패합니다. 설정을 넣었다면 이 한 번의 출력으로 실제 동작을 확인하는 편이 안전합니다. 참고로 환경변수 마스킹에는 이 플랫폼 제약이 없어, 맥에서도 정상 동작합니다. 맥이 주 작업 환경이라면 파일은 차단 기준으로 설계하고 계속 인증이 필요한 값은 환경변수 쪽으로 옮기는 편이 맞습니다.

1인 운영에서는 이 구분이 특히 중요합니다. 쇼핑몰 API 토큰과 SFTP 계정, 문서 도구 인증 정보가 대부분 한 대의 작업 기기에 모여 있고, 그 기기가 예약 실행까지 맡고 있기 때문입니다. 사람이 화면 앞에 있을 때 실패하면 바로 알아채지만, 새벽에 도는 자동 실행이 인증 실패로 멈추면 다음 날 아침에야 확인하게 됩니다.

마스킹이 조용히 차단으로 되돌아가는 조건

문서는 안전하게 가릴 수 없는 대상에 대해 마스킹을 차단으로 되돌린다고 밝히고 있습니다. 디렉터리 경로, 글로브 패턴, 8MiB를 넘는 파일, UTF-8 텍스트가 아닌 파일이 여기 해당합니다. 디렉터리는 처음부터 차단 항목으로 적는 편이 의도가 분명하게 남습니다.

반대 방향으로 더 조심할 값도 있습니다. 파일에서 비밀값 부분만 골라내는 정규식이 아무것도 찾지 못했을 때의 기본 동작은 경고 후 건너뛰기입니다. 이 경우 샌드박스 명령이 실제 파일을 그대로 읽습니다. 값이 없을 수도 있는 파일에는 적절한 기본값이지만, 값은 있는데 패턴이 놓칠 가능성이 있다면 차단으로 두시는 편이 맞습니다.

한 가지 더 확인할 것은 기본 읽기 정책입니다. 문서에 따르면 샌드박스의 기본값은 일부 차단 디렉터리를 뺀 컴퓨터 전체 읽기 허용이고, 이 기본값이 자격증명 파일 읽기까지 허용한다고 따로 적혀 있습니다. 기본 제공되는 자격증명 차단 목록은 없습니다. 내가 적어 넣은 대상만 보호됩니다. 샌드박스를 켰다는 사실만으로 키가 보호되지는 않는다는 뜻입니다.

Anthropic은 엔지니어링 문서에서 내부 테스트 기준 샌드박스가 권한 확인 요청을 84% 줄였다고 밝히고 있습니다. 물어보는 횟수가 줄어드는 만큼 경계선을 미리 정확히 긋는 일의 비중이 커집니다. 순서는 단순합니다. 열어줄 폴더에서 읽히는 자격증명을 먼저 나열하고, 맥이면 파일은 차단 기준으로 잡은 뒤 인증이 계속 필요한 값만 환경변수로 옮기고, 설정을 넣은 다음 한 번 출력해 실제 동작을 확인합니다. 자동 실행을 붙이는 것은 그 확인이 끝난 뒤입니다.

누끼토끼가 운영하는 강의와 칼럼에서는 AI 에이전트를 실제 클라이언트 작업에 붙일 때의 권한 경계와 자동 실행 점검 절차를 실무 기준으로 다루고 있습니다. 혼자 여러 쇼핑몰을 운영하며 키를 한 기기에 모아두고 계시다면, 기능을 늘리기 전에 경계선부터 확인해 보시길 권합니다.