RemoteBridge

내 PC의 AI 코딩 도구(Claude Code · Codex)를 밖에서 폰으로 안전하게 조작하는 1인용 도구.
텔레그램 봇 하나로 두 엔진을 명령·전환·승인까지 완전 원격. Docker·VPN·API 키 불필요, 비용 0.

🇰🇷 한국어 README (기본) · 🇬🇧 English

🐣 컴퓨터·폰·AI가 처음이라 막막하다면 → 가장 쉬운 완전 왕초보 가이드(EASY-START)부터 보세요(따라만 하면 됩니다).

이게 뭐예요? (왕초보 설명)

집·사무실 컴퓨터에서 일하는 AI(Claude Code·Codex)를, 카페·이동 중에 내 폰으로 들여다보고 시키는 "안전한 원격 창문" 입니다.
AI가 위험한 명령(삭제·덮어쓰기 등) 앞에서 멈추면 폰으로 [허용]/[거절] 한 번만 누르면 됩니다.

ℹ️ 비슷한 무료 도구(Happy·공식 앱)도 있어요. RemoteBridge의 값은 ① Claude·Codex를 봇 하나로 함께 ② 알림을 넘어 명령·전환·조종까지 ③ 내 코드가 외부 서버를 안 거치게(무릴레이) ④ 계정·지역 제한 없이 — 이게 필요할 때입니다.

핵심 기능

• 두 엔진 한 봇/웹: Claude Code·Codex 둘 다 새 세션·명령·전환.
• 봇 완전 제어: 텔레그램 /new claude|codex·명령·도구 전환·위험 승인까지 봇 안에서.
• 안전 승인 게이트: 위험 동작은 사람 승인 필수, 무응답 5분(기본) → 자동 거절(fail-safe). 이 시간은 봇 /timeout 으로 조절(30초~24시간).
• 하드라인 차단: rm -rf /·format C:·포크밤 등 파국 + 시스템/자격증명 보호(Windows·System32·Program Files·레지스트리·.ssh/.codex 등에 쓰기·삭제 시도 차단, 읽기·일반 폴더는 통과) — 승인으로도 못 푸는 차단. 시스템 폴더는 허용 목록에도 못 넣음.
• 페어링 우선 방어: 등록 안 된 기기는 로그인 화면조차 안 보임 + 비밀번호 무차별 잠금.
• 무VPN·무릴레이·무키: cloudflared 무료 터널만, 구독 로그인 그대로(API 키 0), 코드는 PC 밖으로 안 나감.
• 세션 기록 영속: 명령·승인 결정·메시지를 로컬 SQLite에 남겨 — 서버를 껐다 켜도 봇 /history·/log 로 "내 AI가 무엇을 했고 내가 무엇을 허용/거절했는지" 다시 조회.

빠른 시작 (3단계)

0. 한 번만 준비

• PC에 Node.js 22+ 설치 — nodejs.org. 확인: node -v → v22.x 이상.
• AI CLI 설치 + 로그인(둘 중 쓸 것만 있어도 됨): claude(Claude Code) / codex(Codex) CLI가 아직 없으면 각 도구 공식 안내대로 먼저 설치·로그인하세요. 설치됐으면 확인 — codex login status(→ Logged in using ChatGPT) 또는 claude -p "hi"(답하면 OK). API 키는 필요 없습니다(구독 로그인 그대로 사용).
• 의존성 설치(앱 폴더에서 1회):

  cd app
  npm install
  

1. 켜기

가장 쉬운 방법: app\start.bat 더블클릭(Node·의존성 자동 확인 → 자동 시작, 명령 입력 0). 또는 명령으로:

cd app
npm start

(부팅 시 자동 시작을 원하면 app\autostart-on.bat — 끄려면 autostart-off.bat. ⚠️ 자동실행은 공개 주소를 상시 노출하니 안 쓸 땐 끄세요.)

📦 폴더 위치·이름 자유: 이 프로젝트 폴더는 어느 드라이브·어떤 폴더 이름에 둬도, 다른 곳으로 옮겨도 그대로 작동해요(설정을 설치 위치 기준으로 읽음 — 현재 폴더 무관). 단, 자동 시작을 켠 뒤 폴더를 옮겼다면 바로가기 경로가 어긋나므로 autostart-on.bat만 한 번 다시 실행하세요.

