설치 컴포넌트

설치 스크립트는 여러 패키지 매니저를 통해 인프라, 플랫폼 패키지, 선택적 도구를 설치합니다. 핵심 인프라와 플랫폼 의존성은 자동으로 설치되고, 선택적 도구는 설치 중 개별적으로 선택할 수 있습니다.

핵심 인프라 (항상 설치)

에이전트 플랫폼 런타임 의존성

플랫폼의 config.env 플래그로 제어됩니다. OpenClaw의 경우 모두 설치됩니다:

OpenClaw 플랫폼

선택적 도구 (설치 중 선택)

각 도구는 개별 Y/n 프롬프트로 제공됩니다. 원하는 도구만 선택하여 설치할 수 있습니다. 선택적 도구 설치가 실패해도 경고만 표시하고 건너뛸 뿐, 나머지 설치 과정을 중단하지 않습니다.

프로젝트 구조

openclaw-android/
├── bootstrap.sh                # curl | bash 원라이너 설치 (다운로더)
├── install.sh                  # 플랫폼 인식 설치 스크립트 (진입점)
├── oa.sh                       # 통합 CLI (설치 시 $PREFIX/bin/oa로 설치)
├── post-setup.sh               # Claw 앱 부트스트랩 후 설치 (OTA 배포)
├── update.sh                   # Thin wrapper (update-core.sh 다운로드 후 실행)
├── update-core.sh              # 기존 설치 환경 경량 업데이터
├── uninstall.sh                # 깔끔한 제거 (오케스트레이터)
├── patches/
│   ├── glibc-compat.js        # Node.js 런타임 패치 (os.cpus, networkInterfaces)
│   ├── argon2-stub.js          # argon2 네이티브 모듈용 JS 스텅 (code-server)
│   ├── termux-compat.h         # Bionic 네이티브 빌드용 C 헤더 (sharp)
│   ├── spawn.h                 # POSIX spawn 스텅 헤더
│   ├── systemctl               # Termux용 systemd 스텅
│   ├── apply-patches.sh        # 레거시 패치 오케스트레이터 (v1.0.2 호환)
│   └── patch-paths.sh          # 레거시 경로 수정 (v1.0.2 호환)
├── scripts/
│   ├── lib.sh                  # 공유 함수 라이브러리 (색상, 플랫폼 감지, 프롬프트)
│   ├── check-env.sh            # 사전 환경 점검
│   ├── install-infra-deps.sh   # 핵심 인프라 패키지 (L1)
│   ├── install-glibc.sh        # glibc-runner 설치 (L2 조건부)
│   ├── install-nodejs.sh       # Node.js glibc 래퍼 설치 (L2 조건부)
│   ├── install-build-tools.sh  # 네이티브 모듈용 빌드 도구 (L2 조건부)
│   ├── backup.sh               # OpenClaw 데이터 백업/복구 (oa --backup/--restore)
│   ├── build-sharp.sh          # sharp 네이티브 모듈 빌드 (이미지 처리)
│   ├── install-chromium.sh     # 브라우저 자동화용 Chromium 설치
│   ├── install-playwright.sh   # Playwright 브라우저 자동화 라이브러리 설치
│   ├── install-code-server.sh  # code-server 설치/업데이트 (브라우저 IDE)
│   ├── install-opencode.sh     # OpenCode 설치
│   ├── setup-env.sh            # 환경변수 설정
│   └── setup-paths.sh          # 디렉토리 및 심볼릭 링크 생성
├── platforms/
│   ├── openclaw/               # OpenClaw 플랫폼 플러그인
│   │   ├── config.env          # 플랫폼 메타데이터 및 의존성 선언
│   │   ├── env.sh              # 플랫폼별 환경변수
│   │   ├── install.sh          # 플랫폼 패키지 설치 (npm, 패치, clawdhub)
│   │   ├── update.sh           # 플랫폼 패키지 업데이트
│   │   ├── openclaw-shim.sh    # `openclaw update` 버전 고정 가드 생성
│   │   ├── uninstall.sh        # 플랫폼 패키지 제거
│   │   ├── limits.sh           # node/npm 호출의 시간 제한 (update · verify · status)
│   │   ├── status.sh           # 플랫폼 상태 표시
│   │   ├── verify.sh           # 플랫폼 검증 체크
│   │   └── patches/            # 플랫폼 전용 패치
│   │       ├── openclaw-apply-patches.sh
│   │       ├── openclaw-patch-paths.sh
│   │       ├── openclaw-patch-hardlink.sh  # Android 하드링크/reflink 대체 처리 (OpenClaw 용)
│   │       └── openclaw-build-sharp.sh
├── tests/
│   └── verify-install.sh       # 설치 후 검증 (오케스트레이터 + 플랫폼)
└── docs/
    ├── disable-phantom-process-killer.md    # 프로세스 라이브 상태 유지 가이드 (영문)
    ├── disable-phantom-process-killer.ko.md # 프로세스 라이브 상태 유지 가이드 (한국어)
    ├── termux-ssh-guide.md     # Termux SSH 접속 가이드 (영문)
    ├── termux-ssh-guide.ko.md  # Termux SSH 접속 가이드 (한국어)
    ├── troubleshooting.md      # 트러블슈팅 가이드 (영문)
    ├── troubleshooting.ko.md   # 트러블슈팅 가이드 (한국어)
    └── images/                 # 스크린샷 및 이미지

