Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
이 도구는 사용자가 휴대폰에서도 컴퓨터의 Claude 코드를 계속 작업할 수 있도록 지원합니다. 게이트웨이나 API 키를 활용하여 데스크톱 환경과 동일한 경험을 제공하며, 제어면(control plane)은 사용자 기기에서 작동하는 것이 특징입니다. 이를 통해 터미널에서 가능한 모든 개발 작업을 모바일에서도 수행할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기登录与设备准入
主页、工作区列表与会话侧栏
会话设置里切到第三方网关的模型
工作区文件浏览与斜杠命令
设置与状态、设备管理、通知与锁屏推送
服务状态、安全事件与手机端安全体检
claude CLI를 구동하며, CLAUDE.md, MCP, skills, 로그인 및 권한 규칙은 모두 동일하게 적용됩니다. 목표는 터미널에서 할 수 있는 모든 것을 휴대폰에서도 할 수 있게 하는 것입니다.claude를 구성하고 사용할 수 있습니다.컴퓨터를 떠날 때 가장 두려운 것은 출력을 못 보는 것이 아니라, 어딘가에서 당신의 개입을 기다리며 하룻밤 동안 멈춰 있는 것입니다. 그래서 먼저 이 세 가지에 대해 말씀드리겠습니다.:
| 터미널에서 | 휴대폰에서 |
|---|---|
| 도구 승인(y / n으로 응답) | 승인/거부/ 이번 라운드 중지 (Esc와 동일). '항상 허용'을 체크하고 현재 세션만 또는 영구적으로 선택 가능 |
| ... | |
| 남은 것은 '계속 작업하기': |
| 터미널에서 | 휴대폰에서 |
|---|---|
claude로 새 대화 시작 / --resume으로 기록 불러오기 | 상단 바의 +를 눌러 새로 만들기, 폴더 선택 (휴대폰에서도 추가 및 생성이 가능하며, '폴더 없음'도 가능), 브랜치, 새 worktree에서 열지 여부 지정; 사이드바에 프로젝트별 모든 대화 목록 표시 (하위 폴더는 각 섹션으로, worktree는 소속 레포지토리에 배치), 제목 자동 생성 및 검색 가능, 실행 중인 항목은 '실행 중'으로 표시 |
| ... | |
추가적으로: 이미지 업로드 및 스크린샷 붙여넣기, 연결 끊김 시 이벤트 보완, PWA를 홈 화면에 추가, doctor로 자체 진단 시작, macOS에는 데스크톱 콘솔도 있음. |
공식 Remote Control을 사용하거나 해당 계정 및 데이터 경로를 수용할 수 있다면, 당연히 공식 기능을 사용하는 것이 기본 권장 사항입니다. 이 프로젝트는 공식 경로에 접근할 수 없거나 그 제어면(Control Plane)을 받아들이지 않는 사람들을 위해 만들어졌습니다: 전자는 일반적으로 claude CLI에서 프록시(중계), 서드파티 모델, 국산 모델 등을 연결하여 사용하며, 이 경우 공식 문은 완전히 닫혀 있습니다. 후자는 대화 기록과 감사 로그를 자신의 기기에 보관해야 하는 경우입니다.
| 공식 Remote Control | Claude Chat Mobile | |
|---|---|---|
| 모델 경로 | claude.ai 구독 로그인 + api.anthropic.com 직접 연결 필요. API key, Bedrock / Google Agent Platform / Microsoft Foundry, 다른 곳을 가리키는 ANTHROPIC_BASE_URL, DISABLE_TELEMETRY 같은 원격 측정(Telemetry) 스위치, ZDR 규정 준수 조직 등 — 이 중 하나라도 충족되면 전체가 사용 불가 | 사용자의 claude CLI 설정대로 사용 가능 — 서드파티 게이트웨이 / API key / Bedrock / Vertex / 원격 측정을 끄는 것 모두 가능 |
| ... |
표현의 경계: 이는 '데이터가 절대 로컬 기기를 벗어나지 않는다'는 의미는 아닙니다. 모델 요청은 본래부터 로컬
claudeCLI에서 사용자의 기존 설정을 따라 발송되기 때문입니다. CCM이 약속하는 것은 그 외에 데이터 출구(data exit)를 하나 더 만들지 않는 것입니다.
CCM은 배포 위치에 대한 가정이 없습니다: claude CLI가 어느 기기에서 작동한다면, 제어면도 그곳을 따라갑니다. 주된 시나리오는 자신의 개발용 컴퓨터이며, 원격 서버에서 실행되는 경우에도 동일합니다. 휴대폰이 연결하는 것은 바로 그 서버입니다.
Node ≥ 20과 로컬 기기에서 이미 사용 가능한 claude CLI가 필요합니다. 이 프로젝트는 Claude를 대신 설치하거나 로그인하지 않습니다.
curl -fsSL https://github.com/Ike-li/claude-chat-mobile/archive/refs/heads/master.tar.gz | tar xz
dcd claude-chat-mobile-master
npm ci --omit=dev && npm run setup && npm start
휴대폰에서 터미널에 출력된 주소를 열면 됩니다. 새 기기에서 처음 접속할 때는 승인 절차를 한 번 거쳐야 합니다: node scripts/device.js list 후 approve <ID>를 실행하세요. 64비트 토큰을 수동으로 입력하는 것은 매우 고통스러우므로, node scripts/qr.js를 사용하면 주소를 QR 코드로 만들어 스캔할 수 있습니다.
서비스 시작 ≠ 채팅 가능. 휴대폰에서 대화가 안 될 경우, 먼저 컴퓨터 터미널에서
claude로 한 라운드 대화를 성공시킨 후 다시 시도하세요. 전체 체크리스트는 [첫 사용 가이드 §8](docs/getting-started.md#8-완료된 첫 검수)를 참조하세요.
코드를 수정하거나 테스트를 실행하려면 전체 레포지토리를 git clone해야 합니다. 설정, 비대화형 setup, PWA, CLI hooks, 업데이트 방식: → 첫 사용 가이드
미리 설치하지 않고도 체험해 보고 싶다면: 온라인 데모를 확인하세요. 이 데모는 본 레포지토리의 실제 프론트엔드(app/public/ 원본)를 사용하며, 백엔드를 브라우저 내 스크립트로 대체한 것입니다 — 작업 공간 전환, 스트리밍 응답, 도구 호출, 승인 카드, 파일 탐색, 백그라운드 작업, 설정 및 상태 등 모든 것이 클릭 가능하지만, 응답은 고정된 스크립트이며 실제로 모델을 호출하지는 않습니다.
휴대폰 PWA / 브라우저 ↕ Socket.io ↕ CCM 서버(로컬 기기) ↕ Claude Agent SDK ↕ 로컬 claude CLI
휴대폰은 단순히 원격 제어면일 뿐입니다. 실제로 코드를 실행하고, 프로젝트를 읽고, 도구를 호출하며, 대화를 유지하는 것은 여전히 사용자의 컴퓨터에 있는 Claude Code입니다 — 데이터베이스도 없고, 멀티테넌시(multi-tenancy)도 없으며, SaaS 백엔드도 없습니다.
알아두어야 할 경계: 동일한 실시간 세션 내에서는 한 순간에 하나의 운전 단말기만 존재합니다. 단말기가 구동 중일 때 Web은 기본적으로 읽기 전용이며, 명시적으로 재개할 수는 있지만 세션 분기(forking)가 발생할 수 있습니다. 즉, 양쪽 끝에서 동시에 동일한 Claude 프로세스로 입력할 수는 없습니다.
컴퓨터에서 떠날 때는 단말기에서 /exit으로 세션을 종료하고; 돌아올 때는 claude -c 또는 claude --resume를 사용하여 다시 시작해야 합니다. 계속 열려 있는 단말기는 사용자가 모바일에서 무엇을 했는지 알지 못합니다. 따라서 나중에 무언가를 작성하거나 종료하면, 다음 재개 시에는 그 단말기가 연결된 가지로 돌아가게 되며, 모바일에서의 내용은 모델의 컨텍스트에 포함되지 않습니다. 만약 이 상황이 발생하면, 전송 전에 사용자에게 팝업창을 띄워 '모바일 내용을 보존하며 새 세션으로 분기할지' 아니면 '평소대로 전송할지' 선택하도록 요청합니다.
듀얼 채널(Dual Channel), 이벤트 동기화, 세션 인수: → 아키텍처 설명
| 시나리오 | 방식 |
|---|---|
| 동일 Wi-Fi | 로컬 네트워크 주소(LAN), 가장 간단한 최초 사용 방법 |
| ... | |
설치 가이드는 모바일에서 어떻게 접근할 계획인지 묻고, 그 답변은 ACCESS_PROFILE에 기록됩니다. doctor는 이와 모바일 단말기의 보안 검진을 바탕으로 맞춤형 점검을 수행합니다. 제품은 어떠한 타사 터널링 도구도 설치하지 않고, 오직 길만 안내할 뿐입니다. PWA 및 Web Push는 HTTPS가 필요하며 (iOS의 경우 16.4 이상 버전이면서 홈 화면에 먼저 추가해야 함)를 충족해야 합니다. |
→ 배포 및 운영
여기는 원격으로 본래 기기의 Claude Code에 접근하고, 간접적으로 본래 기기 코드 실행 능력을 획득할 수 있는 진입점입니다. 일반적인 웹페이지가 아니라 개발용 기기 원격 제어 도구로 간주해야 합니다.
claude를 실행하는 본래 기기의 계정 권한입니다.AUTH_TOKEN은 시작의 전제 조건이며, 모든 바인딩 모드가 마찬가지입니다. 본래 기기 브라우저로 열 때도 토큰이 필요하며, '로컬 면제 인증' 같은 것은 존재하지 않습니다.WORKDIRS에 있는 폴더나 그 하위 폴더, 그리고 해당 리포지토리 자체의 git worktree 안으로만 진입할 수 있습니다. '폴더 없음' 세션은 애플리케이션이 자체 생성한 일회성 디렉터리에 구동됩니다. 모바일에서 폴더를 추가할 수는 있지만, 홈 디렉터리 자체, 디스크 루트, ~/.claude는 추가할 수 없습니다. 연결 범위가 넓을수록 모바일 기기가 접근 가능한 영역도 많아집니다. 예를 들어 ~/code와 같은 대형 디렉토리를 연결하면 그 안에 있는 모든 프로젝트에 접근할 수 있습니다.ssh -R, frp tcp)을 사용할 경우 원격 접속자가 Host: localhost만 전송하면 본래 기기를 사칭할 수 있습니다. 모든 경로에 대해 승인이 적용되도록 하려면 DEVICE_APPROVAL_SCOPE=all로 설정해야 합니다.permissions.allow 등 기존 규칙은 계속 유효하며, 공개 네트워크 사용 전 Bash 및 Write의 자동 허용 규칙을 확인해야 합니다.FILE_EDIT=off로 끌 수 있으며, 장기간 공개 네트워크에 노출하는 것은 비활성화할 것을 권장합니다.장기간 공개 네트워크에 노출하기 전에는 먼저 배포 및 운영을 읽어보십시오. 취약점은 GitHub Security Advisories를 통해 비공개로 보고해야 하며, 이슈를 공개적으로 제기하지 마십시오.
사용법
개발 참여
설정 항목과 명령어 모두 정적 목록을 유지하지 않습니다: node scripts/config.js schema는 현재 설정 정의를 출력하며, 서브 명령어가 없는 모든 CLI는 자체 사용법을 출력합니다.
버그 및 기능 요청은 GitHub Issues로, 보안 취약점은 Security Advisories를 이용해 주세요. 소통 QQ 그룹은 881200369입니다 (클릭하여 참여).
⚠️ 그룹 채팅방에는
AUTH_TOKEN, 공용 네트워크 도메인, 전체ccm.config.json또는 원본doctor출력물을 붙이지 마세요. 이 정보들은 기기를 장악하는 데 충분하며, 그룹 채팅 기록은 모든 멤버에게 공개됩니다.
Apache-2.0 © 2026 Ike-li이며, NOTICE도 참고하세요. 당신은 상업적 용도 및 비공개 제품을 포함하여 자유롭게 사용, 연구, 수정, 자체 호스팅 및 재배포할 수 있습니다. 재배포 시에는 Apache-2.0 제4절의 조건을 충족해야 합니다 (저작권 고지 및 NOTICE 귀속 유지, 라이선스 사본 첨부, 수정된 파일에 변경 사항 표기 등). 전체 조항은 LICENSE를 따릅니다. v1.10.2 이전 버전들은 AGPL-3.0-only로 배포되었으며, 프로토콜 변경에 따른 소급 적용은 없습니다.
관련 링크: LINUX DO