콘솔에 등록 코드 + 공개 주소(https://…trycloudflare.com) 가 뜹니다.
(로컬만 테스트: NO_TUNNEL=1을 환경변수로 두면 http://127.0.0.1:8770)

🟢 이 콘솔 창을 닫지 마세요. RemoteBridge는 클라우드가 아니라 내 PC에서 도는 프로그램이라, 이 창이 켜져 있는 동안에만 폰 접속도 텔레그램 봇도 작동합니다. 창을 닫거나 Ctrl+C 하거나 PC가 절전·종료되면 봇도 함께 멈춥니다(봇이 응답 없으면 → 서버가 꺼진 것). 최소화(_)는 OK.

2. 폰으로 접속

공개 주소 열기 → 등록 코드 입력(기기 등록) → 비밀번호 로그인 → 도구(Codex/Claude)·작업 폴더 선택 → 명령 → 위험하면 [허용]/[거절].

📱 따라 하기 쉬운 전체 안내: app/WALKTHROUGH.md (설치봇 명령어문제 해결 A-Z).

텔레그램 봇 명령어 (메인 사용법)

봇 토큰을 설정(아래 "환경 변수" + KEYS_GUIDE)하면, 텔레그램에서 봇에게:

💡 명령어를 까먹어도 OK: 텔레그램 입력창의 / 버튼(≡ 명령 메뉴) 을 누르면 등록된 명령이 뜨고, /help 를 보내면 전체 목록을 봇이 답해줍니다.
📖 각 명령을 보내면 봇이 어떻게 답하는지(구체 예시) → app/WALKTHROUGH.md §3.
⚠️ 봇은 start.bat 서버가 켜져 있을 때만 응답합니다(봇이 곧 그 서버). 무응답이면 서버 창부터 확인. 봇 메시지의 비밀값은 자동 마스킹됩니다.

🔒 허용 폴더 관리 — AI가 만질 수 있는 폴더 정하기 (PC에서만)

AI는 여기서 정한 폴더 안에서만 파일을 읽고·고치고·지울 수 있어요. 그 밖은 거부됩니다(폰을 잃어버려도 남이 아무 폴더나 못 열게 하는 핵심 방어). 이 목록은 보안 울타리라 폰이 아니라 PC에서만 바꿉니다.

1) 여는 법

PC에서 app\manage-folders.bat 더블클릭 → 버튼 창이 떠요. (창을 못 띄우는 환경이면 자동으로 글자 메뉴로 바뀌니 먹통 없음.)
창 구성: 현재 허용 폴더 목록(각 줄에 "하위 N개 포함" 표시) · 위쪽 경로 붙여넣기 칸 · [폴더 찾아서 추가] · [선택 제거] · [닫기].

2) 폴더 추가 — 두 가지 방법

1. 경로 붙여넣기(가장 빠름): 윈도우 탐색기에서 폴더를 Shift+우클릭 → "경로로 복사"(또는 주소창에서 복사) → 창의 칸에 붙여넣고 [경로로 추가] (또는 Enter).
   • "경로로 복사"가 붙이는 따옴표("…")는 자동 정리되니 그대로 붙여도 돼요.
2. 폴더 찾아서 추가: [폴더 찾아서 추가] → 폴더를 클릭해 고르기(타이핑 0).

📁 추가하면 그 폴더 + 하위 폴더가 전부 열려요. 예: D:\AI_Dev_Work\내프로젝트 를 넣으면 그 안의 모든 하위 폴더까지 AI가 작업 가능. 추가할 때 "하위 N개 포함" 으로 범위를 미리 보여줍니다.

3) 안전 가드 (실수·위험 자동 차단)