아키텍처

이 프로젝트는 플랫폼 플러그인 아키텍처를 사용하여 플랫폼 비종속 인프라와 플랫폼별 코드를 분리합니다:

┌─────────────────────────────────────────────────────────────┐
│  오케스트레이터 (install.sh, update-core.sh, uninstall.sh) │
│  ── 플랫폼 비종속. config.env를 읽고 위임.                │
├─────────────────────────────────────────────────────────────┤
│  공유 스크립트 (scripts/)                                  │
│  ── L1: install-infra-deps.sh (항상 실행)                │
│  ── L2: install-glibc.sh, install-nodejs.sh,              │
│         install-build-tools.sh (config.env 조건부)       │
│  ── L3: 선택적 도구 (사용자 선택)                        │
├─────────────────────────────────────────────────────────────┤
│  플랫폼 플러그인 (platforms/<name>/)                       │
│  ── config.env: 의존성 선언 (PLATFORM_NEEDS_*)           │
│  ── install.sh / update.sh / uninstall.sh / ...           │
└─────────────────────────────────────────────────────────────┘

의존성 계층:

각 플랫폼은 config.env에서 L2 의존성을 선언합니다:

# platforms/openclaw/config.env
PLATFORM_NEEDS_GLIBC=true
PLATFORM_NEEDS_NODEJS=true
PLATFORM_NEEDS_BUILD_TOOLS=true

오케스트레이터는 이 플래그를 읽고 해당하는 설치 스크립트를 조건부로 실행합니다. 특정 의존성이 필요 없는 플랫폼은 해당 플래그를 false로 설정하면 무거운 의존성이 전부 스킵됩니다.

설치 흐름 상세

bash install.sh를 실행하면 아래 8단계가 순서대로 실행됩니다.

[1/8] 환경 체크 — scripts/check-env.sh

설치를 시작하기 전에 현재 환경이 적합한지 검증합니다.

• Termux 감지: $PREFIX 환경변수 존재 여부로 Termux 환경인지 확인. 없으면 즉시 종료
• 아키텍처 확인: uname -m으로 CPU 아키텍처 확인 (aarch64 권장, armv7l 지원, x86_64은 에뮬레이터로 판단)
• 디스크 여유 공간: $PREFIX 파티션에 최소 2000MB 이상 여유 공간이 있는지 확인. 부족하면 필요한 양과 남은 양을 표시하고 오류
• 기존 설치 감지: openclaw 명령어가 이미 존재하면 현재 버전을 표시하고 재설치/업데이트임을 안내
• Node.js 사전 확인: 이미 설치된 Node.js가 있으면 버전을 표시하고, 24 미만이면 업그레이드 예고
• Phantom Process Killer (Android 12+): Phantom Process Killer에 대한 안내 메시지와 비활성화 가이드 링크를 표시

[2/8] 플랫폼 선택

설치할 플랫폼을 선택합니다. 현재는 openclaw으로 하드코딩되어 있습니다. 향후 여러 플랫폼이 제공되면 선택 UI가 추가될 예정입니다.

