Claude Code CLI가 아니라, Claude OAuth로 직접 붙인 개인 AI 에이전트 "유성이"

발표자: 자연어회계처리
한 줄 요약: 나는 Anthropic의 claude CLI를 쓰지 않습니다.
Hermes 게이트웨이가 Claude 구독 계정의 OAuth 토큰으로 모델에 직접 붙어, 텔레그램·터미널·크론을 한 몸으로 묶은 개인 에이전트 "유성이"를 돌립니다.
*유성이는 제가 사용하는 ai agent의 이름입니다.

0. 사람들이 신기해하는 지점

클로드 Oauth로 된다고요??????? 사람들이 "이게 되요??" 본사람들은 "와 진짠가보네??" 라고 하도 하셔서 왜 사례글 안쓰냐고 하셔서 결국 쓰게 되었습니다..... 이게 막힐수도 있고 안될수도 있고 6월 중순에 정책바뀌면 안될수 있고 일종의 버그일수도 있고 해서 그간 안썻지만 지금 이방식으로 거히 한달이 되었기에(토욜첫오프 모임때 큰 에러가 있어 추후에 다시 발급하긴햇습니다) 이 정도 검증이면 써도 되겠다 해서 쓰게 되었습니다. 그리고 헤르메스를 쓰는 모든 스터디분들에게 공유되면 도움이 되실분들이 있을거 같아 사례글을 되었습니다.

단!! 이로인해 계정정지 등 불이익발생가능성은.. 시도하시는분이 판단하고 책임지시기를....

그리고 성공하신다면.... 앤트로픽 정책바뀌기전 꿀을 좀 빠시기를....

대부분은 Claude를 이렇게 쓴다고 생각합니다.

방법 A — Claude Code CLI: 터미널에서 -p, claude 명령을 띄워 코딩을 시킵니다.
방법 B — API Key: sk-ant-api03-... 키를 발급받아 토큰 단위로 과금하며 SDK로 호출합니다.

그런데 유성이는 둘 다 아닙니다. 세 번째 길입니다.

방법 C — Claude 구독 OAuth 토큰 직결: Claude Pro/Max 구독 계정으로 로그인해 받은 OAuth 액세스 토큰(sk-ant-oat...)을, 자체 제작이 아닌 오픈 에이전트 프레임워크(Hermes)가 모델 호출에 직접 사용합니다. CLI 프로세스를 감싸지도 않고, 종량제 API 키도 아닙니다.

이 구성이 만들어내는 차이가 이 글의 핵심입니다.

1. "CLI 래핑"과 무엇이 다른가 (가장 흔한 오해)

많은 자작 비서가 사실은 claude CLI나 다른 CLI를 백그라운드로 띄워놓고, 거기에 명령을 흘려보내는 래퍼(wrapper) 다. 유성이는 그게 아닙니다.

구분

CLI 래핑 방식

유성이 (Hermes + OAuth)

모델 호출

claude 프로세스에 stdin으로 명령 전달

Anthropic Messages API를 OAuth 토큰으로 직접 호출

에이전트 루프

CLI가 자기 루프를 가짐 (제어 불가)

Hermes가 자체 에이전트 루프 소유 (툴·메모리·위임 전부 자기 것)

인증

CLI 로그인에 종속

게이트웨이가 OAuth 토큰을 직접 관리 (~/.hermes/auth.json)

확장

CLI가 주는 것만 가능

멀티봇·크론·스킬·메모리·위임 자유롭게 조립

즉 유성이는 "Claude Code를 자동화한 것"이 아니라, Claude를 두뇌로 쓰는 독립 에이전트 본체입니다. 두뇌(모델)만 OAuth로 빌려 쓰고, 몸통(루프·도구·기억·자동화)은 전부 자기 것입니다.

2. 실제 파일로 증명되는 구조 (라이브 인스펙션)

"그렇다더라"가 아니라 실제 설정 파일에서 뽑은 사실로 말합니다.

2-1. 모델·프로바이더

~/.hermes/config.yaml 최상단:

인증화면 아래 첨부 : 보이십니까? claude-opus-4-8의 영롱한 자태가???

model:
  default: claude-opus-4-8
  provider: anthropic
fallback_providers:
- provider: anthropic
  model: claude-sonnet-4-6

