Cloudflare Workers AI의 BYOK 설정 경험기 (Typesafe의 Jev 사용 예시)

Cloudflare를 통해 타사의 AI 모델을 사용할 때, 비용 지불 방식은 두 가지가 있습니다.

• Cloudflare 크레딧을 구매하여 결제하는 방식 (Unified Billing)
• 직접 계약한 AI 제공업체의 API 키를 Cloudflare에 맡기는 방식 (BYOK)

개인 개발 과정에서 TypeSafe 사의 모델 "Jev"(typesafe/jev)를 Cloudflare를 통해 사용하게 되었고, BYOK 설정을 진행했습니다. 본문에서는 이 과정을 조사하며 알게 된 내용을 정리합니다.

• BYOK란 무엇인가
• 크레딧 결제 방식과의 차이점 및 BYOK의 장단점
• 설정 절차 (Cloudflare 측 API 토큰도 필요하다는 점이 핵심) - 시작 지점

본 정보는 2026년 10월 기준 Cloudflare 공식 문서를 기반으로 합니다. 요금이나 화면 이름은 변경될 수 있으므로, 최신 정보는 반드시 공식 문서를 확인해 주십시오.

BYOK는 **Bring Your Own Key (자체 키 보유)**의 약어입니다.

AI 분야에서 BYOK란 "OpenAI나 Anthropic 같은 AI 제공업체와 직접 계약하여 발급받은 API 키를, 중개 서비스(여기서는 Cloudflare)에 맡겨 사용하는 것"을 의미합니다.

【크레딧 결제 (Unified Billing)】
앱 ──▶ Cloudflare ──▶ AI 제공업체
│ Cloudflare가 계약한 키로 호출
...

어떤 경우든, 앱에서 바라보는 호출 방식은 동일합니다. 다른 점은 "누구의 키로 호출하며, 누구에게 비용을 지불하는지" 뿐입니다.

'BYOK'라는 또 다른 의미도 있습니다.

클라우드 보안 분야에서 BYOK는 "데이터를 암호화하는 키를 이용자가 직접 준비하고 관리하는 것"을 의미합니다 (예: Google Cloud의 CMEK, AWS KMS의 키 가져오기 등). 본문에서 다루는 것은 AI API 키에 대한 BYOK입니다.

BYOK 이야기를 시작하기 전에, 'AI 제공업체를 직접 호출하지 않고 Cloudflare를 경유시키는' 자체의 가치를 먼저 정리해 보겠습니다. BYOK든 크레딧 결제 방식이든, 이 부분은 공통적입니다.

【직접 호출】
앱 ──[OpenAI 키]────▶ OpenAI
──[Anthropic 키]─▶ Anthropic
...

• 호출 방식 통일: 어떤 제공업체의 모델이든 Cloudflare의 동일한 API(/ai/run 또는 OpenAI 호환 /ai/v1/chat/completions 등)를 통해, model 지정만 변경하면 호출할 수 있습니다. 제공업체별 SDK를 넣을 필요가 없어 모델을 교체할 때 코드 수정이 적게 듭니다.
• 로그・캐시・사용량 관리 일원화: AI Gateway의 로그, 캐시, 속도 제한 등이 어떤 제공업체에도 동일하게 적용됩니다.
• "어떤 모델에 얼마를 사용했는지"도 Cloudflare 대시보드에서 한 번에 볼 수 있습니다.

여기에 더해, BYOK 방식을 사용하면 다음 이점이 추가됩니다.

• 앱이 가진 비밀 정보는 Cloudflare의 토큰 하나만: 제공업체의 키는 Cloudflare의 Secrets Store에 암호화되어 보관되므로, 앱의 환경 변수나 소스 코드에 넣을 필요가 없습니다.
• 키를 교체할 때도 Cloudflare 대시보드에서 교체하기만 하면 됩니다. 앱 재배포(re-deploy)는 필요하지 않습니다.

실제로 개인 개발 과정에서 사용해 보니, Cloudflare의 API 호출 방법만 알면 Claude Code가 막힘없이 구현까지 진행될 수 있었습니다. 원래는 서비스마다 호출 방식이 다르지만, Cloudflare가 '진입점과 인증을 통일하는 어댑터' 역할을 해주고 있었기 때문이라고 생각합니다.

입력과 출력의 형태까지 통일되지는 않기 때문에, 이 부분은 각 모델의 문서를 참고해야 합니다.

즉, 가치 대부분은 'Cloudflare를 경유시키는 것'에 있으며, BYOK는 그 위에 추가되는 '돈과 계약 방식', 그리고 '키(Key)를 어디에 둘지'의 선택지입니다.