scripts/lib.sh의 load_platform_config()를 통해 플랫폼의 config.env를 로드하여, 이후 단계에서 사용할 모든 PLATFORM_* 변수를 내보냅니다.

[3/8] 선택적 도구 선택 (L3)

11개의 개별 Y/n 프롬프트(/dev/tty 사용)로 선택적 도구를 선택합니다:

• tmux, ttyd, dufs, android-tools
• Chromium, Playwright
• code-server, OpenCode
• Claude Code, Gemini CLI, Codex CLI (Termux)

모든 선택은 설치 시작 전에 한 번에 수집됩니다. 사용자가 모든 결정을 마치면 설치 중 자리를 비울 수 있습니다.

[4/8] 핵심 인프라 (L1) — scripts/install-infra-deps.sh + scripts/setup-paths.sh

플랫폼 선택과 무관하게 항상 실행됩니다.

install-infra-deps.sh:

• pkg update -y && pkg upgrade -y로 패키지 저장소 갱신 및 업그레이드
• git 설치 (npm git 의존성 및 저장소 클론에 필요)

setup-paths.sh:

• $PREFIX/tmp와 $HOME/.openclaw-android/patches 디렉토리 생성
• 표준 Linux 경로(/bin/sh, /usr/bin/env, /tmp)의 Termux 매핑 표시

[5/8] 플랫폼 런타임 의존성 (L2)

플랫폼의 config.env 플래그에 따라 런타임 의존성을 조건부로 설치합니다:

각 스크립트는 사전 체크와 멱등성(이미 설치된 경우 스킵)을 갖춘 독립 실행형입니다.

Node.js 래퍼의 기본값: OpenClaw 2026.9.x 는 Node.js 24.16 이상을 요구합니다. OpenClaw 의 파일 안전 모듈(@openclaw/fs-safe)은 네이티브 도우미에서 openat2 시스템 콜을 사용하는데, Android 의 앱 seccomp 정책이 이 호출을 SIGSYS(Bad system call)로 종료시킵니다. 그래서 래퍼는 기본으로 FS_SAFE_TEST_NO_OPENAT2=1 을 설정하여, 네이티브 도우미는 유지하되 openat2 를 사용하지 않게 합니다(값이 정확히 1 이어야 인식됩니다). FS_SAFE_NATIVE_MODE=off 를 설정하면 네이티브 도우미 자체를 끌 수 있으나, 그러면 OpenClaw 의 일부 데이터 이전이 거부될 수 있습니다. 래퍼는 OPENCLAW_NO_AUTO_UPDATE=1 도 기본으로 설정하고 OpenClaw 의 자체 업데이트를 차단합니다(업데이트 참고).

하드링크 패치: Android 는 앱 데이터 영역에서 하드링크와 reflink(FICLONE) 복사를 막습니다(앱과 Termux 모두, 오류 EACCES). OpenClaw 2026.10.2 은 하드링크를 먼저 시도하고 「지원 안 함」 오류일 때만 복사로 넘어가는데, EACCES 는 지원 안 함으로 보지 않습니다. 또 대화 기록을 이전한 뒤 원본을 보관 폴더로 옮길 때는 하드링크만 사용합니다. 그대로 두면 7.35 에서 올라온 사용자의 데이터 이전이 실패합니다. OpenClaw on Android 는 OpenClaw 를 설치하거나 업데이트할 때마다(앱 설치, Termux 설치, oa --update, 그리고 npm install -g openclaw@<고정 버전> 으로 다시 설치할 때) platforms/openclaw/patches/openclaw-patch-hardlink.sh 로 OpenClaw 의 해당 부분을 고칩니다. EACCES 를 복사로 넘어가는 경우에 포함하고, 보관 폴더로 옮길 때는 하드링크가 거부되면 같은 파일 시스템 안의 이름 바꾸기(rename)로 처리합니다. 이에 따라 openclaw backup create 도 하드링크 대신 복사를 사용할 수 있습니다. oa --status 에 Hard-link patch: applied (…) 또는 not complete (…) 줄이 표시됩니다. 대화 기록이 있는 7.35 사용자가 고정 버전이 바뀌는 업데이트를 하면, 설치할 OpenClaw 에 이 패치가 맞는지 먼저 확인하고 맞지 않으면 아무것도 바꾸지 않고 멈춥니다(문제 해결 참고). 또 OpenClaw 2026.10 은 게이트웨이 잠금을 위해 프로세스 네임스페이스 파일 /proc/self/ns/pid 를 읽는데, 많은 Android 커널이 앱에 이 파일을 제공하지 않습니다(조회가 ENOENT 또는 EACCES 로 실패). 같은 패치가 OpenClaw 가 이 파일을 「없음」으로 취급하게 하여 게이트웨이가 시작을 거부하지 않도록 합니다.

