핵심 요약

• Anthropic 최상위 모델은 Fable 5.1이다: 장시간 실행 에이전트용 플래그십으로 $10/$50이고, 9월 캐시 읽기 단가가 $1에서 $0.25로 내려 캐싱 효율이 좋아졌다. Opus 5($5/$25)은 복잡한 에이전트 코딩·엔터프라이즈 작업용 주력 모델이다. OpenAI 신규 플래그십 GPT-6 Astra도 $10/$50로 같은 최상위 가격대다.
• 상위 모델 가격 차이가 크다: GPT-6 Astra·Fable 5.1($10/$50), GPT-5.6 Sol($4/$20 프로모션), Opus 5($5/$25), Gemini 3.1 Pro($2/$12). 모델 선택에 따라 월 비용이 열배 단위로 달라진다.
• 주요 최신 모델의 컨텍스트는 1M급: GPT-5.6 약 1.05M, Fable 5·Opus 5·Sonnet 5 1M, Gemini 3.1 Pro 약 1.05M, DeepSeek V4 1M이다. 단, 큰 컨텍스트를 매번 채우면 비용도 함께 커진다.
• 프롬프트 캐싱이 핵심 비용 절감 수단: OpenAI는 캐시된 입력 단가가 기본 입력보다 90% 낮고, DeepSeek V4-Pro는 cache hit 입력 단가가 cache miss보다 약 99.2% 낮다. 전체 청구액 절감률은 output 비중과 cache hit 비율에 따라 달라진다.
• 코딩 에이전트 하루 50회 요청 기준(9월 10일 가격): GPT-6 Astra 월 $261, Fable 5.1 월 $245, GPT-5.6 Sol(프로모) 월 $104, Sonnet 5 월 $52, Gemini 3.1 Pro 월 $58, DeepSeek V4-Pro는 피크 월 $25·오프피크 월 $12. 최대 약 21배 차이(Astra 피크 vs DeepSeek 오프피크).
• 선택 기준: 일일 코딩 → Sonnet 5 / Gemini 3.1 Pro, 복잡한 에이전트 코딩 → Opus 5 / GPT-5.6 Sol(최고 난도 → GPT-6 Astra·Fable 5.1), 장시간 자율 실행 → Fable 5.1, 비용 극소화 → DeepSeek V4 + 캐싱 + 오프피크.

2026년 9월 LLM 라인업: 공식 가격표

아래는 OpenAI, Anthropic, Google, DeepSeek 공식 pricing 페이지에서 직접 확인한 2026년 9월 10일 기준 Standard 티어(짧은 컨텍스트) 가격이다. 단위는 1M(100만) 토큰당 USD다. DeepSeek은 피크 요율을 기본으로 표기하고 오프피크는 별도 표에서 다룬다.

9월 10일 공식 가격표에서 확인된 주의 사항 세 가지. ① 이전 버전이 예고했던 Sonnet 5의 9월 $3/$15 인상은 적용되지 않았고 여전히 $2/$10이다. ② GPT-5.6 Sol의 $4/$20은 11월 21일까지 보장되는 프로모션가다. ③ DeepSeek은 8월 16일부터 피크/오프피크 이원 요금제를 적용 중이며 오프피크가 피크의 절반이다. GPT 계열 비용표의 기본값은 Short context 기준이며, Long context에는 별도 고가 요율이 붙는다.

같은 작업을 하면 비용이 얼마나 다를까

코딩 에이전트를 하루 50회 호출한다고 가정하자. 평균 input 30K 토큰(시스템 프롬프트 + 파일 컨텍스트), output 3K 토큰(코드 + 설명)으로 잡는다. 캐싱 절감 효과를 현실적으로 반영해 input의 70%가 cache hit되는 것으로 계산했다. GPT 계산은 Short context 요율, DeepSeek은 피크 요율을 적용했다.

계산 결과, 월 20일 근무 기준:

같은 사용량에서도 GPT-6 Astra(월 $261)와 DeepSeek V4-Pro 오프피크(월 $12)는 약 21배 비용 차이가 난다. 성능이 “충분히” 좋다면 저가 모델로 바꾸고 캐싱과 오프피크까지 활용하는 것만으로 월 수백 달러를 아낄 수 있다. 8월 말 표의 “최대 89배”는 구 V4 프리뷰 요금 기준 계산이므로 9월 10일 피크/오프피크 요금 기준으로 정정한다.

DeepSeek 피크/오프피크 요금제 (8월 16일 시행)

DeepSeek은 V4 정식 출시에 맞춰 2026년 8월 16일 16:00(UTC)부터 피크/오프피크 이원 요금제를 적용했다. 피크는 평일(월~금) 01:00~04:00, 06:00~10:00 UTC이고 나머지 시간은 모두 오프피크다. 오프피크 요율은 피크의 정확히 절반이다. 한국 시간(KST=UTC+9)으로 환산하면 피크는 평일 10:00~13:00, 15:00~19:00이므로, 한국 개발자의 낮 근무 시간 대부분이 피크에 해당한다. 반대로 한국 시간 밤 9시 이후와 주말은 전부 오프피크다. 야간 배치 작업이나 주말 대량 처리를 DeepSeek로 돌리는 구성이면 요금을 절반으로 줄일 수 있다.

토큰량의 이해: 컨텍스트 윈도우 vs 실제 소비량

사용자가 “받는” 토큰량: 컨텍스트 윈도우

컨텍스트 윈도우는 한 번에 모델에 넣을 수 있는 최대 토큰 수다. 2026년 8월 25일 기준 주요 모델의 윈도우는:

• GPT-5.6 전 라인업: 약 105만 토큰 — 최대 출력 128K. Long context에는 별도 요율이 적용된다.
• Claude Fable 5.1 / Opus 5 / Sonnet 5: 100만 토큰 — 최대 출력 128K.
• Gemini 3.1 Pro / 3.5 Flash: 1,048,576 토큰 — 최대 출력 65,536. Gemini 3.1 Pro는 200K 초과 프롬프트에 고가 요율이 적용된다.
• DeepSeek V4: 100만 토큰 — 최대 출력 384K.

100만 토큰은 영어 기준으로 흔히 약 75만 단어로 환산하지만, 한국어·소스코드·JSON은 토크나이저에 따라 비율이 크게 달라진다. 따라서 “파일 몇 개”나 “책 몇 권”으로 환산하기보다, API 응답의 실제 input/output usage를 확인하는 편이 정확하다.

하지만 컨텍스트 윈도우가 크다고 무조건 좋은 것은 아니다. Gemini 3.1 Pro는 프롬프트가 200K를 넘으면 input이 $2→$4로 2배, output은 $12→$18로 1.5배가 된다. GPT-5.6도 공식 가격표에서 Long context 요율을 별도로 제시한다.

사용자가 “소비하는” 토큰량: 실제 사용 패턴

코딩 에이전트(Codex, Claude Code, Gemini CLI)를 실제로 쓸 때 토큰은 어떻게 소비될까. 아래 수치는 제품사가 보장하는 평균값이나 벤치마크가 아니라, 비용 예산을 잡기 위한 예시 범위다. 실제 값은 에이전트가 읽는 파일 수, 대화 누적 길이, 도구 결과 크기에 따라 달라진다.

1회 요청당 토큰 소비 예시:

코딩 에이전트를 오래 쓰면 input 토큰이 빠르게 누적될 수 있다. 매 요청에 시스템 프롬프트 + 이전 대화 기록 + 파일 컨텍스트가 다시 포함될 수 있기 때문이다. 실제 소비량은 도구마다 다르므로 대시보드나 API 응답의 input_tokens, output_tokens, cached_tokens를 기준으로 확인해야 한다.

