덕삼
블로그

폐쇄망에서 에이전트가 없는 도구를 만나면 기록만 하고 멈춘다 — 재시도 대신 반입 목록

인터넷이 없는 PC 에서 에이전트가 없는 도구를 만나면, 무엇을 하게 해야 할까?

답부터 적는다. 설치를 다시 시도하지 말고 기록하고 멈추게 한다. 없는 명령은 셸이 대신 기록하고, 없는 패키지는 에이전트가 한 줄 명령으로 기록한다. 사람은 그 기록을 주 1회 모아 필요한 것만 반입한다. 이 구조로 무엇이 얼마나 나아졌는지는 아직 재지 못했다. 아래는 구조와 함정이다. 확인한 날은 2026-11-18 이다.

폐쇄망 울타리 안에서 로봇이 도구 선반의 빈 칸을 보고 쪽지에 없음이라고 적어 반입 요청 우편함에 넣는다. 울타리 바깥 인터넷 구름과는 연결이 끊겨 있고, 요청은 바깥의 인터넷 PC 로 간다. 울타리 문으로는 주 1회 상자가 들어온다

그림으로 줄이면 이렇다. 로봇은 없는 공구를 사러 나가지 않는다. 쪽지에 적어 우편함에 넣고, 일주일에 한 번 들어오는 상자를 기다린다.

근거는 은행 개발 조직의 3인 팀 저장소다. 개인 폴더에 폐쇄망 에이전트 도구 환경 가이드가 있다. 가이드의 스크립트와 관제 서버 코드도 저장소에 들어 있다. 저장소가 비공개라 커밋 해시는 독자가 열어 볼 수 없다.

폐쇄망에서는 실패를 빨리 끝내고 남겨야 한다

가이드는 문제를 이렇게 적는다. 에이전트가 실행 중에 인터넷 설치를 시도하게 두면, 폐쇄망에서는 실패한 뒤 다시 시도하는 루프에 빠진다. 다시 시도해도 결과는 같다. 인터넷이 없다는 원인이 그대로이기 때문이다.

그래서 이 저장소의 규칙은 두 갈래다. 실패를 빨리 끝내고, 실패를 기록으로 남긴다. 남긴 기록은 다음 반입 목록이 된다.

반입은 여섯 단계로 돈다

가이드는 반입 사이클을 여섯 단계로 나눈다. 단계마다 맡는 것이 다르다.

단계하는 일맡는 것
1. 감지없는 명령, 로컬 저장소에 없는 패키지를 만난다셸 훅, 설치 실패
2. 기록기록 파일(JSONL)에 한 줄을 더한다agent-missing
3. 집계중복을 지우고 요청 횟수 순으로 줄 세운다missing-report.py
4. 다운로드인터넷 PC 에서 생성된 fetch.sh 를 돌린다사람
5. 반입보안 심의 뒤 도구 폴더에 놓는다사람
6. 보관처리한 기록을 보관 파일로 옮기고 새 주기를 시작한다관제 화면의 정리 버튼

가이드는 이 사이클을 주 1회 돌리라고 권한다. 가이드의 기대는 이렇다. 한 번 반입한 도구는 다시 기록되지 않으니, 몇 주 지나면 필요한 도구만 남는다.

없는 명령은 셸이 기록한다

bash 는 없는 명령을 실행하면 command_not_found_handle 함수를 부른다. zsh 는 같은 일을 command_not_found_handler 로 한다. 이 함수에 기록 명령을 넣어 두면 에이전트가 기록을 잊어도 바이너리 누락은 남는다.

# 도구 폴더의 env.sh 일부
export BASH_ENV=$AGENT_TOOLS/env.sh   # 비대화형 bash 도 시작할 때 이 파일을 읽는다
command_not_found_handle() {
  "$AGENT_TOOLS/bin/agent-missing" binary "$1" "" "command not found: $*" >/dev/null 2>&1 || true
  echo "bash: $1: command not found (반입 요청 로그에 기록됨)" >&2
  return 127
}