알려진 한계: OpenClaw 의 데스크톱 자동화 도구(@trycua/cua-driver)는 Android 10 이하(API 29 이하)에서 필요한 시스템 콜 일부가 막혀 동작하지 않을 수 있습니다.

[6/8] 플랫폼 패키지 설치 (L2) — platforms/<platform>/install.sh

플랫폼 고유의 설치 스크립트에 위임합니다. OpenClaw의 경우:

1. CPATH를 glib-2.0 헤더용으로 설정 (네이티브 모듈 빌드에 필요)
2. pip으로 PyYAML 설치 (.skill 패키징용)
3. glibc-compat.js를 ~/.openclaw-android/patches/에 복사 (Node.js 래퍼는 Node.js 설치 때 함께 들어가는 ~/.openclaw-android/lib/ 사본을 읽습니다 — 앱이 덮어쓰지 않는 위치)
4. systemctl 스텅을 $PREFIX/bin/에 설치
5. npm install -g [email protected] --ignore-scripts 실행 (config.env에 고정된 버전)
6. --ignore-scripts로 건너뛴 OpenClaw 자체 postinstall 스크립트(postinstall-bundled-plugins.mjs) 실행
7. openclaw-apply-patches.sh로 플랫폼별 패치 적용
8. openclaw update 가드(openclaw-shim.sh) 설치 — 고정 버전이 유지되도록 함
9. clawdhub (스킬 매니저) 및 필요 시 undici 의존성 설치
10. 게이트웨이의 "update available" 알림 끄기(openclaw config set update.checkOnStart false) — 이미 직접 설정한 값이 있으면 그대로 둠

이전 설치가 중간에 끊긴 경우: 설치 스크립트는 설치가 진행 중임을 기록하고, 설치·postinstall·패치·확인이 모두 통과한 뒤에만 그 기록을 삭제합니다. 설치 후에도 OpenClaw 가 불완전하면 Termux 설치 프로그램은 [FAIL] OpenClaw <version> was installed but is incomplete (files are missing or it does not start). 와 Run the installer again. 를 표시하고 중단합니다. Claw 앱의 설정 스크립트(post-setup.sh)는 끝나지 않은 이전 설치를 감지하여([WARN] OpenClaw <version> is incomplete (an earlier install was cut off): installing it again) 버전이 같아도 OpenClaw 를 다시 설치하며, 데이터는 건드리지 않습니다. 그 뒤에도 OpenClaw 가 불완전하면 설정은 다음 오류와 함께 중단됩니다: OpenClaw <version> is still incomplete (files are missing or it does not start). Restart the app to try again. Claw 앱(v0.4.5 이상)은 이 실패를 설정 화면에 표시하며, 다시 시도하는 버튼을 제공합니다.

[6.5] 환경변수 + CLI + 마커:

플랫폼 설치 후 오케스트레이터가:

• setup-env.sh를 실행하여 .bashrc 환경변수 블록 작성
• 플랫폼의 env.sh를 평가하여 플랫폼별 변수 설정
• 플랫폼 마커 파일(~/.openclaw-android/.platform) 기록
• oa CLI와 oaupdate 래퍼를 $PREFIX/bin/에 설치
• lib.sh, setup-env.sh, 플랫폼 디렉토리를 ~/.openclaw-android/에 복사 (업데이터와 언인스톨러가 사용)

[7/8] 선택적 도구 설치 (L3)

3단계에서 선택한 도구를 설치합니다:

