AI 에이전트에 API 키 안전하게 넣기 — 모델은 가짜만 봅니다

AI 일꾼에게 외부 서비스를 붙여주려면 열쇠를 쥐여줘야 합니다. 그런데 그 열쇠가 대화 기록이나 로그에 남을까 걱정되죠. 얼마 전까지만 해도 안전하게 넣을 자리 자체가 마땅치 않았는데, 이제 방식이 생겼습니다. 접근이 재미있는데 — 에이전트에게는 가짜 문자열만 쥐여주고, 요청이 밖으로 나가는 순간에 진짜 값으로 바꿔칩니다. 그래서 일하는 쪽은 진짜 값을 끝까지 못 봅니다. 대신 이 방식이라 안 되는 경우도 분명합니다.

📌 30초 요약

• ★에이전트는 진짜 값을 못 봅니다 — 가짜 문자열만 쥡니다.
• 나가는 순간에 바꿔칩니다 — 안쪽에서는 계속 가짜입니다.
• ⚠️ 값을 직접 계산에 쓰는 방식은 안 됩니다 — 서명 같은 것.
• ⚠️ 받아온 토큰은 안 가려집니다 — 나가는 방향만 처리합니다.
• 어느 주소·어느 위치에 붙일지 좁힐 수 있습니다.
• ⚠️ 같은 작업 공간이면 누구나 참조할 수 있습니다.

가짜를 쥐여주고 나갈 때 바꿔칩니다

구조는 이렇습니다. 열쇠를 한곳에 등록해두면, 에이전트가 일하는 공간에는 아무 의미 없는 대체 문자열이 들어갑니다. 에이전트가 외부로 요청을 보내면 바깥으로 나가는 길목에서 그 문자열이 진짜 값으로 교체되죠. 문서 표현대로 "에이전트는 비밀 값을 결코 보지 못합니다".

등록해둔 값은 쓰기 전용이라 나중에 조회해도 응답에 절대 돌아오지 않습니다. 방식은 둘로 나뉘는데, 도구 서버에 붙는 인증은 주소별로 등록해두면 그 서버에 연결할 때 자동으로 실려 가고, 환경 변수 형태는 위에서 말한 바꿔치기 방식으로 동작합니다. 아예 열쇠를 만들지 않는 인증과는 접근이 정반대입니다 — 그쪽이 열쇠 자체를 없애는 쪽이라면, 이쪽은 열쇠는 두되 보여주지 않는 쪽이죠.

그래서 안 되는 경우들

바꿔치기가 밖으로 나가는 길목에서 일어난다는 사실에서 한계가 곧장 따라옵니다. 안쪽에서 그 값을 가지고 뭔가를 하는 방식은 전부 깨집니다.

이런 방식이면	결과
값을 그대로 실어 보냄	정상 동작
시작할 때 형식을 검사	이상한 값이라며 거부
값으로 서명을 계산	엉뚱한 서명이 만들어짐
값으로 다른 토큰을 받아옴	받아온 건 그대로 노출

🔁 교환 방식은 미리 해두세요

네 번째 줄이 특히 놓치기 쉽습니다. 처리되는 건 나가는 방향뿐이라, 등록해둔 값으로 세션 토큰을 받아오는 흐름이면 돌아온 토큰은 가려지지 않은 채 안쪽에 도착합니다. 결국 에이전트가 진짜 토큰을 보게 되죠. 문서의 처방은 명확합니다 — 그 교환을 미리 직접 해두고, 결과로 나온 토큰을 등록하라는 것. 한 단계를 밖으로 빼는 셈입니다.

어디에 붙일지 좁힐 수 있습니다

범위를 두 갈래로 좁힐 수 있습니다. 하나는 어느 주소로 나갈 때만 붙일지, 다른 하나는 요청의 어느 부분에 붙일지입니다. 앞의 것은 목록을 정해두라고 강하게 권장합니다 — 그래야 허가 안 된 곳으로 열쇠가 새어 나가지 않으니까요.

