모든 엔지니어에게 일일 제한이 걸린 Claude Code 키를 제공하는 방법

팀에서 Anthropic API 키를 사용하여 Claude Code를 실행할 경우, 어느 순간 두 가지 질문에 직면하게 됩니다. 지난주에 누가 얼마를 사용했는가? 그리고 새벽 2시에 루프(loop)에 빠진 에이전트가 남은 한 달 동안의 예산을 다 써버리는 것을 무엇이 막아주는가?

하나의 공유 키로는 정직한 답변이 "모른다"와 "아무것도 없다"입니다. 해결책은 지루하지만 효과적입니다. 각 엔지니어에게 개별 키를 제공하고, 각 엔지니어에게 엄격한 일일 한도(daily cap)를 설정하며, 요청이 Anthropic에 도달하기 전에 그 한도를 확인하는 것입니다. 본 가이드에서는 왜 이것이 작동하는지, 사용 가능한 옵션들, 그리고 우리가 구축하는 게이트웨이인 TokenRouter를 이용한 정확한 설정 방법을 다룹니다.

공유 키가 실패하는 이유

공유 키에는 세 가지 문제가 있습니다.

출처 추적 불가(No attribution). Anthropic의 사용량 콘솔은 키별 지출액을 보여줍니다. 모두가 같은 키를 사용하면, 하나의 숫자만 보게 됩니다. Anthropic 자체 Claude 앱 게이트웨이 문서는 명확하게 말합니다. "하나의 공유 상위 인증 정보로는, '귀사 제공업체의 청구서가 모든 것을 개별 개발자가 아닌 해당 인증 정보에 귀속시킵니다.'"

개인별 한도 설정 불가(No per-person limit). 공유 키에 대한 어떤 제한도 팀 전체에 대한 제한입니다. 하나의 통제 불능 세션이 모두의 예산을 소진할 수 있습니다.

퇴사 처리 시 키를 순환해야 함. (Offboarding means rotating the key for everyone.)

유용한 한도의 모습

한도는 네 가지 일을 할 때만 유용합니다.