• Termux 패키지: tmux, ttyd, dufs, android-tools — pkg install로 설치
• code-server: 브라우저 기반 VS Code IDE. Termux 전용 워커라운드 포함 (번들 node 교체, argon2 패치, 하드 링크 실패 처리)
• OpenCode: AI 코딩 어시스턴트. proot + ld.so 결합 방식으로 Bun 독립 실행 바이너리 지원
• Chromium: OpenClaw 브라우저 자동화 지원 (~400MB)
• Playwright: 브라우저 자동화 라이브러리 (playwright-core npm 설치). PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH 및 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD 환경변수 자동 설정. Chromium 미설치 시 자동 설치
• AI CLI 도구: Claude Code, Gemini CLI, Codex CLI (Termux) — npm install -g로 설치. 설치 실패 시 경고만 표시하고 건너뛰며 설치 전체를 중단하지 않음 (Claude Code는 glibc 로더를 통해 실행됩니다. Codex CLI는 패키지가 os: android 를 선언하는데 이 Node.js는 linux 를 보고하므로 Claw 앱에서는 --force 로 설치합니다. Termux에서는 여전히 경고와 함께 건너뛸 수 있습니다)

[8/8] 검증 — tests/verify-install.sh

2단계 검증을 실행합니다:

오케스트레이터 검증 (FAIL 레벨):

오케스트레이터 검증 (WARN 레벨, 비필수):

플랫폼 검증 — platforms/<platform>/verify.sh에 위임:

모든 FAIL 레벨 항목 통과 시 PASSED. FAIL 발생 시 재설치 안내를 표시합니다. WARN 항목은 실패로 처리되지 않습니다.

경량 업데이터 흐름 — oa --update

oa --update (또는 하위 호환을 위한 oaupdate)를 실행하면 GitHub에서 최신 릴리스 tarball을 다운로드하고 아래 5단계를 순서대로 실행합니다.

[1/5] 사전 점검

업데이트를 위한 최소 조건을 확인합니다.

• $PREFIX 존재 확인 (Termux 환경)
• curl 사용 가능 여부 확인
• ~/.openclaw-android/.platform 마커 파일에서 플랫폼 감지
• 아키텍처 감지: glibc (.glibc-arch 마커) 또는 Bionic (레거시)
• 구버전 디렉토리 마이그레이션 (.openclaw-lite → .openclaw-android — 레거시 호환)
• Phantom Process Killer (Android 12+): 비활성화 가이드 링크와 함께 안내 메시지를 표시
• 한 번에 한 실행: 설치·업데이트·도구 설치는 한 번에 하나만 실행합니다. 두 번째 실행은 [FAIL] Another update, setup or tools run is in progress. Try again when it has finished. 를 출력하고, 설치 상태를 바꾸지 않은 채 종료 코드 2 로 끝납니다

[2/5] 최신 릴리스 다운로드

GitHub에서 전체 저장소 tarball을 다운로드하고 임시 디렉토리에 추출합니다. 필수 파일의 존재를 확인합니다:

• scripts/lib.sh
• scripts/setup-env.sh
• platforms/<platform>/config.env
• platforms/<platform>/update.sh

[3/5] 핵심 인프라 업데이트

업데이터, 언인스톨러, CLI가 사용하는 공유 파일을 갱신합니다. 이번 업데이트로 고정된 Node.js 나 OpenClaw 의 버전이 바뀌면, 무엇이든 바꾸기 전에 세 가지 안전장치가 먼저 실행됩니다. 여유 공간 확인(2000MB), OpenClaw 게이트웨이가 실행 중이 아닌지 확인, ~/.openclaw-android/backup/pre-update/ 에 데이터 백업(업데이트 참고)입니다.

• 업데이트 스크립트 자신이 최신인지 확인합니다. 옛 캐시 사본이 내려왔으면(릴리스 직후 몇 분 동안 가능) 아무것도 바꾸지 않고 멈춥니다. 몇 분 뒤 oa --update 를 다시 실행하세요
• 최신 플랫폼 디렉토리를 ~/.openclaw-android/platforms/에 복사
• ~/.openclaw-android/scripts/의 lib.sh와 setup-env.sh 갱신
• 패치 파일 갱신 (glibc-compat.js, argon2-stub.js, spawn.h, systemctl)
• $PREFIX/bin/의 oa CLI와 oaupdate 래퍼 갱신
• ~/.openclaw-android/의 uninstall.sh 갱신
• Bionic 아키텍처가 감지되면 자동 glibc 마이그레이션 수행
• Node.js를 고정 버전으로 수렴 (sha256 검증 다운로드, 원자적 교체 — 실패 시 이전 설치 복원). OA_ALLOW_NODE_DOWNGRADE=1 을 설정하지 않으면 Node.js 를 더 낮은 버전으로 내리지 않음
• setup-env.sh를 실행하여 .bashrc 환경변수 블록 갱신
• Node 게이트: 이후에도 Node.js가 고정 버전이 아니면 여기서 업데이트를 중단합니다 — OpenClaw([4/5])는 건드리지 않습니다. oa --update를 다시 실행하세요

