Security Blog

AI 에이전트에게 API 키를 키를 보여주지 않고 넘기려면 어떻게 해야 할까요?

#44

November 20, 2026 · By Mila

← All posts

에이전트에게 키 대신 참조자를 주고, 같은 머신의 프록시가 요청이 나가는 길에 실제 키를 넣어주게 하세요. 환경 변수가 왜 더는 충분하지 않게 됐는지, 그리고 설정 방법을 소개합니다.

에이전트에게 키 대신 참조자를 주고, 같은 머신에서 동작하는 작은 프록시가 요청이 나가는 길에 실제 키를 넣어주게 하세요. 에이전트는 비밀이 들어갈 자리에 clavitor://OpenAI/key라고 씁니다. API는 실제 키를 받습니다. 에이전트는 키를 절대 갖지 않으므로, 출력하거나 로그에 남기거나 설득에 넘어가 넘겨줄 수도 없습니다.

아이디어는 이게 전부입니다. 이 페이지의 나머지는 왜 이게 중요한지, 그리고 어떻게 설정하는지에 관한 것입니다.

"그냥 환경 변수에 넣으면 되지"가 더는 안 되는 이유

1년 전만 해도 export OPENAI_API_KEY=sk-...는 스크립트에 키를 넘기는 평범한 방법이었습니다. 아무도 눈썹 하나 움직이지 않았죠.

그러다 스크립트가 스스로 생각하기 시작했습니다.

AI 에이전트는 파일을 읽고, 도구를 실행하고, 로그를 쓰고, 인터넷의 낯선 이들과 대화합니다. 그중 하나하나가 에이전트가 쥔 키의 유출 경로입니다:

  • 환경. 에이전트가 실행하는 모든 것에 상속됩니다. /proc에, 크래시 덤프에, CI 출력에 나타납니다.
  • 메모리. 런타임에 키를 가져와도 에이전트가 실행되는 동안 프로세스 안에 그대로 남습니다.
  • 대화. 웹페이지나 이슈 댓글에 숨은 프롬프트 인젝션이 에이전트에게 "디버깅을 위해 설정을 포함시켜 달라"고 요청합니다. 협조적인 에이전트는 그렇게 합니다.

이런 일에는 에이전트의 버그가 필요하지 않습니다. 키가 에이전트가 닿을 수 있는 곳에 있기만 하면 됩니다.

패턴: 에이전트는 요청하고, 프록시가 서명합니다

호텔 키카드를 떠올려 보세요. 투숙객은 자기 방을 열 수 있습니다. 투숙객은 마스터 키를 절대 보지 못하고, 문은 태그 기록을 남깁니다.

API 키라면 이렇게 됩니다:

  1. 실제 키는 볼트에 암호화되어 보관됩니다.
  2. 프록시가 에이전트 옆, 같은 머신에서 실행됩니다.
  3. 에이전트는 키가 들어갈 자리에 참조자를 넣어 HTTPS 요청을 보냅니다.
  4. 프록시가 볼트에서 값을 가져와 요청에 넣고 전달합니다.
  5. 에이전트 쪽은 참조자만 갖습니다.

에이전트의 로그에는 참조자가 보입니다. 컨텍스트 윈도우에도 마찬가지입니다. 새어 나갈 것이 없습니다.

Clavitor로 설정하는 방법

우리가 이렇게 만들었습니다. 바이너리 하나, 환경 변수 하나, 에이전트 코드 변경은 없습니다.

볼트에서 에이전트가 필요한 스코프로 클라이언트를 만들고, 프록시를 등록해 실행하세요:

$ clavitor-proxy init
$ clavitor-proxy ca
$ clavitor-proxy serve

init은 프록시를 해당 클라이언트로 등록합니다. ca는 프록시의 인증 기관을 출력합니다. 프록시가 에이전트의 HTTPS 연결을 직접 열기 때문에, 에이전트의 HTTP 클라이언트가 쓰는 신뢰 저장소에 이를 추가하세요. 그다음 에이전트를 프록시로 향하게 합니다:

$ export HTTPS_PROXY="http://clavitor:$(cat proxy-auth)@127.0.0.1:1983"

