Menu
Claude Code CLI를 headless(`claude -p`) 모드로 프로그래매틱 실행하고, 구독(OAuth) 인증으로 중계 서버·샌드박스에서 사용하는 방법. stream-json 파싱, 인증 우선순위, 안전 가드 포함.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
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>
| 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를 다른 디렉터리에서 호출 | 세션 못 찾음 | 첫 호출과 같은 디렉터리에서 실행 |