[4/5] 플랫폼 업데이트

platforms/<platform>/update.sh에 위임합니다. OpenClaw의 경우:

• 고정 버전이 바뀐 경우: 설치 뒤 OpenClaw 설정과 데이터 상태를 확인하고, 데이터 이전이 필요하며 이번 실행에서 백업을 만들었을 때 openclaw doctor --fix 를 한 번 실행 (업데이트 참고)
• 설치 뒤 설정 확인 직전에 다른 앱의 폴더를 가리키는 경로를 고침 (백업 및 복구 참고)
• 마지막 데이터 확인(openclaw config validate 와 openclaw doctor --non-interactive): 게이트웨이가 OpenClaw 데이터를 사용 중이고 이번 실행에서 OpenClaw 를 교체하지 않았다면, 확인을 실패로 처리하지 않고 건너뛰며 [WARN] The gateway is using the OpenClaw state, so the data check was skipped. Stop the gateway, then run: openclaw doctor 를 표시한 채 업데이트를 계속합니다
• binutils 설치 (네이티브 모듈 빌드용)
• 안전장치로 Node.js 고정 버전을 재확인 (방어적 이중 확인 — [3/5]에서 이미 게이트를 거침)
• openclaw을 고정 버전으로 수렴 — 설치된 버전이 더 낮으면 고정 버전을 설치. OA_ALLOW_OPENCLAW_DOWNGRADE=1 을 설정하지 않으면 OpenClaw 를 더 낮은 버전으로 내리지 않음
• OpenClaw 가 불완전하면(이전 설치가 중간에 끊겨 버전은 맞지만 파일이 빠진 상태) 버전이 고정 버전과 같아도 다시 설치합니다: [WARN] openclaw <version> is incomplete (an earlier install was cut off): installing it again. 마지막 데이터 확인에서 OpenClaw 자체의 파일이 없다고 보고하면(OpenClaw 패키지 안의 경로에 대한 Cannot find module 또는 Cannot find package) 한 번 다시 설치합니다: [WARN] OpenClaw <version> is missing some of its own files (an earlier install was cut off): installing it again. 어느 경우에도 데이터는 건드리지 않습니다. 이번 실행에서 설치한 뒤에도 OpenClaw 가 불완전하면 [FAIL] OpenClaw <version> was installed but is incomplete (files are missing or it does not start). 를 표시하고 업데이트를 중단합니다.
• 플랫폼별 패치 재적용
• openclaw update 가드(openclaw-shim.sh) 갱신 — openclaw update/--update가 계속 차단되도록 유지 (Node.js 래퍼는 OpenClaw 의 자체 업데이트 경로도 차단)
• clawdhub (스킬 매니저) 업데이트/설치
• 필요 시 clawdhub용 undici 설치 (Node.js v24+)
• 게이트웨이의 "update available" 알림 끄기(update.checkOnStart=false) — 직접 설정한 값이 없을 때만
• 필요 시 ~/skills/에서 ~/.openclaw/workspace/skills/로 스킬 마이그레이션
• PyYAML 누락 시 설치

[5/5] 선택적 도구 업데이트

이미 설치된 도구만 업데이트합니다:

• code-server: install-code-server.sh를 update 모드로 실행 — 고정 버전 4.117.0 으로 유지(예전에 더 새 버전이 설치됐으면 되돌림). 미설치 시 스킵
• OpenCode: 설치된 경우 업데이트, 미설치 시 설치 여부 문의. glibc 아키텍처 필요
• Chromium: 설치된 경우 업데이트. 미설치 시 스킵
• AI CLI 도구 (Claude Code, Gemini CLI, Codex CLI (Termux)): 설치된 버전과 최신 npm 버전을 비교하여 필요 시 업데이트. 미설치 도구는 설치를 제안하지 않음