• 시스템 폴더 차단: C:\Windows·Program Files·.ssh·.codex 같은 폴더는 추가 자체가 거부.
• 드라이브 전체 차단: D:\·C:\ 처럼 드라이브 통째는 너무 넓어 거부(특정 작업 폴더를 고르라고 안내).
• 너무 넓은 폴더 확인: 홈 폴더(C:\Users\내계정)나 하위가 아주 많은 폴더(프로젝트 모음 등) 는 추가 전에 ⚠️ "그래도 추가할까요?"를 물어요 — 여기서 [하위 폴더 다시 고르기] 로 더 좁은 폴더를 고를 수 있어요. 이미 넓게 들어간 폴더는 목록에 [!] 로 표시돼 바로 제거 가능.

4) 제거 / 즉시 적용

• 제거: 목록에서 폴더를 고르고 [선택 제거] → 확인.
• 즉시 적용: 서버(start.bat)가 켜져 있으면 추가/제거가 바로 반영돼요(재시작 불필요·진행 중 작업 안 끊김). 곧바로 봇에서 /cd <그 폴더> 로 옮겨 작업 가능.

직접 편집을 원하면 app\.env.local 의 RB_ALLOWED_ROOTS=D:\일감;D:\실험 처럼 세미콜론으로 적어도 돼요.

환경 변수

⚠️ 비밀값은 app/.env.local에 저장하고 절대 Git에 올리지 마세요(이미 .gitignore 처리됨).
🔑 키·비밀번호·봇 토큰 추가/수정/교체/제거가 처음이면 → app/KEYS_GUIDE.md (왕초보 단계형 가이드 · API 키는 불필요합니다).

텔레그램 봇 토큰 넣기 · 바꾸기 · 빼기 (선택 — 봇으로 쓸 때)

🖱️ 가장 쉬운 길: app\manage-env.bat 더블클릭 — 버튼으로 토큰·chat ID·포트·비밀번호 넣기/바꾸기/빼기(형식검증으로 오타 차단·저장 전 자동 백업·비밀값 마스킹·PC 전용). 아래는 직접 편집하고 싶을 때.

app\.env.local 을 메모장으로 열어 아래 두 줄을 적고 저장 → 서버 재시작(Ctrl+C → 다시 start.bat):

TELEGRAM_BOT_TOKEN=8123456789:AAE...   # 텔레그램 @BotFather → /newbot 에서 받기
TELEGRAM_CHAT_IDS=123456789            # 텔레그램 @userinfobot 에서 받기(내 chat ID)

• 수정·교체: 위 토큰 값을 새 것으로 바꾸고 저장 → 재시작.
• 제거: 두 줄을 지우고(또는 값 비우고) 재시작 → 봇 비활성(웹 화면은 그대로 사용).
• ⚠️ 토큰이 노출되면(스크린샷·복사 등) 즉시 텔레그램 @BotFather /revoke 로 옛 토큰을 무효화하고 새 토큰으로 교체하세요.

그림처럼 따라 하는 전체 단계(비밀번호 변경·오류 대처 포함) → app/KEYS_GUIDE.md

테스트 / 빌드

• 타입 검사: npm run typecheck
• 빌드: 별도 빌드 없음 — Node 22의 네이티브 TypeScript 실행(tsx/esbuild 불필요).
• 엔진 업데이트 점검: npm run doctor — Claude·Codex 버전 감지 + 안전 게이트 라이브 재확인(거절=차단/허용=실행) + .env 건강검진(토큰·chatID·포트 형식·인코딩(BOM)·PORT 충돌을 비밀값 노출 없이 진단). 빠르게 버전만: npm run doctor quick(env 점검은 항상 포함). CLI가 업데이트되면 켤 때 자동으로 "재확인 권장" 안내가 뜨고(봇 /doctor 로도 확인), doctor 가 통과하면 그 버전을 "확인됨"으로 기록해 조용해집니다.
• 자동 검증(스모크): 39종. 빠른 것(외부 불필요):

  npm run smoke:auth      # 비번·페어링·잠금·fail-safe
  npm run smoke:hardline  # 파국 명령 차단
  npm run smoke:paths     # 허용 루트 가드
  npm run smoke:telegram  # 봇 명령·마스킹
  npm run smoke:folders   # 허용 폴더 추가/제거·넓은폴더 가드
  npm run smoke:versions  # 엔진 버전 감지·변화 판정
  npm run smoke:env-config # .env 형식·인코딩(BOM)·PORT 충돌 진단
  

  실제 CLI 호출(느림·구독 사용): smoke:engine(Codex)·smoke:claude·smoke:server·smoke:webclaude 등.

  실 CLI 스모크는 하나씩 돌리는 걸 권장(여러 개 연속 실행 시 일시적 부하로 실패할 수 있음).