메인 두뇌: claude-opus-4-8
opus가 과부하로 막히면 claude-sonnet으로 자동 강등(fallback) — 끊기지 않고 계속 답합니다.

2-2. 인증이 API 키가 아니라 OAuth라는 결정적 증거

환경변수 ANTHROPIC_TOKEN의 접두사를 직접 확인하면:

ANTHROPIC_TOKEN=sk-ant-oat0...   ← oat = OAuth Access Token

종량제 API 키라면 sk-ant-api03-...로 시작한다.
유성이의 토큰은 sk-ant-oat0... — OAuth 액세스 토큰입니다. 구독 계정으로 로그인해 발급받은 자격증명이라는 뜻.

~/.hermes/auth.json의 anthropic 자격증명도 이를 뒷받침합니다:

"anthropic": [{
  "auth_type": "oauth",
  "source": "env:ANTHROPIC_TOKEN",
  "base_url": "https://api.anthropic.com"
}]

auth_type: oauth — API 키가 아니라 OAuth로 명시돼 있습니다.
base_url은 Anthropic 공식 API. 즉 CLI를 거치지 않고 API에 OAuth로 직접 붙습니다.

2-3. 이 OAuth 토큰을 어떻게 발급·추출했나

"CLI를 안 쓴다면서 토큰은 어디서 났냐?" — 핵심은 CLI를 인증 발급기로만 한 번 쓰고, 실행 단계에선 버린다는 것입니다. 흐름은 이렇습니다.

Claude Code CLI로 OAuth 로그인 (발급기 역할) claude CLI(설치 확인: /usr/local/bin/claude, v2.1.x)로 구독 계정 OAuth 로그인을 한 번 수행한다. 이때 브라우저 동의 플로우를 거쳐 Anthropic이 OAuth 토큰을 발급합니다.
토큰은 macOS 키체인에 저장됩니다. (진짜 원본) 발급된 토큰의 single source of truth는 macOS Keychain의 generic-password 항목입니다.
```
service = "Claude Code-credentials"
account = "사용자"
payload = { "claudeAiOauth": { accessToken, expiresAt, scopes } }
```
백업 호환 경로로 ~/.claude/.credentials.json에도 같은 값이 쓰입니다. 이 파일 생성 시각(2026-05-24 21:01:11)이 곧 토큰 발급 시점이고, 만료(2027-05-24 21:01)와 정확히 1년 차이가 납니다.
키체인에서 access_token만 뽑아 Hermes의 ANTHROPIC_TOKEN에 박는다 (추출)
```
security find-generic-password -s "Claude Code-credentials" -a 사용자이름 -w
# → JSON에서 claudeAiOauth.accessToken 추출 → .env의 ANTHROPIC_TOKEN= 에 주입
```
이렇게 하면 Hermes 게이트웨이는 claude 프로세스를 띄울 필요 없이, 그 토큰 문자열만 들고 Anthropic API에 직접 OAuth로 붙습니다. CLI는 "로그인해서 토큰 받아오는 도구"로만 쓰이고, 실제 추론 호출 경로에선 완전히 빠지는 겁니다.
추출된 토큰에는 refresh_token을 일부러 안 넣었습니다. 현재 .credentials.json과 Hermes 쪽 토큰 모두 accessToken / expiresAt / scopes만 있고 refreshToken은 제거돼 있습니다. 1년 수명 장기 토큰이라 중간 갱신이 필요 없고, refresh_token이 single-use라 여러 경로(CLI·credential_pool·watchdog)가 동시에 쓰면 깨지는 race를 원천 차단하기 위해서입니다. 만료가 다가오면 1번부터 다시(재로그인 → 추출) 하면 됩니다.

요약하면: CLI = 1회용 인증 발급기, 키체인 = 토큰 금고, Hermes = 그 토큰으로 직접 API 호출.그러니까 cli인증절차가면서 oauth토큰 뺀다음 붙여버리고 앤트로픽으로 가는 통신은 헤르메스가 발신해주는 형태로 가는겁니다. 엔트로픽 서버는 현재 토큰이 유효한가를 중점으로 보는거 같습니다. 그리고 봇마다 oauth를 각각 해서 분리시키면 누적사용량이 따로 잡히는거 같습니다 때문에 아직까지 허용되는거 같습니다. 한키로쓰면 누적사용량때매 밴될수도있으니까요. "Claude Code로 로그인해서 토큰만 빼 쓴다"가 한 줄 정리입니다.

