클로드 코드 화면 없이 돌리기 — claude -p와 예약 실행 따라 하기

클로드 코드 화면 없이 돌리기란 — claude -p 한 줄

평소에는 터미널에서 claude를 치고 대화 창을 연 뒤 부탁을 주고받는다. 여기에 -p(또는 --print)를 붙이면 클로드 코드는 대화 창을 열지 않는다. 부탁 하나를 처리하고, 답을 터미널에 찍고, 스스로 끝난다. 공식 문서는 이 방식을 스크립트나 CI(코드를 올릴 때마다 시험을 자동으로 돌리는 장치)에서 쓰라고 안내한다.

끝나는 모양이 분명하다는 점이 쓸모다. 성공하면 종료 코드(프로그램이 끝나며 남기는 숫자) 0으로 끝나고, 실패하면 0이 아닌 코드로 끝난다. 그래서 다른 프로그램이 그 숫자를 보고 다음 일을 할지 정할 수 있다. 로그인이 빠진 것처럼 실행 도중에 생긴 실패는 결과 자리에 글로 찍힌다. 옵션 이름을 잘못 적으면 실행이 시작되기 전에 오류가 나온다.

첫 실행 — 연습 폴더에서 claude -p 한 줄 돌려 보기

처음에는 지워도 되는 연습 폴더 하나에서 해 본다. 중요한 자료가 든 폴더에서 바로 시작하지 않는 편이 마음이 편하다.

1. PowerShell을 열고 연습 폴더를 만든 뒤 그 안으로 들어간다.

mkdir $HOME\Documents\claude-practice
cd $HOME\Documents\claude-practice

잘 됐으면 프롬프트 앞 경로가 Documents\claude-practice로 끝난다.

1. 대화 창 없이 질문 하나를 보낸다.

claude -p "이 폴더에 어떤 파일이 있는지 세 줄 안으로 알려 줘"

잘 됐으면 대화 창이 열리지 않고 답 몇 줄이 찍힌 뒤 PowerShell 프롬프트가 다시 나온다.

1. 방금 실행이 성공했는지 종료 코드로 확인한다.

$LASTEXITCODE

잘 됐으면 0이 나온다. 0이 아니면 바로 위에 찍힌 글에 실패 까닭이 적혀 있다. 이 글을 정리한 PC에서는 버전과 claude --help 목록까지만 확인했고, 모델을 부르는 2단계는 공식 문서 설명을 옮겼다.

대화 창과 claude -p는 무엇이 다른가

• 묻는 창: 대화 창에서는 권한을 물으면 사용자가 고른다. -p 실행에서는 답할 사람이 없어서 미리 허락하지 않은 일은 거절된다.
• 대화 안 명령: 내가 만든 스킬과 사용자 명령은 프롬프트에 /이름을 넣으면 쓴다. /login처럼 대화 창에서만 도는 명령은 못 쓴다.
• 결과 형식: 기본은 글이다. --output-format json을 붙이면 결과와 세션 ID가 든 JSON(프로그램이 읽기 좋은 데이터 형식)으로 받는다.
• 이어 하기: --continue를 붙이면 가장 최근 대화를 이어 간다.

표에서 가장 먼저 걸리는 줄은 묻는 창이다. 사람 없이 돌릴 명령은 아래 «권한» 절에서 허락할 일을 미리 정해 두고 돌린다. 클로드 코드 설치부터 낯설다면 클로드 코드 설치·요금제·첫 사용 (2026) — Windows에서 시작하기를 먼저 보면 된다.

클로드 코드 예약 실행 — 네 가지 길 가운데 고르기

정해진 시각에 저절로 돌게 하는 길은 클로드 쪽에 셋, Windows 쪽에 하나가 있다. 공식 문서는 클로드 코드의 예약을 클라우드 예약, 데스크톱 앱 예약, /loop 세 가지로 나눈다.

