Claude 자체 호스팅 인증 오류 — 30분 뒤 갑자기 전부 실패합니다

사내 서버에서 AI 세션을 돌리다 보면 세션마다 준비 작업을 끼워 넣고 싶어집니다. 자격을 미리 발급하거나, 언어 도구를 깔거나, 자원 한도를 걸거나. 그런데 공식 문서를 읽어보니 여기에 30분쯤 멀쩡하다가 갑자기 전부 인증 오류로 죽는 함정이 있습니다. 처음엔 정상으로 보여서 더 잡기 어려운 종류예요. 저장 안 한 작업이 사라지는 지점, 설정을 고쳐도 반영이 안 되는 이유까지 같이 정리했습니다.

📌 30초 요약

• ★★뒤로 돌리면 30분 뒤 죽습니다 — 갱신 값이 오는 통로가 끊깁니다.
• ★세 번째 통로는 건드리면 안 됩니다 — 살아 있는지 재는 데 씁니다.
• ★저장 안 한 작업을 건질 기회는 한 번뿐입니다.
• ⚠️ 그 마무리 스크립트가 실패해도 조용히 넘어갑니다.
• 내려받기 준비가 실패하면 저장소 종류에 따라 갈립니다.
• 설정은 켤 때 한 번만 읽습니다 — 고쳐도 다시 켜야 합니다.

뒤로 돌리면 30분 뒤에 죽습니다

세션 준비 스크립트는 본체 실행 파일 자리에 대신 끼워 넣는 구조입니다. 세션마다 한 번 돌고, 마지막에 본체로 넘겨주면서 자기 자신을 갈아치우는 방식으로 끝내야 해요. 그래야 신호와 종료 값이 제대로 전달됩니다.

여기서 함정이 나옵니다. 자식 프로세스의 표준 입력이 실은 관제 통로예요. 짧은 수명의 인증 값이 만료 전에 갈아 끼워지는데, 그 새 값이 표준 입력으로 들어옵니다. 세션을 끝내라는 신호도 같은 통로로 오고요. 그런데 준비 스크립트가 자식을 그냥 뒤로 돌려버리면 이 통로가 끊깁니다.

⚠️ 증상이 늦게 옵니다

통로가 끊겨도 처음엔 아무 문제가 없어 보입니다. 처음 받은 인증 값이 30분쯤 살아 있으니까요. 그러다 그 값이 만료되는 순간 모든 요청이 한꺼번에 인증 실패로 떨어집니다. 뒤로 돌려야만 하는 사정이 있다면 — 정리 작업을 걸어두려고 그러는 경우가 많죠 — 표준 입력을 다른 번호에 따로 챙겨두었다가 자식에게 다시 이어 붙여야 합니다. 그리고 세 번째 통로는 닫거나 다른 데 쓰면 안 됩니다 — 세션이 살아 움직이는지 재서 대기 시간을 판단하는 데 쓰거든요. 자식의 출력만 다른 데로 돌리는 건 괜찮습니다.

같은 결로 조용히 망가지는 게 하나 더 있습니다. 사용자가 세션에 붙인 첨부를 내려받을 때 쓰는 값이 환경에 들어오는데, 넘겨주는 방식으로 끝내면 자동으로 딸려 갑니다. 반대로 환경을 새로 짜서 자식을 띄우면 이 값이 빠지고, 첨부 내려받기가 아무 소리 없이 멈춥니다. 그리고 모델을 부를 주소는 바꾸지 말라고 못을 박습니다 — 여기서 쓰는 인증 값은 다른 제공자가 받아주지 않는 종류라, 추론만은 다른 곳으로 못 돌립니다. 도구를 처음 고를 때는 안 보이지만, 조직에 깔고 나면 이런 배관이 전부 내 몫이 됩니다.

저장 안 한 작업을 건질 기회는 한 번