핵심은 BASH_ENV 다. 에이전트가 부르는 셸은 대개 bash -c 같은 비대화형 셸이라 .bashrc 를 읽지 않는다. 비대화형 bash 는 대신 BASH_ENV 에 적힌 파일을 읽는다. 그래서 에이전트를 띄우기 전에 env.sh 를 한 번 읽어 두면 자식 셸마다 훅이 살아 있다.

함수가 남기는 문장도 일을 한다. “기록됨"이라는 말을 에이전트가 읽고, 같은 명령을 다른 경로에서 찾아 헤매지 않게 하려는 장치다. 이 효과도 재지는 않았다.

관제 화면은 사용자 홈의 .zshenv·.zshrc·.bashrc 가 env.sh 를 읽는지 따로 보여 준다. 훅은 셸 설정에 걸려 있어야 일하기 때문이다.

없는 패키지는 에이전트가 한 줄로 기록한다

pip 나 bun 의 설치 실패는 셸 훅이 잡지 못한다. 명령 자체는 있기 때문이다. 이때는 에이전트가 직접 기록한다. 지침 파일에 넣은 규칙을 일반화하면 이렇다.

## 도구·패키지가 없을 때
1. 설치는 한 번만 시도한다. 다시 시도하지 않는다.
2. 실패하면 바로 기록한다. agent-missing <binary|pypi|npm|system> <이름> [버전] "<필요한 이유>"
3. 표준 라이브러리나 있는 도구(rg, fd, jq)로 대신할 수 있으면 대신하고, 대신했다고 응답에 적는다.
4. 대신할 수 없으면 작업을 멈추고 "반입 필요: <이름>" 으로 보고한다.

기록을 JSON 으로 직접 쓰게 하지 않은 데는 이유가 있다. 가이드는 LLM 에게 JSON 을 쓰게 하면 형식이 깨진다고 적는다. 기록 명령은 인자만 받고 시각, 작업자, 호출한 에이전트, 작업 폴더를 스스로 붙여 한 줄을 쓴다. 호출한 에이전트는 셸에 남은 환경변수로 가린다.

패키지 설치는 로컬 폴더만 보게 해서 바로 끝낸다

사내에 패키지 미러가 없어 로컬 폴더를 저장소로 쓴다. 환경변수 네 개로 pip 와 uv 가 인터넷 대신 그 폴더만 보게 한다.

export PIP_NO_INDEX=true
export PIP_FIND_LINKS=$AGENT_TOOLS/wheels
export UV_NO_INDEX=1
export UV_FIND_LINKS=$AGENT_TOOLS/wheels

이렇게 두면 없는 패키지는 네트워크 시간 초과를 기다리지 않고 “찾을 수 없다"로 바로 끝난다. 재시도 루프를 끊으려면 실패가 빨라야 한다. 반입한 wheel 파일은 관제 화면에서 이 폴더로 올릴 수 있다.

npm 쪽은 덜 깔끔하다. 인터넷 PC 에서 npm pack 으로 받은 tgz 를 들여와 파일로 설치한다. 그런데 npm pack 은 그 패키지 하나만 받고 의존성은 받지 않는다. 의존성이 많으면 인터넷 PC 에서 npm install 한 폴더를 통째로 들여오는 편이 낫다고 가이드는 적는다.

집계는 이미 들어온 것을 지운다

집계 스크립트는 기록을 이름별로 묶고 요청 횟수 순으로 줄 세운다. 결과는 반입 요청 목록(md)과 인터넷 PC 에서 돌릴 fetch.sh 두 파일이다. pypi 항목은 폐쇄망의 플랫폼과 Python 버전을 지정해 pip download 하고, npm 항목은 npm pack 한다.

