Claude Code를 서브에이전트로 실행하면 기본 상태에서는 Bash 명령어도, 웹 요청도 막혀 있습니다. 이 상태 그대로 쓰면 자동화 작업의 절반은 시작도 못 합니다. Claude Code 서브에이전트 allowlist 설정을 통해 필요한 도구만 열어두는 것, 그게 핵심입니다.
서브에이전트란 무엇인가
Claude Code에서 말하는 서브에이전트(subagent)는 메인 에이전트가 특정 작업을 위임하는 하위 실행 단위입니다. 예를 들어 메인 에이전트가 코드 리뷰를 요청하면, 파일 읽기와 수정은 별도 서브에이전트에게 분리해서 맡기는 구조입니다.
이 구조의 장점은 역할 분리입니다. 서브에이전트마다 허용 범위를 다르게 설정할 수 있기 때문에, 전체 시스템 권한을 열지 않아도 필요한 작업만 처리할 수 있습니다.
문제는 기본값입니다. 서브에이전트는 기본적으로 도구 사용 권한이 없습니다. Bash 명령 실행도, 외부 URL 요청도 차단된 상태로 시작합니다. 그래서 Claude Code 서브에이전트 allowlist 설정이 반드시 필요합니다.
allowlist 설정 구조 이해하기
Claude Code의 권한 설정은 settings.json 또는 API 호출 시 전달하는 설정 객체 안에서 이루어집니다. allowlist는 서브에이전트가 사용할 수 있는 도구 목록을 명시적으로 선언하는 방식입니다.
기본 구조는 아래와 같습니다.
{
"subagent": {
"allowedTools": ["Bash", "WebFetch", "Read", "Write"]
}
}allowedTools 배열 안에 허용할 도구 이름을 문자열로 넣으면 됩니다. 선언하지 않은 도구는 자동으로 차단됩니다.
| 도구명 | 역할 | 기본 상태 |
|---|---|---|
| Bash | 터미널 명령 실행 | 차단 |
| WebFetch | 외부 URL HTTP 요청 | 차단 |
| Read | 파일 읽기 | 차단 |
| Write | 파일 쓰기 | 차단 |
| Edit | 파일 부분 수정 | 차단 |
Bash와 WebFetch를 allowlist에 등록하는 방법
가장 자주 쓰이는 두 도구는 Bash와 WebFetch입니다. Bash는 스크립트 실행, 패키지 설치, 파일 이동 등 터미널에서 하는 모든 작업을 처리합니다. WebFetch는 외부 API 호출이나 웹페이지 데이터 수집에 씁니다.
설정 파일에 두 도구를 추가하는 방법은 다음과 같습니다.
{
"subagent": {
"allowedTools": ["Bash", "WebFetch"]
}
}이 설정만으로 서브에이전트는 Bash 명령과 웹 요청을 실행할 수 있게 됩니다. 단, 설정 파일 위치가 프로젝트 루트의 .claude/settings.json인지, 전역 설정 파일인지에 따라 적용 범위가 달라집니다.
- 프로젝트 단위 설정:
{프로젝트 루트}/.claude/settings.json - 전역 설정:
~/.claude/settings.json
특정 프로젝트에서만 Bash를 허용하고 싶다면 프로젝트 루트에 설정 파일을 두는 것이 안전합니다. 전역으로 열어두면 모든 프로젝트의 서브에이전트에 동일하게 적용됩니다.
Bash allowlist 세부 제한 설정
Bash를 통째로 여는 것이 불안하다면, 허용할 명령어 패턴을 제한하는 방법도 있습니다. allowedTools 대신 bashAllowlist를 사용하면 특정 명령어만 허용할 수 있습니다.
{
"subagent": {
"allowedTools": ["Bash", "WebFetch"],
"bash": {
"allowlist": ["npm", "node", "python", "git"]
}
}
}이렇게 설정하면 npm install이나 git status는 실행되지만 rm -rf나 sudo 같은 명령은 차단됩니다. 자동화 파이프라인에서 서브에이전트가 시스템 전체를 건드리지 못하게 막는 실용적인 방법입니다.
WebFetch 도메인 제한 설정
WebFetch도 전체 인터넷을 열지 않고 특정 도메인만 허용하도록 제한할 수 있습니다.
{
"subagent": {
"allowedTools": ["WebFetch"],
"webFetch": {
"allowedDomains": ["api.github.com", "docs.anthropic.com"]
}
}
}allowedDomains에 등록된 도메인만 요청이 통과됩니다. 내부 API 서버나 특정 문서 사이트만 접근하게 하고 싶을 때 유용합니다.
allowlist 설정 시 자주 발생하는 문제
설정 후 도구가 여전히 차단된다면 아래 항목을 먼저 확인하는 것이 좋습니다.
- 설정 파일 경로가 올바른지 확인합니다.
.claude/settings.json이 프로젝트 루트에 있어야 합니다. - JSON 문법 오류를 점검합니다. 쉼표 하나만 빠져도 설정 전체가 무시됩니다.
- 도구 이름 대소문자를 확인합니다.
bash가 아니라Bash로 써야 인식됩니다. - Claude Code 버전을 확인합니다. allowlist 기능은 일부 버전부터 지원됩니다. 공식 문서(docs.anthropic.com)에서 현재 지원 범위를 확인하는 것이 정확합니다.
어떤 도구를 열고 닫을지 판단하는 기준
allowlist를 설정할 때 모든 도구를 다 열어두고 시작하는 방식은 권장하지 않습니다. 서브에이전트가 필요 이상의 권한을 가지면 예상치 못한 작업을 실행할 가능성이 생깁니다.
판단 기준은 간단합니다. 이 서브에이전트가 이 작업을 완료하는 데 이 도구가 반드시 필요한가. 필요하면 열고, 아니면 닫는 것이 원칙입니다.
| 작업 유형 | 필요한 도구 | 열지 않아도 되는 도구 |
|---|---|---|
| 코드 리뷰 | Read | Bash, Write, WebFetch |
| 패키지 설치 자동화 | Bash, Read | WebFetch, Edit |
| API 데이터 수집 | WebFetch, Write | Bash, Edit |
| 파일 자동 수정 | Read, Edit, Write | Bash, WebFetch |
작업별로 필요한 도구만 열어두는 습관을 들이면 서브에이전트가 예기치 않은 동작을 할 가능성을 줄일 수 있습니다.
정리
Claude Code 서브에이전트 allowlist 설정은 복잡하지 않습니다. .claude/settings.json에 allowedTools 배열을 추가하고, Bash와 WebFetch를 필요한 경우에만 등록하면 됩니다. 도메인 제한, 명령어 패턴 제한 같은 세부 설정은 시스템 안전성을 높이는 선택 사항입니다.
Claude Code가 버전업 되면서 권한 설정 방식이 바뀔 수 있으므로, 최신 내용은 Anthropic 공식 문서에서 확인하는 것이 가장 정확합니다.
자주 묻는 질문
Q. allowedTools에 아무것도 안 쓰면 어떻게 됩니까?
모든 도구가 차단된 상태로 동작합니다. 서브에이전트는 텍스트 응답만 가능하고 파일이나 명령 실행은 모두 막힙니다.
Q. 전역 설정과 프로젝트 설정이 동시에 있으면 어느 쪽이 우선입니까?
일반적으로 프로젝트 단위 설정이 전역 설정보다 우선 적용됩니다. 다만 Claude Code 버전에 따라 병합 방식이 다를 수 있으므로 공식 문서 확인이 필요합니다.
Q. WebFetch로 HTTPS가 아닌 HTTP 요청도 됩니까?
기본적으로 HTTP 요청도 허용되지만 보안상 HTTPS 도메인만 allowedDomains에 등록하는 것이 권장됩니다.
썸네일: Team Nocoloco on Unsplash