세션이 끝나면 작업 폴더를 정리하기 직전에 딱 한 번 내 스크립트를 돌려줍니다. 문서는 여기를 저장 안 한 작업을 살릴 유일한 기회라고 표현해요. 한 대에서 여러 세션을 받는 설정이면 이 스크립트가 끝나자마자 작업 폴더가 지워지고, 한 대에 한 세션만 두는 설정에서도 다음 세션이 시작할 때 통째로 되돌려집니다. 어느 쪽이든 커밋 안 한 변경은 안 남습니다.

다만 기대를 낮춰야 하는 대목이 둘 있습니다. 첫째, 이 스크립트의 종료 상태는 세션 결과에 아무 영향을 안 줍니다 — 실패해도 기록만 남고 넘어가요. 둘째, 기계가 갑자기 회수되거나 전원이 나가면 아예 안 돕니다. 그런 경우까지 막고 싶으면 세션 안쪽에서 주기적으로 스스로 저장하게 걸어두라는 게 문서의 권고입니다. 대기 시간도 정해져 있어서, 정해진 시간을 넘기면 기다려주지 않습니다.

💡 세션이 저장소에 심어둔 설정을 조심하라고 합니다

이 마무리 스크립트는 러너 쪽 권한으로 돕니다. 그런데 작업 폴더 안의 버전 관리 설정은 세션이 얼마든지 고쳐둘 수 있어요. 그래서 문서의 예제는 감시 기능·훅 경로·서명 프로그램 설정을 명령 줄에서 강제로 덮어써서 세션이 심어둔 값이 실행되지 않게 막습니다. 밀어 넣을 주소와 자격 도우미도 마찬가지 — 세션이 갖지 못한 자격을 이 스크립트가 들고 있다면, 어디로 밀어 넣을지까지 운영자가 고정해야 세션이 방향을 틀지 못합니다.

실패했을 때 갈리는 지점들

소스를 내려받는 단계도 내 스크립트로 갈아 끼울 수 있습니다. 사내 거울에서 받아오거나, 압축본을 풀어 쓰거나. 여기서 실패했을 때가 흥미로운데, 저장소 종류에 따라 결과가 갈립니다.

상황	어떻게 되나
결과를 밀어 넣는 저장소	세션 실패 — 오류 끝부분이 사용자 화면에 뜸
읽기만 하는 저장소	건너뛰고 계속 — 남은 저장소로 진행
건너뛰었더니 남는 게 없을 때	그래도 세션 실패
기계를 띄우는 쪽 스크립트	돌려준 값에 따라 재시도 / 관리자 개입으로 갈림

세션이 밀릴 때마다 기계를 한 대씩 띄우는 방식도 있는데, 여기 붙는 스크립트의 계약이 꽤 엄격합니다. 같은 주문이 두 번 와도 기계는 한 대만 떠야 하고, 스스로 재시도하면 안 됩니다 — 기계가 안 올라오면 정해진 시간 뒤에 새 주문이 다시 옵니다. 그리고 돌려주는 값이 셋으로 갈려요. 정상 제출이면 그대로 진행, 가벼운 실패면 잠시 쉬었다 다시 제안, 그보다 무거운 값이면 관리자가 화면에서 직접 다시 시도를 눌러줄 때까지 그 세션은 아예 막힙니다. 그래서 실패 사유는 사람이 읽고 조치할 수 있게 남기되 비밀은 절대 적지 말라고 합니다.

설정은 켤 때 한 번만 읽습니다

운영하면서 가장 헷갈리는 대목입니다. 세션마다 설정 폴더를 따로 주는데, 그 내용은 러너가 시작할 때 호스트 설정을 한 번 떠놓은 사본에서 옵니다. 지시문·훅·에이전트·명령·스킬이 전부 여기서 내려와요. 그래서 돌고 있는 기계의 설정을 고쳐도 다시 켜기 전까지는 반영되지 않습니다. 연결 서버를 붙일 때도 같습니다 — 이미지 만들 때 넣거나, 호스트에 넣었으면 러너를 다시 시작해야 하고, 사용자 범위로 넣지 않으면 세션에 아예 안 실립니다.