구독제에서 사용자가 받는 토큰량

API가 아닌 구독(ChatGPT Plus, Claude Pro 등)을 쓰는 경우, 정확한 토큰량은 공개되지 않지만 사용량 한도가 존재한다.

• ChatGPT Plus: 모델별 고정 토큰 묶음을 주는 방식이 아니다. 메시지·기능 사용 한도는 모델과 서비스 상황에 따라 달라질 수 있으므로 앱에 표시되는 현재 한도를 확인해야 한다.
• Claude Pro ($17~$20/월): Free보다 더 많은 사용량을 제공하지만 정확한 토큰 수는 공개하지 않는다.
• Claude Max ($100~/월): 공식 안내상 Pro 대비 5x 또는 20x 사용량을 5시간 세션 단위로 제공하며, 출력 한도도 더 높다.

구독제는 토큰당 과금이 아니므로 예측 가능한 비용이 장점이지만, 한도에 도달하면 일정 시간 사용이 제한되거나 모델·기능 이용 가능 범위가 달라질 수 있다. API는 사용량에 비례해 과금되며, 계정별 rate limit과 지출 한도를 함께 고려해야 한다.

프롬프트 캐싱: 비용 절감의 핵심

코딩 에이전트에서 input 토큰의 대부분은 매번 반복되는 컨텍스트(시스템 프롬프트, 코드베이스, 이전 대화)다. 프롬프트 캐싱은 이 반복 부분을 서버에 저장해 두고, 다음 요청에서 캐시된 토큰을 저렴하게 재사용하는 기능이다.

캐싱 적용 시 비용 절감 효과

input 토큰의 70%가 캐시 hit된다고 가정하면:

이 글의 70% cache hit 가정에서는 일일 비용이 약 39~46% 줄어든다(DeepSeek 피크 기준 52%). 특히 DeepSeek V4-Pro의 피크 cache hit 입력 단가는 $0.044/1M로, cache miss($1.32)보다 약 96.7% 저렴하다. 이는 전체 청구액이 그만큼 줄어든다는 뜻이 아니라, 캐시에 적중한 입력 토큰 부분의 단가 차이다. 또한 Fable 5.1은 캐시 읽기 단가가 $0.25로 인하되면서 같은 조건 절감률이 42%에서 46%로 올라갔다.

캐싱을 극대화하는 방법

1. 시스템 프롬프트를 고정한다: 도구 정의, 코딩 규칙, 프로젝트 컨텍스트를 매 요청마다 바꾸지 않는다.
2. 코드베이스 컨텍스트를 캐시 블록으로 묶는다: 관련 파일을 한 번에 크게 전송하고, 이후 요청에서는 변경분만 추가한다.
3. 5분 TTL을 의식한다: Anthropic의 기본 캐시 TTL은 5분. 연속 작업 세션 안에서 캐시를 유지하려면 요청 간격을 5분 이내로 유지하거나 확장 캐싱(extended prompt caching) 옵션을 확인한다.
4. 캐시 가능한 프롬프트 구조를 설계한다: 동적 내용(사용자 질문)은 프롬프트 끝에 배치하고, 정적 내용(컨텍스트)은 앞에 배치한다.

모델별 선택 기준: 어떤 모델을 언제 쓸까

Claude Fable 5.1 — Anthropic의 플래그십, 장시간 실행 에이전트용

Fable 5.1은 Anthropic 공식 가격표에서 “Next generation intelligence for long-running agents”로 소개되는 현행 최상위 모델이다(모델 ID claude-fable-5-1). input $10, output $50로 Opus 5의 정확히 2배이며, 장시간 자율 실행·복잡한 계획 유지·다단계 에이전트 오케스트레이션처럼 실패 비용이 큰 작업에 맞는다. 9월에는 캐시 읽기 단가가 $1에서 $0.25로 인하돼, 캐싱을 쓰는 장기 세션의 실효 비용이 눈에 띄게 줄었다. 일반적인 코드 수정에 기본 모델로 쓰기에는 여전히 과도하게 비싸므로, 장시간 실행 에이전트의 계획 수립과 최종 검증 단계에 제한적으로 배치하는 편이 현실적이다. 참고로 구세대 Fable 5는 공식 가격표의 레거시 항목으로 남아 있다.

Claude Opus 5 — 복잡한 에이전트 코딩의 주력 모델

Opus 5은 Anthropic이 “complex agentic coding and enterprise work”에 적합하다고 명시한 모델이다. Fable 5보다 한 단계 아래지만, 복잡한 코딩과 엔터프라이즈 에이전트 작업을 비용과 성능의 균형으로 처리하는 주력 모델이다. Claude Code로 대규모 리팩토링, 버그 추적, 멀티 에이전트 조정을 해야 한다면 1순위다. 단가는 $5/$25로 GPT-5.6 Sol과 비슷하지만, output이 $5 저렴해 장기 세션에서 비용이 적게 나온다.

GPT-6 Astra / GPT-5.6 Sol — 최고 성능이 필요할 때

OpenAI의 현행 플래그십은 GPT-6 Astra($10/$50, 컨텍스트 1.05M, 최대 출력 128K, 지식 컷오프 4월 30일)다. Astra 위에서 GPT-5.6 Sol은 “복잡한 전문 작업용 플래그십” 위치로 내려갔고, gpt-5.6 별칭이 Sol로 라우팅된다. Sol은 reasoning effort를 none부터 max까지 6단계로 조절할 수 있고 $4/$20 프로모션가가 11월 21일까지 보장된다. 비용 민감도가 높으면 Terra($2/$12)나 Luna($0.20/$1.20)로 하향하는 것이 현명하다. Astra의 output $50는 캐싱 없이 남용하면 Fable 5.1과 동일한 최고가 청구 구간에 들어가므로, 난도가 실제로 Astra급인 작업에만 쓰는 편이 안전하다.

Gemini 3.1 Pro — 가성비와 멀티모달의 교차점

Gemini 3.1 Pro는 input $2, output $12로 고성능 에이전트·멀티모달 모델 중 단가가 낮은 편이다. 200K 토큰까지는 $2/$12가 유지된다. 텍스트·이미지·영상·오디오·PDF 입력을 지원해 스크린샷 기반 디버깅이나 UI 분석에 활용할 수 있다. 단, 200K 초과 시 input은 2배, output은 1.5배 요율이 적용된다. 가격 민감한 고처리량 작업은 같은 Gemini 3.x 계열의 3.8 Flash($0.75/$3.75, 12월 31일까지 프로모션가)를 검토한다. 3.8 Flash는 “장기 실행 소프트웨어 엔지니어링·자율 에이전트용 지능형 Flash” 포지션이라 코딩 에이전트 보조 모델로 쓸 만하다.

Sonnet 5 — 일일 코딩의 기본값

Claude Sonnet 5는 9월 10일 현재도 $2/$10 표준가를 유지 중이다. 앞서 예고됐던 9월 인상은 공식 가격표에 반영되지 않았다. Opus 5과 동일한 생태계(MCP, Claude Code)를 저렴하게 쓸 수 있다는 것이 가장 큰 장점이다. 일상적인 코딩, 코드 리뷰, 단순 디버깅은 Sonnet 5로 충분하고, 복잡한 작업만 Opus 5로 라우팅하는 전략이 비용 효율적이다.

DeepSeek V4 — 비용 극소화, 대량 처리