이미 들어온 도구는 목록에서 해결로 표시하고 fetch.sh 에서 건너뛴다. 기준은 구비 카탈로그에 있는지, 추천 목록의 확인 명령이 통과하는지다. 관제 화면의 “반입 완료 정리” 버튼은 해결된 기록을 보관 파일로 옮기고 남은 기록만 둔다.

기록만으로는 앞으로 필요할 도구를 미리 알 수 없다. 그래서 커밋 63ad989 에서 추천 반입 목록을 더했다. 그때 29개였고 지금 38개다. 항목마다 우선순위, 용량, 라이선스, 반입 방법, 확인 명령이 있다. 기록은 겪은 부족을, 추천 목록은 겪기 전의 부족을 맡는다.

기록에는 잡음과 민감 정보가 섞인다

운영하면서 나온 함정은 셋이다. 표로 묶었다.

함정무슨 일이 있었나지금 처리
잡음마우스 이스케이프 문자열 조각, 한글 오타, 숫자로 시작하는 이름, 한 글자 오타가 “없는 명령"으로 기록됐다훅과 기록 명령에서 영문자로 시작하는 2~64자 이름만 받는다(커밋 69e9390)
경로 노출기록에 작업 폴더가 남는다. 저장소에 올라간 다섯 줄 모두 계정 이름이 든 홈 경로를 담았고, 한 줄은 내부 호스트 이름도 담았다가이드가 업무 경로 이름을 확인하라고 적어 두었다. 자동 처리는 없다
버전 고르기집계가 버전을 문자열로 정렬해 마지막 값을 쓴다. 1.10 과 1.9 가 함께 기록되면 1.9 를 고른다가이드에 한계로 적혀 있고 코드는 그대로다

기록 파일을 git 으로 추적한다면 두 번째 줄을 먼저 봐야 한다. 기록은 에이전트가 남기는 작업 흔적이라 생각보다 많은 것을 담는다.

효과는 아직 재지 못했다

저장소에 올라간 기록은 다섯 줄이다. 2026-10-17 부터 10-22 사이에 남았고 모두 없는 명령이다. 그중 두 도구는 나중에 구비 목록에 들어갔다. 하나는 기록 35분 뒤, 다른 하나는 약 6일 뒤다. 다만 두 커밋 메시지 모두 그 기록을 들인 이유로 적지 않았다. 기록 때문에 들였는지는 알 수 없다.

폐쇄망 PC 의 실제 기록은 저장소 밖에 있어 세지 못했다. 그래서 재시도가 얼마나 줄었는지, 반입까지 며칠 걸리는지 말할 숫자가 없다. 재려면 아래 세 가지를 남겨야 한다.

잴 것남길 곳
세션마다 같은 설치를 다시 시도한 횟수에이전트 실행 기록
기록부터 반입까지 걸린 날기록 시각과 보관 시각
기록 가운데 반입으로 해결된 비율보관 파일의 해결 표시

이 판단이 틀리는 경우

  • 사내에 패키지 미러가 있으면 패키지 기록은 필요 없다. 미러에 올리는 절차가 반입을 대신한다.
  • 에이전트가 셸 설정을 물려받지 않으면 훅이 돌지 않는다. sh 로 명령을 부르거나 환경변수를 비우고 실행하는 샌드박스가 그렇다.
  • 보안 심의가 몇 주씩 걸리면 주 1회 사이클이 성립하지 않는다. 그때는 추천 목록으로 미리 들이는 쪽이 더 중요하다.
  • 패키지 기록은 에이전트가 규칙을 지킬 때만 남는다. 셸 훅과 달리 강제가 아니다.

정리

폐쇄망의 에이전트에게 필요한 것은 설치하는 능력보다 멈추는 규칙이다. 실패는 빨리 끝내고, 셸과 기록 명령이 그 실패를 한 줄씩 남기고, 사람은 그 줄을 모아 반입한다.

지금 확인할 것은 하나다. 에이전트가 쓰는 셸에서 bash -c '없는명령' 을 실행해 기록 파일에 한 줄이 생기는지 본다.