뒤의 것이 흥미롭습니다. 붙일 자리가 요청 머리 부분과 본문 둘인데, 문서가 본문 쪽이 노출면이 더 넓다고 짚습니다. 이유가 명쾌해요 — 본문은 에이전트가 다루던 내용으로 조립되기 때문입니다. 대부분의 서비스는 머리 부분에서 열쇠를 읽으니, 머리 쪽만 켜두는 게 더 좁은 설정이라는 권고입니다.

여기서 진단에 유용한 신호가 하나 나옵니다. 꺼둔 자리에 있는 가짜 문자열은 바꿔치기도 안 되고 지워지지도 않은 채 그대로 나갑니다. 그래서 받는 쪽에 그 이상한 문자열이 그대로 도착했다면, 원인은 둘 중 하나입니다 — 그 자리가 꺼져 있거나, 그 주소가 허용 목록에 없거나. 참고로 관리 화면으로 만들면 머리 부분만 켜집니다. 본문으로 보내는 클라이언트라면 이것 때문에 인증이 실패합니다.

같은 공간이면 누구나 씁니다

경고 상자로 따로 표시된 대목이 있습니다. 등록해둔 열쇠는 작업 공간 단위로 공유돼서, 같은 공간의 키를 가진 사람이면 누구나 참조해서 쓸 수 있습니다. 접근을 끊으려면 삭제하는 수밖에 없습니다. 팀 단위로 쓴다면 공간을 어떻게 나눌지가 곧 권한 설계가 되는 셈이죠.

정리하는 방법이 둘인데 성격이 다릅니다. 보관은 비밀 값만 없애고 기록은 남겨 나중에 감사할 수 있게 하고, 삭제는 흔적까지 지웁니다. 보관한 뒤에는 새 열쇠를 같은 이름으로 다시 등록할 수 있고요. 값 교체는 돌아가는 작업을 재시작하지 않아도 반영되는데, 주기적으로 다시 확인하는 구조라서 그렇습니다. 열쇠가 만료되거나 갱신에 실패하면 알림을 받도록 걸어둘 수도 있습니다.

🚦 "그 열쇠로 할 수 있는 일"을 막는 쪽 (8월 27일 추가)

이 글에서 값을 안 보여주는 것과 안전한 것은 다르다고 짚었는데, 그 나머지 절반을 담당하는 장치가 따로 있습니다. 도구마다 그냥 실행할지 사람에게 물어볼지를 정하는 방식인데, 실무에서는 기본은 자동으로 두고 되돌리기 어려운 것만 확인 대상으로 두는 구성이 현실적입니다. 특히 거부할 때 이유를 한 줄 적으면 그 이유가 AI에게 전달돼 단순 차단이 아니라 방향 수정이 됩니다. 다만 답할 때까지 무기한 기다리고, 이미 돌아가는 작업에는 변경이 안 먹힙니다. 확인한 내용은 묻는 쪽과 안 묻는 쪽에 적었습니다.

🔓 내 서버에 올리면 이 안전망이 사라집니다 (8월 27일 추가)

여기서 다룬 값을 안 보여주는 장치는 제공 환경이라서 자동으로 돌아갑니다. 같은 제품을 내 서버에 올려 쓰면 그런 안전망의 상당 부분을 직접 다시 만들어야 합니다. 자격도 두 갈래로 나뉘는데 — 환경 단위 키는 일감을 가져오는 용도고, 기억 저장소는 그 키를 아예 거부하고 세션마다 딸려 오는 비밀만 받습니다. 넓은 권한으로 남의 기억까지 만지지 못하게 한 설계죠. 그리고 읽기 전용으로 붙인 기억도 로컬에서는 고쳐질 수 있어, 확실히 막으려면 셸 도구를 꺼야 합니다. 확인한 내용은 경계가 멈추는 곳에 적었습니다.