DeepSeek V4-Pro(V4-Pro-0813)는 8월 16일부터 피크/오프피크 이원 요금제를 적용한다. 피크 기준 input(cache miss) $1.32, output $3.96이고 오프피크는 그 절반이다. 공식 문서상 1M 컨텍스트, 최대 384K 출력, tool calling·Responses API·Anthropic API 호환을 지원하고 context caching이 기본 활성화된다. 따라서 대량 배치 분석과 정형화된 처리, 특히 한국 시간 야간·주말 작업의 비용 후보로 강력하게 검토할 수 있다. 다만 가격표만으로 결과 품질과 운영 안정성을 판단할 수 없으므로, 실제 한국어 입력·도구 스키마·오류 복구 패턴으로 자체 평가한 뒤 적용해야 한다.

모델 선택 체크리스트

• ☐ 일일 사용량이 적은가 (< 20회)? → Sonnet 5 또는 Gemini 3.1 Pro. 실제 월 비용은 요청당 컨텍스트 크기로 계산한다.
• ☐ 몇 시간 이상 자율 실행하는 에이전트인가? → Fable 5.1. 장기 계획 유지와 오케스트레이션.
• ☐ 복잡한 에이전트 코딩인가? → Opus 5. 다단계 도구 호출과 대규모 리팩토링.
• ☐ 최고 성능이 필수인가? → GPT-6 Astra 또는 Fable 5.1. 프롬프트 캐싱으로 청구를 끌어내린다.
• ☐ 비용을 극소화해야 하는가? → DeepSeek V4-Pro + 프롬프트 캐싱 + 오프피크 실행. 이 글 계산 기준 월 $12까지 낮아진다.
• ☐ 멀티모달(이미지/영상)이 필요한가? → Gemini 3.1 Pro. 텍스트·이미지·영상·오디오·PDF 입력을 지원하지만 각 입력은 내부 토큰으로 환산되어 과금된다.
• ☐ 200K 토큰 이상 컨텍스트가 필요한가? → 모델별 장문 요율까지 비교한다. Gemini 3.1 Pro는 200K 초과 요율이 있으며, GPT-5.6도 공식 가격표에서 Long context 요율을 별도로 제시한다. DeepSeek V4는 공식 가격표상 1M 단일 요율이다.
• ☐ 구독으로 충분한가? → Claude Pro/Max 또는 ChatGPT Plus. 예측 가능한 고정 비용, 세션 기반 제한.

비용 최적화 3단계

1. 모델 라우팅: 단순 작업은 저가 모델(Sonnet 5, Gemini Flash-Lite), 복잡한 코딩은 Opus 5·GPT-5.6 Sol, 장시간 실행 에이전트의 핵심 단계만 Fable 5로 보낸다. AI Gateway(LiteLLM, Cloudflare AI Gateway)로 라우팅 규칙을 설정하면 자동화된다.
2. 프롬프트 캐싱: 시스템 프롬프트 + 코드베이스 컨텍스트의 정적 prefix를 재사용한다. 캐시된 입력 단가는 크게 낮아지지만, 이 글의 70% hit 시나리오에서 전체 비용 절감률은 약 39~58%다.
3. Batch 처리: 동기 처리가 필요 없는 작업(코드 리뷰, 문서 생성, 테스트 케이스 작성)은 Batch API를 써서 50% 할인을 받는다. Anthropic, OpenAI 모두 Batch 처리 시 50% 할인을 제공한다.

FAQ

Q. Fable 5.1과 Opus 5은 무엇이 다른가?

Fable 5.1은 Anthropic의 장시간 실행 에이전트용 최상위 모델이고, Opus 5은 복잡한 에이전트 코딩과 엔터프라이즈 작업을 위한 주력 모델이다. Fable 5.1의 API 가격은 $10/$50로 Opus 5($5/$25)의 2배지만, 캐시 읽기 단가는 $0.25로 오히려 Opus 5($0.50)보다 낮다. 일반 코딩은 Opus 5을 쓰고, 장시간 자율 실행과 실패 비용이 큰 계획·검증 단계에만 Fable 5.1을 제한적으로 배치하는 편이 경제적이다.

Q. 코딩 에이전트에서 가장 비용 효율적인 조합은?

Sonnet 5를 기본으로 쓰고, 복잡한 디버깅이나 대규모 리팩토링만 Opus 5으로 라우팅하는 방식이 현실적이다. 다만 실제 비용은 요청 횟수와 컨텍스트 크기에 따라 달라지므로, 고정 금액보다 API usage를 기준으로 판단해야 한다.

Q. Gemini 3.1 Pro의 200K 초과 요율은 언제 문제가 되나?

전체 코드베이스나 매우 긴 대화 기록을 한 요청에 넣어 프롬프트가 200K를 넘을 때 적용된다. 이 구간에서는 input이 $2→$4, output이 $12→$18로 오른다. 파일 개수만으로 토큰 수를 예측하지 말고 API usage나 tokenizer로 확인해야 한다.

Q. DeepSeek V4는 프로덕션 에이전트에 써도 되나?

DeepSeek 공식 문서상 V4는 tool calling과 1M 컨텍스트를 지원한다. 다만 프로덕션 적합성은 각 서비스의 실제 한국어 입력, 도구 스키마, 오류 복구 패턴으로 자체 평가(Eval)를 거쳐 판단하는 것이 안전하다.

Q. DeepSeek 오프피크 시간대는 한국 시간으로 언제인가?

피크는 평일(월~금) 01:00~04:00, 06:00~10:00 UTC다. KST(UTC+9)로는 평일 10:00~13:00, 15:00~19:00이 피크고, 나머지 전 시간(평일 밤·심야, 주말 전체)이 오프피크다. 한국 기준 야간 배치·주말 대량 처리를 DeepSeek로 돌리면 동일 작업을 피크 대비 절반 가격에 처리할 수 있다.

Q. 프롬프트 캐싱은 어떻게 켜나?

제공자마다 방식이 다르다. Anthropic API는 캐시할 블록에 {"cache_control": {"type": "ephemeral"}}을 지정하며, 공식 가격표의 기본 prompt cache read 요율은 5분 TTL 기준이다. OpenAI는 조건을 충족하는 동일 prefix에 프롬프트 캐싱을 자동 적용한다. DeepSeek context caching은 모든 사용자에게 기본 활성화되며, 이후 요청이 이전 요청의 prefix와 겹치고 캐시 규칙을 충족할 때 hit로 계산된다.

Q. 구독(ChatGPT Plus / Claude Pro)과 API 중 뭘 써야 하나?

월 사용량이 예측 가능하고 한도 내에서 충분하다면 구독이 싸다. 하지만 코딩 에이전트를 하루 종일 쓰거나, 여러 모델을 동시에 쓰거나, 자동화 파이프라인에 통합해야 한다면 API가 유연하다. 구독 한도에 자주 도달한다면 API 전환이 더 경제적일 수 있다.

참고 자료

• OpenAI API Pricing — GPT-6 Astra, GPT-5.6 Sol(프로모션 11월 21일까지)/Terra/Luna 가격 및 스펙 (2026년 9월 10일 확인)
• Anthropic Pricing — Fable 5.1(캐시 읽기 $0.25), Opus 5, Sonnet 5, Haiku 4.5 API 가격과 공식 포지셔닝 (2026년 9월 10일 확인)
• Google AI Gemini API Pricing — Gemini 3.1 Pro, 3.8 Flash(12월 31일까지 프로모션) 가격 (2026년 9월 10일 확인)
• DeepSeek API Models & Pricing — V4-Pro, V4-Flash 피크/오프피크 가격 및 캐싱 (2026년 9월 10일 확인)
• OpenAI Models — GPT-6 Astra — 컨텍스트 1.05M, 최대 출력 128K (2026년 9월 10일 확인)
• Claude Models Overview — Fable 5.1·Opus 5·Sonnet 5 컨텍스트·최대 출력·지식 컷오프 (2026년 9월 10일 확인)

