외부 API 연결하기
스킬에서 외부 API를 안전하게 연결하고, 자격 증명을 보호하고, 에러를 처리하는 법을 배워요.
프리미엄 강좌 콘텐츠
이 레슨은 프리미엄 강좌의 일부예요. Pro로 업그레이드하면 모든 프리미엄 강좌와 콘텐츠를 이용할 수 있어요.
- 모든 프리미엄 강좌 이용
- 1000개 이상의 AI 스킬 템플릿 포함
- 매주 새로운 콘텐츠 추가
외부 세계와 연결하기
🔄 Quick Recall: 이전 레슨에서 $ARGUMENTS와 셸 확장으로 스킬을 동적으로 만들었어요. 이번에는 외부 API를 연결해서 스킬의 능력을 확장해요.
스킬이 외부 서비스와 통신할 수 있으면 활용도가 폭발적으로 늘어나요. 하지만 API 연결은 보안 실수가 가장 많이 발생하는 영역이기도 해요.
이 레슨을 마치면 API를 안전하게 연결하고 자격 증명을 보호하는 스킬을 만들 수 있어요.
배울 내용
- ClawHub의 7.1% 자격 증명 유출 문제
- API 보안 4대 원칙
- 세 가지 API 연동 패턴
- 인증 방식 비교
- 에러 핸들링과 자격 증명 보호
7.1% 문제
Snyk의 조사에서 ClawHub 스킬 3,984개 중 283개(7.1%)가 API 키를 하드코딩하고 있었어요. 이건 단순한 실수가 아니라 심각한 보안 취약점이에요 — 누구나 공개 스킬에서 키를 추출해서 악용할 수 있어요.
API 보안 4대 원칙
- 절대 하드코딩하지 않기 — 키를 SKILL.md에 직접 넣지 마세요
- 환경 변수 사용 —
$API_KEY형태로 참조 - 최소 권한 — 필요한 API 범위만 허용
- 정기 교체 — 키를 주기적으로 변경
패턴 1: 환경 변수 참조
가장 기본적인 방법:
## API 호출
다음 환경 변수에서 자격 증명을 읽어요:
- WEATHER_API_KEY: 날씨 데이터 API 키
curl 명령 시 헤더로 전달:
```bash
curl -H "Authorization: Bearer $WEATHER_API_KEY" \
https://api.weather.com/forecast
중요: URL 쿼리 파라미터(`?key=...`)가 아니라 **헤더**(`-H "Authorization: ..."`)로 전달하세요. URL의 키는 로그에 노출돼요.
## 패턴 2: 스크립트 기반 API 호출
더 안전한 방법은 scripts/ 디렉토리에 API 호출 스크립트를 두는 거예요:
```python
# scripts/fetch_weather.py
import os
import requests
api_key = os.environ.get("WEATHER_API_KEY")
if not api_key:
print("ERROR: WEATHER_API_KEY 환경 변수가 설정되지 않았습니다.")
exit(1)
response = requests.get(
"https://api.weather.com/forecast",
headers={"Authorization": f"Bearer {api_key}"}
)
if response.status_code == 200:
print(response.json())
else:
print(f"ERROR: API 호출 실패 (status: {response.status_code})")
SKILL.md에서: !python3 scripts/fetch_weather.py로 호출해요.
패턴 3: MCP 서버 활용
가장 깔끔한 방법. MCP 서버가 API 연결을 담당하고, 스킬은 MCP 도구를 호출해요:
## 도구 사용
날씨 정보가 필요하면 `weather_forecast` MCP 도구를 사용하세요.
자격 증명은 MCP 서버가 관리합니다 — 스킬에서 직접 처리하지 마세요.
MCP 서버가 자격 증명을 캡슐화하기 때문에, 스킬 파일에 키가 노출될 위험이 제로예요.
인증 방식 비교
| 방식 | 만료 | 보안 수준 | 적합한 경우 |
|---|---|---|---|
| API 키 | 수동 교체 전까지 영구 | 중간 | 내부 도구, 저위험 API |
| OAuth 2.0 | ~60분 | 높음 | 사용자 데이터 접근, 공개 스킬 |
| MCP 서버 | MCP가 관리 | 가장 높음 | 프로덕션, 팀 스킬 |
✅ Quick Check: curl URL에 API 키를 넣는 것(
?key=...)과 헤더로 전달하는 것(-H "Authorization: ...")의 보안 차이는 뭘까요?
에러 핸들링
API 호출이 실패할 때를 대비해야 해요:
## 에러 처리
API 호출이 실패하면:
1. 사용자에게 실패 사실과 이유를 알려주세요
2. API 키가 유효한지 확인하라고 안내하세요
3. 절대 에러 메시지에 자격 증명을 포함하지 마세요
4. 가능하면 대안 행동을 제안하세요
절대 하지 말 것: 에러 로그에 API 키나 토큰을 출력하는 것. 디버깅 중에도 자격 증명은 감춰야 해요.
핵심 정리
- ClawHub 스킬 7.1%가 자격 증명을 노출 — 남의 일이 아니에요
- API 키는 환경 변수에, 절대 SKILL.md에 하드코딩하지 않기
- URL 쿼리가 아닌 헤더로 인증 정보 전달
- OAuth는 토큰 만료로 피해 범위 제한, MCP는 자격 증명을 완전히 캡슐화
- 에러 메시지에 자격 증명 절대 포함하지 않기
Up Next: 다음 레슨에서 스킬의 품질과 보안을 검증하는 테스트 방법을 배워요.
이해도 체크
먼저 위의 퀴즈를 완료하세요
레슨 완료!