freebuff 무료 모델을 OpenAI 호환 API로 쓸 수 있게 해주는 Cloudflare Worker입니다. 파일 하나, 의존성 없이 동작하며 Cloudflare 콘솔에 붙여넣거나 wrangler CLI로 바로 배포할 수 있습니다.
- 두 개 모델은 한도 없이 동작 —
deepseek-v4-flash,mimo-v2.5는 실측에서 별도 한도 없이 동작했습니다. - 나머지 모델도 정상 호출 —
meta/muse-spark-1.2-contributor는minimal~xhigh까지 공식reasoning_effort를 지원합니다. 현재 배포 환경(미국 리전 고정)에서는high,xhigh등으로 실제 호출이 성공했습니다. - 미국 리전 고정 배포 —
wrangler.toml의[placement] region = "aws:us-west-1"로 Worker 실행 위치를 미국 서부 근처로 고정했습니다. freebuff 무료 모델이 미국 출구 IP를 요구하기 때문입니다. - 여러 계정 자동 전환 —
FREEBUFF_TOKEN에 토큰을 쉼표로 이어 붙이면, 한도가 걸리거나 세션이 실패했을 때 자동으로 다음 계정으로 넘어갑니다. - 무제한 계정이 한도 계정보다 먼저 선택됨 —
muse-spark처럼 어떤 계정은 한도가 있고 어떤 계정은 한도가 없는 모델이 있습니다. 한 계정이 6회 한도에 걸리면 다음 요청부터는 한도가 없는 계정이 먼저 선택됩니다 (45분 동안 기억, 태평양일 기준으로 리셋). - 중복 토큰 자동 정리 — 같은 토큰을 두 번 넣어도 하나의 계정으로만 처리됩니다.
- 살아 있는 세션 재사용 우선 — 세션은 보통 1시간 정도 유지되며 만들 때만 한도가 차감됩니다. 아직 유효한 세션이 있으면 같은 계정을 계속 쓰고, 없을 때만 다른 계정으로 옮겨 한도를 아납니다.
- 광고 요청 흐름 모방 — 새 세션을 만들기 전에 공식 클라이언트처럼 광고 노출 요청을 한 번 보냅니다. 실패해도 채팅에는 영향이 없습니다.
- OpenAI 호환 —
GET /v1/models,POST /v1/chat/completions을 스트리밍과 일반 응답 모두 지원합니다. - 헬스 체크 —
GET /healthz는 인증 없이 호출할 수 있습니다. - 단일 파일 — 별도 설치 없이 바로 배포할 수 있습니다.
- 전체 한국어 — 코드 주석, CLI 출력, 텔레그램 알림까지 모두 한국어입니다.
한도는 모델·계정별로 다르며, 서버가 수시로 갱신합니다. 아래는 실측 기준 rateLimitsByModel에서 확인한 값입니다.
| 모델 | 한도 |
|---|---|
deepseek/deepseek-v4-flash |
한도 항목 없음 (실측 무제한으로 동작) |
mimo/mimo-v2.5 |
한도 항목 없음 |
meta/muse-spark-1.2-contributor |
계정마다 다름 — 어떤 계정은 6회/일, 어떤 계정은 제한 없음 |
z-ai/glm-5.2 |
레퍼럴 없이는 한도 0 (세션 생성 429) |
한도는 태평양 시간 기준 하루 단위이며, 한국 시간으로는 보통 오후 4시쯤 리셋됩니다. 세션을 새로 만들 때만 차감됩니다.
| API 모델 이름 | 세션 모델 | upstream agentId |
|---|---|---|
deepseek/deepseek-v4-flash |
동일 | base2-free-deepseek-flash |
deepseek/deepseek-v4-pro |
동일 | base2-free-deepseek |
minimax/minimax-m3 |
동일 | base2-free-minimax-m3 |
mimo/mimo-v2.5 |
동일 | base2-free-mimo |
openai/gpt-5.6-luna |
동일 | base2-free-luna |
z-ai/glm-5.2 |
동일 | base2-free-glm |
poolside/laguna-s-2.1 |
동일 | base2-free-laguna-s-2-1 |
openrouter/poolside/laguna-s-2.1 |
동일 | base2-free-laguna-s-2-1-openrouter |
inclusionai/ling-3.0-flash:free |
동일 | base2-free-ling-3-flash |
crof/greg-2-ultra |
동일 | base2-free-greg-2-ultra |
crof/greg-2-super |
동일 | base2-free-greg-2-super |
anthropic/claude-fable-5 |
동일 | base2-free-fable |
meta/muse-spark-1.2-contributor |
동일 | base2-free-muse-spark |
none은 지원하지 않습니다 (400 오류)minimal,low,medium,high,xhigh만 공식에서 지원합니다max,extreme,ultra는 공식에 없고 무시될 수 있습니다
참고: https://dev.meta.ai/docs/reasoning
- freebuff 토큰을 발급합니다 (아래 `FREEBUFF_TOKEN 발급` 참고)
- Worker를 배포합니다 (아래 `배포` 참고. 콘솔에 붙여넣거나 wrangler로 배포)
- Cloudflare 대시보드에서 변수를 설정합니다
FREEBUFF_TOKEN(필수)FREEBUFF_API_KEY(선택, 비워두면freebuff-default-key)
- OpenAI 호환 클라이언트에서 아래처럼 연결합니다
- Base URL:
https://<워커 주소>/v1 - API Key:
FREEBUFF_API_KEY에 넣은 값
- Base URL:
curl https://<워커 주소>/healthz
# {"status":"ok","version":"1.6.0","time":"..."}인증 없이 호출할 수 있어 모니터링용으로 쓰기 좋습니다.
freebuff_tools/extract_freebuff.py를 씁니다. 파이썬 표준 라이브러리만 있으면 됩니다.
cd freebuff_tools
python3 extract_freebuff.py login # 인증 주소가 나오면 브라우저에서 열고 구글 로그인, 이후 자동으로 토큰 저장
python3 extract_freebuff.py show # 저장된 토큰 확인 (마스킹되어 표시)
python3 extract_freebuff.py tgsend # 텔레그램 연결 테스트 (선택)토큰은 freebuff_tools/freebuff_credentials.json에 저장됩니다. 이 파일은 깃에 올리지 마세요.
이 저장소에는 이미 워크플로가 포함되어 있습니다 (.github/workflows/extract-token.yml).
필요한 준비물
- 텔레그램에서 @BotFather에게
/newbot을 보내 봇을 만든 뒤 HTTP API 토큰을 받습니다 - @freebuff_token_bot(방금 만든 봇)을 열고
/start를 보낸 뒤, 터미널에서curl "https://api.telegram.org/bot<토큰>/getUpdates"로chat.id를 확인합니다 - 저장소의
Settings → Secrets and variables → Actions에서 두 secret을 넣습니다TG_BOT_TOKEN: 봇 토큰TG_CHAT_ID: 숫자 chat id
실행
Actions → Freebuff authToken 발급 → Run workflow → Run을 누르면 GitHub의 미국 러너에서 인증 절차가 시작됩니다.
텔레그램 봇 채팅으로 인증 링크가 오면, 꼭 새 구글 계정으로 로그인하세요. 같은 구글 계정으로 다시 로그인하면 같은 토큰이 다시 발급될 수 있습니다. 인증이 끝나면 새 토큰이 텔레그램으로 옵니다.
- 텔레그램 봇 토큰을 채팅에 그대로 올리면 즉시 유출로 간주됩니다. 확인 뒤 @BotFather에서
/revoke로 재발급하세요. - 실제 토큰을 채팅에 붙여넣지 마세요.
- https://dash.cloudflare.com 에서 Workers & Pages로 이동한 뒤 Worker를 새로 만들고 배포합니다
- 해당 Worker에서 Edit code를 열고
worker.js전체를 붙여넣은 뒤 다시 배포합니다 - Settings, Variables and Secrets에서 Add를 눌러 아래 값을 넣습니다
FREEBUFF_TOKENFREEBUFF_API_KEY(선택)
- 배포가 잘 됐는지 확인합니다
curl https://<워커 주소>/healthz
curl https://<워커 주소>/v1/models -H "Authorization: Bearer <API_KEY>"npm i -g wrangler
npx wrangler login
cp .env.example .dev.vars # FREEBUFF_TOKEN 입력
npx wrangler dev # 로컬에서 테스트
npx wrangler deploy # 배포
npx wrangler secret put FREEBUFF_TOKEN
npx wrangler secret put FREEBUFF_API_KEYwrangler.toml에 아래 설정이 추가되어 있습니다.
[placement]
region = "aws:us-west-1"freebuff 무료 모델은 미국 출구 IP를 요구합니다. Cloudflare Workers는 기본적으로 미국 쪽으로 나가지만, 이 설정을 넣으면 실행 위치 자체를 미국 서부(N. California) 근처로 고정해 지연을 줄일 수 있습니다.
북미 6개 리전을 실제로 배포해가며 실측한 결과 (서울에서)
| 리전 | median healthz |
|---|---|
aws:us-west-2 (Oregon) |
0.308초 |
aws:us-west-1 (N. California) |
0.326초 — 편차 최소 |
gcp:us-west1 |
0.319초 |
gcp:us-central1 |
0.335초 |
gcp:us-east4 |
0.315초 |
aws:us-east-1 (Virginia 동부, 이전 기본값) |
0.382초 |
- 서부 리전이 동부 대비 50~75ms 빠릅니다
aws:us-west-1이 편차가 가장 작아 최종 고정했습니다mode = "smart"는 북미가 아닌 곳으로 튈 수 있어 쓰지 않았습니다- chat 스모크(
deepseek-v4-flash)는 6/6 리전 모두 성공했습니다
관련 문서: https://developers.cloudflare.com/workers/configuration/placement/
*.workers.dev 접속이 막힌 환경이라면 Worker에 본인 도메인을 연결한 뒤 Base URL을 https://api.내도메인/v1 형태로 바꾸면 됩니다.
curl https://<워커 주소>/v1/chat/completions \
-H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
-d '{"model":"deepseek/deepseek-v4-flash","messages":[{"role":"user","content":"안녕"}],"reasoning_effort":"high"}'
curl -N https://<워커 주소>/v1/chat/completions \
-H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
-d '{"model":"meta/muse-spark-1.2-contributor","messages":[{"role":"user","content":"증명해줘"}],"reasoning_effort":"xhigh","stream":true}'FREEBUFF_TOKEN에 token1,token2처럼 쉼표로 구분해 넣으면 됩니다. 한도가 걸리면 해당 토큰은 잠시 쿨다운되고 다음 토큰으로 넘어가며, 아직 유효한 세션이 있으면 같은 계정을 계속 씁니다.
중복으로 넣어도 무해합니다. 같은 토큰을 두 번 넣어도 내부에서 하나의 계정으로만 처리됩니다.
muse-spark는 계정마다 한도가 다릅니다 — 어떤 계정은 6회/일, 어떤 계정은 한도 항목 자체가 없습니다. 현재 풀은 3계정 모두 6회로 동일하지만, 이전에는 중복 토큰으로 한 계정이 두 번 보이며 실제로는 한도만 공유되는 상태가 생겼고, 또 6회 계정이 먼저 선택되어 바로 한도에 걸리면 무제한 계정은 나중에야 선택되는 문제가 있었습니다. 지금은 같은 토큰은 Set으로 중복을 제거하고, 한 계정이 429 한도 초과로 거부되면 그 모델에 대해 소진으로 기억해 두고 다음 요청부터는 소진되지 않은 계정을 먼저 선택합니다 (45분 유지).
처음 로컬에서 발급받은 토큰은 세션 조회에서 accessTier: limited였고, GitHub Actions 미국 러너에서 새로 발급받은 토큰은 full로 표시되었습니다. freebuff가 가입/로그인 시점의 출구 IP(리전)에 따라 등급을 매기는 것으로 보입니다. 한국 IP와 미국 IP에서 같은 절차로 받아도 tier가 달랐습니다.
추가로, 처음에는 muse-spark가 limited 계정에서 session_model_mismatch로 거부되었고, 같은 토큰을 미국 출구 Worker에 그대로 두면 정상 동작했습니다. 한국 로컬과 미국 Worker의 차이가 실제 호출에도 반영됩니다.
레퍼럴 코드 (FREEBUFF_TOKEN과 함께 오는 referral/streak 정보)는 현재 z-ai/glm-5.2의 한도를 여는 데 주로 관여합니다. 레퍼럴 없이는 limit 0으로 세션 생성 429가 납니다. muse-spark, deepseek, mimo의 한도는 레퍼럴로 크게 늘어나지 않습니다.
세션 생성 -> agent-runs (main + context-pruner) -> chat/completions
이 전체 과정을 Worker가 처리합니다. upstream에서 바이트 단위로 검증하는 You are Buffy, the strategic coding assistant. 접두사도 자동으로 붙입니다. /v1/models는 upstream을 조회하지 않고 목록을 그대로 돌려줍니다. 한 계정에서 동시에 세션을 하나만 쓸 수 있어, 조회가 진행 중인 대화를 방해할 수 있기 때문입니다.
중간에 끊기는 원인은 대부분 upstream codebuff.com의 free 채널 불안정(동시 1 초과 시 queued 타임아웃 — 최대 8회×1.5초 폴링, 428 waiting_room_required, 세션 만료 409 등)입니다.
이 코드는 요청 내부에서 풀의 모든 계정을 끝까지 순회하며 재시도합니다:
세션 만료 428/409는 sessCache를 비우고 강제 재생성해 1회 재시도하고, 그래도 실패하면 해당 계정을 쿨다운하고 다음 계정으로 교체합니다.
타임아웃·종료 등도 쿨다운 후 다음 계정으로 넘어갑니다. chainTail + 300ms로 직렬화해 동시 폭주도 방지합니다.
한도가 소진된 계정은 다음 요청부터 스킵되며, 모든 계정이 소진됐을 때만 다시 시도합니다. 한도가 동시에 임박하면 셋 다 끊길 수 있어 그때는 리셋(오후 4시)까지 기다려야 합니다.