전제: 이건 내 구독 계정의 토큰을, 내 맥에서 도는 내 개인 에이전트에 연결한 셋업입니다. 토큰을 외부에 공유하거나 재판매하는 게 아니라 개인 사용 범위 안에서 입구만 바꾼 것입니다.

2-4. 토큰 수명 — 단명 토큰이 아니라 약 1년짜리 장기 토큰

자주 받는 오해: "OAuth면 자주 만료되는 거 아니냐?" 실제로 키체인에 살아있는 토큰의 만료 시각을 직접 읽어보면:

expiresAt: 2027-05-24  (발급: 2026-05-24)
남은 수명: 약 352일 ≈ 1년
scopes: user:inference, user:profile, user:sessions:claude_code ...

흔히 헷갈리는 "7일 만료"는 구글 OAuth(테스트 모드 refresh_token 정책) 얘기지, 이 Anthropic 토큰과 무관합니다.
한때는 access_token이 24시간 단명이라, 만료 40분 전에 refresh_token으로 자동 갱신하는 watchdog(5분 주기 launchd)를 운영했었습니다.
그 자동 refresh가 HTTP 400으로 깨지는 문제(refresh_token single-use race)를 겪은 뒤, 약 1년 수명의 장기 OAuth 토큰으로 갈아끼웠습니다. 그래서 평소엔 인증을 신경 쓸 일이 거의 없습니다. (watchdog는 옛 구조의 안전망으로 남아있을 뿐, 지금은 갱신할 게 없어 사실상 무동작.)

→ 정리하면: 단명 토큰을 쥐어짜 갱신하는 구조가 아니라, 1년짜리 구독 OAuth 토큰을 박아 안정적으로 운영하는 구조입니다.

2-5. Claude Code 경로를 일부러 "억제"한 흔적

같은 auth.json에 이런 항목이 있습니다:

"suppressed_sources": {
  "anthropic": ["claude_code"]
}

claude_code 자격증명 소스를 억제(suppress) 하도록 설정돼 있습니다.
해석: 시스템에 Claude Code CLI 인증이 있어도 그걸 쓰지 않고, 명시적으로 OAuth 토큰 경로를 택했다는 증거. "우연히 OAuth가 잡힌 것"이 아니라 의도된 구성입니다.

이 세 가지(sk-ant-oat0 접두사 + auth_type: oauth + claude_code 억제)가 "CLI가 아니라 OAuth 직결"이라는 주장의 파일 레벨 증명입니다.

3. 이 구성이 주는 실제 이득

OAuth 직결이 단순한 호기심거리가 아닌 이유.

구독 한도로 돈다, 토큰 종량 과금이 아니다!!! Claude 구독(Pro/Max)의 사용량 한도 안에서 작동합니다. API 키처럼 호출 1건마다 과금이 쌓이지 않아, 하루 종일 비서를 굴려도 비용이 예측 가능합니다.
하나의 두뇌, 여러 입구 터미널이든 텔레그램이든 크론이든, 어디로 들어와도 같은 OAuth·같은 메모리·같은 페르소나의 "유성이"입니다. 입구만 다르고 정체성은 하나.
모델 자유 opus-4-8을 기본으로 쓰다가 과부하면 sonnet으로 자동 강등. 구독 계정이 접근 가능한 최신 모델을 그대로 두뇌로 씁니다.
풀 에이전트 기능이 전부 붙습니다 CLI 한 개가 아니라 게이트웨이라서, 아래의 모든 게 한 몸에 얹힙니다.

4. OAuth 두뇌 위에 얹힌 "에이전트 본체" (실측 수치)

같은 게이트웨이에서 실제로 돌고 있는 것들. 이게 "그냥 Claude 쓰는 것"과의 진짜 차이입니다.

4-1. 스킬 시스템 — 절차적 기억 100개+

$ find ~/.hermes/skills -name SKILL.md | wc -l
100+