권한 쪽에도 함정이 하나 있습니다. 저장소에 커밋한 규칙에 파일 도구 이름만 덜렁 적어두면 안 됩니다. 경로와 무관하게 걸려서 작업 폴더가 아니라 기계 어디든 쓰기를 허용하는 셈이 되거든요. 러너가 이걸 잡아내고, 엄격하게 걸어두면 세션을 아예 안 띄웁니다. 애초에 클라우드 세션은 파일 수정을 미리 허용해 두니 저장소 쪽에 규칙이 없어도 됩니다. 굳이 적겠다면 작업 폴더 범위로 좁히세요. 그리고 저장소가 스스로에게 자동 승인 모드를 줄 수는 없습니다 — 그 값은 이미지나 사용자 단계 설정에서만 먹힙니다. 모델을 직접 받아 내 장비에 올리는 흐름과 비교하면, 세션 자체를 호스팅하는 쪽은 이렇게 운영 규칙이 훨씬 촘촘합니다.

자주 묻는 질문 (FAQ)

Q. 준비 스크립트를 두 가지 방법으로 지정할 수 있던데, 둘 다 하면요?

파일을 직접 가리키는 쪽이 이깁니다. 모아둔 폴더에 넣어둔 쪽은 조용히 무시돼요. 안 도는 것처럼 보이면 여기부터 확인하세요.

Q. 세션 안에 끼우는 훅과 같은 건가요?

다릅니다. 세션 안쪽 훅은 세션이 도는 동안 끼어들고, 여기서 말하는 것들은 세션 바깥에서 세션을 감싸며 돕니다. 도는 위치도, 권한도 달라요.

Q. 이 스크립트들은 어디에 두는 게 안전한가요?

세션이 그 스크립트와 같은 권한으로 돕니다. 그래서 문서는 읽기 전용으로 붙이거나 아예 이미지에 구워 넣으라고 합니다. 안 그러면 세션 코드가 고칠 수 있어요.

Q. 승인 창이 자꾸 뜨는데 없앨 수 있나요?

준비 스크립트에서 모드를 고정할 수 있습니다. 러너가 붙여주는 값 뒤에 내가 붙이면 뒤에 온 게 이깁니다. 단, 문서는 바깥으로 나가는 연결을 기본 차단해 둔 환경에서만 그렇게 하라고 못 박습니다.

Q. 세션이 다른 기계로 넘어가면 마무리 스크립트는 언제 도나요?

상황에 따라 순서가 다릅니다. 일을 마치고 쉬는 중이었다면 스크립트를 끝까지 돌린 뒤에 넘깁니다. 반대로 사용자 답을 기다리는 중이었다면 먼저 넘기고 그다음에 돌아서, 스크립트가 도는 사이에 다른 기계에서 세션이 이어질 수 있습니다.

✨ 정리하면

자체 호스팅의 확장 지점은 편하지만, 틀렸을 때 즉시 안 터지고 한참 뒤에 터지는 종류가 많습니다. 통로를 끊으면 30분 뒤에, 설정을 고치면 다시 켤 때까지, 첨부는 아무 소리 없이. 넘겨주는 방식으로 끝내고, 설정은 이미지에 굽고, 마무리 스크립트는 실패해도 조용하다는 걸 전제로 짜세요. 누가 만든 세션인지 확인하는 쪽은 신원 확인 편에, 비용과 권한 설계는 AI 지출 관리 허브에 정리해 두었습니다.

출처: Claude Code 공식 문서 「자체 호스팅 환경의 세션 맞춤 설정」 (2026-08-31 열람). 자체 호스팅 환경은 공개 베타 단계이며 팀·기업 요금제에서 관리자가 켜야 씁니다. 일부 동작은 러너 버전에 따라 다르며, 세부 절차는 변경될 수 있습니다.