pencil.dev 클로드코드 연동 API Key 에러, 이렇게 해결했습니다

TLDR

• pencil.dev에서 "Invalid API key · Fix external API key" 에러가 뜨면, ~/.zshrc뿐 아니라 ~/.claude/settings.json의 API 키도 함께 업데이트해야 합니다
• 에러 메시지가 "limit reached"에서 "Invalid API key"로 바뀌었다면, 첫 번째 문제는 해결된 것입니다 — 이것이 전문가가 에러를 읽는 방식입니다
• 이 글에서는 실제 해결 과정과 함께, 전문가의 문제 해결 사고법(RPD 모델)과 컴파운딩 엔지니어링까지 다룹니다

1. 무슨 일이 있었나

상황

Retention Inc.에서는 클로드 코드(Claude Code)와 pencil.dev를 함께 사용하고 있습니다. 2월 8일, pencil.dev 맥 앱에서 갑자기 에러가 발생했습니다.

처음 뜬 에러는 API 사용량 한도 초과였습니다. 원인을 추적해보니, Anthropic Console에서 월 $100로 설정해둔 spending limit을 OpenClaw에 연결해둔 API 키가 2월 8일에 소진해버린 것이었습니다.

참고로, Anthropic Console의 MANAGE → Limits 메뉴에서 Monthly limit을 설정할 수 있습니다. 아래처럼 월 사용량과 한도를 한눈에 확인할 수 있고, "Change Limit" 버튼으로 즉시 조정이 가능합니다.

첫 번째 오해

처음에는 "Anthropic이 클로드 코드 외에서 API 키를 쓰는 걸 막으려는 건가?"라고 오해했습니다. 최근 AI 기업들이 API 사용 정책을 자주 변경하다 보니, 정책 변경으로 착각하기 쉬운 상황이었습니다.

하지만 실제 원인은 단순했습니다. OpenClaw가 2월 예산을 전부 써버린 것이었습니다.

에러 메시지의 변화

spending limit 문제를 해결한 뒤(한도 상향 + 새 API 키 발급), pencil.dev를 다시 열었더니 이번에는 다른 에러가 떴습니다:

Invalid API key · Fix external API key

에러 메시지가 바뀌었습니다. 이 변화가 중요한 진단 단서였습니다.

2. 클로드 코드에서 해결하는 3단계

Step 1: 새 API 키 유효성 확인

가장 먼저, 새로 발급받은 API 키가 실제로 작동하는지 테스트했습니다.

curl -s -o /dev/null -w "%{http_code}" \
  https://api.anthropic.com/v1/messages \
  -H "x-api-key: sk-ant-api03-새키..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5-20250929","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

결과: 200 OK. 키 자체는 유효합니다.

Step 2: ~/.zshrc 업데이트

대부분의 가이드가 안내하는 방법입니다. 쉘 설정 파일에서 API 키를 교체합니다.

# ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-api03-새키..."

교체 후 터미널을 새로 열고, pencil.dev도 재시작했습니다.

결과: 여전히 "Invalid API key" 에러 발생.

Step 3: ~/.claude/settings.json 업데이트 (핵심!)

pencil.dev는 ~/.zshrc의 환경변수가 아니라, ~/.claude/settings.json의 env 필드에서 API 키를 읽고 있었습니다.

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-옛날키...",
    ...
  }
}

이 파일에서 옛날 키를 새 키로 교체하니 즉시 해결되었습니다.

정리: API 키가 저장되는 2곳

두 곳 모두 업데이트해야 합니다. 하나만 바꾸면 일부 도구에서만 작동합니다.

💡 이 단계가 복잡하게 느껴지시나요? 30분 무료 상담에서 AI 도구 설정을 함께 점검해 드립니다.

3. pencil.dev 공식 문서가 빈약한 이유

pencil.dev 공식 트러블슈팅 문서에는 이 에러에 대해 이렇게 안내합니다:

딱 한 줄입니다. ~/.claude/settings.json에 대한 언급은 없습니다. "Clear env vars"가 구체적으로 어떤 파일의 어떤 값을 의미하는지도 설명하지 않습니다.

그런데 왜 .zshrc와 settings.json 두 곳에 같은 API 키가 존재하게 된 걸까요?

두 곳에 키가 존재하는 이유

