메뉴
Claude Code CLI를 headless(`claude -p`) 모드로 프로그래매틱 실행하고, 구독(OAuth) 인증으로 중계 서버·샌드박스에서 사용하는 방법. stream-json 파싱, 인증 우선순위, 안전 가드 포함.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
Spring Security 5.5.x + jjwt 0.10.7 레거시 JWT 인증 - WebSecurityConfigurerAdapter, OncePerRequestFilter, javax.servlet 환경
Spring Boot 3.x + Spring Security 6.x + jjwt 0.12.x 기반 모던 JWT 인증 패턴. SecurityFilterChain Bean, 람다 DSL, jakarta.servlet, Virtual Threads 적용
Unity 6 LTS 2D 모바일 게임용 uGUI 시스템 전문 스킬. Canvas/RectTransform/TextMeshPro, 모바일 UI 패턴(팝업·무한 스크롤·광고·IAP), 성능 최적화, UI Toolkit과의 선택 기준 포함.
아크라시아(akrasia, 자제력 없음) 학술 논쟁의 핵심 구도와 주요 연구자·문헌을 빠르게 파악할 수 있는 도메인 지식 스킬. 도덕윤리교육 전공 대학원생(석/박사)이 학위논문·KCI 투고·세미나 준비 시 고대–현대–한국 학계–도덕심리학 흐름을 한 번에 짚도록 구성. <example>사용자: "아리스토텔레스의 propeteia와 astheneia 구분을 인용하려는데 출처를 알려줘"</example> <example>사용자: "데이비슨이 의지박약을 어떻게 가능하다고 봤는지 핵심 논증을 정리해줘"</example> <example>사용자: "한국 도덕교육 학계에서 아크라시아 다룬 논문 있어?"</example>
아리스토텔레스 『니코마코스 윤리학』에서 akrasia(자제력없음)와 akolasia(무절제)의 5축 차이를 정밀하게 정리한 학위논문 자료 스킬. NE VII.4 1147b20-1148b14, VII.8 1150b29-1151a28, III.10-12 1117b23-1119b18 절별 분해와 표준 학자 해석(Bostock, Broadie-Rowe, Pakaluk, Hursthouse, Charles 등)을 포함. 도덕교육 적용을 위한 두 상태 차이의 함의 및 한국어 번역어 처리 권장안 제공. <example>사용자: "akrates와 akolastos를 prohairesis 측면에서 어떻게 구분해야 하나요?"</example> <example>사용자: "NE VII.4의 ἁπλῶς akrasia가 akolasia와 어떻게 갈라지는지 절별 분해해주세요"</example> <example>사용자: "Hursthouse의 연속체 모델을 도덕교육 적용 절에서 어떻게 활용할 수 있나요?"</example>
한국 위기 대응 자원(자살·자해·정신건강·여성·청소년·노인·다문화) 핫라인과 앱·챗봇 안전 가드 응답 패턴 종합. 꿈 해몽·정신건강 앱 등 자가 진단/감정 콘텐츠 도메인에서 위험 신호 포착 시 안전한 자원 안내 문구를 작성할 때 참조. <example>사용자: "꿈 해몽 앱에 위기 안내 문구를 어떻게 넣을까?"</example> <example>사용자: "한국에서 자살예방 핫라인 번호가 어떻게 바뀌었지?"</example> <example>사용자: "정신건강 챗봇 안전 가드 응답 템플릿을 짜줘"</example>
SOC 직업 분류 기준
| name | claude-code-headless |
| description | Claude Code CLI를 headless(`claude -p`) 모드로 프로그래매틱 실행하고, 구독(OAuth) 인증으로 중계 서버·샌드박스에서 사용하는 방법. stream-json 파싱, 인증 우선순위, 안전 가드 포함. |
소스:
- https://code.claude.com/docs/en/headless (Run Claude Code programmatically)
- https://code.claude.com/docs/en/authentication (Authentication)
- https://code.claude.com/docs/en/cli-reference (CLI reference)
- https://code.claude.com/docs/en/agent-sdk/overview (Agent SDK overview)
- https://support.claude.com/en/articles/15036540 (Use the Agent SDK with your Claude plan) 검증일: 2026-07-03
Vercel Sandbox 등 비대화형 환경에서 Claude Code CLI를 구독 인증으로 헤드리스 실행해 프롬프트를 중계(예: SSE)할 때 필요한 핵심 지식을 정리한다.
claude -p) 핵심 플래그-p (--print)를 붙이면 대화형 UI 없이 프롬프트를 실행하고 결과를 stdout으로 출력한다.
모든 CLI 옵션은 -p와 함께 동작한다.
claude -p "이 저장소의 auth 모듈이 하는 일을 설명해줘"
| 플래그 | 값 / 설명 |
|---|---|
-p, --print | 비대화형 실행. stdin도 읽으므로 파이프 입력 가능 |
--output-format | text(기본) / json / stream-json |
--model | 별칭(sonnet, opus, haiku, fable) 또는 전체 모델명 |
--resume, -r | 세션 ID 또는 이름으로 특정 대화 이어가기 |
--continue | 가장 최근 대화 이어가기 |
--allowedTools | 프롬프트 없이 자동 승인할 도구 (permission rule 문법) |
--disallowedTools, --disallowed-tools | 거부 규칙. bare 이름은 모델 컨텍스트에서 도구 제거 ("*"=전체 제거) |
--max-turns | agentic turn 수 제한 (print 모드 전용). 초과 시 에러로 종료 |
--append-system-prompt | 기본 시스템 프롬프트에 지시 추가 (기본 동작 유지) |
--system-prompt | 시스템 프롬프트를 완전히 교체 |
--tools | 내장 도구 제한. ""=전체 비활성, "Bash,Edit,Read" 등 |
# 파이프 입력 → 결과를 파일로
cat build-error.txt | claude -p '이 빌드 에러의 근본 원인을 간결히 설명' > out.txt
# JSON 출력: result / session_id / total_cost_usd 등 메타 포함
claude -p "이 프로젝트 요약" --output-format json | jq -r '.result'
주의: piped stdin은 v2.1.128부터 10MB 상한. 초과 시 non-zero 종료. 큰 입력은 파일로 저장 후 경로를 프롬프트에 참조시킨다.
--output-format stream-json은 줄 단위(newline-delimited) JSON을 내보낸다.
각 줄이 하나의 이벤트 객체다. 토큰 단위 실시간 스트리밍은 아래 두 플래그가 필수다.
claude -p "재귀를 설명해줘" \
--output-format stream-json --verbose --include-partial-messages
--verbose: turn-by-turn 전체 출력 (stream-json에 필수)--include-partial-messages: 부분 스트리밍 이벤트 포함 (--print + stream-json 필요)| type / subtype | 의미 |
|---|---|
system / init | 첫 이벤트. 모델·도구·MCP·plugin 등 세션 메타 (session_id 포함) |
stream_event | 부분 델타. event.delta.type == "text_delta"면 event.delta.text가 토큰 |
system / api_retry | 재시도 이벤트. attempt, max_retries, retry_delay_ms, error_status, error |
result | 최종 결과 (--output-format json에서 result 필드) |
claude -p "시를 써줘" --output-format stream-json --verbose --include-partial-messages | \
jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
중계 서버에서는 각 줄을 JSON.parse → type/subtype으로 분기 →
stream_event의 text_delta만 SSE data: 청크로 흘려보내는 패턴을 쓴다.
system/init에서 session_id를 캡처해 두면 이후 --resume으로 대화를 이어갈 수 있다.
# 세션 ID 캡처 후 이어가기
session_id=$(claude -p "리뷰 시작" --output-format json | jq -r '.session_id')
claude -p "그 리뷰 계속" --resume "$session_id"
주의:
--resume의 세션 ID 조회는 현재 프로젝트 디렉터리(및 git worktree) 범위로 한정된다. 첫 호출과 이어가기 호출을 같은 디렉터리에서 실행해야 한다.
claude setup-token브라우저 로그인이 불가능한 CI·스크립트·샌드박스 환경에서는 장기 OAuth 토큰을 발급한다.
claude setup-token
# OAuth 승인 절차를 거쳐 토큰을 터미널에 출력 (어디에도 저장하지 않음)
export CLAUDE_CODE_OAUTH_TOKEN=your-token
핵심 제약:
여러 자격증명이 동시에 존재하면 Claude Code는 아래 순서로 하나를 고른다.
CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX / CLAUDE_CODE_USE_FOUNDRYANTHROPIC_AUTH_TOKEN — Authorization: Bearer 헤더 (LLM 게이트웨이/프록시용)ANTHROPIC_API_KEY — X-Api-Key 헤더 (직접 API 접근)apiKeyHelper — 스크립트가 반환하는 동적 키 (short-lived 토큰 등)CLAUDE_CODE_OAUTH_TOKEN — setup-token으로 만든 장기 OAuth 토큰/login) — Pro/Max/Team/Enterprise 기본값함정:
ANTHROPIC_API_KEY가 설정돼 있으면 구독보다 우선한다. 비대화형(-p) 모드에서는 키가 존재하면 항상 사용된다. 구독으로 되돌리려면unset ANTHROPIC_API_KEY후/status로 활성 인증 방식 확인. 샌드박스 이미지·CI 시크릿에 API 키가 섞여 들어가면 구독 인증이 조용히 덮어써지므로, 구독 인증 중계 서버에서는ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN을 명시적으로 비운다.
--bare) 제약--bare는 hook·skill·plugin·MCP·auto memory·CLAUDE.md 자동 탐색을 건너뛰어 시작을 빠르게 한다.
CI·스크립트에서 머신마다 동일한 결과를 얻는 데 유용하다. 하지만:
주의: bare 모드는
CLAUDE_CODE_OAUTH_TOKEN을 읽지 않는다. OAuth·keychain 읽기를 모두 건너뛰므로,--bare스크립트는ANTHROPIC_API_KEY또는--settings에 담은apiKeyHelper로 인증해야 한다.
즉 구독 토큰으로 중계하려면 --bare를 쓰면 안 된다.
claude -p(bare 미적용)로 실행해야 CLAUDE_CODE_OAUTH_TOKEN이 적용된다.
(bare 모드에서는 Bash·file read·file edit 도구만 기본 제공되고, 컨텍스트는 플래그로만 주입된다.)
| 상황 | 선택 |
|---|---|
| 단순 프롬프트 중계 / 일회성 태스크 / 인터랙티브 개발 | CLI (claude -p) |
| 도구 실행 제어·훅 콜백·권한 콜백·구조화 메시지 객체 필요 | Agent SDK |
| CI/CD 파이프라인, 커스텀 앱, 프로덕션 자동화 | Agent SDK |
npm install @anthropic-ai/claude-agent-sdk (query() 함수, 네이티브 바이너리 번들)pip install claude-agent-sdk (Python 3.10+)단순히 프롬프트를 받아 stream-json을 SSE로 흘려보내는 채팅 중계 서버라면
CLI 직접 실행(claude -p --output-format stream-json)이 가장 단순하다.
훅으로 도구 사용을 감사(audit)하거나 권한을 코드로 판정해야 하면 SDK를 쓴다.
claude -p / Agent SDK 사용 허용.claude -p 사용을 구독 풀에서 분리해
별도 월 크레딧으로 청구"하는 변경은 **시행 직전 일시 중지(paused)**되었다.
현재는 claude -p·Agent SDK·GitHub Actions 사용이 기존 구독 사용 한도에서 차감되는 방식 유지.
Anthropic은 향후 변경 시 사전 고지하겠다고 밝혔다.즉 개인 중계 서버(본인 사용)는 구독 토큰으로 문제없으나, 외부 사용자에게 노출하는 서비스로 확장하면 API 키 기반으로 전환해야 한다.
채팅·텍스트 응답만 필요한 중계 용도라면 파일 수정·명령 실행 도구를 반드시 차단한다.
# 모든 도구 비활성 — 순수 텍스트 응답만
claude -p "$USER_PROMPT" --tools "" \
--output-format stream-json --verbose --include-partial-messages \
--model haiku --max-turns 1
체크리스트:
--tools ""(전체 비활성) 또는 --disallowedTools "*"로 Bash/Edit/Write 등 제거--model haiku로 구독 사용량 절감--max-turns 제한: 무한 agentic loop 방지 (채팅이면 1로 고정)CLAUDE_CODE_OAUTH_TOKEN은 로그·응답·에러 메시지에 절대 출력하지 않는다ANTHROPIC_API_KEY가 비어 있는지 확인 (우선순위 함정)--bare를 쓰지 않는다 (5번 참조)| 실수 | 결과 | 해결 |
|---|---|---|
--bare로 구독 토큰 인증 시도 | OAuth 미로드 → 인증 실패 | --bare 제거, claude -p로 실행 |
샌드박스에 ANTHROPIC_API_KEY 잔존 | 구독 대신 API 키로 청구됨 | unset ANTHROPIC_API_KEY, /status 확인 |
stream-json에 --verbose 누락 | 스트리밍 이벤트 안 나옴 | --verbose --include-partial-messages 추가 |
| 채팅 중계에 도구 미차단 | 임의 파일·명령 실행 위험 | --tools "" 또는 --disallowedTools "*" |
--resume를 다른 디렉터리에서 호출 | 세션 못 찾음 | 첫 호출과 같은 디렉터리에서 실행 |