LLM Wiki

Android Termux에서 nanobot-ai 설치 가이드

10 min read

Android Termux에서 nanobot-ai 설치 가이드

nanobot-ai를 Android Termux에 설치하는 일은 단순 pip install이 아니라 Rust, C 라이브러리, Android wheel 패키징 문제를 하나씩 해결하는 모바일 빌드 작업에 가깝다.

개요

이 문서는 Android의 Termux 환경에서 nanobot-ai를 설치할 때 실제로 마주칠 수 있는 대표적인 빌드 오류와 해결 절차를 한 번에 정리한 최종 종합판이다. 특히 구형 기기에서는 아래 세 가지가 핵심 난관이다.

  1. Rust 기반 Python 패키지(rpds-py, jiter 등) 빌드
  2. lxml이 요구하는 시스템 C 라이브러리 의존성 해결
  3. maturin의 Android wheel 패키징 단계에서 ANDROID_API_LEVEL 누락 해결

즉, Android에서의 nanobot-ai 설치는 “패키지 설치”보다 빌드 체인을 복구하고 끝까지 통과시키는 과정에 더 가깝다.

1) 사전 주의사항

구형 기기 메모리 제약

  • 갤럭시 S8처럼 RAM 4GB급 기기에서는 빌드 도중 Termux가 종료될 수 있다.
  • 설치 전에 백그라운드 앱을 최대한 정리하는 편이 좋다.

배터리와 발열

  • 컴파일은 CPU를 길게 점유한다.
  • 충전기 연결 상태에서 진행하는 편이 안전하다.

화면 꺼짐 방지

  • 화면이 꺼지면 Android가 Termux 작업을 중단할 수 있다.
  • 설치가 끝날 때까지 화면을 켜 둔다.

2) 기본 환경 및 빌드 도구 설치

먼저 Termux 패키지를 최신 상태로 맞추고, Python과 C/C++ 빌드 도구를 설치한다.

pkg update && pkg upgrade -y
pkg install python git clang make pkg-config libffi openssl binutils -y

선택 사항이지만, 패키지 설치와 실행 관리 편의를 위해 uv도 같이 설치할 수 있다.

pip install uv

3) 핵심 오류 해결 1 — Rust 빌드 이슈

설치 중 rpds-py나 jiter 같은 Rust 기반 패키지에서 panic 오류가 날 수 있다. 대표 증상은 다음과 같다.

  • rustls-platform-verifier 관련 panic
  • rustup 크래시
  • Rust 컴파일러 미인식

원인

공식 rustup 스크립트는 Termux 특유의 TLS/보안 인증서 구조와 충돌할 수 있다. 그래서 Termux에서는 rustup을 억지로 살리기보다 Termux 저장소의 Rust 패키지를 쓰는 편이 더 안정적이다.

해결 절차

① 기존 rustup 설정 삭제

rm -rf ~/.cargo ~/.rustup

② Termux 네이티브 Rust 설치

pkg install rust -y

③ 설치 확인

rustc --version
cargo --version

버전이 정상 출력되면 Rust 빌드 환경은 준비된 것이다.

4) 핵심 오류 해결 2 — lxml 빌드 이슈

python-docx 같은 의존성을 따라가다 보면 lxml 설치 과정에서 아래와 같은 오류를 만날 수 있다.

  • libxml2 and libxslt development packages are required

이 경우는 Python 패키지 문제가 아니라, 시스템 레벨 XML 라이브러리가 빠진 상태다.

해결 절차

pkg install libxml2 libxslt libiconv -y

이 패키지들은 lxml이 C 확장을 빌드할 때 필요한 XML 처리 및 문자 인코딩 라이브러리다.

5) 기본 설치 시도

필수 의존성을 준비한 뒤 uv로 nanobot-ai를 설치한다.

uv tool install nanobot-ai

구형 기기에서는 Rust 패키지와 lxml 컴파일에 수십 분이 걸릴 수 있다. 한동안 출력이 없어 보여도 실제로는 빌드가 진행 중일 수 있으므로 성급히 중단하지 않는 편이 낫다.

