외부 API 연결하기

외부 세계와 연결하기

🔄 Quick Recall: 이전 레슨에서 $ARGUMENTS와 셸 확장으로 스킬을 동적으로 만들었어요. 이번에는 외부 API를 연결해서 스킬의 능력을 확장해요.

스킬이 외부 서비스와 통신할 수 있으면 활용도가 폭발적으로 늘어나요. 하지만 API 연결은 보안 실수가 가장 많이 발생하는 영역이기도 해요.

이 레슨을 마치면 API를 안전하게 연결하고 자격 증명을 보호하는 스킬을 만들 수 있어요.

배울 내용

• ClawHub의 7.1% 자격 증명 유출 문제
• API 보안 4대 원칙
• 세 가지 API 연동 패턴
• 인증 방식 비교
• 에러 핸들링과 자격 증명 보호

7.1% 문제

Snyk의 조사에서 ClawHub 스킬 3,984개 중 283개(7.1%)가 API 키를 하드코딩하고 있었어요. 이건 단순한 실수가 아니라 심각한 보안 취약점이에요 — 누구나 공개 스킬에서 키를 추출해서 악용할 수 있어요.

API 보안 4대 원칙

1. 절대 하드코딩하지 않기 — 키를 SKILL.md에 직접 넣지 마세요
2. 환경 변수 사용 — $API_KEY 형태로 참조
3. 최소 권한 — 필요한 API 범위만 허용
4. 정기 교체 — 키를 주기적으로 변경

패턴 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 서버가 자격 증명을 캡슐화하기 때문에, 스킬 파일에 키가 노출될 위험이 제로예요.

인증 방식 비교

✅ 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: 다음 레슨에서 스킬의 품질과 보안을 검증하는 테스트 방법을 배워요.