헤드리스 모드

대화형 UI 없이 프로그래밍 방식으로 Claude Code 실행

개요

헤드리스 모드를 사용하면 대화형 UI 없이 명령줄 스크립트와 자동화 도구에서 프로그래밍 방식으로 Claude Code를 실행할 수 있습니다.

기본 사용법

Claude Code의 주요 명령줄 인터페이스는 claude 명령입니다. --print(또는 -p) 플래그를 사용하여 비대화형 모드로 실행하고 최종 결과를 출력합니다:

claude -p "내 변경사항을 스테이징하고 커밋 세트를 작성해줘" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

구성 옵션

SDK는 Claude Code에서 사용 가능한 모든 CLI 옵션을 활용합니다. SDK 사용을 위한 주요 옵션들은 다음과 같습니다:

플래그	설명	예시
--print, -p	비대화형 모드로 실행	claude -p "쿼리"
--output-format	출력 형식 지정 (text, json, stream-json)	claude -p --output-format json
--resume, -r	세션 ID로 대화 재개	claude --resume abc123
--continue, -c	가장 최근 대화 계속	claude --continue
--verbose	상세 로깅 활성화	claude --verbose
--append-system-prompt	시스템 프롬프트에 추가 (--print와 함께만 사용)	claude --append-system-prompt "사용자 지정 지침"
--allowedTools	허용된 도구의 공백으로 구분된 목록, 또는 쉼표로 구분된 허용 도구 목록 문자열	claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedTools	거부된 도구의 공백으로 구분된 목록, 또는 쉼표로 구분된 거부 도구 목록 문자열	claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-config	JSON 파일에서 MCP 서버 로드	claude --mcp-config servers.json
--permission-prompt-tool	권한 프롬프트 처리를 위한 MCP 도구 (--print와 함께만 사용)	claude --permission-prompt-tool mcp__auth__prompt

CLI 옵션과 기능의 전체 목록은 CLI 참조 문서를 참조하세요.

다중 턴 대화

다중 턴 대화의 경우, 대화를 재개하거나 가장 최근 세션에서 계속할 수 있습니다:

# 가장 최근 대화 계속
claude --continue "이제 더 나은 성능을 위해 리팩터링해줘"

# 세션 ID로 특정 대화 재개
claude --resume 550e8400-e29b-41d4-a716-446655440000 "테스트를 업데이트해줘"

# 비대화형 모드로 재개
claude --resume 550e8400-e29b-41d4-a716-446655440000 "모든 린팅 문제를 수정해줘" --no-interactive

출력 형식

텍스트 출력 (기본값)

claude -p "src/components/Header.tsx 파일을 설명해줘"
# 출력: 이것은 다음을 보여주는 React 컴포넌트입니다...

JSON 출력

메타데이터를 포함한 구조화된 데이터를 반환합니다:

claude -p "데이터 레이어는 어떻게 작동하나요?" --output-format json

응답 형식:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "여기에 응답 텍스트...",
  "session_id": "abc123"
}

스트리밍 JSON 출력

수신되는 각 메시지를 스트리밍합니다:

claude -p "애플리케이션을 빌드해줘" --output-format stream-json

각 대화는 초기 init 시스템 메시지로 시작하고, 사용자와 어시스턴트 메시지 목록이 이어지며, 통계가 포함된 최종 result 시스템 메시지로 끝납니다. 각 메시지는 별도의 JSON 객체로 방출됩니다.

입력 형식

텍스트 입력 (기본값)

# 직접 인수
claude -p "이 코드를 설명해줘"

# stdin에서
echo "이 코드를 설명해줘" | claude -p

스트리밍 JSON 입력

각 메시지가 사용자 턴을 나타내는 stdin을 통해 제공되는 메시지 스트림입니다. 이를 통해 claude 바이너리를 다시 시작하지 않고도 대화의 여러 턴을 수행할 수 있으며, 모델이 요청을 처리하는 동안 지침을 제공할 수 있습니다.

각 메시지는 출력 메시지 스키마와 동일한 형식을 따르는 JSON ‘사용자 메시지’ 객체입니다. 메시지는 입력의 각 줄이 완전한 JSON 객체인 jsonl 형식을 사용하여 포맷됩니다. 스트리밍 JSON 입력에는 -p와 --output-format stream-json이 필요합니다.

echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"이 코드를 설명해줘"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

에이전트 통합 예시

SRE 인시던트 대응 봇

#!/bin/bash

# 자동화된 인시던트 대응 에이전트
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "인시던트: $incident_description (심각도: $severity)" \
      --append-system-prompt "당신은 SRE 전문가입니다. 문제를 진단하고, 영향을 평가하며, 즉각적인 조치 항목을 제공하세요." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# 사용법
investigate_incident "결제 API가 500 오류를 반환함" "high"

자동화된 보안 검토

# 풀 리퀘스트를 위한 보안 감사 에이전트
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "당신은 보안 엔지니어입니다. 이 PR을 취약점, 안전하지 않은 패턴, 규정 준수 문제에 대해 검토하세요." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# 사용법 및 파일로 저장
audit_pr 123 > security-report.json

다중 턴 법률 어시스턴트

# 세션 지속성을 가진 법률 문서 검토
session_id=$(claude -p "법률 검토 세션 시작" --output-format json | jq -r '.session_id')

# 여러 단계로 계약서 검토
claude -p --resume "$session_id" "contract.pdf에서 책임 조항을 검토해줘"
claude -p --resume "$session_id" "GDPR 요구사항 준수를 확인해줘"
claude -p --resume "$session_id" "위험에 대한 경영진 요약을 생성해줘"

모범 사례

• 응답의 프로그래밍 방식 파싱을 위해 JSON 출력 형식 사용:

  # jq로 JSON 응답 파싱
  result=$(claude -p "코드 생성" --output-format json)
  code=$(echo "$result" | jq -r '.result')
  cost=$(echo "$result" | jq -r '.cost_usd')
  

• 오류를 우아하게 처리 - 종료 코드와 stderr 확인:

  if ! claude -p "$prompt" 2>error.log; then
      echo "오류가 발생했습니다:" >&2
      cat error.log >&2
      exit 1
  fi
  

• 다중 턴 대화에서 컨텍스트 유지를 위해 세션 관리 사용

• 장시간 실행되는 작업에 대한 타임아웃 고려:

  timeout 300 claude -p "$complex_prompt" || echo "5분 후 타임아웃됨"
  

• 여러 요청을 할 때 호출 간 지연을 추가하여 속도 제한 준수

관련 리소스

• CLI 사용법 및 제어 - 완전한 CLI 문서
• 일반적인 워크플로우 - 일반적인 사용 사례에 대한 단계별 가이드