클로드 코드는 ~/.claude/settings.json의 env 필드에서 환경변수를 읽습니다. MCP 서버, pencil.dev 같은 클로드 코드 생태계 도구들은 이 파일을 참조합니다.

반면, 터미널에서 직접 실행하는 Python 스크립트, Node.js 앱, 기타 CLI 도구들은 ~/.zshrc(또는 ~/.bashrc)의 환경변수를 읽습니다.

하나의 API 키를 여러 도구에서 사용하려면, 두 곳 모두에 설정해야 합니다. 이것은 잘못된 설정이 아니라, 클로드 코드 생태계와 일반 터미널 환경이 설정을 읽는 경로가 다르기 때문입니다. Claude Code 공식 문서에서도 환경변수 관리 방법을 안내하지만, 이 "이중 저장" 구조에 대한 명확한 설명은 부족합니다.

문제는 키를 갱신할 때 발생합니다. 한 쪽만 업데이트하고 다른 쪽을 잊으면, 정확히 이번 사례처럼 일부 도구만 작동하고 나머지는 에러가 나는 상황이 됩니다.

4. 에러 메시지가 바뀌면 오히려 좋은 신호다

이 해결 과정에서 가장 중요한 순간은 에러 메시지가 바뀐 시점이었습니다.

"limit reached" → "Invalid API key"

초보자는 이 변화를 보고 "또 다른 문제가 생겼다"고 좌절합니다. 하지만 전문가는 다르게 읽습니다: "첫 번째 문제는 해결됐다. 이제 두 번째 문제가 드러났다."

이것이 바로 Gary Klein의 RPD(Recognition-Primed Decision) 모델이 설명하는 전문가의 의사결정 방식입니다.

RPD 모델이란

RPD 모델은 소방관, 군사 지휘관, 응급실 의사 같은 전문가들이 복잡한 상황에서 빠르게 의사결정하는 방식을 연구한 모델입니다. Gary Klein이 1980년대 후반에 발견했습니다.

핵심은 이렇습니다: 전문가는 선택지를 비교하지 않습니다. 대신 패턴을 인식하고, 과거 경험에서 유사한 상황을 떠올리며, 즉시 행동 계획을 세웁니다.

RPD에는 3가지 변형(variation)이 있습니다:

에러 메시지 변화를 RPD로 읽기

이번 사례에서 RPD가 어떻게 작동했는지 봅시다:

Phase 1 — 패턴 인식: "에러 메시지가 바뀌었다" → 전문가의 뇌에서 즉시 패턴 매칭이 발생합니다. "에러가 바뀌었다 = 이전 상태와 다른 상태다 = 무언가가 변했다 = 이전 문제는 해결되었을 가능성이 높다."

Phase 2 — 멘탈 시뮬레이션: "Invalid API key라면... 키가 틀렸다는 뜻이다 → .zshrc는 이미 바꿨다 → 다른 곳에서 키를 읽고 있을 가능성이 있다 → settings.json, .env, 시스템 환경변수를 확인해야 한다."

Phase 3 — 즉시 실행: curl로 키 유효성 테스트 → 환경변수와 설정 파일 전수 조사 → settings.json에서 옛날 키 발견 → 교체 → 해결.

초보자가 "왜 안 되지?"를 반복하는 동안, 전문가는 에러 메시지의 변화 자체를 진단 도구로 활용합니다.

5. 메타러닝과 컴파운딩 엔지니어링

이 경험이 다음 문제를 더 쉽게 만드는 이유

이번 문제를 해결하면서 학습한 것:

1. API 키는 여러 곳에 저장될 수 있다 (.zshrc, settings.json, .env 등)
2. 에러 메시지 변화는 진단 정보다
3. 환경변수보다 설정 파일이 우선할 수 있다

이 학습은 pencil.dev에만 국한되지 않습니다. 다음에 Braze MCP 서버, Amplitude 연동, 또는 다른 AI 도구에서 비슷한 에러가 발생하면, 이번 경험이 즉시 패턴 매칭 됩니다.

이것이 메타러닝(Meta-Learning) 입니다. 개별 문제의 해결법을 배우는 것이 아니라, 문제를 해결하는 방법 자체를 학습하는 것입니다.

컴파운딩 엔지니어링

