AI 에이전트에게 API 키를 주지 마세요 — 크리덴셜 게이트웨이 OneCLI 해부

핵심 요약 (TL;DR)

AI 에이전트에게 API 키를 넘기는 대신, 키를 아예 보여주지 않는 방법이 있습니다. 오픈소스 크리덴셜 게이트웨이 OneCLI는 에이전트가 플레이스홀더로 요청하면 Rust 기반 프록시가 권한을 검증한 뒤 실제 시크릿으로 치환해 전달합니다. 에이전트는 진짜 키를 처음부터 끝까지 모릅니다. 2026년 3월 공개 후 GitHub 스타 2,768개(2026-07-25 기준)를 모았습니다.

에이전트에게 .env를 통째로 넘기고 계신가요?

Claude Code 같은 에이전트에게 배포를 시키려면 클라우드 키가, 결제 테스트를 시키려면 결제 키가 필요합니다. 그래서 많은 분들이 .env 파일을 통째로 물려주고는 찜찜함을 안고 삽니다. 프롬프트 인젝션에 당하는 순간, 에이전트가 읽을 수 있는 모든 시크릿이 함께 털린다는 걸 알기 때문이죠.

오픈소스 DB 도구 ChartDB를 만들던 보안 전문가 듀오 Jonathan Fishner와 Guy는 이 문제를 반대 방향에서 풀었습니다. 에이전트를 더 감시하는 게 아니라, 애초에 훔칠 것을 주지 않는 겁니다. 그렇게 나온 것이 OneCLI(https://github.com/onecli/onecli)입니다. Hacker News에서 103포인트·댓글 31개(https://news.ycombinator.com/item?id=49023427), 공개 4개월여 만에 스타 2,768개를 모았습니다.

키를 안 주고 어떻게 일을 시키나요?

구조는 호텔 프런트와 같습니다. 투숙객(에이전트)은 마스터키를 받지 않습니다. 프런트(게이트웨이)에 "302호 열어주세요"라고 요청하면, 프런트가 투숙객 명부(권한)를 확인하고 대신 문을 열어주는 거죠.

1. 에이전트의 아웃바운드 트래픽이 OneCLI의 Rust 프록시를 거치도록 설정합니다. HTTPS_PROXY 환경변수만 잡으면 되기 때문에 특정 에이전트 프레임워크에 종속되지 않습니다.
2. 에이전트는 실제 키 대신 플레이스홀더를 넣어 API를 호출합니다.
3. 프록시가 요청의 권한을 검증하고, 통과한 요청에만 실제 시크릿을 치환해 목적지로 보냅니다. 시크릿은 AES-256-GCM으로 암호화 저장되고, 키 로테이션을 지원합니다.
4. 민감한 작업은 네트워크 레이어에서 사람의 승인(human-in-the-loop)을 강제할 수 있습니다. 에이전트가 아무리 설득당해도, 승인 버튼은 사람 손에 있는 겁니다.

# 개념 구조: 에이전트의 모든 아웃바운드 요청이 문지기를 거치게 한다
export HTTPS_PROXY=<OneCLI 프록시 주소>
claude   # 이후 에이전트의 API 호출은 프록시가 검증하고 치환한다

구체적인 설치 절차와 프록시 주소는 공식 문서(https://onecli.sh/)를 따르는 것이 안전합니다.

"결국 키 하나를 다른 키로 바꾼 것 아닌가요?"

HN 댓글에서 실제로 나온 반론입니다. 게이트웨이 접근 권한 자체가 새로운 단일 실패 지점이 되지 않느냐는 거죠. 절반은 맞는 말입니다. 다만 달라지는 것이 있습니다. 시크릿이 에이전트의 컨텍스트에 평문으로 들어가지 않으니 인젝션으로 유출될 표면이 사라지고, 모든 사용이 한 지점을 지나니 감사와 차단이 가능해집니다. '위험 제로'가 아니라 '위험의 위치를 통제 가능한 곳으로 옮기는 것' — 보안 설계의 기본 문법입니다.

FAQ

Q. 어떤 에이전트와 함께 쓸 수 있나요?
HTTPS_PROXY를 존중하는 도구라면 프레임워크를 가리지 않습니다. Claude Code 같은 CLI 에이전트가 대표적인 적용 대상입니다.

Q. 시크릿 매니저와는 뭐가 다른가요?
시크릿 매니저는 '안전한 보관과 배포'가 중심이고, OneCLI는 '에이전트가 키를 아예 못 보게 하는 실행 시점 치환'이 중심입니다. HN 스레드에서도 Infisical, Varlock 같은 도구와의 비교가 오갔으니 함께 읽어보시길 권합니다.

Q. 지금 당장 도입해야 하나요?
에이전트에게 프로덕션 키를 물려주고 있다면 검토 가치가 충분합니다. 최소한 개발용 키와 프로덕션 키를 분리하는 것부터 시작하세요.

핵심은 하나입니다. 에이전트에게 키를 '잘 관리하며 주는' 방법을 고민하기 전에, '안 주고도 되는' 구조인지 먼저 물어보세요. 이번 주말, .env에서 가장 위험한 키 하나만 게이트웨이 뒤로 옮겨보는 것 — 그게 다음 액션입니다.