트러블슈팅

이 글은 ‘폰 서버 안정화 일지’ 시리즈의 첫 번째다. 재부팅만 하면 절반쯤의 서비스가 안 올라오던 시절, 원인이 부팅 스크립트의 한 줄이었다는 이야기와, 그걸 고치려고 만든 첫 워치독이 거꾸로 건강한 봇을 매번 죽이던 이야기다. 증상: 재부팅 뒤 Claude 세션이 안 뜬다 폰을 재부팅하면 카카오톡 봇은 살아나는데 Claude Code 세션과 터널 몇 개가 안 올라오는 날이 반복됐다. 재부팅 직후 tmux 세션 목록을 보면 iris만 있고 claude, cloudflare, blogadmin 같은 세션이 없었다. 하루는 수동으로 띄우고 넘어갔지만, 같은 일이 세 번째 반복되자 부팅 스크립트를 처음부터 끝까지 읽었다.

루팅과 Termux 환경까지 다 갖춰놓고도, 정작 카카오톡 봇의 핵심인 IRIS 서버 APK 하나가 설치되지 않아 발목을 잡힌 적이 있다. 원인과 해결법, 그리고 이후 장애 복구 때마다 참고하는 수동 기동 절차를 정리해둔다. Termux 사이드로딩부터 막혔다 Termux 자체를 F-Droid나 GitHub에서 받은 arm64-v8a apk로 설치하려는 시도부터 전부 “패키지를 파싱하는 중 문제가 발생했습니다"로 실패했다. adb install로 우회해봐도 이번엔 INSTALL_FAILED_VERIFICATION_FAILURE로 막혔다. 원인은 Play Protect였다. 설정 → Play 스토어 → Play Protect → “기기에서 앱 검사” 토글이 켜져 있으면, Play 스토어 밖에서 받은 apk의 설치 자체를 사전 검증 단계에서 막아버린다. 이 폰은 개인용이 아니라 전용 서버로만 쓸 것이므로 이 토글을 영구적으로 꺼두기로 했다. 이후 Termux(v0.118.3, GitHub release)는 문제없이 설치됐다.

이번에 인텔 아이맥에 Claude Code CLI를 새로 설치하면서 겪은 EACCES 에러를, 다른 프로젝트에서도 반복해서 마주쳤던 참에 한 번 근본 원인부터 정리해두기로 했다. 에러가 나는 이유 $ npm install -g @anthropic-ai/claude-code npm error code EACCES npm error syscall access npm error path /usr/local/lib/node_modules npm의 전역 설치 기본 경로(/usr/local/lib/node_modules 또는 Homebrew/Node 버전에 따라 다른 시스템 경로)는 macOS·리눅스 배포판 대부분에서 일반 사용자 계정에 쓰기 권한이 없는 시스템 디렉터리다. npm install -g는 이 경로에 패키지를 풀어야 하는데, 권한이 없으니 거부당하는 것이다.

Aider를 실행할 때마다 새 버전이 있다는 안내가 떴다. 안내를 따라 자체 업그레이드를 진행했는데, 완료 메시지에는 분명 0.86.2로 올라갔다고 나왔다. 그런데 이후 aider --version을 찍어보면 여전히 이렇게 나왔다. $ aider --version aider 0.82.3 큰 문제로 이어지진 않았지만, 왜 이런 불일치가 생겼는지는 짚고 넘어갈 만하다. 의심되는 원인들 1. 여러 개의 pip/python 경로 공존 pip install --user aider-chat으로 설치했는데, 시스템에 Python 경로가 여러 개 있는 환경(macOS는 특히 Xcode Command Line Tools의 Python, Homebrew Python, python3.9 등이 뒤섞이기 쉽다)이라면, 업그레이드 명령이 실행되는 pip과 실제로 PATH에서 먼저 잡히는 aider 실행파일이 서로 다른 설치본을 가리킬 가능성이 있다.

4개 모델을 순서대로 벤치마크하던 중, 이상하게 다음 모델의 로딩이 평소보다 느리게 느껴지는 순간이 있었다. ps aux로 확인해보니 원인이 바로 보였다. $ ps aux | grep llama-server simon 41203 539.6 ... llama-server --model .../qwen2.5-coder-14b ... simon 40891 0.0 ... llama-server --model .../deepseek-coder-v2-16b ... 새로 시작한 14B 테스트는 CPU 539.6%로 활발히 계산 중인데, 바로 아래에 방금 전에 테스트했던 DeepSeek 16B 프로세스가 CPU 0%로 여전히 살아있었다. 이미 다른 터미널에서 Aider 세션을 종료했는데도 말이다. keep_alive, 알아서 안 꺼주는 5분 원인은 Ollama의 keep_alive 메커니즘이었다. Ollama는 한 번 로드한 모델을 요청이 끝난 뒤에도 기본 5분간 메모리에 유지한다. 같은 모델로 연속 요청이 들어올 걸 대비한 최적화인데, 이게 여러 모델을 짧은 간격으로 번갈아 테스트하는 상황에서는 오히려 방해가 된다 — 이전 모델이 여전히 RAM을 점유하고 있어서, 새 모델이 로드될 때 쓸 수 있는 메모리 대역폭이 줄어들기 때문이다.