컴파운딩 엔지니어링(Compounding Engineering)은 이 원리를 시스템 차원에서 적용한 개념입니다. 일반적인 개발에서는 기능이 추가될수록 복잡도가 증가합니다. 하지만 컴파운딩 엔지니어링에서는 매 작업이 다음 작업을 더 쉽게 만듭니다.

핵심 루프는 이렇습니다:

작업 수행 → 문제 발견 → 해결 → 학습 기록 → 다음 작업에 적용

이번 경험을 예로 들면:

복리처럼 학습이 쌓입니다. 각 문제 해결이 다음 문제 해결 시간을 줄여줍니다. 10번째 문제를 해결할 때쯤이면, 1번째 문제를 해결할 때의 1/10 시간이면 충분합니다.

AI 도구 시대의 디버깅 역량

AI 도구가 점점 많아지면서, 도구 간 설정 충돌은 더 흔해질 것입니다. pencil.dev, 클로드 코드, 각종 MCP 서버, 외부 서비스들이 같은 API 키를 서로 다른 위치에서 읽습니다.

이때 필요한 역량은 코딩 실력이 아닙니다. "어디서 무엇을 읽고 있는가"를 추적하는 시스템적 사고입니다. 그리고 이 사고력은 경험이 쌓일수록 — 컴파운딩 엔지니어링의 복리 효과로 — 기하급수적으로 향상됩니다.

자주 묻는 질문 (FAQ)

Q. pencil.dev에서 "Invalid API key · Fix external API key" 에러가 나면 어떻게 해야 하나요?

~/.claude/settings.json 파일의 env.ANTHROPIC_API_KEY 값을 확인하세요. 대부분 이 파일에 만료되거나 폐기된 API 키가 남아있는 것이 원인입니다. ~/.zshrc와 settings.json 두 곳 모두 새 키로 업데이트해야 합니다.

Q. .zshrc를 바꿨는데 왜 pencil.dev에 반영이 안 되나요?

pencil.dev는 쉘 환경변수(~/.zshrc)가 아닌 ~/.claude/settings.json에서 API 키를 읽습니다. 이 두 파일은 독립적이므로 각각 업데이트해야 합니다. 터미널에서 실행하는 Python 스크립트 등은 .zshrc를 읽지만, 클로드 코드 생태계(pencil.dev, MCP 서버 등)는 settings.json을 읽습니다.

Q. API 키를 여러 서비스에 공유해서 쓰는 건 안전한가요?

가능하지만 권장하지 않습니다. 이번 사례처럼 한 서비스(OpenClaw)가 한도를 전부 소진하면 다른 모든 서비스(pencil.dev 포함)가 영향을 받습니다. 서비스별로 API 키를 분리하고, Anthropic Console에서 각 키에 별도 spending limit을 설정하는 것이 안전합니다.

Q. RPD 모델을 일상 디버깅에 어떻게 적용하나요?

에러가 발생하면 "이전에 비슷한 패턴을 본 적 있는가?"를 먼저 떠올리세요. 에러 메시지가 바뀌면 "이전 문제는 해결되었고 새로운 문제가 드러난 것"으로 읽으세요. 이 습관만으로도 디버깅 속도가 크게 향상됩니다.

Q. 컴파운딩 엔지니어링을 개인 차원에서 실천하려면?

문제를 해결할 때마다 30초만 투자해서 "무엇을 배웠는가"를 기록하세요. 노트앱이든, CLAUDE.md 파일이든 형식은 상관없습니다. 핵심은 다음에 같은 유형의 문제를 만났을 때 즉시 떠올릴 수 있도록 기록하는 것입니다.

다음 단계

직접 해결하기

1. ~/.claude/settings.json의 ANTHROPIC_API_KEY 값 확인
2. ~/.zshrc의 ANTHROPIC_API_KEY 값 확인
3. 두 곳 모두 현재 유효한 키로 업데이트
4. pencil.dev 완전 종료 후 재시작

전문가와 함께하기

AI 도구 스택 설정이나 마케팅 자동화 구축이 필요하다면:

📅 30분 무료 상담 예약

• AI 도구 간 설정 충돌 진단
• 마케팅 자동화 아키텍처 설계
• 데이터 기반 그로스 전략 수립

Retention Inc. — 데이터 기반 스타트업 그로스 컨설팅