The post 2026년 하반기 LLM 비교: GPT-5.6 vs Fable 5·Opus 5 vs Gemini 3.1 Pro appeared first on .

OpenClaw를 맥미니에 설치하면 무엇이 달라지나

OpenClaw를 맥미니에 설치하면 집이나 사무실에 항상 켜져 있는 개인 AI 에이전트 서버를 둘 수 있다. 단순한 챗봇과 달리 Gateway, 메신저 채널, skills, 모델 인증, 파일 접근 권한이 함께 움직이기 때문에 설치 직후부터 운영과 보안을 같이 설계해야 한다.

Google Trends 값은 절대 검색량이 아니라 상대 지수다. 다만 최근 12개월 흐름을 보면 AI agent는 꾸준한 큰 흐름이고, OpenClaw와 Hermes Agent에도 docs, install, skills, memory 같은 실사용 관련 관심이 붙어 있다.

OpenClaw를 한 줄로 정리하면

OpenClaw는 로컬 또는 개인 서버에서 실행되며 여러 메신저 채널을 통해 명령을 받고, 파일·터미널·브라우저·도구·skills를 연결해 작업하는 개인 AI assistant다. 공식 README 기준으로 WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Microsoft Teams, Matrix, LINE, WeChat 등 여러 채널을 언급한다.

중요한 점은 Gateway가 단순 챗봇 서버가 아니라 control plane 역할을 한다는 것이다. 메시지를 받고, 어떤 agent와 tool을 사용할지 결정하고, 권한 정책과 session 상태를 관리한다. 그래서 설치 글에는 보안과 운영 항목이 반드시 들어가야 한다.

설치 전 준비물

모델 인증 방식: OAuth와 API 키 중 무엇을 쓸까

OpenClaw에서 모델을 연결하는 방식은 크게 구독 계정 기반 인증과 API 키 기반 인증으로 나눌 수 있다. 개인 사용자는 ChatGPT/Codex OAuth, GitHub Copilot device flow, Claude Code CLI 로그인처럼 이미 쓰는 구독 계정을 연결하는 방식이 편하다. 반대로 장시간 자동화, 팀 공유, 비용 통제, 서버 운영처럼 예측 가능한 과금과 권한 관리가 중요하면 API 키 방식이 더 단순하다.

OpenClaw 2026.9.1의 빠른 시작은 같은 기기에 있는 Claude Code·Codex 로그인과 API 키 후보를 찾아 실제로 검증하고 기본 모델 선택으로 이어 준다. 개인 실험은 이 경로가 편하지만, 장시간 자동화나 팀 공유 환경은 API 키 기반 과금과 권한 관리가 더 명확한 경우가 많다.

# 1. 개인 사용자는 OAuth/device-code 방식으로 먼저 시작
openclaw models auth login --provider openai
openclaw models auth login --provider openai --device-code

# 2. OpenRouter도 OAuth 또는 API 키 방식 선택 가능
openclaw models auth login --provider openrouter --method oauth
openclaw models auth login --provider openrouter --method api-key

# 3. 인증 후 기본 모델 선택
openclaw models set openai/gpt-5.5

OpenClaw 설치 기본 흐름

공식 설치 문서는 macOS에서 설치 스크립트를 우선 권장한다. 이 스크립트는 운영체제를 확인하고, 필요한 경우 지원되는 Node.js를 설치한 뒤 OpenClaw 설치와 온보딩을 이어 간다. 아래 첫 번째 흐름이 일반 사용자용이고, 이미 Node.js를 직접 관리할 때만 npm 대안을 쓰면 된다.

# 권장: macOS 설치 스크립트
curl -fsSL https://openclaw.ai/install.sh | bash

# 설치 확인
openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

# 대안: Node.js를 직접 관리하고 npm 12 또는 npm 11.16+를 쓸 때
npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

# npm 11.15 이하에서는 --allow-scripts 옵션을 빼야 한다

공식 문서의 현재 요구사항은 Node.js 22.22.3+, 24.15+, 25.9+다. 설치 스크립트는 macOS에서 Node가 없을 때 Node 26을 준비한다. npm 12 또는 11.16+는 패키지 생명주기 스크립트를 허용하기 위해 --allow-scripts=openclaw가 필요하고, npm 11.15 이하는 이 옵션 자체를 지원하지 않으므로 빼야 한다. 설치 뒤에는 openclaw doctor와 Gateway 상태, 대시보드 접속을 확인한다.

맥미니에서 먼저 잡아야 할 운영 설정

• 절전 모드와 자동 잠자기 설정을 꺼서 Gateway가 끊기지 않게 한다.
• 전용 macOS 사용자 계정을 만들고, OpenClaw가 접근할 폴더 범위를 제한한다.
• SSH 또는 화면 공유는 필요할 때만 열고, 강한 인증과 방화벽을 적용한다.
• launchd 또는 OpenClaw daemon 설치로 재부팅 후 자동 시작을 확인한다.
• 로그 위치와 에러 확인 명령을 문서화한다.
• API 키는 셸 히스토리, README, 스크립트에 남기지 않는다.

많이 함께 볼 만한 플러그인·skills·편의 도구

OpenClaw 자체 설치보다 중요한 것은 “무엇을 붙여서 실제로 편하게 쓸 것인가”다. GitHub와 ClawHub 주변 생태계를 보면 memory, skills, UI manager, VPS panel, web search MCP가 반복적으로 나타난다. 아래 항목은 모든 사용자에게 필수는 아니지만, 개인 AI 에이전트 서버를 오래 운영할 때 편의성을 크게 높이는 도구들이다.

처음 설치할 때 추천 조합

1단계: 최소 안정 조합

• OpenClaw Gateway
• 모델 인증 한 가지(API 키, OAuth, Claude CLI 로그인 중 선택)
• Telegram 또는 Discord 한 채널
• 전용 macOS 계정
• 자동 시작과 로그 확인

처음부터 모든 플러그인을 넣지 않는 것이 좋다. 먼저 Gateway와 채널 연결, 선택한 모델 인증과 기본 모델 호출, 재부팅 후 자동 시작만 검증한다. 이 상태에서 하루 정도 실제 메시지와 간단한 파일 작업을 테스트한다.

2단계: 생산성 조합

• ClawHub skills에서 자주 쓰는 작업 skill 설치
• Claude-Mem 같은 memory 계열 도구 검토
• 웹 검색 MCP 또는 공식 문서 검색 도구 추가
• 모델 failover 또는 provider fallback 설정

이 단계에서는 “매번 반복하는 작업”을 skills로 뽑아내는 것이 핵심이다. 예를 들어 블로그 리서치, 서버 상태 확인, GitHub 이슈 요약, 캘린더 브리핑처럼 자주 쓰는 일을 먼저 자동화한다.

3단계: 운영 조합

• 로그와 health check
• 비용 알림과 API 사용량 제한
• 백업과 설정 파일 버전 관리
• 원격 접근 보안 정책
• Gateway exposure runbook 확인