• 클라우드 예약: Anthropic이 관리하는 클라우드에서 돈다. 내 컴퓨터가 꺼져 있어도 돈다. 그 대신 내 PC 파일은 못 보고, 저장소를 새로 받아 와서 일한다. 가장 짧은 간격은 1시간이다. Pro · Max · Ultra · Team · Enterprise 요금제에서 쓰며, 아직 연구 미리보기(research preview) 단계라 동작과 한도가 바뀔 수 있다.
• 데스크톱 앱 예약: Claude 데스크톱 앱이 정해진 시각에 내 PC에서 새 세션을 열어 돌린다. 내 PC 파일과 도구를 바로 쓴다. 앱이 켜져 있고 컴퓨터가 깨어 있을 때만 돈다.
• /loop: 지금 열린 대화 안에서 같은 부탁을 되풀이한다. 대화가 열려 있어야 하고, 되풀이 작업은 만든 지 7일이 지나면 저절로 끝난다.
• Windows 작업 스케줄러 + claude -p: Windows에 들어 있는 예약 도구가 정해진 시각에 명령을 돌린다. 클로드 앱을 켜 둘 필요가 없고 내 PC 파일을 쓴다. 컴퓨터는 켜져 있어야 한다.

내 일에 맞는 예약 고르기

고르는 기준은 두 가지면 된다. 내 PC 파일을 써야 하는지, 그리고 무엇을 켜 둘 수 있는지다.

1. 내 PC 파일이 필요 없고 컴퓨터를 꺼 두고 싶다 → 클라우드 예약.
2. 내 PC 파일이 필요하고 Claude 데스크톱 앱을 늘 켜 둔다 → 데스크톱 앱 예약. 화면에서 만들고, 실행 기록도 앱에서 본다.
3. 내 PC 파일이 필요하고 앱 없이 명령으로 돌리고 싶다 → Windows 작업 스케줄러 + claude -p. 이 글 뒤쪽 절에서 따라 한다.
4. 지금 대화 중에 잠깐 되풀이해서 확인만 하면 된다 → /loop.

데스크톱 앱 예약에는 알아 둘 동작이 있다. 컴퓨터가 잠든 사이 예약 시각이 지나면 그 회차는 건너뛴다. 앱이 다시 켜지거나 컴퓨터가 깨어나면 지난 7일 안에 놓친 회차 가운데 가장 최근 것 하나만 돌린다. 그래서 오전에 돌 일이 밤에 돌 수도 있다. 공식 문서는 시각이 중요하면 «늦었으면 건너뛰라» 같은 조건을 프롬프트에 적으라고 권한다. 잠들지 않게 하려면 앱 설정의 Keep computer awake를 켠다. 노트북 덮개를 닫으면 그래도 잠든다.

인용 — Claude Code Docs «Run Claude Code programmatically»

«Claude Code exits with code 0 on success and a non-zero code when the run fails, so your scripts can branch on the exit status.» — 클로드 코드는 성공하면 종료 코드 0, 실패하면 0이 아닌 코드로 끝나므로 스크립트가 그 값을 보고 다음 일을 가를 수 있다.

예약 실행이 잘 돌았는지는 결국 이 숫자와 남은 기록으로 확인한다.

사람 없이 돌 때 권한 정하기 — 묻는 창 없이 끝까지

대화 창에서는 클로드가 파일을 고치거나 명령을 돌리기 전에 묻는다. -p 실행에는 답할 사람이 없다. Claude Code v2.1.302부터는 권한 모드를 따로 정하지 않은 -p 실행이 Manual 모드(허락이 필요한 일마다 묻는 기본 모드)로 시작한다. 이때 허락이 필요한 호출은 미리 허락해 둔 것이 없으면 거절된다. 작업 폴더 안 파일 읽기처럼 허락이 필요 없는 일은 그대로 돈다.

그래서 사람 없이 돌릴 명령에는 무엇을 허락할지 미리 적어 둔다. 공식 문서가 보여 주는 방법은 아래와 같다.

• --allowedTools: 묻지 않고 쓸 도구를 적는다. Read,Edit를 적으면 파일 읽기와 고치기를 묻지 않는다. Bash(git diff *)처럼 명령 앞부분만 허락할 수도 있다.
• --permission-mode acceptEdits: 파일 쓰기를 묻지 않고, mkdir · mv · cp 같은 흔한 파일 명령도 허락한다. 그 밖의 셸 명령과 인터넷 요청은 여전히 따로 허락해야 한다.
• --permission-mode dontAsk: 물어야 할 호출을 모두 거절한다. 읽기만 하고 끝나는 일에 맞다.
• --permission-mode auto: 사람 대신 분류기 모델(위험한 동작인지 가려내는 별도 모델)이 대부분의 동작을 검토한다.

