클라우드 세션에서 외부 API를 호출하다가 응답이 아예 안 오고 막힌 적이 있습니다. 401이나 403처럼 인증 문제라는 신호도 아니고, 그냥 연결 자체가 끊겼습니다. 로컬에서는 한 번도 본 적 없는 종류의 실패라 처음엔 API 쪽 문제인지부터 의심했습니다.
어떤 작업이었나
번역 API 응답 형식을 확인하려고 curl로 호출했는데, 이런 식으로 끊겼습니다.
$ curl -s https://api.translate-example.com/v1/translate
curl: (35) OpenSSL SSL_connect: Connection reset by peer
키가 없어서 생기는 401/403이 아니라 연결 자체가 끊기는 모양이라 이상했습니다. 같은 API를 로컬 머신에서 호출하면 바로 응답이 왔다는 걸 확인하고서야, 이 컨테이너의 네트워크 자체가 막혀 있을 가능성을 생각하게 됐습니다.
AI를 어떻게 활용했나
Claude Code 클라우드 세션은 아웃바운드 요청이 전부 프록시를 거치고, 그 프록시가 허용된 호스트 목록만 통과시키는 구조였습니다. 지금 세션이 어떤 환경에서 돌고 있는지, 그 환경의 네트워크 설정이 뭔지 알려주는 도구(get_environment)를 호출해봤더니 이런 값이 돌아왔습니다.
{
"network": {
"type": "limited",
"allow_mcp_servers": true,
"allow_package_managers": true,
"allowed_hosts": []
},
"is_default": true
}
allowed_hosts가 빈 배열이었습니다. 패키지 레지스트리(npm, PyPI 같은 곳)와 MCP 서버는 따로 허용돼 있지만, 그 외의 임의 호스트는 하나도 목록에 없는 상태였습니다. 즉 번역 API 같은 일반 외부 서비스는 애초에 통과할 수 없는 설정이었던 겁니다.
이 환경은 "Default"라서, 여기 호스트를 추가하면 이 저장소와 무관한 다른 모든 작업에도 똑같이 영향을 줍니다. 이번 작업은 번역 API 하나만 필요했으므로, Default를 건드리는 대신 이 작업 전용으로 호스트를 추가해달라고 요청하는 쪽을 선택했습니다. 이 요청은 update_environment/create_environment 같은 도구를 통해 나가는데, 둘 다 호출하는 즉시 실행되는 게 아니라 사람이 승인 화면에서 호스트 이름과 이유를 보고 직접 허용해야 적용되는 구조였습니다. 제가 직접 호스트를 추가한 게 아니라, 그 승인 요청이 뜨는 걸 보고서야 "아, 이게 그냥 되는 게 아니구나"를 알았습니다.
결과와 얻은 팁
- 401/403은 키 문제, 연결이 아예 끊기는 건 호스트 자체가 허용 목록에 없다는 신호였습니다. 둘을 구분하지 않고 바로 키를 넣어보려고 했으면 엉뚱한 데서 시간을 썼을 겁니다.
request_credential(API 키 주입)과 환경의 네트워크 허용 목록은 완전히 다른 레이어였습니다. 호스트가 허용 목록에 없으면 키가 있어도 애초에 요청 자체가 나가지 못하고, 반대로 호스트는 열려 있어도 키가 없으면 401이 돌아옵니다. 둘 중 하나만 확인하고 끝내면 안 되는 이유였습니다.- 평소 쓰는 환경이 "Default"처럼 모든 작업이 공유하는 환경이라면, 한 번만 쓸 API를 위해 거기 호스트를 영구로 추가하는 게 맞는 선택인지부터 따져볼 필요가 있었습니다. 일회성 작업이면 범위를 좁혀서 요청하는 쪽이 나중에 어떤 호스트가 왜 열려 있는지 추적하기도 더 쉬웠습니다.