로컬에서 Claude Code를 쓸 때는 .env 파일에 API 키를 넣어두고 그냥 쓰면 끝입니다. 그런데 클라우드 세션은 매번 깨끗한 컨테이너에서 시작하기 때문에 그 파일이 없습니다. 외부 API를 호출해야 하는 작업이 걸렸을 때, 키를 채팅창에 붙여넣어도 되는지부터 고민이 됐습니다.
어떤 작업이었나
환율 정보를 가져오는 외부 API를 호출해서 응답 형식을 확인해야 하는 작업이었습니다. 그 API는 헤더에 키를 넣어야 응답을 주는 구조였는데, 로컬 세션이 아니라 클라우드에서 띄운 세션이라 키를 어디서 가져와야 할지가 불분명했습니다. 채팅에 키를 그냥 적어서 넘기면 세션 기록에 평문으로 남는다는 게 걸렸고, 컨테이너 환경변수로 넣는 것도 결국 설정 파일에 평문으로 저장되는 거라 썩 안전한 방법은 아니었습니다.
AI를 어떻게 활용했나
일단 키 없이 호출해봤습니다. 예상대로 401이 돌아왔습니다.
$ curl -s -o /dev/null -w "%{http_code}\n" https://api.exchangerate-example.com/v1/latest
401
여기서 Claude Code가 request_credential이라는 도구를 호출했습니다. 호스트와 이유만 알려주면 되는 구조였습니다.
request_credential({
host: "api.exchangerate-example.com",
reason: "환율 조회 API가 인증 헤더 없이 401을 반환해서, 응답 형식을 확인하려면 키가 필요합니다.",
suggested_type: "bearer"
})
이 호출이 실행되자 화면에 보안 입력 폼이 떴고, 거기에 실제 키 값을 입력했습니다. 그 값이 채팅으로 돌아오는 게 아니라, 세션이 붙어 있는 환경에 암호화된 "네트워크 시크릿"으로 저장되는 구조였습니다. Claude Code는 이후 그 호스트로 나가는 모든 요청에 프록시가 알아서 키를 끼워 넣는다는 결과만 받았고, 키 값 자체는 세션 쪽에서 한 번도 보지 못했습니다.
처음에 걸렸던 부분
폼에서 저장을 마치고 바로 같은 curl을 다시 돌렸는데, 또 401이 나왔습니다. 저장이 실패했나 싶어 당황했는데, 알고 보니 프록시가 새로 저장된 시크릿을 반영하는 데 약간의 지연이 있었습니다. 1분 정도 기다렸다가 다시 호출하니 그제서야 200과 함께 정상 응답이 돌아왔습니다. 저장 직후 한 번 더 실패해도 바로 설정을 건드리지 말고, 잠깐 기다렸다가 한 번만 더 재시도해보는 게 맞는 순서였습니다.
또 헷갈렸던 부분은 이 키가 저장되는 범위였습니다. 같은 환경을 공유하는 다른 세션(같은 계정의 다른 클라우드 세션)에서도 그 호스트로 나가는 요청에는 똑같이 키가 자동으로 붙는다고 했습니다. 혼자 쓰는 환경이면 문제가 없지만, 여러 세션이 환경을 공유하는 구조라면 거기서 도는 다른 작업에도 같은 키가 쓰인다는 뜻이라 범위를 한 번 확인해두는 게 나을 것 같았습니다.
결과와 얻은 팁
- 401/403처럼 인증 때문에 막히는 응답을 받으면, 환경변수를 새로 만들기 전에
request_credential로 호스트 하나를 지정해서 요청하는 게 더 안전했습니다. 키 값이 세션 대화 기록이나 설정 파일 어디에도 평문으로 남지 않습니다. - 저장 직후 첫 재시도가 401로 실패하는 건 흔한 일이었습니다. 설정을 의심하기 전에 1분 정도 기다렸다가 딱 한 번만 더 재시도해보는 편이 맞았습니다.
- CLI나 SDK가 키 없이는 아예 시작도 안 되는 경우, 헤더 형식에 맞는 가짜 값을 일단 넣어서 실행시키면 프록시가 그 자리를 실제 값으로 바꿔준다는 점도 알아뒀습니다. 다만 이번 API는 그런 제약이 없어서 직접 쓸 일은 없었습니다.
- 같은 환경을 공유하는 세션이 여러 개라면, 저장한 키가 그 환경의 모든 세션에 적용된다는 걸 염두에 두고 범위를 따져볼 필요가 있었습니다.