보안 주의사항 (꼭)

• 공개 주소(터널 URL)를 SNS·메신저에 올리지 마세요.
• 비밀번호는 길고 추측 어렵게, 첫 실행 전 MASTER_PASSWORD로 바꾸세요.
• 첫 실험은 빈 폴더로(중요 코드 폴더 금지).
• 폰 분실 시 다른 기기 로그인 → ⚙ 기기 관리 → [폐기].
• 봇 토큰이 노출되면 즉시 텔레그램 @BotFather /revoke 로 무효화 후 새 토큰으로 교체(위 "텔레그램 봇 토큰" 참고).
• 세션 기록(app/data/history.sqlite)에는 명령·출력 일부가 남아요 — data 폴더(비번 해시도 있음)는 공유하지 말고 PC에 안전히 두세요.
• 안 쓸 땐 Ctrl+C로 끄세요(공개 URL 노출 면적 최소화).

자주 막히는 곳

프로젝트 구조

.PRD/        설계 문서(PRD)
app/
  src/
    auth/    비밀번호·페어링·잠금
    db/      SQLite 저장소
    engine/  Codex(app-server) · Claude(PreToolUse 훅) 엔진
    gateway/ 텔레그램 봇 어댑터
    safety/  하드라인 차단
    server/  Fastify + WebSocket + 웹 UI
    tunnel/  cloudflared 관리
  WALKTHROUGH.md         첫 사용 / 실폰 런북
  VERIFICATION_STATUS.md 검증 원장(무엇이 진짜 검증됐는지)
spike/       기술 검증 기록(Claude 승인 가로채기 등)

상태 (정직)

• 자동 검증 300+개 단언 + 타입 검사 통과(보안·엔진·서버·봇·복구·웹UI·세션기록).
• ⬜ 미검증(사용자 영역): 실제 폰 1회 종단 테스트, macOS·Linux 실기, 실제 봇 토큰 e2e.
• 세션 활동 기록(명령·승인 결정·메시지)은 로컬 SQLite에 영속 — 서버 재시작 후에도 조회 API로 다시 봄(smoke:history/history-wiring/history-api). 단 재시작 시 진행 중 세션 자체는 종료되므로 과거 기록 보기이지 세션 이어하기는 아님. 프롬프트 인젝션은 다층 방어로 완화(완전 차단은 비목표).
• ⚖️ 엔진 역할 분담(2026-06-09 확정): Claude = 신중 엔진 — 자체 PreToolUse 훅으로 모든 도구(파일 편집 포함) 전에 [허용]/[거절]을 받습니다(smoke:claude). Codex = 빠른 작업 엔진 — 파일 쓰기·명령을 매번 묻지 않고 바로 실행합니다(승인 카드가 codex엔 안 뜸). 이유(실측): Windows 글로벌 [windows] sandbox="elevated"로 실제 OS 샌드박스가 없고, codex는 막아도 "승인이 필요 없는 방식"으로 우회해서(app-server/exec/sandbox 어떤 설정으로도) 신뢰성 있는 codex 승인 게이트가 불가능합니다. (codex 훅 강제는 사용자 codex 설정을 건드려야 하고 oh-my-codex가 조용히 무력화 가능 = 거짓 안심이라 채택 안 함.) → codex는 가볍고 빠른 작업에, 위험·되돌리기 힘든 작업(중요 파일 수정·삭제·시스템 명령)은 /new claude로(매번 묻고 파국 명령 차단). 봇이 세션 시작 시 이 차이를 안내합니다. 상세 = app/VERIFICATION_STATUS.md.

1인 사적 사용 도구입니다. 검증 현황 정본 = app/VERIFICATION_STATUS.md.

라이선스

Apache License 2.0 — © 2026 SoDam AI Studio. 전체 본문은 LICENSE 참고.