Cloudflare 공식 문서를 기준으로 비교하면 다음과 같습니다.

• 5% 수수료가 없음 - 이용액이 커질수록 차이가 납니다.

• AI 프로바이더와 직접적인 관계를 유지할 수 있음 - 이용 한도(Rate Limit/Quota)나 데이터 처리 규약이 자신의 계약과 동일하게 적용됩니다.

• 이미 프로바이더와 계약하고 있다면, 그 계약을 그대로 활용할 수 있습니다.

• 키 교체가 한 곳에서 끝남 - 키는 Cloudflare의 Secrets Store에 암호화되어 저장됩니다.

• 키를 교체할 때는 Cloudflare 대시보드에서 대체하기만 하면 됩니다. 앱 코드를 수정하거나 중단할 필요가 없습니다.

• Cloudflare 기능은 그대로 사용 가능 - AI Gateway의 로그, 캐시, 속도 제한 등은 BYOK에서도 사용할 수 있습니다.

• AI 프로바이더와 개별 계약이 필요함 - 사용하는 프로바이더가 늘어날수록 계약, 청구, 키 관리가 증가합니다.

• 청구가 분산됨 - 크레딧 결제는 Cloudflare의 단일 청구서로 통합되지만, BYOK에서는 프로바이더별로 도착합니다.

• 키를 찾지 못하면, 조용히 크레딧 결제로 전환될 수 있음 - 이후에 '함정'에서 자세히 설명하겠습니다.

| 이런 경우 | 추천 | |
|---|---|
| 일단 시도해 보고 싶다 / 이용액이 적을 때 | 크레딧 결제 (계약 불필요, 바로 시작 가능) |
| ... |
제가 경우에는, 크레딧을 선불로 관리하는 것보다 사용한 만큼 TypeSafe와 직접 거래하는 것이 더 편리해서 BYOK를 선택했습니다.

'장점이 있는지'에 대한 결론은 '수수료 5%와 계약/결제 편의성이 신경 쓰인다면 BYOK, 간편함을 원한다면 크레딧 결제'입니다. 기능적인 차이는 거의 없습니다.

솔직히 말해서, BYOK만의 장점은 돈과 계약 관련이 중심입니다. 다만, 이전 장에서 설명했듯이, Cloudflare를 경유시켜 API를 통합하는 것에는 큰 가치가 있습니다. BYOK는 '그 구조를 자신의 프로바이더 계약 그대로 사용하는 방법'이라고 생각하면 이해하기 쉽습니다.

크게 3단계로 나뉩니다.

• AI 프로바이더의 API 키 발급
• Cloudflare에 AI 프로바이더의 키 보관
  Cloudflare의 API 토큰 발급

여기서 오해하기 쉬운 부분이 3번입니다. BYOK는 'AI 프로바이더의 키를 보관하는' 시스템이므로, 앱에서 Cloudflare를 호출하기 위한 Cloudflare 자체의 API 토큰도 별도로 필요합니다.

앱 ──[Cloudflare의 API 토큰]──▶ Cloudflare ──[보관된 AI 프로바이더의 키]──▶ AI 프로바이더

사용하고 싶은 AI 프로바이더(이번에는 TypeSafe)의 관리 화면에서 API 키를 발급합니다.

전제 조건으로 다음 두 가지가 필요합니다.

• AI Gateway가 인증됨(Authenticated) 상태여야 함
• Secrets Store에서 시크릿을 생성 및 배포할 권한이 있어야 함

Cloudflare 대시보드에서 다음과 같이 조작합니다.

• AI → AI Gateway를 열기 - 사용할 게이트웨이를 선택합니다(없으면 생성).

• Provider Keys → Add API Key - 프로바이더를 선택하고 1에서 발급한 키를 붙여넣어 저장합니다.

• TypeSafe의 경우, 목록에 TypeSafe AI가 나타납니다.

• TypeSafe의 경우, 목록에

• Configured 목록에 프로바이더가 표시되면 완료입니다 (키는 끝 몇 자리를 제외하고 가려져서 표시됩니다).

키 이름(별칭)은 default로 유지합니다.

/ai/run와 같이 Cloudflare의 REST API나 Workers의 env.AI.run()에서 호출하는 경우, 참조되는 것은 default라는 이름으로 저장된 키뿐입니다. 다른 이름으로 저장하면 BYOK으로 사용되지 않습니다. - Cloudflare 대시보드에서,
계정 API 토큰(또는 오른쪽 상단 프로필의 API 토큰)을 엽니다. - 토큰 생성 → 커스텀 토큰을 만듭니다. - 권한에 Account → Workers AI → Read를 부여합니다. - 생성하고 표시된 토큰을 기록해둡니다 (한 번만 표시됩니다).