재무분석·회계·PPT·옵시디언·크론 운영 등 100+개의 검증된 작업 절차가 스킬로 저장돼 있고, 필요할 때만 로드해서 토큰을 아낍니다. 매번 처음부터 설명할 필요가 없습니다.

4-2. 지속 메모리 — 세션을 넘어 기억

USER 프로파일: 내가 누구인지(이름·타임존·말투·취향).
Memory 노트: 환경 사실·운영 교훈·도구 함정.

세션이 새로 시작돼도 이 기억이 매 턴 주입돼 "처음 보는 사람" 취급을 하지 않습니다.

4-3. 자동화 — 살아있는 크론

실제 등록돼 돌고 있는 스케줄 작업 예시:

- 비서 유성이 아침 리마인더            매일 07:00
- 비서 유성이 옵시디언 데일리노트       매일 07:55
- 비서 주간 일정 브리핑                일요일 21:00
- 회계사 Q&A 학습 검토 리포트          매일 21:00
- KIFRS 커뮤니티 Q&A 학습 검토         매일 08:00
- 동업타사봇 월간 데이터 자동갱신       매월 1일 09:00
- 세법 변경 감지 (법제처 OpenAPI)      매월 1일 09:00
- 회계사 db.kasb 문단링크 매핑 재수집   매월 1일 09:00
- 회계사 학습자료 승인 대기 알림        매일 09:00

OAuth 두뇌가 사람 없는 새벽·아침에도 알아서 일하고, 결과를 채널로 보내줍니다.

5. 운영하며 얻은 교훈 (현실의 함정)

OAuth 구성이라 생기는 진짜 운영 이슈들. 발표의 신뢰도를 올려주는 부분.

OAuth 토큰은 결국 만료됩니다 — 단 지금은 1년짜리라 여유가 큽니다 현재 토큰은 약 1년 수명(2027-05-24 만료)이라 평소엔 끊길 일이 없습니다. 다만 과거 24시간 단명 토큰 시절엔, 토큰이 만료·꼬이면 게이트웨이가 연결돼 있어도 모델이 안 붙어 "재로그인 하래"가 떴었습니다. 에러가 시끄럽게 안 나고 조용히 멈추는 게 함정입니다. 자동 refresh(watchdog)가 HTTP 400으로 깨진 경험 때문에, 지금은 자동 갱신에 기대지 않고 장기 토큰 + 만료 시 수동 재발급으로 운영하고 있습니다.
혼동 주의: "7일마다 죽는 토큰"은 구글 OAuth(비서 유성이의 캘린더 연동, 테스트 모드 refresh_token 7일 정책) 얘기입니다. Anthropic 토큰과는 전혀 다른 사안입니다.
세션은 시작 시점의 모델을 PIN합니다 이미 떠 있는 세션은 config를 바꿔도 소급되지 않습니다. 새 모델을 쓰려면 게이트웨이를 재시작해야 합니다.
기기별 인증 분리 맥미니·회사 노트북·카카오 봇들이 서로 인증을 안 꼬이게 분리해 둡니다. OAuth 자격증명이 한 군데서 엉키면 연쇄로 멈춥니다.
비밀값은 절대 노출 금지 OAuth 토큰은 곧 구독 계정 접근권이라 더 민감합니다.

6. 한 장 요약 (발표 마무리 멘트용)

나는 Claude를 CLI로 부리지 않는다. OAuth로 두뇌만 빌려와, 기억·도구·자동화·멀티봇을 가진 독립 에이전트 "유성이"의 머리에 꽂았다.!!!!!!!!
인증: sk-ant-oat0... = 구독 OAuth 토큰 (API 키 아님, CLI 아님), 약 1년 수명(2027-05-24 만료)이라 안정적
두뇌: claude-opus-4-8 (과부하 시 sonnet 자동 강등)
몸통: 100+개 스킬 + 지속 메모리 + 크론 + 위임 오케스트레이션 + 멀티봇
철학: 입구는 여러 개, 유성이는 하나.

부록 — 환경 사실 (작성 시점)

Hermes Agent v0.15.1 (2026.5.29)
Host: macOS, Python 3.11
설정 위치: ~/.hermes/ (config.yaml, auth.json, skills/, cron/)
워크스페이스: ~/.openclaw/workspace

🔥<24기 AI 스터디> 9/21 모집 마감 🔥