차단(Block)하는 것, 단순히 보고(Report)만 하는 것이 아닙니다. 돈이 지출된 후에 도착하는 알림은 영수증일 뿐입니다.
회사 단위가 아닌 개인별로 적용되어야 합니다.
도구가 감지할 수 있는 방식으로 실패해야 합니다. 에이전트는 일반적인 답변처럼 보이는 것이 아니라 명확한 오류를 받아야 합니다. 현재 open Claude Code 이슈(anthropics/claude-code#98441)에서는 플랜 만료가 일반 어시스턴트 턴으로 도착하는 경우가 있어, 서브에이전트들이 이를 실제 답변과 구분할 수 없습니다.
호출 후가 아닌 호출 전에 확인되어야 합니다. Claude Code의 --max-budget-usd 플래그는 각 호출이 반환된 후에 확인되며, open 이슈(#100111)에서는 1달러 한도가 1.38달러에서 멈추는 것을 측정했습니다. 이는 단일 헤드리스(headless) 실행에는 괜찮지만, 하루 동안의 에이전트 트래픽을 위한 약한 경계입니다.

사용 가능한 옵션들

--max-budget-usd: 헤드리스(headless) 실행에 대한 횟수당 한도이며, 개인별 예산이 아닙니다.
Claude Team 또는 Enterprise 좌석: 좌석 사용자에게는 회원별 제한이 적용되지만, 스크립트나 CI에서 원시 API 키를 사용하는 경우에는 그렇지 않습니다.
Anthropic의 Claude 앱 게이트웨이: Claude 트래픽에 대해 사용자별, 그룹별, 조직별 지출 한도를 가진 자체 호스팅(self-hosted) 방식입니다.
가상 키 및 예산 기능을 갖춘 자체 호스팅 프록시: 오픈 소스 LiteLLM과 같은 솔루션이 있습니다.
개인별 예산을 갖춘 호스팅 게이트웨이: TokenRouter가 적합한 곳입니다.

TokenRouter를 사용한 설정

1. Anthropic 키 연결. 콘솔에서 Provider Keys → Provider Key 추가를 열고, Anthropic을 선택한 후 키를 붙여넣습니다. 프로바이더 키는 저장 시 AES 암호화되며, 요청 시 메모리에서만 복호화되고 로그에 절대 기록되지 않습니다. Anthropic은 사용자에게 직접 요금을 청구합니다. 저희는 고정 구독료를 부과하며 토큰당 비용을 받지 않습니다.

2. 팀 생성 및 엔지니어 초대. 구조는 조직(organization) → 팀(teams) → 멤버(members) → 키(keys) 순서입니다. Teams → Team 생성에서 팀을 만듭니다 (예: platform 또는 mobile). 그런 다음 Members → 회원 초대로 이동하여 엔지니어의 이메일을 입력하고, 역할은 Member로 유지하며, 해당 팀을 선택합니다. 좌석 수는 플랜에 따라 다릅니다. Free는 1개 좌석과 1개 팀을 제공하고, Starter는 5개 좌석, Team은 25개를 제공합니다.

3. 각 엔지니어에게 일일 하드캡(hard cap) 설정. Budgets → 예산 생성을 열고 다음을 설정합니다:

Scope (범위): Member를 선택한 후, 해당 엔지니어를 지정합니다.
Period (기간): Daily (일별)
Limit (USD) (제한 금액): 원하는 숫자 (아래

'일일(daily)' 초기화 시점은 언제인가요? 예산 기간은 UTC 일자 경계를 사용하므로, 일일 예산은 00:00 UTC에 재설정됩니다. 이는 서머타임 적용 시 미국 동부 시간으로 오후 8시, 겨울철에는 오후 7시입니다. 조직의 시간대 설정은 콘솔에 표시되는 시간을 변경할 뿐, 예산이 초기화되는 시점은 아닙니다.

4. 각 엔지니어가 자체 키를 생성합니다. 각 엔지니어는 로그인하여 API Keys → Key 생성을 열고 팀을 선택한 후 claude-code-alice와 같은 이름으로 지정합니다. 멤버가 생성한 키는 해당 멤버에게 자동으로 연결되므로, 그 멤버의 예산이 적용되고 분석 기능은 지출을 그 멤버에게 귀속시킵니다. 관리자가 콘솔에서 생성하는 키는 팀에 속하지만 특정 멤버에게는 속하지 않으므로, 팀 예산만 적용됩니다. 개인별 제한(per-person caps)을 위해서는 각 사람이 자체적으로 생성하도록 하세요.

5. 안전 장치로 속도 제한(rate limit)을 추가합니다. 동일한 대화 상자에는 **RPM 제한(RPM limit)**과 TPM 제한(TPM limit) 필드가 있으며, 일일 만료 옵션도 있습니다. 속도 제한을 초과하면 429 rate_limit_exceeded 오류와 함께 Retry-After 헤더가 반환됩니다. 예산은 하루 동안의 느린 소모를 포착합니다. TPM 제한은 몇 분 안에 발생하는 재시도 루프를 포착합니다.

6. 선택적으로 모델을 제한합니다. 각 팀은 모델 허용 목록(Model Access, 또는 팀 자체 페이지 아래)을 가질 수 있습니다. 이 목록에 없는 모델에 대한 요청은 403 model_not_allowed 오류와 함께 실패합니다.

7. Claude Code를 게이트웨이로 연결합니다. 각 엔지니어의 장치에서 다음 명령어를 실행합니다:

export ANTHROPIC_BASE_URL=https://api.tokenrouter.io
export ANTHROPIC_AUTH_TOKEN=tr_your_key_here
claude

기본 URL에 /v1이 없습니다. Claude Code가 자체적으로 /v1/messages를 추가하므로, /v1을 추가하면 /v1/v1/messages가 되어 404 오류가 발생합니다. ANTHROPIC_API_KEY=tr_...도 작동합니다. 이 환경 변수들을 셸 프로필에 넣어주세요.

8. 확인합니다.

claude -p "Reply with exactly: routed via TokenRouter"

응답이 돌아오면 게이트웨이를 거치게 됩니다. 요청은 해당 엔지니어의 키로 기록되어 몇 초 안에 **로그(Logs)**에 나타납니다. Claude 요청은 그대로 통과되므로, 확장된 사고(extended thinking), 도구(tools), 비전(vision) 기능은 Anthropic을 직접 사용하는 경우와 동일하게 작동합니다.

제한(Cap)에서 발생하는 일

제한 여부는 요청이 전달되기 전에 확인됩니다. 게이트웨이는 해당 요청의 최악의 비용을 예약합니다. 이는 프롬프트에 요청의 최대 출력 토큰을 더한 추정치이며, 해당 모델의 요율로 가격이 책정됩니다. 만약 지금까지 지출된 금액과 아직 진행 중인 다른 요청들, 그리고 이 예약 비용까지 합산했을 때 제한을 초과한다면, 요청은 429 budget_exceeded 오류와 함께 거부되며 Anthropic에 도달하지 않습니다. 응답이 완료되면, 예약된 비용은 정확한 토큰 수와 제공업체의 공개 가격 책정 방식을 기반으로 계산되는 실제 비용으로 대체됩니다.

두 가지 실질적인 결과:

제한치에 가까울수록 대용량 요청이 먼저 거부되며, 소용량 요청은 여전히 처리될 수 있습니다.
예약된 프롬프트 부분은 추정치입니다. 이 제한을 정확한 회계가 아닌, 빡빡한 상한선으로 간주하십시오.

배포 전에 테스트해야 할 문제점(Gotchas)

이것들은 저희 게이트웨이를 포함하여 모든 게이트웨이나 프록시에 적용됩니다:

데스크톱 앱의 Code 탭은 현재 ~/.claude/settings.json에 있는 ANTHROPIC_BASE_URL을 무시하는 반면, 터미널 CLI는 이를 인식합니다(anthropics/claude-code#97574).
열려있는 이슈 보고서에 따르면, 기본이 아닌 모든 베이스 URL은 바이트 단위로 그대로 통과되더라도 메시지 스레드를 끊고 헤드리스 실행에서 병렬 도구 호출을 급격히 감소시킵니다(#98464). 워크플로우에 병렬성이 중요하다면, 전후를 측정해야 합니다.
자체 모델 호출을 수행하는 플러그인은 사용자 지정 헤더를 보내지 못할 수 있습니다(#99857).

숫자를 선택하기

보편적인 일일 제한은 없으며, 저희도 그런 것이 있다고 주장하지 않을 것입니다. 적절한 수치를 정하는 방법은 다음과 같습니다. 하드 캡(hard-cap) 스위치를 끈 상태로 일주일 동안 운영하면서 (알림만 확인), 각 엔지니어의 가장 바쁜 일반적인 날을 살펴본 다음, 그보다 여유롭게 높은 제한으로 하드 캡을 다시 활성화하는 것입니다. 이 캡의 역할은 정상적인 작업을 할당하는 것이 아니라, 통제 불능 루프(runaway loops)를 막는 것입니다. TPM 제한은 너무 타이트하게 유지하여 루프가 몇 분 만에 하루 전체를 소진할 수 없도록 해야 합니다.

퇴사자 처리 (Offboarding)

API Keys 페이지에서 해당 사용자의 키를 취소하고, Members 섹션에서도 제거합니다. 다른 모든 사람은 계속 작업하며, 아무도 무언가를 순환시키지 않습니다.

저희는 TokenRouter를 구축합니다. 무료 플랜은 카드 정보가 필요 없으며 유료 플랜과 동일한 예산 및 하드 캡을 포함합니다. Claude Code 설정은 문서에서 확인할 수 있습니다: tokenrouter.io/docs/claude-code.