여기에 --permission-prompts none을 더하면 아무도 허락해 줄 수 없다는 사실이 클로드에게 전해지고, 거절된 일을 다시 시도하지 않는다. 이 옵션은 v2.1.259 이상에서 쓴다. 이 글을 정리한 PC의 claude --help 목록에도 --permission-prompts가 있었다.

지시는 파일로 넘기고 결과는 파일로 받기

명령 줄에 긴 부탁을 다 적으면 따옴표와 줄바꿈 때문에 틀리기 쉽다. 그래서 이 글에서는 부탁을 task.md 파일에 적고, 명령 줄에는 «task.md를 읽고 따르라»는 짧은 문장만 둔다. 작업 폴더 안 파일 읽기는 허락이 필요 없어서 클로드가 이 파일을 바로 읽는다. 넘길 내용이 아주 길 때도 파일이 맞다. 파이프(앞 명령의 출력을 다음 명령의 입력으로 잇는 것)로 넣는 입력은 10MB까지이고, 넘으면 오류로 끝난다. 공식 문서도 큰 입력은 파일로 두고 프롬프트에 파일 경로를 적으라고 한다.

1. 연습 폴더에 task.md 파일을 만들고 아래 내용을 붙여 넣는다. 메모장에서 저장할 때 인코딩은 UTF-8로 둔다.

# 할 일
1. 이 폴더 안 reports 폴더에 있는 .csv 파일을 모두 읽는다.
2. 파일마다 행 수와 첫 줄의 열 이름을 적는다.
3. 결과를 이 폴더의 summary.md 파일에 표로 쓴다. 같은 이름 파일이 있으면 덮어쓴다.
4. 다른 파일은 고치거나 옮기거나 지우지 않는다.

잘 됐으면 연습 폴더에 task.md가 보인다. 시험용으로 reports 폴더를 만들고 작은 CSV 파일 하나를 넣어 둔다.

1. 손으로 한 번 돌려 본다.

claude -p "Read task.md in this folder and follow it." --permission-mode acceptEdits --max-turns 10

--max-turns는 클로드가 도구를 쓰며 주고받는 차례의 상한이다. -p 실행에서만 쓰고, 적지 않으면 상한이 없다. 잘 됐으면 끝에 짧은 보고가 찍히고 연습 폴더에 summary.md가 생긴다.

처음에는 acceptEdits 하나로 시작하고, 셸 명령이 꼭 필요해질 때 --allowedTools에 그 명령만 더하는 편이 원인을 찾기 쉽다. 남이 만든 폴더에서 돌릴 때는 한 가지를 더 조심한다. --bare 없이 돌린 -p 실행은 처음 보는 폴더에서도 그 폴더의 .claude/settings.json에 든 훅과 .mcp.json에 든 서버를 확인 창 없이 쓴다. 훅이 무엇인지는 클로드 코드 훅 — 실수를 자동으로 막는 장치 만들기에, 모드마다 무엇이 달라지는지는 클로드 코드 권한 모드 — 묻게 할 일과 맡길 일 나누기에 정리했다.

Windows 작업 스케줄러로 클로드 코드 자동화 — claude -p 예약 연결

작업 스케줄러는 Windows가 정해진 시각에 프로그램을 돌려 주는 기본 도구다. schtasks는 그 도구의 명령 줄 판이고, 제어판의 작업 스케줄러와 같은 일을 해서 둘을 섞어 써도 된다. 여기서는 앞 절의 claude -p 한 줄을 실행 파일에 담고, 그 파일을 매일 같은 시각에 돌게 등록한다.

1. 연습 폴더에 run-summary.cmd 파일을 만들고 아래 내용을 붙여 넣는다.

@echo off
cd /d "%USERPROFILE%\Documents\claude-practice"
claude -p "Read task.md in this folder and follow it." --permission-mode acceptEdits --permission-prompts none --max-turns 10 > run-log.txt 2>&1
echo exit code %ERRORLEVEL% >> run-log.txt

맨 아래 줄은 종료 코드를 기록 파일 끝에 붙인다. 잘 됐으면 이 파일을 더블클릭했을 때 검은 창이 잠깐 떴다가 닫히고, run-log.txt 끝에 exit code 0이 남는다.

1. PowerShell에서 예약을 등록한다.

