휴대폰에서 Claude Code 사용하는 방법
Claude Code는 휴대폰이 아니라 VPS의 tmux에서 실행됩니다. SSH 키 설정, 불안정한 모바일 데이터를 위한 mosh, tmux attach와 모바일 키보드 문제 해결법을 안내합니다.
휴대폰에서 Claude Code 사용하기: 실제 작동 방식
휴대폰에서 사용하는 Claude Code는 모바일 앱이 아닙니다. Claude Code는 VPS(가상 사설 서버)의 계속 열려 있는 tmux 세션 안에서 실행됩니다. 휴대폰은 사용자가 화면을 보고 있는 동안 SSH(보안 셸) 연결을 통해 해당 세션에 접속합니다. 앱을 닫아도 에이전트는 계속 작업합니다. 프로세스가 휴대폰에서 실행된 것이 아니기 때문입니다.
이 분리가 전체 설계의 핵심입니다. 휴대폰 운영 체제는 앱에서 다른 화면으로 전환한 뒤 몇 초가 지나면 앱을 일시 중지합니다. 따라서 휴대폰에서 시작한 장시간 작업은 중단됩니다. 또한 wifi에서 모바일 데이터로 이동할 때마다 새로운 네트워크 주소를 할당받습니다. 프로세스를 서버에서 실행하고 휴대폰은 화면만 표시하도록 하면 두 문제가 모두 해결됩니다.
서버에는 4가지가 필요합니다. 세션을 유지할 tmux, 접속에 사용할 SSH 키, 네트워크 변경을 처리할 mosh, 그리고 Claude Code 자체입니다. 휴대폰에는 손이 닿는 위치에 키 행이 있는 터미널 앱 하나가 필요합니다.
VPS에 필요한 사항
SSH와 tmux를 사용하는 데는 소형 Ubuntu 24.04 서버로 충분합니다. Claude Code에는 더 많은 리소스가 필요합니다. 2026년 7월 기준 공식 요구 사항은 x64 또는 ARM64 프로세서에서 Ubuntu 20.04 이상을 실행하고 RAM이 4 GB 이상인 환경입니다. 1 GB 플랜에서는 설치되더라도 부하가 발생하면 kernel이 프로세스를 종료합니다. Claude Code를 사용하려면 유료 Claude 계정(Pro, Max, Team 또는 Enterprise)이나 API 액세스가 가능한 Console 계정도 필요합니다. 무료 Claude.ai 플랜에는 Claude Code가 포함되지 않습니다.
서버는 root가 아니라 sudo 권한이 있는 일반 사용자로 설정합니다. 새 서버라면 먼저 새 VPS에서 처음 10분 동안 수행할 작업을 진행합니다. 이 가이드의 뒤쪽에서 SSH를 변경할 때 사용자와 방화벽이 이미 있으면 작업이 더 쉽습니다.
sudo apt update && sudo apt install -y tmux mosh
curl -fsSL https://claude.ai/install.sh | bash
claude --version설치 프로그램은 바이너리를 ~/.local/bin/claude에 저장합니다. claude --version을 실행하면 2.1.211 (Claude Code)와 같은 행이 출력됩니다. command not found이 출력되면 아직 해당 디렉터리가 PATH에 포함되지 않은 것입니다. 로그아웃한 다음 다시 로그인하고 command -v claude로 확인합니다. claude doctor은 세션을 시작하지 않고 설치 및 설정 진단 정보를 출력합니다.
이제 휴대폰에 의존하기 전에 노트북에서 한 번 로그인합니다. 프로젝트 디렉터리에서 claude을 실행하고 로그인 프롬프트를 따릅니다. 이 과정에서는 브라우저에서 URL을 열고 코드를 터미널에 입력해야 합니다. 휴대폰 화면에서 두 앱을 번갈아 사용하는 작업은 느립니다. 실제 키보드로 한 번 완료하면 인증 정보가 서버에 유지됩니다.
연결이 끊겨도 종료되지 않도록 tmux 안에서 Claude Code 시작하기
tmux new -s claude
cd ~/projects/api
claudeCtrl-b을 사용해 분리한 다음 d을 사용합니다. tmux는 [detached (from session claude)]을 출력하고 셸로 돌아갑니다. 이제 앱을 닫거나, 신호를 잃거나, 휴대폰을 주머니에 넣어도 됩니다. pane은 계속 실행됩니다.
tmux ls
tmux attach -t claudetmux ls은 세션마다 한 줄씩 출력하며, 예를 들면 claude: 1 windows (created Thu Jul 30 09:14:02 2026)와 같습니다. tmux attach -t claude을 사용하면 작업을 중단한 지점으로 정확히 돌아갑니다. 완료되지 않은 편집 내용도 그대로 유지됩니다.
이는 tmux가 자체 server process를 실행하기 때문입니다. 사용자의 shell과 Claude Code는 sshd가 아니라 해당 server process의 child process입니다. SSH 연결이 종료되면 kernel은 해당 연결에 연결된 process에 hangup signal인 SIGHUP을 보냅니다. tmux server는 이 process에 포함되지 않습니다. tmux가 없으면 연결을 끊는 동일한 화면 잠금으로 인해 tool call 중간에 Claude Code가 중지됩니다. VPS의 tmux 안에서 Claude Code 실행하기에서 세션 레이아웃을 자세히 설명합니다.
tmux는 항상 server에서 실행합니다. phone에서 실행하지 마십시오. 이미 연결된 session 안에서 tmux를 입력하면 sessions should be nested with care, unset $TMUX to force이 출력됩니다. 이를 강제로 실행하면 서로 사용할 prefix key가 2개가 되어 충돌합니다.
로그인할 때마다 자동으로 연결
터치 키보드에서 연결 명령을 입력하는 작업은 번거롭습니다. 서버의 ~/.profile 끝에 다음 내용을 추가합니다.
if command -v tmux >/dev/null 2>&1 && [ -z "$TMUX" ] && [ -t 1 ]; then
exec tmux new-session -A -s claude
finew-session -A -s claude은 claude이라는 세션이 있으면 해당 세션에 연결하고, 없으면 세션을 생성합니다. 따라서 두 경우 모두 하나의 명령으로 처리할 수 있습니다. exec은 로그인 셸을 tmux로 교체하므로, tmux를 종료하면 빈 프롬프트로 돌아가는 대신 연결이 종료됩니다. 일반 셸이 필요하면 파일을 건너뜁니다: ssh you@server -t "bash --noprofile".
~/.profile에 추가해야 하며 ~/.bashrc에는 추가하면 안 됩니다. ~/.bashrc도 비대화형 세션에서 실행되므로 파일 전송이 중단됩니다. scp 및 sftp은 예기치 않은 출력을 프로토콜 데이터로 읽고 Received message too long과 함께 실패합니다. ~/.profile은 로그인 셸에서만 실행되며, 대화형 SSH 세션은 로그인 셸입니다.
Ubuntu가 ~/.local/bin을 PATH에 추가하는 위치도 ~/.profile입니다. 로그인 직후에는 claude가 작동하지만 tmux 내부의 셸에서 command not found이라고 표시된다면 그 순서가 원인입니다. 따라서 프로필을 건너뛰는 스크립트에서 tmux를 시작하지 말고 위와 같이 로그인 셸에서 시작합니다.
iOS: Termius 또는 Blink Shell
두 앱 모두 SSH와 mosh를 지원하며 앱에 키를 저장합니다. 차이는 인터페이스입니다.
Blink Shell은 명령 기반입니다. 프롬프트에서 ssh you@server 또는 mosh you@server를 입력합니다. 데스크톱 터미널과 동일한 구문입니다. config를 입력하면 설정이 열립니다. Keys 섹션에서 키 쌍을 생성할 수 있습니다.
Termius는 양식 기반입니다. 호스트 항목을 입력한 다음 호스트 세부 정보에서 해당 호스트의 연결 방식을 SSH에서 Mosh로 전환합니다. Termius에는 자체 mosh 구현이 포함되어 있으며 mosh 1.3.0 이상을 지원합니다. 따라서 서버에도 mosh 패키지를 설치해야 합니다.
두 경우 모두 앱 안에서 키를 생성합니다. 기존 개인 키를 휴대폰에 복사하지 마십시오. 앱에는 공개 키 부분이 표시됩니다. 서버의 ~/.ssh/authorized_keys에 추가하는 한 줄이 공개 키입니다. 장치별 SSH 키와 키를 폐기하는 방법에서는 키 이름 지정과 폐기 절차를 설명합니다. 이 절차는 노트북보다 휴대폰에서 더 중요합니다.
터미널 앱 자체의 생체 인증 또는 암호 잠금을 활성화합니다. 이 기능이 없으면 화면이 켜져 있는 동안 잠금 해제된 휴대폰이 서버에 연결된 열린 셸이 됩니다.
Android: Termux
pkg upgrade
pkg install openssh mosh
ssh-keygen -t ed25519 -C "pixel"
cat ~/.ssh/id_ed25519.pubTermux는 자체 저장소에서 OpenSSH와 mosh를 패키지로 제공하므로 ssh, ssh-keygen, mosh은 데스크톱에서와 동일하게 작동합니다. 출력된 공개 키 줄을 서버의 ~/.ssh/authorized_keys에 추가한 다음 mosh you@server으로 연결합니다.
Android 화면 키보드에는 Esc 키와 Ctrl 키가 없으며 Claude Code에는 두 키가 모두 필요합니다. Termux에서는 자체 키 행을 표시할 수 있습니다. ~/.termux/termux.properties에 다음 한 줄을 추가합니다.
extra-keys = [['ESC','|','/','HOME','UP','END','PGUP'],['TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN']]그런 다음 termux-reload-settings를 실행하면 키보드 위에 키 행이 나타납니다. 동일한 다시 로드 작업을 수행하면 ~/.termux/font.ttf에 넣은 고정폭 TrueType 글꼴도 적용됩니다.
Android는 Termux가 백그라운드에 있을 때 Termux를 중지할 수 있습니다. 이 경우 재연결만 하면 되므로 문제가 되지 않습니다. 세션과 에이전트는 서버에서 실행됩니다.
wifi를 벗어날 때 터미널이 멈추는 이유와 mosh가 해결하는 문제
SSH 연결은 TCP (transmission control protocol) 연결입니다. TCP 연결은 양쪽 주소와 양쪽 포트로 식별됩니다. wifi 범위를 벗어나면 휴대폰은 모바일 네트워크에서 새 주소를 받습니다. 그러면 기존 연결은 어느 쪽에서도 일치하는 항목을 찾지 못합니다. 이 변경을 알리는 신호는 없습니다. TCP가 포기할 때까지 터미널은 단순히 응답하지 않습니다. 그 후 ssh가 client_loop: send disconnect: Broken pipe를 출력합니다. 멈춘 세션을 즉시 종료하려면 Enter, ~, .을 차례로 누릅니다.
mosh (mobile shell)는 이 장애를 제거합니다. mosh는 SSH를 한 번 사용해 로그인하고 mosh-server 프로세스를 시작합니다. 그런 다음 서버가 선택한 UDP (user datagram protocol) 포트를 읽고 SSH 연결을 닫습니다. 이후 양쪽은 공유 세션 키로 인증한 UDP 데이터그램을 교환합니다. 따라서 세션은 주소가 아니라 해당 키로 식별됩니다. 주소가 바뀌어도 세션은 계속됩니다. mosh는 입력한 내용을 로컬에서 즉시 표시하고, 서버의 상태와 다르면 화면을 다시 그립니다. 따라서 느린 모바일 링크에서도 계속 사용할 수 있습니다.
mosh는 60000과 61000 사이의 UDP 포트를 사용하므로 다음 범위를 엽니다.
sudo ufw allow 60000:61000/udp
sudo ufw statusufw로 포트 열기에서 방화벽 구성의 나머지 내용을 설명합니다. 공급자가 제어판에서 별도의 네트워크 방화벽을 제공한다면 그곳에도 같은 범위를 추가합니다. ufw 규칙은 시스템 앞단에 있는 필터에는 적용되지 않기 때문입니다.
mosh에서는 2가지 오류가 자주 발생합니다. 로그인이 성공한 뒤 멈추고 Nothing received from server on UDP port 60001.가 표시되면 휴대폰과 서버 사이 어딘가에서 해당 UDP 범위가 차단된 것입니다. 연결 시 mosh-server not found가 표시되면 서버에 패키지가 없거나 로그인 PATH에 등록되어 있지 않은 것입니다. 패키지를 설치하거나 mosh --server=/usr/bin/mosh-server you@server로 직접 지정합니다.
로그인 로캘이 UTF-8이 아니면 mosh도 실행되지 않으며 다음과 같이 알립니다: mosh-server needs a UTF-8 native locale to run. 서버에서 로캘을 수정해야 하며, 휴대폰에서 수정하면 안 됩니다.
locale
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8mosh가 하지 않는 일은 2가지입니다. README에 따르면 mosh는 X forwarding과 port forwarding을 포함한 SSH의 비대화형 사용을 지원하지 않습니다. 따라서 Claude Code가 방금 시작한 웹 앱을 미리 보려면 일반 ssh -L 8080:127.0.0.1:8080 you@server가 여전히 필요합니다. 또한 mosh는 현재 표시되는 화면만 동기화하므로 자체 scrollback이 없습니다. 이 두 번째 제한은 여기서 문제가 되지 않습니다. tmux가 scrollback을 유지하기 때문입니다: Ctrl-b 다음에 [를 입력하면 copy mode가 시작됩니다. 드래그하거나 화살표 키를 사용해 스크롤하고, q을 누르면 종료합니다.
휴대폰 화면을 사용하기 쉽게 만들기
서버의 ~/.tmux.conf에 있는 4개 줄이 대부분의 작업을 처리합니다.
set -g mouse on
set -g status-position top
set -g default-terminal "tmux-256color"
set -g history-limit 20000mouse on는 터치 드래그를 스크롤로 변환하고 탭을 창 또는 패널 선택으로 변환합니다. 따라서 입력하기 불편한 prefix 키 대부분을 사용하지 않아도 됩니다. status-position top는 tmux 상태 표시줄을 화면 하단 가장자리에서 옮깁니다. 화면 키보드와 제안 표시줄이 하단을 가리기 때문입니다. default-terminal도 중요합니다. 그렇지 않으면 tmux가 Claude Code에 screen 터미널을 알립니다. 그러면 색상과 상자 그리기가 필요한 수준보다 나쁘게 표시됩니다. 이후 tmux가 missing or unsuitable terminal: tmux-256color 때문에 시작되지 않으면 terminfo 항목이 없는 것입니다. sudo apt install ncurses-term을 실행합니다.
키 4개만 익히면 나머지는 편하게 사용할 수 있습니다.
Esc는 응답 중인 Claude를 중단하고 이미 완료한 작업은 유지합니다. 따라서 엄지손가락 가까이에 두어야 하는 키입니다.Ctrl+C도 실행 중인 작업을 중단합니다. 유휴 프롬프트에서 처음 누르면 입력을 지우고, 두 번째 누르면 Claude Code를 종료합니다. 따라서 더 강제적인 도구입니다.Esc을 2번 누르면 초안 프롬프트를 지웁니다. 빈 프롬프트에서는 대신 rewind 메뉴를 엽니다.- 여러 줄 프롬프트를 입력하려면
\을 입력한 다음 Enter를 누릅니다. 이 방식은 모든 터미널에서 작동합니다. Shift+Enter는 일부 데스크톱 터미널에서만 기본 지원되며, 모바일 클라이언트는 해당 목록에 포함되지 않습니다.
분할 패널은 사용하지 않는 것이 좋습니다. 세로 모드의 휴대폰은 너비가 약 40 columns이므로 세로 분할을 사용하면 각 패널에 20 columns만 남습니다. 그러면 모든 diff가 줄바꿈되어 내용을 알아보기 어렵습니다. 대신 tmux 창을 사용합니다. Ctrl-b c로 창을 만들고 Ctrl-b n으로 다음 창으로 이동합니다. diff를 제대로 읽어야 할 때는 휴대폰을 가로로 돌립니다.
작은 화면에서 긴 세션을 사용할 때는 대부분 context 문제가 발생합니다. 따라서 기차에서 하루 종일 작업을 실행하기 전에 Claude Code context window 관리를 읽어 보는 것이 좋습니다.
보안 강화: 키만 사용하고 비밀번호는 사용하지 않기
이제 휴대폰에는 코드를 편집하고 명령을 실행하는 시스템에 접속할 수 있는 키가 저장되어 있다. 비밀번호 인증을 끈다. sshd_config를 직접 편집하는 것보다 drop-in 파일을 사용하는 편이 안전하다. Ubuntu의 sshd_config에는 상단에 /etc/ssh/sshd_config.d/*.conf가 포함되어 있으며, 설정에 대해 처음 발견되는 값이 사용되기 때문이다.
sudo tee /etc/ssh/sshd_config.d/99-phone.conf >/dev/null <<'EOF'
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
PermitRootLogin no
EOF
sudo sshd -t && sudo systemctl reload sshsshd -t는 설정을 구문 분석하며, 설정이 유효하면 아무것도 출력하지 않는다. 이 단계를 건너뛰면 오타 하나 때문에 다시 불러오는 과정에서 sshd가 실패한다. 현재 작업 중인 세션은 열린 상태로 유지하고, 모든 연결을 닫기 전에 두 번째 연결에서 테스트한다. 잘못된 키를 사용하면 Permission denied (publickey).가 발생하며, 비밀번호를 꺼 둔 상태에서는 대체 접속 방법이 없기 때문이다. 이때 복구하려면 provider의 console을 사용해야 한다.
각 장치에 고유한 키를 사용한다. 휴대폰을 분실하면 ~/.ssh/authorized_keys에서 한 줄만 삭제하면 되고, 노트북은 계속 사용할 수 있다. 키 하나를 여러 장치에서 공유하면 소유한 모든 장치에서 키를 변경해야 한다.
Ubuntu 24.04에서 SSH를 다른 port로 옮기는 경우 listener가 ssh.socket에 속한다는 점에 유의한다. 따라서 Port 줄만 추가해도 아무것도 변경되지 않는다. sudo systemctl edit ssh.socket를 실행하고, 빈 ListenStream=로 기본값을 지운 다음, 다음 줄에 사용할 port를 설정한다. VPS에서 SSH 보안 강화에서 이 방법과 나머지 공격 표면에 대해 설명한다.
SSH용 fail2ban은 비밀번호를 끈 뒤에는 보안을 거의 강화하지 않는다. 추측한 비밀번호를 애초에 받아들일 수 없기 때문이다. fail2ban이 추가하는 기능은 로그를 조용하게 만드는 것이며, 이를 통해 실제 로그인 시도를 쉽게 확인할 수 있다.
더 강력한 방법은 SSH를 public internet에 노출하지 않는 것이다. 서버를 직접 호스팅하는 WireGuard VPN 뒤에 두고, 필요할 때 휴대폰에서 tunnel을 활성화한 다음, tunnel에서만 sshd가 ListenAddress를 사용하도록 설정한다. 양쪽이 모두 UDP를 사용하므로 mosh는 tunnel을 통해 작동한다. 한 가지 주의할 점은 tunnel이 packet overhead를 추가한다는 것이다. 대용량 전송이 중단되면 휴대폰의 WireGuard 설정에서 MTU (maximum transmission unit)를 낮춘다.
마지막으로 이 방식으로 작업할 때의 중요한 점이 있다. 휴대폰에서는 한 번에 몇 줄의 diff만 표시되는 화면에서 permission prompt를 승인한다. 이는 보호 장치를 끄라는 이유가 아니라, 그대로 유지해야 할 이유다. VPS에서 Claude Code 안전하게 실행하기에서는 주된 접속 수단이 touchscreen이 되기 전에 설정할 가치가 있는 user 및 directory 제한을 설명한다.
다시 연결했을 때 문제가 있는 경우
tmux attach가 no server running on /tmp/tmux-1000/default을 출력하면 tmux 서버가 사라진 것입니다. 대부분 시스템이 재부팅되었다는 뜻입니다. uptime로 확인합니다. 자동 보안 업데이트로 인한 커널 업데이트는 시스템을 재부팅합니다. 재부팅된 시스템에는 tmux 세션이 없으므로 Claude Code 실행은 언제든 다시 시작할 수 있는 작업으로 처리합니다.
can't find session: claude는 다릅니다. tmux 서버는 실행 중이지만 해당 이름의 세션이 없습니다. tmux ls으로 현재 존재하는 세션을 확인합니다.
연결했을 때 Claude Code가 있던 위치에 일반 셸 프롬프트가 표시되면 세션은 종료되지 않았지만 프로세스가 끝난 것입니다. dmesg -T | tail에서 Out of memory: Killed process 4821 (claude)와 같은 줄을 확인합니다. 이는 4 GB 요구 사항을 충족하지 못하는 시스템이 대규모 편집 중에 표시하는 내용입니다. 이러한 줄이 없으면 Claude Code가 자체적으로 종료된 것입니다. 이 경우 프롬프트 위에 남아 있는 셸의 스크롤백에서 원인을 확인합니다.
창이 작은 크기로 돌아오고 주변에 사용하지 않는 공간이 있으면 서로 다른 크기의 클라이언트 2개가 연결된 것입니다. tmux는 연결된 클라이언트 중 가장 작은 크기에 맞춰 창 크기를 조정합니다. 노트북은 여전히 세션을 200 columns 너비로 유지하고 있지만, phone은 40을 요청하고 있습니다. 연결할 때 다른 클라이언트의 연결을 해제합니다: tmux attach -d -t claude.
FAQ
VPS 대신 휴대폰 자체에서 Claude Code를 실행할 수 있습니까?
아니요. 2026년 7월 기준 지원 플랫폼은 macOS, Windows, Ubuntu 20.04 이상, Debian 10 이상, Alpine 3.19 이상이며 RAM은 4 GB 이상이어야 합니다. Android와 iOS는 지원 목록에 없습니다. 또한 휴대폰은 앱을 절전 상태로 전환하고 네트워크 주소를 계속 변경하므로 장시간 실행되는 에이전트 작업을 처리할 수 없습니다. 서버에서 실행하고 휴대폰은 화면으로 사용하십시오.
앱을 닫거나 신호가 끊겨도 세션이 유지됩니까?
예. 이 작업을 처리하는 구성 요소는 서로 다릅니다. tmux는 서버에서 프로세스를 계속 실행하므로 연결이 종료되어도 프로세스가 중단되지 않습니다. mosh는 주소가 변경되어도 연결 자체를 유지하므로 wifi에서 모바일 데이터로 전환해도 다시 연결할 필요가 없습니다. tmux 없이 일반 SSH만 사용하면 연결이 끊길 때 SIGHUP이 전송되고 Claude Code가 작업 중간에 중지됩니다.
mosh가 연결된 다음 아무것도 표시하지 않는 이유는 무엇입니까?
로그인이 성공한 뒤 Nothing received from server on UDP port 60001.에서 멈춘다면 UDP 60000~61000이 열려 있지 않은 것입니다. ufw에 해당 범위를 추가하고, 대부분의 패널에서 별도로 제공하는 공급자의 네트워크 방화벽에도 같은 범위를 추가하십시오. mosh가 대신 mosh-server을(를) 찾을 수 없다고 보고한다면 서버에 해당 패키지가 없는 것입니다. sudo apt install mosh.
Esc 키가 없는 키보드에서 Claude Code를 중단하려면 어떻게 합니까?
키 행을 추가하십시오. Termux에서는 ~/.termux/termux.properties에서 extra-keys을 사용해 키 행을 구성할 수 있으며, Termius와 Blink에는 설정에서 편집할 수 있는 키 행이 기본 제공됩니다. Esc은(는) 실행 중인 응답을 중단하고 이미 완료된 작업은 유지합니다. Ctrl+C도 중단 기능을 수행하지만, 유휴 프롬프트에서 두 번 누르면 Claude Code가 종료됩니다. 따라서 먼저 Esc을(를) 사용하십시오.
인터넷에 SSH를 공개해도 충분히 안전합니까?
암호 인증을 끄면 인증에 성공할 수 있는 자격 증명은 장치를 벗어나지 않는 키뿐입니다. 다시 구축할 수 있는 시스템이라면 이는 합리적인 위험 수준입니다. 각 장치에 고유한 키를 할당하십시오. 그러면 휴대폰을 분실해도 authorized_keys에서 한 줄만 삭제하면 됩니다. 공용 포트에서 아예 연결을 받지 않으려면 시스템을 WireGuard 뒤에 배치하고 sshd가 터널 주소에서 수신하도록 설정하십시오.