메신저로 컴퓨터를 조작하는 도구는 편하지만 위험하다. 공식 문서도 inbound DM을 untrusted input으로 다루라고 안내한다. 그룹 채팅이나 외부 네트워크에 열기 전에는 allowlist, pairing policy, channel별 권한을 반드시 확인해야 한다.

보안 체크리스트

설치 후 다음에 점검할 것

OpenClaw 설치가 끝나면 바로 여러 채널과 플러그인을 한꺼번에 붙이기보다 하루 정도 최소 구성으로 운영해 보는 것이 좋다. 이 기간에는 Gateway 재시작, 메신저 응답 지연, API 비용, 로그 크기, 파일 접근 범위를 확인한다. 문제가 없으면 memory, skills, 웹 검색 MCP, UI 관리 도구를 순서대로 추가한다.

FAQ

OpenClaw는 맥미니에서만 써야 하나?

아니다. OpenClaw는 macOS, Linux, Windows를 지원한다. 다만 맥미니는 저전력 상시 구동, 조용한 운영, macOS 자동화와 음성 기능 활용 측면에서 개인 AI 에이전트 서버 용도로 잘 맞는다.

OpenClaw 설치 후 가장 먼저 연결할 채널은 무엇이 좋은가?

처음에는 Telegram이나 Discord처럼 봇 토큰과 접근 제어가 비교적 명확한 채널이 좋다. 그룹 채팅에 열기 전에는 allowlist와 DM 접근 정책을 먼저 확인해야 한다.

OpenClaw에 꼭 추가할 만한 도구는 무엇인가?

모든 사람에게 필수인 도구는 없다. 다만 장기 운영에는 persistent memory 계열 도구, ClawHub skills, 웹 검색 MCP, UI 관리 도구, 비용·모델 전환 도구가 편의성을 크게 높인다.

참고 자료

• OpenClaw GitHub repository
• OpenClaw 2026.9.1 release notes
• OpenClaw Install
• OpenClaw Getting Started
• OpenClaw Onboarding CLI
• OpenClaw Gateway Security
• OpenClaw Skills
• OpenClaw OpenAI provider
• OpenClaw Anthropic provider
• OpenClaw OAuth concepts
• OpenClaw Model providers
• OpenClaw GitHub Copilot provider
• OpenClaw OpenRouter provider
• Awesome OpenClaw Skills
• Claude-Mem
• CC Switch
• AionUi
• 1Panel
• Kindly Web Search MCP Server

함께 읽으면 좋은 글

• 바이브코딩 시대 개발자의 생존 전략
• AI 코딩 에이전트 선택 기준 7가지

The post OpenClaw 설치 가이드 2026: 맥미니로 개인 AI 에이전트 서버 구축하기 appeared first on .

왜 이 주제가 지금 중요해졌나

AI 코딩 도구가 처음 등장했을 때 논의는 주로 개발자 생산성에 머물렀다. 더 빨리 코드를 쓰는가, 테스트를 대신 만들어 주는가, 버그를 얼마나 잘 찾는가가 중심이었다. 하지만 바이브코딩이 확산되면서 변화의 중심은 개발자 내부가 아니라 개발 주체 자체로 이동했다.

이제 세무사, 노무사, 부동산 전문가, 마케터, 운영 담당자 같은 도메인 전문가도 자연어로 간단한 앱과 자동화 도구를 만들 수 있다. 이들은 고객의 문제와 업무 흐름을 잘 안다. AI는 그 지식을 빠르게 화면과 기능으로 바꾼다. 문제는 그다음이다. 데모가 실제 고객에게 노출되는 순간, 그것은 더 이상 장난감이 아니라 운영 책임이 있는 서비스가 된다.

2025~2026년 자료가 보여주는 흐름

이 글에서는 2025년 이후 자료만 사용한다. 오래된 AI 낙관론보다 최근의 개발 도구 사용, 조직 리스크, agent-generated code 검토 문제를 함께 보는 편이 현재 상황을 더 정확히 설명한다.

바이브코딩은 요구사항 문서 대신 데모를 가져온다

과거에는 도메인 전문가가 개발자에게 문제를 설명했다. 개발자는 요구사항을 듣고 화면, 데이터, 로직, 배포 구조를 설계했다. 바이브코딩 이후에는 상황이 달라진다. 도메인 전문가는 AI에게 설명하고, AI는 동작하는 데모를 만든다. 개발자에게는 빈 문서가 아니라 이미 움직이는 결과물이 온다.

이 변화는 개발자의 가치를 없애지 않는다. 대신 개발자가 개입하는 위치를 뒤로 민다. 개발자는 0에서 1을 만드는 사람만이 아니라, 0.3 또는 0.7짜리 데모를 실제 고객이 쓸 수 있는 1.0짜리 서비스로 끌어올리는 사람이 된다.

데모와 프로덕션 서비스는 다르다

바이브코딩 산출물은 데모로는 충분할 수 있다. 화면이 있고, 버튼이 동작하고, 로컬 환경에서는 기대한 결과가 나온다. 하지만 프로덕션 서비스는 다른 기준을 요구한다.

• 사용자 인증과 권한이 안전하게 분리되는가
• 개인정보와 결제 정보가 적절히 보호되는가
• DB 스키마가 실제 데이터 증가를 견딜 수 있는가
• 실패 케이스와 예외 처리가 충분한가
• 배포가 재현 가능하고 롤백 가능한가
• 로그, 메트릭, 알림이 준비돼 있는가
• 운영자가 문제를 추적할 수 있는가
• 비용이 예측 가능한가
• 법적·보안 리스크를 설명할 수 있는가

이 질문에 답하지 못하면 그것은 서비스가 아니라 공개된 데모에 가깝다. 개발자의 기회는 바로 이 간극에 있다.

개발자가 노려야 할 시장은 프로덕션화다

앞으로 개발자에게 들어오는 요청은 “이런 기능을 만들어 달라”에서 “AI로 여기까지 만들었는데 실제 서비스로 올릴 수 있게 해 달라”로 바뀔 가능성이 크다. 이때 필요한 역량은 단순 구현보다 넓다.

도메인 전문가와 개발자의 역할은 충돌하지 않는다

도메인 전문가는 문제를 안다. AI는 빠르게 데모를 만든다. 개발자는 그것을 서비스로 책임진다. 이 세 역할은 경쟁 관계보다 분업 관계에 가깝다. 개발자가 모든 도메인을 더 잘 알 필요는 없다. 대신 도메인 전문가의 데모를 읽고, 위험한 부분을 찾아내고, 출시 가능한 구조로 재설계할 수 있어야 한다.

여기서 중요한 개발자는 “AI보다 코드를 잘 치는 사람”이 아니다. “AI가 만든 코드를 설명하고, 검증하고, 운영 가능한 구조로 바꿀 수 있는 사람”이다.

개발자가 지금 준비할 체크리스트

이 주장을 과장하지 않기 위해 필요한 선 긋기

아직 “도메인 전문가가 만든 바이브코딩 데모의 프로덕션화 시장 규모”를 직접 측정한 표준 통계는 부족하다. 따라서 이 글의 주장은 확정된 시장 규모 예측이 아니라, 2025~2026년 자료가 보여주는 흐름을 바탕으로 한 전략적 해석이다.

다만 자료가 가리키는 방향은 일관적이다. AI 도구 사용은 확산됐고, 비IT 조직에서도 AI 앱과 에이전트가 구현되고 있으며, AI는 조직의 약점을 증폭하고, agent-generated code는 리뷰와 기술부채 문제를 만든다. 그러므로 개발자가 집중할 지점은 코드 생성 경쟁이 아니라 프로덕션화 역량이다.