/accounts/{account_id}/ai/* API는 호출하는 것이 Cloudflare의 모델이든 타사 모델이든, Workers AI 권한이 필요합니다. AI Gateway 권한만으로는 호출할 수 없습니다.

나머지는 Cloudflare의 API를 호출하기만 하면 됩니다. 요청에 AI 프로바이더 키는 포함하지 않습니다. Cloudflare가 보관하고 있는 키를 사용해 줍니다.

curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-H "Content-Type: application/json" \
...

input의 내용은 모델에 따라 다르므로, Cloudflare의 모델 카탈로그에서 각 모델 페이지를 확인하세요.

가장 주의해야 할 점입니다. Cloudflare는 요청을 받으면 다음 순서로 키를 찾습니다.

• 요청에 AI 프로바이더 키가 붙어 있으면 그것을 사용합니다.
• 아니면, Gateway에 default라는 이름으로 맡겨둔 키를 사용합니다 (BYOK). - 이것도 없으면,
  Cloudflare의 크레딧으로 지불합니다(Unified Billing).

즉, 키 이름을 잘못 지정하거나 키를 삭제하면 오류가 나지 않고 크레딧 결제로 동작해 버립니다. 크레딧 잔액이 있으면 모르는 사이에 수수료가 포함되어 청구될 수 있습니다.

이를 방지하려면, Gateway의 Settings에서 Require provider credentials를 켭니다. 켜면 타사 모델에 대한 요청에서 키를 찾을 수 없을 때 크레딧 결제로 전환되지 않고 HTTP 400 에러가 발생합니다. BYOK으로 운영할 계획이라면, 켜두는 것이 권장됩니다.

Cloudflare의 API 토큰을 환경 변수나 설정 화면에 붙여넣을 때, 끝에 줄 바꿈이나 공백이 끼어 들어갈 수 있습니다. 이 상태로 호출하면 Cloudflare는 **'Authentication error'**를 반환합니다. 토큰 자체는 올바르므로 원인을 파악하기 어렵습니다.

코드 측에서 읽어온 값의 앞뒤 공백을 제거해 두면 안전합니다.

const token = (process.env.CLOUDFLARE_API_TOKEN ?? "").trim();

API 토큰이 유효한지 여부는 다음 API로 확인할 수 있습니다(추론은 수행하지 않으므로 요금이 발생하지 않습니다). 다만, 토큰을 어디서 만들었는지에 따라 확인하는 곳이 다릅니다.

curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/tokens/verify \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

다른 곳에서 확인하면 '무효'로 응답이 오기 때문에, 토큰이 손상되었다고 착각하기 쉽습니다.

AI Gateway의 로그를 활성화해 놓으면, 모델에 전송한 본문이나 반환된 결과가 Cloudflare에 저장됩니다. 외부에 공개되지 않는 정보나 개인정보를 보낼 경우에는, 로그를 끄거나 메타데이터만 남기는 설정으로 해두는 것이 좋습니다.

• Cloudflare를 경유할 경우,
  어떤 프로바이더의 모델이든 같은 API로 호출할 수 있고, 로그와 캐시도 한 곳에 모입니다. 가치의 대부분은 여기에 있습니다. - BYOK(Bring Your Own Key)은 '자신의 AI 프로바이더의 API 키를 Cloudflare에 맡기는' 방식입니다. 차이점은 누구의 키로 호출하고 누구에게 지불하는가입니다. 앱에 프로바이더의 키를 보관할 필요가 없다는 것도 장점입니다. - 크레딧 결제는 구매액에 5%의 수수료가 부과됩니다. BYOK은 그렇지 않습니다. - 기능적인 차이는 거의 없으며, 수수료・계약・결제의 편의성으로 선택하면 됩니다. - 설정에는 AI 프로바이더의 키 외에도 **Cloudflare의 API 토큰 (Workers AI의 읽기 권한)**이 필요합니다. - 키를 찾을 수 없을 경우 조용히 크레딧 결제로 처리되므로, Require provider credentials를 켜두는 것이 좋습니다.

• BYOK (Store Keys) · Cloudflare AI Gateway docs

• Unified Billing · Cloudflare AI Gateway docs

• REST API · Cloudflare AI Gateway docs

• AI Gateway의 요금

• Create API token (사용자 토큰 확인 방법) · Cloudflare docs

• Verify Token (계정 토큰) · Cloudflare API

• Account API tokens · Cloudflare docs

• Jev (typesafe) · Cloudflare AI docs

• Customer-managed encryption keys (CMEK) · Google Cloud