이 글에는 제휴 링크가 없고 OpenAI·앤트로픽과 아무 관계가 없습니다. 제가 직접 만든 중계기의 개발 기록을 바탕으로 썼습니다. 삽화는 GPT 이미지 생성, 도식은 직접 제작했습니다.
로그인했는데 401 — 서랍 속 옛 열쇠가 문을 막다 (LLM 중계기 개발기)
현관 도어락을 휴대폰 키로 바꿨다고 해 볼게요. 휴대폰을 대면 문이 열려야 하는데, 도어락은 “등록되지 않은 카드입니다”라는 소리만 냅니다. 알고 보니 휴대폰 케이스 안에 예전에 쓰던 카드키가 그대로 꽂혀 있었어요. 도어락은 휴대폰보다 그 카드를 먼저 읽었고, 그 카드는 이미 등록이 지워진 카드였던 거죠.
새 열쇠는 멀쩡한데, 잊고 있던 옛 열쇠가 먼저 나서서 문을 막은 셈이에요.
제가 만든 LLM 중계기에서도 똑같은 일이 있었어요. Claude에 분명히 로그인해 두었는데, 중계기가 부르면 “인증 실패”가 돌아왔습니다.
이 글은 LLM 중계기 개발기의 8편입니다. 지난 7편 「AI가 엉뚱한 메모를 읽고 왔다」에서는 AI 프로그램이 실행된 폴더의 메모를 읽어 오는 바람에 빈 전용 폴더를 마련한 이야기를 했어요. 이번에는 폴더가 아니라 컴퓨터 전체에 붙어 있던 메모 한 줄이 말썽을 부린 이야기입니다.
결론 요약
- 증상 — Claude 명령어 도구에 로그인해 둔 컴퓨터에서, 중계기가 Claude를 부르면 401(인증 실패)이 돌아왔어요
- 원인 — 컴퓨터 전체 설정인 환경 변수에 API 키가 남아 있었고, Claude는 로그인보다 그 키를 먼저 썼어요. 그 키로는 문이 열리지 않았고요
- 해결 — 중계기가 Claude를 켤 때 건네는 설정 사본에서 그 키만 지워 로그인을 쓰게 했어요. 연결 결과에는 어떤 열쇠를 썼는지 함께 적어요
🚪 1. 증상 — 로그인했는데 401
중계기를 만든 첫날, 7월 13일의 일이에요. 4편의 첫날 기록에서 한 줄로 지나갔던 바로 그 문제입니다.
어떤 윈도 컴퓨터에서 중계기에 Claude를 연결하면 실패했어요. 상황은 이랬습니다.
- 명령창에서 Claude 명령어 도구의 버전 확인은 멀쩡히 됐어요. 설치에는 문제가 없었죠
- 계정 로그인도 해 둔 상태였어요
- 그런데 중계기가 Claude에게 말을 걸면 401과 함께 “Invalid authentication credentials”, 우리말로 “인증 정보가 올바르지 않습니다”라는 답이 돌아왔어요
401은 웹에서 흔히 쓰는 상태 번호로, “누구인지 확인이 안 된다”는 뜻이에요. 열쇠가 없거나, 열쇠가 맞지 않을 때 나옵니다. 로그인을 해 두었는데, 열쇠가 맞지 않는다는 답이 온 거예요.
버전 확인은 서비스의 문을 두드리지 않는 일이라 열쇠 문제가 드러나지 않았어요. 문 앞까지 가서야 탈이 난 거예요.
📝 2. 환경 변수 — 컴퓨터 전체에 붙여 둔 메모
원인을 말하려면 환경 변수(environment variable)부터 알아야 해요.
환경 변수는 컴퓨터 전체에 붙여 둔 메모 같은 설정값이에요. ‘이름 = 값’ 모양의 짧은 메모가 여러 장 붙어 있고, 프로그램들은 켜질 때 이 메모 묶음을 읽어 갑니다.
- “임시 파일은 이 폴더에 둬” 같은 메모
- “이 프로그램을 찾으려면 이 폴더들을 뒤져 봐” 같은 메모
- 그리고 가끔은 “이 서비스의 열쇠(API 키)는 이거야” 같은 메모
환경 변수는 평소에 열어 볼 일이 거의 없어요. 한 번 넣어 두면 서랍 속 물건처럼 눈에 띄지 않은 채 그대로 남아 있죠.
여기에 한 가지 규칙이 더 있어요. 프로그램이 다른 프로그램을 켜면, 켜진 쪽은 켠 쪽의 메모 묶음을 그대로 물려받아요. 따로 말하지 않으면 부모가 들고 있던 메모가 고스란히 자식에게 넘어가는 거죠.
중계기는 Claude에게 질문을 전할 때 Claude 프로그램을 직접 켜서 부릅니다(6편에서 다룬 이야기예요). 그러니 중계기가 들고 있던 메모 묶음, 곧 그 컴퓨터의 환경 변수가 전부 Claude에게 넘어갔어요.
🔑 3. 원인 — 열쇠가 두 개였고, 통하지 않는 쪽이 먼저 꽂혔다
그 컴퓨터의 환경 변수에는 ANTHROPIC_API_KEY라는 이름의 메모가 남아 있었어요. Claude를 만든 앤트로픽의 API 키를 담는 자리예요.
Claude 입장에서는 열쇠가 두 개였던 셈이에요.
- ① 환경 변수에 남아 있던 API 키
- ② 명령어 도구에 해 둔 계정 로그인
그리고 중계기가 Claude를 부르는 방식에서는, 환경 변수에 API 키가 있으면 Claude가 로그인보다 그 키를 먼저 썼어요. 그 키는 문을 열지 못하는 키였고, 결과는 401이었습니다. 로그인은 멀쩡히 살아 있었는데 차례가 오지 않은 거예요.
도어락 비유로 돌아가면, 휴대폰 케이스에 꽂힌 옛 카드를 도어락이 먼저 읽은 것과 같아요. 새 열쇠(로그인)에는 아무 문제가 없었어요.
🧰 4. 해결 — 건네는 메모에서 그 열쇠만 뺀다
고치는 방법은 단순했어요. 중계기가 Claude를 켤 때 건넬 메모 묶음을 직접 만들어 주는 것이에요.
- 중계기가 들고 있는 메모 묶음을 복사해요
- 사본에서 API 키 메모와, 같은 역할을 하는 인증 토큰 메모를 지워요
- 그 사본을 Claude에게 건네요
이제 Claude 손에 남은 열쇠는 계정 로그인 하나뿐이라, 로그인으로 문을 엽니다. 첫날 오후 1시 44분의 수정이었어요.
이 방법에서 신경 쓴 점이 두 가지 있어요.
- 컴퓨터의 설정은 건드리지 않아요 — 지우는 건 중계기가 Claude에게 건네는 사본뿐이에요. 컴퓨터의 환경 변수는 그대로 남아서, 그 키를 일부러 쓰는 다른 프로그램은 영향을 받지 않아요. 옛 열쇠를 버리지 않고 상자에 따로 넣어 두는 셈이죠
- 로그인 파일도 건드리지 않아요 — 중계기는 Claude의 로그인 정보를 직접 만들거나 고치지 않아요. 로그인은 사람이 명령어 도구에서 한 그대로 씁니다
같은 일이 다시 생기지 않도록 자동 검사도 붙였어요. “컴퓨터에 API 키가 있어도 Claude에게 건네는 사본에는 없어야 한다”는 검사예요.
혹시 Claude 명령어 도구에 로그인했는데도 다른 프로그램을 거치면 인증 오류가 난다면, 환경 변수에 이 이름의 메모가 남아 있는지 확인해 볼 만해요. 확인할 때 키 값을 화면에 띄우거나 남에게 보내지는 마시고요.
🏷️ 5. 남긴 규칙 — 어떤 열쇠를 썼는지 말하고, 실패는 갈래를 나눈다
이 사고에서 드러난 빈틈은, “인증 실패”라는 말만으로는 어느 열쇠가 실패했는지 알 수 없다는 점이었어요. 그래서 규칙을 몇 가지 남겼어요.
하나, 열쇠의 순서는 중계기가 정한다. Claude는 명령어 도구의 로그인으로 부른다고 정하고, 그 순서를 흔드는 메모는 건네지 않아요.
둘, 어떤 열쇠를 썼는지 함께 적는다. 연결에 성공하면 연결 완료 표시 옆에 어떤 열쇠로 문을 열었는지가 함께 적혀요. 컴퓨터에 API 키가 남아 있으면 “인증: CLI 로그인 (머신의 ANTHROPIC_API_KEY는 무시함)“처럼요. 열쇠의 값은 보여 주지 않고, 이것도 자동 검사로 지켜요.
셋, 401에도 원인이 여럿이다. 닷새 뒤에는 401이 났을 때 할 일을 정확한 명령으로 안내하도록 고쳤어요. 새로 설치한 컴퓨터에서 가장 흔한 401은 아직 로그인을 하지 않은 경우였거든요. 같은 401이라도 틀린 열쇠가 먼저 쓰였을 수도, 로그인이 없을 수도, 로그인이 만료됐을 수도 있어요. 로그인이 만료됐다는 안내문이 정상 답처럼 도착한 날도 있었는데, 이 이야기는 17편에서 따로 다룰게요.
지금의 중계기는 Claude의 실패를 ‘설치가 안 됨’, ‘로그인이 필요함’, ‘사용 한도를 다 씀’처럼 갈래로 나눠, 갈래마다 할 일을 다르게 안내해요.
쓰는 쪽 프로그램에 실패를 돌려줄 때도 번호를 나눠 씁니다. 자주 보게 될 세 가지만 추리면 이래요.
| 번호 | 쉬운 말로 | 중계기에서는 |
|---|---|---|
| 401 | 누구인지 확인이 안 돼요 — 열쇠 문제 | 그 AI가 중계기에 연결돼 있지 않아요. 관리 화면에서 연결부터 해야 해요 |
| 403 | 누구인지는 알지만 들어갈 수 없어요 | 관리 화면에서 그 AI나 모델을 ‘사용 안 함’으로 꺼 두었어요 |
| 429 | 너무 많이, 너무 자주 왔어요 | 대기 줄이 가득 찼거나, 분당 한도에 걸렸거나, 사용 한도를 다 썼어요 |
같은 429라도 ‘잠깐 붐빔’과 ‘사용 한도를 다 씀’은 따로 표시해요. 한도를 다 쓴 경우는 금방 다시 시도해도 풀리지 않으니, 기다릴 시간을 길게 알려 줍니다.
정리
① 환경 변수는 컴퓨터 전체에 붙여 둔 메모 같은 설정값이고, 프로그램이 켠 프로그램은 그 메모 묶음을 그대로 물려받아요 ② 로그인을 했는데도 401이 난 건, 환경 변수에 남아 있던 API 키를 Claude가 로그인보다 먼저 썼기 때문이에요 ③ 중계기는 Claude에게 건네는 설정 사본에서 그 키만 지워 로그인을 쓰게 하고, 어떤 열쇠를 썼는지와 실패의 갈래를 함께 알려 줘요 — 다음 편은 “모델마다 다른 스펙을 카드로”입니다
2026년 10월 1일 기준입니다. 제가 만든 중계기의 개발 기록을 바탕으로 썼고, 특정 기업·서비스의 공식 입장이 아닙니다.