FAQ

바이브코딩 시대에 개발자는 정말 필요 없나?

아니다. 코드 생성과 프로덕션 운영은 다른 문제다. AI가 데모를 만들 수 있어도 인증, 권한, 데이터 모델링, 배포, 모니터링, 장애 대응은 여전히 전문적인 개발 역량을 요구한다.

도메인 전문가가 직접 만든 앱은 왜 프로덕션화가 필요한가?

도메인 전문가는 문제를 잘 알지만 운영 환경에서 필요한 보안, 테스트, 백업, 비용 관리, 감사 로그, 장애 대응 체계를 모두 갖추기 어렵다. 실제 고객이 쓰는 서비스로 전환하려면 이 간극을 메워야 한다.

개발자가 준비해야 할 핵심 능력은 무엇인가?

AI 코드 리뷰, 시스템 설계, 테스트 전략, 인증과 권한, 클라우드 배포, 모니터링, 보안 점검, 도메인 전문가와의 요구사항 정리 능력이 중요하다.

AI 코딩 도구를 쓰면 생산성이 항상 오르나?

항상 그렇지는 않다. METR의 2025년 RCT 연구처럼 성숙한 코드베이스와 높은 품질 기준에서는 AI 산출물을 이해하고 검증하는 비용이 커질 수 있다.

참고 자료

• Stack Overflow Developer Survey 2025 — AI
• DORA 2025 State of AI-assisted Software Development
• METR / arXiv 2025 — Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity
• GitHub Blog 2026 — Agent pull requests are everywhere. Here’s how to review them.
• Nutanix 2026 Enterprise Cloud Index
• IBM Cost of a Data Breach Report 2025
• Lovable, Replit Agent, Bolt.new

함께 읽으면 좋은 글

• AI 생산성 역설: 왜 팀은 더 빨라졌는데 더 자주 어긋날까
• AI 코딩 에이전트 비교 2026 최신판
• AI 에이전트 도구 레지스트리 시대

The post 바이브코딩 시대 개발자의 생존 전략: AI 데모를 프로덕션 서비스로 바꾸는 일 appeared first on .

Agent Skills는 Claude의 기능을 모듈화된 폴더 형태로 확장하는 시스템입니다. 각 Skill은 필수 파일인 SKILL.md와 선택적 지원 파일들(스크립트, 템플릿 등)로 구성됩니다.

핵심 특징: Model-Invoked

Skills의 가장 중요한 특징은 Model-Invoked 방식입니다. 사용자가 명시적으로 호출하지 않아도, Claude가 작업 맥락을 분석해 자동으로 적절한 Skill을 활성화합니다. 이는 Slash Commands와의 가장 큰 차이점입니다.

Skills vs Slash Commands

언제 Skills를 사용하나:
– Claude가 자동으로 인식해야 하는 복잡한 워크플로우
– 다중 파일과 스크립트가 필요한 작업
– 검증 절차가 포함된 복잡한 프로세스
– 팀 전체가 공유하는 표준화된 가이드

언제 Slash Commands를 사용하나:
– 같은 프롬프트를 반복 실행
– 단일 파일로 충분한 간단한 작업
– 명시적인 수동 실행이 필요한 경우

Skills의 종류와 적용 범위

Claude Code의 Skills는 3가지 범위로 관리됩니다.

1. Personal Skills (~/.claude/skills/)

목적: 개인 워크플로우와 실험적 도구

특징:
– 홈 디렉토리에 저장
– 모든 프로젝트에서 접근 가능
– Git 버전 관리 불필요
– 개인 개발 환경에 특화

사용 예시:

~/.claude/skills/
├── my-code-review/       # 개인 코드 리뷰 스타일
├── debug-helper/         # 자주 사용하는 디버깅 워크플로우
└── quick-refactor/       # 개인용 리팩토링 패턴

2. Project Skills (.claude/skills/)

목적: 프로젝트/팀 공유 전문 지식

특징:
– 프로젝트 루트의 .claude/skills/에 저장
– Git으로 팀원과 공유
– 프로젝트별 표준과 가이드라인
– 특정 프로젝트에만 적용

사용 예시:

project-root/
└── .claude/
    └── skills/
        ├── blog-posting-style/   # 블로그 스타일 가이드
        ├── api-design-guide/     # API 설계 표준
        └── test-automation/      # 프로젝트별 테스트 자동화

3. Plugin Skills

목적: 플러그인이 제공하는 번들 기능

특징:
– 플러그인 설치 시 자동 제공
– 플러그인 개발자가 관리
– 범용적인 도구와 워크플로우
– 설치만으로 사용 가능

적용 범위 비교표

Skills 사용 방법

자동 활성화 (권장)

Claude는 다음 3곳에서 Skills를 자동으로 발견합니다:

# 1. Personal Skills
~/.claude/skills/

# 2. Project Skills (현재 프로젝트)
/path/to/project/.claude/skills/

# 3. Plugin Skills (설치된 플러그인)

사용자가 요청할 때, Claude는 각 Skill의 description 필드를 분석해 가장 적합한 Skill을 자동으로 활성화합니다.

예시:

# 사용자 요청
"블로그 포스팅 초안 작성해줘"

# Claude의 동작
1. 사용 가능한 Skills 확인
2. description에서 "블로그", "포스팅" 키워드 발견
3. blog-posting-style Skill 자동 활성화
4. Skill 가이드라인에 따라 작성

사용 가능한 Skills 확인

# Claude Code에서 실행
claude "What Skills are available?"

명시적 호출 (선택적)

특정 Skill을 강제로 사용하려면:

# Skill 도구 명시
claude "blog-posting-style skill을 사용해서 경험 기록형 포스팅 작성해줘"

Skills 만들기 – 실전 가이드

디렉토리 구조

my-skill/
├── SKILL.md           # 필수: Skill 정의와 지침
├── reference.md       # 선택: 추가 참고 자료
├── scripts/           # 선택: 실행 스크립트
│   └── validate.sh
└── templates/         # 선택: 템플릿 파일
    └── template.yaml

SKILL.md 작성법

필수 구성 요소:

1. YAML 프론트매터 (필수)
2. 상세 지침 (필수)
3. 예시와 템플릿 (권장)

전체 예시:

---
name: blog-posting-style
description: 블로그 포스팅 작성 스타일 가이드. 정보 정리형과 경험 기록형 두 가지 모드 지원. 블로그, 포스팅, 글쓰기 작업 시 자동 적용.
allowed-tools: [Read, Write, Edit, WebFetch]
---

# 블로그 포스팅 스타일 가이드

## 목적
ShowMeTheTime 블로그의 표준 작성 스타일을 정의합니다.

## 모드 구분

### 정보 정리형
- 공식 문서 기반 객관적 정보
- "~입니다", "~합니다" 체
- 코드 예시와 비교표 중심

### 경험 기록형
- 실제 경험과 시행착오 기록
- 구어체 사용
- 솔직한 감정 표현

## 작성 원칙

### 코드 예시
- 반드시 주석 추가
- 동작하는 코드만 제시

```yaml
# 좋은 예시
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config  # ConfigMap 이름
data:
  LOG_LEVEL: "info"  # 로그 레벨 설정

구조화

• 짧은 문단 (2-4줄)
• 불렛 포인트 적극 활용
• 비교는 표로 정리

참고 자료

• 마크다운 가이드

### YAML 프론트매터 필드

#### name (필수)

**규칙:**
- 소문자, 숫자, 하이픈만 사용
- 최대 64자
- 고유해야 함

```yaml
# ✅ 올바른 예시
name: blog-posting-style
name: api-design-guide
name: test-automation-v2