schtasks /create /tn "ClaudePracticeSummary" /tr "$env:USERPROFILE\Documents\claude-practice\run-summary.cmd" /sc daily /st 08:30

/tn은 겹치지 않는 작업 이름이다. /tr은 돌릴 파일의 전체 경로이고 262자를 넘으면 안 된다. /sc daily는 매일, /st는 24시간 형식의 시작 시각이다. 잘 됐으면 작업을 만들었다는 성공 한 줄이 나온다.

1. 예약 시각을 기다리지 말고 바로 한 번 돌려 본다.

schtasks /run /tn "ClaudePracticeSummary"

잘 됐으면 잠시 뒤 run-log.txt가 새로 쓰이고 summary.md의 수정 시각이 바뀐다.

1. 등록된 내용을 확인하고, 연습이 끝나면 지운다.

schtasks /query /tn "ClaudePracticeSummary"
schtasks /delete /tn "ClaudePracticeSummary"

잘 됐으면 첫 명령에 작업 이름과 다음 실행 시각이 보인다. 작업은 따로 정하지 않으면 등록한 사용자의 권한으로 돈다. 그래서 그 사용자 계정으로 클로드 코드에 로그인해 두면 예약 실행도 그 로그인을 쓴다. 등록할 때 /it를 붙이면 그 사용자가 로그온해 있을 때만 돈다.

작업 스케줄러 예약이 안 돌 때 — run-log.txt부터 보기

예약이 생각대로 돌지 않으면 run-log.txt부터 열어 본다. 증상에 맞춰 아래 순서로 확인한다.

1. run-log.txt가 아예 생기지 않는다. 작업이 돌지 않았거나 cd 경로가 틀린 경우다. schtasks /query로 작업이 있는지 보고, run-summary.cmd를 더블클릭해 손으로도 돌려 본다.
2. 기록에 claude 명령을 찾을 수 없다는 오류가 있다. PowerShell에서 아래 명령으로 claude의 전체 경로를 찾아 .cmd 파일의 claude 자리에 그 경로를 넣는다.

where.exe claude

1. 기록에 로그인 관련 실패가 찍혔다. 실행 도중 생긴 실패는 결과 자리에 글로 남는다. -p 실행에서는 /login을 못 쓰므로 대화 창 claude를 열어 로그인한다. 브라우저 로그인이 어려운 환경이면 claude setup-token으로 1년짜리 토큰을 만드는 길도 있다.
2. summary.md가 생기지 않고 거절됐다는 보고가 있다. --permission-mode acceptEdits가 빠졌는지 본다. 셸 명령이 필요한 일이라면 --allowedTools에 그 명령을 더한다.
3. 일은 끝난 것 같은데 실행이 한참 안 닫힌다. 클로드가 띄운 백그라운드 작업을 기다리는 경우다. 기본으로는 쉬는 상태가 10분 이어지면 남은 일을 멈추고 끝낸다.
4. 구독을 쓰는 줄 알았는데 API 요금이 나간다. ANTHROPIC_API_KEY 환경 변수가 있으면 한 번 승인한 뒤부터 그 키를 쓴다. 대화 창의 /status로 지금 어떤 로그인을 쓰는지 확인한다.

표의 위 두 줄은 «Windows가 명령을 제대로 불렀느냐»의 문제다. 아래 네 줄은 «불린 클로드 코드가 무엇에 막혔느냐»의 문제다. 처음에는 손으로 .cmd를 돌려 보고, 그다음 schtasks /run으로 한 번 더 돌려 보는 두 가지만 해도 대부분 원인이 보인다. 예약 실행도 돌 때마다 사용량이 쌓이니 처음에는 하루 한 번 정도로 시작한다. 한도가 닳는 원리는 클로드 사용 한도 이해하기 — 왜 빨리 닳고 언제 풀리나에 있다.

자주 묻는 것

claude -p를 쓰면 구독 대신 API 요금이 나가나요?

로그인 방식에 따릅니다. 구독 계정으로 로그인해 두었다면 그 로그인을 씁니다. 다만 ANTHROPIC_API_KEY 환경 변수가 있으면 승인한 뒤부터 그 API 키를 쓰고, --bare로 돌리면 구독 로그인을 읽지 않아 API 키가 필요합니다. 지금 어떤 방식이 쓰이는지는 대화 창의 /status에서 봅니다.

