claude setup-token: 자동화 서버에 내 권한 안전하게 넘기기

GitHub Actions 같은 자동화 서버가 내 대신 Claude를 호출하게 만들고 싶을 때가 있어요. 그런데 사람이 매번 로그인을 해 줄 수는 없죠. 이럴 때 "내 권한을 대신 쓸 수 있는 열쇠"를 발급해 주는 명령어가 claude setup-token이에요.

정의 (뭐냐면)

claude setup-token은 CI나 스크립트에서 쓸 장기 토큰을 발급하는 명령어예요. 발급한 토큰은 따로 저장하지 않고 화면에 출력만 합니다. 사용하려면 구독이 필요해요.

여기서 토큰(token)은 "사람 대신 인증을 통과하게 해 주는 디지털 열쇠"라고 보면 돼요. CI는 "Continuous Integration(지속적 통합)"의 줄임말로, 코드를 올릴 때마다 자동으로 검사·실행해 주는 자동화 시스템을 말해요. 장기 토큰은 오래 유효한 열쇠라서, 한 번 발급해 두면 자동화 서버가 매번 사람 손을 빌리지 않고도 내 계정으로 Claude를 호출할 수 있게 됩니다.

이 명령어는 고급 자동화용이라 입문 단계에서 당장 쓸 일은 적지만, "자동화에 권한을 넘기는 정식 방법이 있구나" 정도로 알아 두면 좋아요.

어떻게 쓰나 (난이도별)

기초 — 토큰 발급하기

claude setup-token

이 한 줄을 실행하면 장기 OAuth 토큰이 화면에 출력돼요. OAuth는 "비밀번호를 직접 넘기지 않고도 권한을 위임하는 표준 방식"이라고 이해하면 됩니다. 출력된 토큰을 복사해서 자동화 서버에 등록하면, 그 서버가 내 계정 권한으로 Claude를 쓸 수 있게 돼요.

흔한 함정

• 토큰은 비밀번호와 같아요. 출력된 값을 블로그·채팅·공개 저장소에 그대로 올리면 절대 안 돼요. 등록할 때도 <your-token> 같은 자리표시자로 가리고, 실제 값은 안전한 비밀 저장소(예: GitHub의 Secrets)에 넣으세요.
• 이 명령어는 토큰을 저장하지 않고 출력만 해요. 화면을 닫으면 다시 볼 수 없으니, 발급 직후 바로 안전한 곳에 등록해 두세요.
• 구독이 필요한 기능이라, 구독이 없으면 발급이 안 될 수 있어요.

실전 사례

GitHub Actions가 코드 변경이 생길 때마다 내 계정으로 Claude를 호출해 자동 리뷰나 작업을 하도록 만들고 싶을 때, claude setup-token으로 토큰을 발급해 Actions의 비밀 저장소에 등록해요. 그러면 사람이 로그인하지 않아도 자동화가 내 권한으로 매끄럽게 돌아갑니다.

이렇게 더 씁니다

정기적으로 돌아가는 자동화 작업, 예를 들어 매일 밤 코드를 점검하거나 문서를 생성하는 작업에 이 토큰을 쓰면, 사람이 지켜보지 않아도 작업이 진행돼요. 다만 권한을 넘기는 일인 만큼, 토큰을 안전하게 보관하고 더 이상 쓰지 않는 토큰은 폐기하는 관리 습관을 함께 들이는 게 중요합니다.

정리

claude setup-token은 CI·스크립트용 장기 토큰을 발급하는 명령어예요. 발급한 토큰을 자동화 서버에 등록하면, 그 서버가 사람 손 없이 내 계정으로 Claude를 호출할 수 있습니다. 토큰은 비밀번호처럼 다뤄야 하니, 절대 공개된 곳에 노출하지 말고 안전한 비밀 저장소에 보관하세요.

기준: Claude Code v2.1.154 (2026.05)