# ❌ 잘못된 예시
name: Blog Posting Style  # 공백 불가
name: api_design_guide    # 언더스코어 불가
name: API-Design-Guide    # 대문자 불가

description (필수)

중요: description은 Claude가 Skill을 발견하는 핵심입니다.

작성 원칙:
– 무엇을 하는 Skill인지 명확히
– 언제 Claude가 사용해야 하는지 구체적으로
– 사용자가 언급할 트리거 키워드 포함
– 최대 1024자

#  나쁜 예시: 너무 모호함
description: 문서 작업을 돕습니다.

#  좋은 예시: 구체적이고 트리거 키워드 포함
description: 블로그 포스팅 작성 스타일 가이드. 정보 정리형과 경험 기록형 두 가지 모드 지원. 블로그, 포스팅, 글쓰기, 기술 블로그 작업 시 자동 적용.

트리거 키워드 예시:

allowed-tools (선택)

특정 도구만 허용해 보안과 읽기 전용 워크플로우를 구현합니다.

---
name: security-audit
description: 보안 감사를 위한 읽기 전용 Skill. 코드 수정 불가.
allowed-tools: [Read, Grep, Glob, Bash]
---

주요 도구:
– Read: 파일 읽기
– Write: 파일 쓰기
– Edit: 파일 수정
– Bash: 쉘 명령 실행
– Grep: 코드 검색
– Glob: 파일 검색
– WebFetch: 웹 페이지 가져오기

선택적 파일들

reference.md

추가 참고 자료와 긴 문서를 분리합니다.

# reference.md
## 추가 참고 자료

