Claude Code 헤드리스 모드(headless mode) — 화면이나 대화형 세션 없이 명령 한 번으로 실행되고 바로 끝나는 방식입니다. claude -p 플래그를 붙이면 터미널에서 주고받는 대화 대신, 프롬프트 하나를 넣으면 응답만 출력하고 즉시 종료됩니다. 이 방식을 쓰면 스크립트, 서버, cron(정해진 시각에 자동으로 명령을 실행하는 예약 작업) 안에서 사람이 옆에 앉아 있지 않아도 Claude Code를 호출할 수 있습니다. 이 글을 따라 하면 20분 안에 기본 헤드리스 호출부터 출력 형식 지정, 권한 플래그 때문에 자주 생기는 실수까지 직접 실행해 볼 수 있습니다.
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
시작 전 준비물
헤드리스 모드를 시도하기 전에 아래 항목을 먼저 확인하세요.
- Claude Code CLI(터미널에서 실행하는 명령줄 도구) 설치 완료 — macOS·Linux·WSL은
curl -fsSL https://claude.ai/install.sh | bash, Windows는 PowerShell·WinGet 등 공식 설치 방법을 사용합니다. claude명령으로 최소 한 번 로그인한 상태이거나, 서버·CI 환경이라면 API 키(ANTHROPIC_API_KEY환경 변수)를 준비합니다.- 터미널(명령줄) 기본 사용법 — 명령을 입력하고 실행하는 방법, 파이프(
|) 기호의 의미를 알고 있으면 좋습니다. - 스크립트를 실행할 셸 환경(bash 등) — 서버나 cron에서 자동화하려는 경우에 필요합니다.
용어 빠른 풀이
- 헤드리스 모드(headless mode) — 화면이나 대화형 세션 없이 명령 한 번으로 실행되고 끝나는 방식입니다.
- 플래그(flag) — 명령어 뒤에 붙여 동작을 바꾸는 옵션입니다. 예:
-p,--output-format. - 표준 입력/출력(stdin/stdout) — 프로그램이 다른 프로그램으로부터 값을 받는 통로(stdin)와 내보내는 통로(stdout)입니다.
- 파이프(pipe,
|) — 한 명령어의 출력을 다른 명령어의 입력으로 바로 연결해 주는 셸 기호입니다. - 권한 프롬프트(permission prompt) — Claude Code가 파일 수정이나 명령 실행 전에 사용자에게 승인을 요청하는 대화형 확인 화면입니다.
단계별 실행
아래 플래그 이름과 옵션 값은 버전에 따라 달라질 수 있으니, 실제 스크립트에 반영하기 전에 터미널에서 claude -p --help를 실행해 현재 환경의 정확한 옵션을 한 번 확인하는 것을 권장합니다.
1단계 — 기본 헤드리스 호출
claude -p "이 폴더의 package.json에 있는 의존성 목록을 요약해줘"-p(또는 --print) 플래그를 붙이면 Claude Code가 대화형 세션을 열지 않고, 프롬프트에 대한 응답만 출력한 뒤 즉시 종료합니다.
이렇게 보이면 성공입니다: 터미널에 응답 텍스트가 출력되고 다시 명령을 입력할 수 있는 상태로 바로 돌아옵니다. 반대로 화면이 계속 입력을 기다리는 것처럼 멈춰 있다면 -p를 빠뜨리고 대화형 모드로 실행했을 가능성이 큽니다. 이때는 Ctrl+C로 종료한 뒤 -p를 붙여 다시 실행하세요.
2단계 — 파일이나 다른 명령의 결과를 입력으로 전달하기
cat error.log | claude -p "이 에러 로그에서 원인을 한 줄로 요약해줘"파이프(|)로 표준 입력을 전달하면 그 내용을 프롬프트와 함께 Claude Code에 넘길 수 있습니다. 로그 파일, git diff 결과 등 텍스트로 된 것이면 무엇이든 연결할 수 있습니다.
이렇게 보이면 성공입니다: 넘긴 파일의 내용을 반영한 응답(예: 실제 로그 안의 에러 문구를 인용한 요약)이 출력됩니다.
3단계 — 출력 형식 지정하기
스크립트가 결과를 그대로 사람에게 보여주는 게 아니라 파싱해서 다음 단계에 쓰려면, 형식이 흔들리는 일반 텍스트보다 구조화된 형식을 지정하는 편이 안전합니다.
| --output-format 값 | 특징 | 언제 사용하나 |
|---|---|---|
| text (기본값) | 사람이 읽기 편한 일반 텍스트로 출력 | 터미널에서 직접 결과를 확인할 때 |
| json | 응답 전체를 하나의 JSON 객체로 한 번에 출력 | 스크립트가 결과를 파싱해 다음 단계에 활용할 때 |
| stream-json | 처리 과정을 여러 JSON 이벤트로 나눠 순차 출력 | 진행 상황을 실시간으로 다른 프로그램에 전달할 때 |
claude -p "src 폴더의 TODO 주석을 모두 나열해줘" --output-format json이렇게 보이면 성공입니다: 터미널에 사람이 읽는 문장 대신 {로 시작하는 JSON 텍스트가 출력됩니다. 정확한 필드 구성은 실행해서 직접 확인한 뒤 스크립트에 반영하세요.
4단계 — 권한 플래그 이해하기
헤드리스 모드에는 승인을 물어볼 화면이 없습니다. 그래서 파일 수정처럼 원래 승인이 필요한 동작을 만나면 스크립트가 멈추거나 실패로 종료될 수 있습니다. 아래 플래그로 어떤 동작을 허용할지 미리 정해 두어야 예상대로 동작합니다.
| 플래그 | 역할 | 주의할 점 |
|---|---|---|
| --permission-mode | 승인 절차를 진행하는 모드를 지정 | 정확한 모드 이름과 기본값은 claude -p --help로 확인하세요. |
| --allowedTools | 지정한 도구만 사전 승인해 확인 없이 진행 | 스크립트에 실제로 필요한 도구만 최소한으로 지정하는 것이 안전합니다. |
| --disallowedTools | 특정 도구의 사용을 명시적으로 금지 | 민감한 동작(예: 삭제 관련 명령)을 막을 때 유용합니다. |
| --dangerously-skip-permissions | 모든 승인 절차를 건너뜀 | 이름 그대로 위험한 옵션입니다. 아래 주의 참고. |
주의: --dangerously-skip-permissions는 파일 수정이나 명령 실행 전 확인 절차를 전부 생략합니다. 신뢰할 수 없는 입력(예: 외부에서 받은 텍스트를 그대로 프롬프트에 넣는 경우)이 섞일 수 있는 자동화 환경에서 사용하면 예상치 못한 파일 변경·삭제로 이어질 수 있습니다. 반드시 컨테이너 등 격리된 환경에서, 입력을 스스로 통제할 수 있을 때만 사용하세요.
5단계 — 여러 단계로 이어지는 작업에서 세션 유지하기
claude -p "방금 만든 파일에 이어서 테스트 코드도 추가해줘" -c-c(--continue)나 --resume을 쓰면 이전 헤드리스 호출의 맥락을 이어받아 다음 프롬프트를 실행할 수 있습니다. 한 번의 호출로 끝내기 어려운, 여러 단계로 나뉜 작업을 스크립트 안에서 순차적으로 이어갈 때 유용합니다.
이렇게 보이면 성공입니다: 이전 호출에서 다룬 파일이나 맥락을 다시 설명하지 않아도 이어서 처리한 응답이 나옵니다.
6단계 — 서버·cron에서 실행하기
export ANTHROPIC_API_KEY="여기에_API_키"
claude -p "오늘 커밋된 변경 사항을 요약해서 slack용 텍스트로 만들어줘" --output-format json대화형으로 로그인할 수 없는 서버나 cron 환경에서는 ANTHROPIC_API_KEY 환경 변수로 인증합니다.
주의: API 키는 절대 코드나 저장소에 직접 커밋하지 말고, 환경 변수나 시크릿 관리 도구(예: 서버의 환경 변수 설정, CI의 시크릿 저장소)를 통해 주입하세요.
자주 막히는 지점 & 해결
헤드리스 자동화를 처음 시도할 때 자주 부딪히는 상황과 조치입니다.
- 터미널이 멈춘 것처럼 보임 —
-p를 빠뜨려서 대화형 모드로 실행되어 입력을 기다리는 중인 경우가 많습니다.Ctrl+C로 종료한 뒤-p를 붙여 다시 실행하세요. - 스크립트가 멈추거나 실패로 종료됨 — 승인이 필요한 동작을 만났는데 확인 화면을 띄울 수 없어서입니다. 필요한 도구를
--allowedTools로 사전 승인하거나--permission-mode를 조정하세요. - CI·cron에서 로그인 관련 오류가 남 —
ANTHROPIC_API_KEY가 설정되지 않은 경우입니다. 환경 변수가 실제로 그 셸 세션에 전달되고 있는지 확인하세요. - 스크립트에서 결과를 파싱하다 오류가 남 —
--output-format을 지정하지 않고 사람이 읽는 일반 텍스트를 그대로 파싱하려 한 경우입니다.json이나stream-json으로 바꾸세요.
응용/다음 단계
git diff의 결과를 파이프로 넘겨 커밋 메시지 초안을 만들거나, 여러 리포지토리를 순회하며 같은 프롬프트로 일괄 점검하는 스크립트를 만드는 식으로 응용할 수 있습니다. 이번 글은 로컬·서버 스크립트 관점의 범용 자동화를 다뤘습니다. GitHub Actions 같은 CI 플랫폼에 통합하는 방법은 별도로 다루고 있으니, 파이프라인 단계에 자동으로 끼워 넣고 싶다면 그 글을 참고하세요.
자주 묻는 질문
Q. claude -p는 claude 명령과 무엇이 다른가요?-p(--print) 플래그를 붙이면 대화형 세션을 열지 않고, 프롬프트에 대한 응답만 출력한 뒤 즉시 종료합니다. 스크립트나 서버처럼 사람이 옆에서 대화를 이어갈 수 없는 환경에 적합합니다.
Q. 헤드리스 모드에서도 파일을 수정할 수 있나요?
네, 가능합니다. 다만 대화형 확인 화면이 없으므로 --allowedTools 같은 권한 플래그로 어떤 동작을 허용할지 미리 정해 두어야 스크립트가 멈추지 않고 예상대로 동작합니다.
Q. --dangerously-skip-permissions는 언제 써도 되나요?
가능하면 피하는 것이 안전합니다. 꼭 필요하다면 컨테이너 등으로 격리된 환경에서, 입력값을 스스로 통제할 수 있을 때만 최소 범위로 사용하세요.
Q. 결과를 다른 프로그램에서 읽으려면 어떤 출력 형식을 써야 하나요?--output-format json 또는 stream-json을 권장합니다. 기본값인 일반 텍스트는 사람이 읽기엔 편하지만, Claude의 표현 방식이 조금만 바뀌어도 파싱 스크립트가 깨질 수 있습니다.