컴퓨터를 꺼 둬도 예약이 도나요?

클라우드 예약만 됩니다. 데스크톱 앱 예약과 /loop는 내 컴퓨터에서 돌기 때문에 컴퓨터가 켜져 있어야 하고, Windows 작업 스케줄러도 마찬가지입니다. 대신 클라우드 예약은 내 PC 파일을 보지 못합니다.

예약한 시각에 컴퓨터가 잠들어 있으면 어떻게 되나요?

데스크톱 앱 예약은 그 회차를 건너뜁니다. 깨어난 뒤에는 지난 7일 안에 놓친 회차 가운데 가장 최근 것 하나만 돌립니다. 그래서 시각이 중요한 일이면 프롬프트에 «그날 것만» 같은 조건을 넣어 둡니다.

claude -p 실행이 성공했는지 스크립트에서 어떻게 아나요?

종료 코드를 봅니다. 성공하면 0, 실패하면 0이 아닌 값으로 끝납니다. .cmd 파일에서는 %ERRORLEVEL%, PowerShell에서는 $LASTEXITCODE에 그 값이 담깁니다.

정리 — 손으로 한 줄 돌려 보고, 그다음에 예약한다

claude -p는 대화 창 없이 부탁 하나를 처리하고 스스로 끝나는 실행 방식이다. 정해진 시각에 돌리는 길은 클라우드 예약, 데스크톱 앱 예약, /loop, Windows 작업 스케줄러가 있고, 내 PC 파일이 필요한지와 무엇을 켜 둘 수 있는지로 고른다. 사람 없는 실행은 허락하지 않은 일이 거절로 끝나므로 acceptEdits나 --allowedTools로 할 일을 미리 정한다. 작업 스케줄러에는 .cmd 파일 하나를 걸고, 기록 파일과 종료 코드로 결과를 확인한다. 명령과 동작은 판마다 바뀔 수 있으니, 이 글은 2026년 11월 10일 기준으로 읽고 쓰기 전에 공식 문서를 한 번 더 확인한다. 지금 하나만 해 본다면, 연습 폴더에서 claude -p 한 줄을 돌린 뒤 $LASTEXITCODE가 0인지 보자.

참고 자료

1. Claude Code Docs. Run Claude Code programmatically — -p 비대화 실행 · 종료 코드 · bare 모드 · 끝날 때 백그라운드 작업 10분 · 입력 10MB · 출력 형식 · 도구 미리 허락 · 권한 모드 · --permission-prompts none · 대화 안 명령 · 이어 하기(2026-11-10 확인). code.claude.com
2. Claude Code Docs. CLI reference — --print · --max-turns · --max-budget-usd · --output-format · --permission-mode · --permission-prompts 설명(2026-11-10 확인). code.claude.com
3. Claude Code Docs. Choose a permission mode — v2.1.302부터 -p 실행은 Manual 모드로 시작 · 허락 규칙이나 auto 모드로 풀기(2026-11-10 확인). code.claude.com
4. Claude Code Docs. Schedule recurring tasks in Claude Code Desktop — 데스크톱 앱 예약 · 앱과 컴퓨터가 깨어 있을 때만 · 놓친 회차 7일 · Keep computer awake · 작업별 권한 모드 · Run now(2026-11-10 확인). code.claude.com
5. Claude Code Docs. Run prompts on a schedule — 클라우드 · 데스크톱 · /loop 비교 표 · 되풀이 작업 7일 만료(2026-11-10 확인). code.claude.com
6. Claude Code Docs. Automate work with scheduled tasks — 클라우드 예약 · 연구 미리보기 · 쓸 수 있는 요금제(2026-11-10 확인). code.claude.com
7. Claude Code Docs. Authentication — 로그인 우선순위 · ANTHROPIC_API_KEY가 있을 때 · /status · claude setup-token 1년 토큰(2026-11-10 확인). code.claude.com
8. Microsoft Learn. schtasks create — /tn · /tr 262자 · /sc daily · /st 24시간 형식 · 기본 실행 계정 · /it(2026-11-10 확인). learn.microsoft.com
9. Microsoft Learn. schtasks commands — /create · /run · /query · /delete · 제어판 작업 스케줄러와 같은 일(2026-11-10 확인). learn.microsoft.com