### 관련 문서
- [공식 가이드](https://example.com)

### 상세 예시
...

scripts/

검증 스크립트나 자동화 도구를 포함합니다.

# scripts/validate.sh
#!/bin/bash
# 포스팅 형식 검증 스크립트

echo "Validating blog post format..."
# 검증 로직

templates/

재사용 가능한 템플릿 파일을 저장합니다.

# templates/api-template.yaml
openapi: 3.0.0
info:
  title: API Name
  version: 1.0.0
paths:
  /resource:
    get:
      summary: Get resource

고급 기능

Progressive Disclosure (점진적 컨텍스트 로딩)

Claude는 필요한 시점에만 지원 파일을 로드해 컨텍스트를 효율적으로 관리합니다.

동작 방식:
1. 초기에는 SKILL.md만 로드
2. 추가 정보 필요 시 reference.md 로드
3. 스크립트 실행 필요 시 scripts/ 로드

이점:
– 토큰 사용량 최적화
– 빠른 응답 시간
– 필요한 정보만 로드

보안 중심 워크플로우

allowed-tools로 읽기 전용 Skill을 만들 수 있습니다.

예시: 보안 감사 Skill

---
name: security-audit
description: 코드베이스 보안 취약점 검사. 읽기 전용으로 동작하며 코드 수정 불가.
allowed-tools: [Read, Grep, Glob, Bash]
---

# 보안 감사 Skill

## 검사 항목
- SQL Injection 취약점
- XSS 취약점
- 하드코딩된 시크릿
- 안전하지 않은 의존성

## 검사 방법
```bash
# 하드코딩된 API 키 검색
grep -r "API_KEY\s*=\s*['\"]" .

# SQL Injection 취약 패턴
grep -r "execute.*\+.*request\." .

보고서 형식

• 발견된 취약점 목록
• 심각도 평가
• 수정 권장사항

### 팀 표준화

Project Skills로 팀 전체의 작업 방식을 표준화합니다.

**예시: API 설계 표준**

```bash
project-api/
└── .claude/
    └── skills/
        └── api-design-standard/
            ├── SKILL.md
            ├── naming-conventions.md
            ├── templates/
            │   ├── rest-api.yaml
            │   └── graphql-schema.graphql
            └── scripts/
                └── validate-api.sh

베스트 프랙티스

1. 효과적인 description 작성

핵심 원칙:
– 구체적인 트리거 키워드 포함
– 사용 시점 명확히 설명
– 간결하지만 충분한 정보

비교 예시:

#  모호한 description
description: 문서 작업 도구

#  효과적인 description
description: PDF에서 텍스트 추출. PDF, 문서, 텍스트 추출 작업 시 사용.

#  너무 일반적
description: 코드 리뷰를 돕습니다.

#  구체적이고 명확
description: Pull Request 코드 리뷰 자동화. PR, 코드 리뷰, 검토 요청 시 자동으로 코드 품질, 보안, 스타일 검사 수행.

2. 하나의 Skill = 하나의 기능

각 Skill은 단일 목적에 집중해야 합니다.

#  나쁜 예시: 너무 많은 기능
general-helper/
└── SKILL.md  # 블로그 작성 + 코드 리뷰 + API 설계

#  좋은 예시: 명확한 분리
skills/
├── blog-posting/      # 블로그 작성만
├── code-review/       # 코드 리뷰만
└── api-design/        # API 설계만

3. 팀과 함께 테스트

Project Skills는 팀원들과 함께 테스트해야 합니다.

테스트 프로세스:
1. Skill 작성 및 커밋
2. 팀원들에게 다양한 요청으로 테스트 요청
3. 활성화 빈도와 정확도 확인
4. description 개선 및 재배포

예시:

# 팀원 A: "API 엔드포인트 설계해줘"
# → api-design Skill 활성화됨 

# 팀원 B: "REST API 만들어줘"
# → api-design Skill 활성화 안 됨 
# → description에 "REST" 키워드 추가 필요

4. 버전 관리와 문서화

SKILL.md 내에 버전 히스토리를 포함합니다.

---
name: blog-posting-style
description: 블로그 포스팅 스타일 가이드
---

# 블로그 포스팅 스타일 가이드

## 버전 히스토리

### v2.0.0 (2025-10-27)
- 경험 기록형 모드 추가
- SEO 최적화 가이드 추가

### v1.0.0 (2025-10-01)
- 초기 버전 (정보 정리형만)

5. Unix 스타일 경로 사용

파일 경로는 항상 Forward Slash(/)를 사용합니다.

#  올바른 경로
참고: scripts/validate.sh
템플릿: templates/api.yaml

#  잘못된 경로 (Windows 스타일)
참고: scripts\validate.sh

문제 해결

Skill이 활성화되지 않을 때

원인 1: 모호한 description

# 문제
description: 코드 작업 도구

# 해결
description: Python 코드 리팩토링 자동화. 리팩토링, 코드 정리, Python, 클린 코드 작업 시 사용.

원인 2: YAML 문법 오류

# 문제: 콜론 뒤 공백 누락
description:블로그 작성 도구

# 해결
description: 블로그 작성 도구

원인 3: 잘못된 파일 경로

# 문제
참고: ./reference.md  # 상대 경로 사용

# 해결
참고: reference.md    # 직접 파일명만

원인 4: 누락된 의존성

스크립트가 외부 도구를 사용하는 경우, SKILL.md에 명시합니다.

## 사전 요구사항
- Node.js 18+
- `jq` (JSON 처리)
- `yq` (YAML 처리)

설치 방법:
```bash
brew install jq yq

## 실제 사용 예시

### 예시 1: 블로그 포스팅 자동화

**Skill 구조:**

```bash
.claude/skills/blog-posting-style/
├── SKILL.md
├── templates/
│   ├── info-post.md      # 정보 정리형 템플릿
│   └── experience-post.md # 경험 기록형 템플릿
└── scripts/
    └── seo-check.sh      # SEO 검증 스크립트

SKILL.md:

---
name: blog-posting-style
description: 기술 블로그 포스팅 자동 작성. 블로그, 포스팅, 글쓰기, 기술 블로그 작업 시 정보 정리형/경험 기록형 중 적절한 템플릿 적용.
allowed-tools: [Read, Write, Edit, WebFetch]
---

# 기술 블로그 포스팅 스타일

## 모드 선택

사용자 요청 분석:
- "공식 문서 정리", "비교 분석", "설치 가이드" → 정보 정리형
- "삽질", "트러블슈팅", "회고", "경험" → 경험 기록형

## 정보 정리형 작성

### 구조
```markdown
# [기술명] 개념 및 사용 가이드

## 개요
- 정의와 목적
- 주요 특징

## 상세 설명
- 비교표
- 코드 예시 (주석 포함)

## 참고 자료
- 공식 문서 링크

스타일

• 객관적이고 명확한 설명
• “~입니다”, “~합니다” 체
• 공식 문서 기반

경험 기록형 작성

구조

# [경험 제목]

## 문제 상황
- 배경과 동기

## 시행착오
- 실패 과정 솔직하게
- 에러 로그 전체 포함

## 해결 과정
- 최종 해결 방법

## 고민했던 포인트
- 의사결정 과정

## 느낀 점
- 배운 점과 교훈

스타일

• 솔직하고 개인적인 표현
• 구어체 사용
• 감정 표현 OK

SEO 최적화

스크립트 실행:

./scripts/seo-check.sh draft.md

체크 항목:
– 제목 40-60자
– 메타 설명 120-160자
– 헤딩 구조 (H2, H3)
– 내부 링크 포함

**사용 시나리오:**

```bash
# 사용자 요청
"Docker Compose 설치 가이드 작성해줘"

# Claude의 동작
1. "설치 가이드" 키워드 감지
2. blog-posting-style Skill 활성화
3. 정보 정리형 모드 선택
4. templates/info-post.md 템플릿 사용
5. 공식 문서 리서치 (WebFetch)
6. 포스팅 작성
7. scripts/seo-check.sh 실행

예시 2: 코드 리뷰 자동화

Skill 구조:

.claude/skills/code-review/
├── SKILL.md
├── checklists/
│   ├── backend.md
│   ├── frontend.md
│   └── security.md
└── scripts/
    └── lint-check.sh

SKILL.md:

---
name: code-review-automation
description: Pull Request 코드 리뷰 자동화. PR, 코드 리뷰, 검토, pull request 작업 시 코드 품질, 보안, 스타일 검사 자동 수행.
allowed-tools: [Read, Grep, Glob, Bash]
---

# 코드 리뷰 자동화

## 리뷰 프로세스

### 1단계: 변경 파일 분석
```bash
git diff --name-only origin/main

2단계: 타입별 체크리스트 선택

• *.ts, *.tsx → frontend.md
• *.py, *.go → backend.md
• 모든 파일 → security.md

3단계: 자동 검사

./scripts/lint-check.sh

4단계: 수동 리뷰 포인트

코드 품질

• [ ] 중복 코드 없음
• [ ] 명확한 변수명
• [ ] 적절한 주석
• [ ] 에러 처리 완료

보안

• [ ] 입력 검증
• [ ] SQL Injection 방어
• [ ] XSS 방어
• [ ] 하드코딩된 시크릿 없음

성능

• [ ] N+1 쿼리 없음
• [ ] 적절한 인덱스
• [ ] 캐싱 고려

5단계: 리뷰 코멘트 작성

형식:

## 요약
- 변경 파일: X개
- 주요 변경: [설명]
- 전체 평가:  승인 /  수정 필요 /  재작업 필요

## 상세 리뷰

### 긍정적인 부분
- ...

### 개선 필요
1. [파일명:줄번호] 문제 설명
   - 권장: 개선 방법

### 질문
- ...

**사용 시나리오:**

```bash
# 사용자 요청
"PR #123 코드 리뷰해줘"

# Claude의 동작
1. "코드 리뷰", "PR" 키워드 감지
2. code-review-automation Skill 활성화
3. git diff로 변경 파일 확인
4. 파일 타입별 체크리스트 선택
5. scripts/lint-check.sh 실행
6. 수동 리뷰 포인트 확인
7. 구조화된 리뷰 코멘트 작성

예시 3: 프로젝트별 문서 생성

Skill 구조:

.claude/skills/doc-generator/
├── SKILL.md
├── templates/
│   ├── README.md
│   ├── API.md
│   ├── CONTRIBUTING.md
│   └── CHANGELOG.md
└── scripts/
    └── generate-api-docs.sh

SKILL.md:

---
name: project-doc-generator
description: 프로젝트 문서 자동 생성. README, API 문서, CONTRIBUTING, CHANGELOG 생성 및 업데이트. 문서, 문서화, docs 작업 시 사용.
allowed-tools: [Read, Write, Grep, Glob, Bash]
---

# 프로젝트 문서 생성 Skill

## 지원 문서 타입

### README.md
- 프로젝트 개요
- 설치 방법
- 사용 예시
- 라이선스

자동 수집 정보:
- `package.json`에서 의존성
- `scripts/`에서 사용 가능한 명령어
- 테스트 파일에서 예시 코드

### API.md
스크립트 실행:
```bash
./scripts/generate-api-docs.sh src/

포함 내용:
– 엔드포인트 목록
– 요청/응답 스키마
– 인증 방법
– 에러 코드

CONTRIBUTING.md

• Git 워크플로우
• 브랜치 전략
• PR 템플릿
• 코드 스타일 가이드

CHANGELOG.md

• 버전별 변경사항
• Git 커밋 히스토리 분석
• Semantic Versioning 준수

문서 생성 프로세스

1. 프로젝트 분석

# 프로젝트 타입 감지
ls package.json 2>/dev/null && echo "Node.js"
ls requirements.txt 2>/dev/null && echo "Python"
ls go.mod 2>/dev/null && echo "Go"

2. 템플릿 선택

프로젝트 타입에 맞는 템플릿 선택

3. 정보 수집

• Git 로그 분석
• 코드 구조 파악
• 의존성 목록 추출

4. 문서 생성

템플릿에 수집 정보 삽입

5. 검증

• 링크 유효성 확인
• 코드 예시 문법 검사
• 목차 구조 검증

**사용 시나리오:**

```bash
# 사용자 요청
"프로젝트 README 생성해줘"

# Claude의 동작
1. "README", "문서" 키워드 감지
2. project-doc-generator Skill 활성화
3. 프로젝트 타입 감지 (package.json → Node.js)
4. templates/README.md 템플릿 로드
5. package.json 파싱 (의존성, 스크립트)
6. src/ 디렉토리 분석 (주요 파일)
7. README.md 생성

참고 자료

공식 문서

• Claude Code Skills 공식 가이드
• Skills vs Slash Commands 비교
• Plugin Skills 개발

관련 리소스

• Claude Code 공식 문서
• Sub-Agents 가이드

작성 일자: 2025-10-27
공식 문서 버전: Claude Code 최신 버전 기준
카테고리: Development Tools
태그: Claude, Claude Code, AI, Development, Automation, Skills, Developer Tools, Productivity

The post Claude Code Skills 세팅 완벽 가이드 appeared first on .