자주 묻는 질문 (FAQ)

Q. 그럼 이제 완전히 안전한가요?

"값을 안 보여준다"와 "안전하다"는 다릅니다. 에이전트가 값을 못 보는 건 맞지만, 그 열쇠로 할 수 있는 일은 전부 할 수 있습니다. 문서도 이 점을 짚으며 필요한 권한만 담긴 열쇠를 쓰라고 권합니다 — 권한이 넓을수록 엉뚱하게 움직였을 때 번지는 범위가 커지니까요. 값 유출과 권한 남용은 다른 문제이고, 이 방식이 막아주는 건 앞쪽입니다.

Q. 주소 목록만 정해두면 그리로 갈 수 있나요?

아닙니다. 이게 헷갈리기 쉬운 지점입니다. 열쇠에 붙이는 주소 목록은 "어디에 열쇠를 붙일지"를 정하는 것이지 "어디로 갈 수 있는지"가 아닙니다. 실제로 그 주소에 닿으려면 환경 쪽에서도 따로 허용돼 있어야 하고, 두 겹이 모두 열려야 요청이 성공합니다. 한쪽만 열어두고 "왜 안 되지" 하기 쉬운 구조라 미리 알아둘 만합니다.

Q. 열쇠가 잘못됐는지 미리 알 수 있나요?

등록 시점에는 검사하지 않습니다. 실제로 작업이 돌 때가 되어서야 인증 오류로 드러납니다 — 다만 그 오류가 작업 전체를 멈추지는 않습니다. 갱신 방식 열쇠라면 왜 갱신에 실패했는지 확인하는 도구가 따로 있어서 세 갈래로 답을 줍니다 — 멀쩡함 / 승인이 끊겼으니 사용자에게 다시 받아야 함 / 일시적 문제라 기다렸다 재시도. 어느 쪽이냐에 따라 할 일이 갈리니 유용합니다.

🧾 정직하게 밝혀둘 것

• 직접 붙여보지 않았습니다. 공식 문서의 구조·제약·주의사항을 정리한 것입니다.
• ★열쇠 형태의 예시는 일절 옮기지 않았습니다. 원문에는 여러 서비스의 실제 형식이 예로 나오는데, 그런 문자열을 글에 싣지 않는 것이 이 블로그의 원칙입니다.
• ★설정 이름·항목명·주소·식별자도 전부 풀어서 적었습니다. 실제로 구성할 때는 원문 표기를 그대로 보셔야 합니다.
• ★조직 계정에서 쓰는 제품군의 일부이고 시험 단계 표기로 제공됩니다. 개인 계정에는 접근 경로가 없습니다.
• 자체 호스팅 환경에서는 환경 변수 방식이 아직 지원되지 않습니다. 도입 전에 이 조건부터 확인하세요.

✨ 정리하면

가짜를 쥐여주고 나갈 때 바꿔칩니다. 덕분에 일하는 쪽은 진짜 값을 끝까지 못 보지만, 그 값을 가지고 뭔가를 계산하는 방식은 깨집니다. 특히 받아온 토큰은 안 가려진다는 점, 같은 작업 공간이면 누구나 쓸 수 있다는 점은 미리 알고 가세요. 넣을 자리가 없던 시절 이야기는 클라우드 환경과 API 키, 열쇠 자체를 안 만드는 쪽은 키 없이 부르는 API, 같은 제품군의 기억 정리는 AI가 꾸는 꿈, 전체 지출 흐름은 AI 지출 관리 허브에 모아뒀습니다.

※ 출처: Claude 관리형 에이전트 자격증명 보관 기능 공식 문서(2026년 8월 27일 열람). 조직 계정 전용이며 시험 단계 표기로 제공돼 항목과 제약이 바뀔 수 있습니다. 실제 구성 전에는 원문을 확인하시길 권합니다.