로컬 LLM 파이프라인에는 두 가지 활용 방식이 있다고 생각했다. 하나는 Aider가 터미널에서 로컬 모델로 자율 작업을 하는 방식, 다른 하나는 Claude Code 세션 안에서 필요할 때만 로컬 모델에 작업을 위임하는 MCP(Model Context Protocol) 서버 방식이다. 이 둘은 서로 배타적이지 않고 병행할 수 있어서, 일단 MCP 쪽도 붙여보기로 했다. CONNECTION_CLOSED claude mcp add local-llm -- npx -y mcp-local-llm 등록은 됐는데, claude mcp list로 확인하면 상태가 이렇다. local-llm: npx -y mcp-local-llm - ✘ Failed to connect — CONNECTION_CLOSED 에러 메시지만으로는 원인을 알 수 없었다. npx가 내부적으로 어떤 명령을 실행하는지 직접 눈으로 확인해야 했다.

지난 글에서 잠깐 언급했던, Gemini 원격 코딩 어시스턴트를 만들면서 겪은 설치 문제를 이번 글에서 자세히 다룹니다. 최신 환경이 오히려 발목을 잡는, 은근히 자주 마주치는 종류의 문제였습니다. 증상: 기본적인 패키지 설치가 안 된다 aider를 설치하려고 하니 의존 패키지 중 하나가 설치 단계에서 실패했습니다. 에러 메시지를 따라가 보니 distutils.msvccompiler를 찾을 수 없다는 식의, 파이썬 빌드 도구 체인과 관련된 에러였습니다. numpy처럼 오래되고 널리 쓰이는 과학계산 라이브러리조차 순순히 설치되지 않았습니다. 원인: 너무 최신 파이썬 이 환경의 기본 파이썬 버전은 3.14였습니다. 최신 버전을 쓰는 것 자체는 보통 좋은 일이지만, 이번엔 오히려 문제가 됐습니다. distutils는 오래전부터 파이썬 표준 라이브러리에서 단계적으로 제거되어 온 모듈이고, 여러 과학계산·빌드 관련 패키지들이 이 모듈에 의존한 채로 아직 최신 파이썬 버전에 맞춰 업데이트되지 않은 상태였습니다. 결과적으로 “너무 최신이라서” 오래된 패키지들과 호환이 깨지는, 흔치 않지만 실제로 마주치면 당황스러운 상황이었습니다.

이번 글은 겉보기엔 서버 쪽 로직이 아니라 아주 평범한 웹 프론트엔드 버그처럼 보였지만, 실제로는 모바일 브라우저의 특성을 몰라서 한참 헤맸던 사례입니다. 채팅 랭킹과 등급 시스템 Iris 봇에는 누적 채팅 수에 따라 자동으로 등급이 올라가는 채팅 랭킹 시스템이 있습니다. 이번에 포팅하면서 기존 방식(누적 채팅수 기반 자동 승급)에 더해, 포인트를 소모해서 등급을 직접 “구매"하는 방식도 선택적으로 켤 수 있도록 기능을 추가했습니다. 등급 자체의 개수(최대 6개)도 방마다 다르게 설정할 수 있게 만들었습니다. 증상: 줄이기는 되는데 늘리기가 안 된다 이 등급 개수를 설정하는 UI는 숫자 입력창(스피너)이었습니다. 테스트해보니 이상한 패턴이 나타났습니다 — 값을 줄이는 건 잘 되는데, 늘리는 조작만 화면에 반영되지 않는 것처럼 보였습니다. 처음엔 서버 쪽 유효성 검사 로직이 최댓값을 잘못 제한하고 있는 줄 알고 그쪽을 한참 들여다봤지만 문제가 없었습니다.

블로그 관리자 페이지의 글쓰기 에디터를 세 번 연속으로 다시 만들었다. 세 번 다 “고쳤다"고 생각했는데, 실제로 브라우저를 열면 카테고리 목록도 안 뜨고 툴바 버튼도 하나도 반응하지 않았다. 원인은 라이브러리가 아니라, 훨씬 더 근본적인 곳에 있었다. 처음 시도는 Tiptap이었다. esm.sh CDN에서 @tiptap/core, @tiptap/starter-kit, @tiptap/extension-placeholder를 각각 따로 불러왔는데, 패키지마다 별도로 번들링된 esm.sh 특성상 같은 클래스가 서로 다른 인스턴스로 중복 로드될 위험이 있는 조합이었다. 전혀 동작하지 않아서 Quill.js로 바꿨다 — 단일 UMD 스크립트라 이 위험 자체가 없는 선택이었다. 그런데도 여전히 안 됐다.