6) 마지막 패키징 오류 — ANDROID_API_LEVEL 누락

Rust 코드 자체는 이미 성공적으로 컴파일됐는데, 마지막에 wheel 패키징 단계에서 아래 오류가 날 수 있다.

Failed to determine Android API level.
Please set the ANDROID_API_LEVEL environment variable.

이 메시지는 maturin이 현재 Termux 환경의 Android API 레벨을 자동 인식하지 못했다는 뜻이다. 즉, 빌드 실패라기보다 안드로이드용 Python wheel로 포장하는 마지막 설정이 비어 있는 상태다.

왜 중요한가

  • 로그에 Finished 'release' profile [optimized] target(s)가 보였다면, 가장 무거운 Rust 컴파일은 이미 끝난 것이다.
  • 갤럭시 S8 같은 기기에서 이 단계까지 왔다면 사실상 거의 다 온 상태다.
  • 따라서 처음부터 다시 할 필요 없이, API 레벨만 지정하고 설치 명령을 다시 실행하면 된다.

해결 절차

① Android API 레벨 지정

export ANDROID_API_LEVEL=24

Termux 환경에서는 호환성을 위해 보통 API 레벨 24를 지정하는 방식이 안정적이다.

② 설치 명령 재실행

uv tool install nanobot-ai

이미 직전 빌드 결과물이 캐시에 남아 있을 가능성이 높기 때문에, 이번에는 Rust 전체를 다시 오래 컴파일하지 않고 더 빠르게 통과할 수 있다.

7) 최종 권장 설치 순서

처음부터 다시 정리하면, 가장 실전적인 설치 순서는 아래와 같다.

pkg update && pkg upgrade -y
pkg install python git clang make pkg-config libffi openssl binutils -y
pkg install rust -y
pkg install libxml2 libxslt libiconv -y
pip install uv
export ANDROID_API_LEVEL=24
uv tool install nanobot-ai

이 순서의 장점은 다음과 같다.

  • Rust panic 우회
  • lxml 시스템 의존성 선해결
  • Android wheel 패키징 오류 선제 차단

즉, 위 순서대로 가면 중간에 겪은 오류들을 대부분 한 번에 예방할 수 있다.

8) 설치 확인 및 실행

설치가 끝나면 CLI가 정상 동작하는지 먼저 확인한다.

nanobot --help

도움말이 정상적으로 뜨면 설치 자체는 성공한 것이다.

9) 실제 사용 전 준비

실제 사용을 위해서는 OpenAI 또는 Anthropic 같은 LLM API 키가 추가로 필요할 수 있다. 일반적으로는 다음 방식 중 하나로 설정한다.

  • 환경 변수 (export ...)
  • .env 파일

즉, 설치 성공과 실제 작업 가능 상태는 다를 수 있다.

트러블슈팅 요약

  • Rust panic이 나면 rustup 대신 pkg install rust
  • lxml 오류가 나면 libxml2, libxslt, libiconv 설치
  • ANDROID_API_LEVEL 오류가 나면 export ANDROID_API_LEVEL=24 후 설치 재시도
  • OOM이 의심되면 백그라운드 앱 정리 후 재시도
  • 장시간 멈춘 것처럼 보여도 구형 기기에서는 빌드 시간이 오래 걸릴 수 있음

실전 포인트

이번 설치 경험은 Android에서 에이전트형 CLI를 돌리는 일이 단순 앱 설치가 아니라는 점을 잘 보여준다. 모바일 환경에서는 패키지 매니저보다도 빌드 체인 복구 능력이 더 중요하다. 즉, Termux 기반 AI 도구 운용은 “사용법”보다 “의존성 문제를 어떻게 뚫는가”가 핵심이다.

또한 이번 사례는, 구형 Android 기기에서도 시간이 오래 걸릴 뿐 끝까지 해결 가능하다는 점을 보여준다. 가장 무거운 Rust 컴파일을 통과했다면 마지막 단계는 대개 설정 문제이므로, 로그를 세밀하게 읽고 작은 누락값을 보완하는 접근이 중요하다.

그래프 뷰

백링크