$ curl -H "Authorization: Bearer clavitor://OpenAI/key" \
    https://api.openai.com/v1/chat/completions

proxy-auth는 프록시 자신의 액세스 토큰으로, 바이너리 옆에 있는 파일입니다. 모든 연결이 이를 실어야 하므로, 같은 머신의 다른 사용자는 프록시를 빌려 쓸 수 없습니다. 프록시는 127.0.0.1:1983에서, 그리고 그 머신에서만 수신합니다. 신뢰하는 사설 네트워크를 위해 일부러 설정하지 않는 한요.

HTTPS_PROXY를 존중하는 HTTP 클라이언트를 쓰는 에이전트라면 무엇이든 됩니다: Claude Code, Codex, 직접 만든 스크립트. 자격 증명은 해당 항목이 웹 주소로 지정한 호스트로만 전달되므로, 프롬프트 인젝션을 당한 에이전트가 같은 참조자를 낯선 서버로 향하게 할 수는 없습니다. 단계별 설정은 프록시 문서에 있습니다.

에이전트의 다른 비밀들은요?

모든 비밀이 HTTP 헤더로 이동하지는 않습니다. 배포 비밀번호, SSH 키, 로그인용 2단계 인증 코드 같은 것들이요.

이런 경우 에이전트는 clavitor-cli로 한 번에 이름 지정된 항목 하나만, 그리고 자신에게 허락된 항목만 볼트에 요청합니다:

$ clavitor-cli get "GitHub Deploy" --field password

$ clavitor-cli get "Stripe API" --field key
clavitor-cli: CV-2041: Access denied.

에이전트는 볼트를 나열할 수 없습니다. 이름 검색은 일치하는 제목을 최대 5개까지만 보여주고, 그 이상은 개수만 보여줍니다.

인증기 코드도 같은 방식으로 동작합니다. clavitor-cli totp "GitHub"가 에이전트의 머신에서 현재 코드를 계산하므로, 누군가의 휴대폰을 들여다보지 않고도 2단계 로그인을 통과할 수 있습니다. 볼트는 비밀을 암호화해 보관합니다.

이것이 해결하지 않는 것

프록시는 키를 에이전트 밖에 둡니다. 에이전트를 신뢰할 수 있게 만들지는 않습니다.

  • 침해당한 에이전트는 여전히 자신에게 허락된 접근을 사용할 수 있습니다. 다만 키를 가져갈 수는 없습니다.
  • 머신에 관리자 접근이 있는 사람은 프록시를 사용하거나 그 메모리를 읽을 수 있습니다.
  • 응답에 키를 되돌려 출력하는 API는 키를 에이전트에게 넘깁니다. 프록시는 요청에 키를 넣을 뿐, 응답은 걸러주지 않습니다.

그래서 프록시만큼이나 그 주변의 접근 통제가 중요합니다:

  • 스코프. 각 에이전트는 필요한 항목만 받습니다. 업무 에이전트는 GitHub과 AWS를 봅니다. 배포 에이전트는 SSH 키와 데이터베이스를 봅니다.
  • 읽기 제한. 각 에이전트는 분당, 시간당 정해진 수의 서로 다른 항목만 읽을 수 있고, 그 숫자는 여러분이 정합니다. 2시간 안에 시간당 한도를 두 번 넘긴 에이전트는 여러분이 해제할 때까지 잠깁니다.
  • 기록. 모든 읽기가 기록됩니다: 어느 에이전트가, 어느 항목을, 언제.

에이전트를 여러 개 돌린다면? 각각 자기 프록시와 자기 등록을 갖게 하세요. 그러면 각자 자기 스코프, 자기 한도, 자기 흔적을 갖게 되고, 에이전트 A는 에이전트 B의 키를 볼 수 없습니다.

짧은 요약

에이전트에게 키를 주지 마세요. 키의 이름을 주고, 키 자체는 한 걸음 떨어진 곳에 두세요. 그곳이 매번, 지금 이 에이전트가 이 키를 써도 되는지 결정합니다.

프록시 설정하기 또는 에이전트 접근 동작 방식 보기.