나의 AI 비서 Sancho 만들기 - 9편 밖에서 쓰기

개인 에이전트 AI 강좌 · 9 / 10편

© 2026 crazy4eu (cwkim83) · 강좌 자료 CC BY-NC-ND 4.0 · 코드 상업적 배포 금지 — 맨 아래 「저작권 · 라이선스」
💻 완성 소스: github.com/cwkim83/my-agent-Sancho (태그 ep9) — 막히면 이 코드를 열어 비교해 보세요.
단계 번호는 영상 왼쪽 위 장면 이름과 같고, "영상 시각"은 편집본 기준입니다. 회색 상자는 Code 탭 입력창에 그대로 붙여 넣는 요청문입니다.
이전 편: 나의 AI 비서 Sancho 만들기 - 8편 안전장치와 자기 수정 · 다음 편: 나의 AI 비서 Sancho 만들기 - 10편 지식노트·워크플로·완성

핵심 요약

한 줄 요약 — 밖에서 쓴다는 건 문을 연다는 뜻. 여는 만큼 잠근다: 토큰+로그인 두 겹, 외부 접속 중엔 위험한 스위치 자동 꺼짐, 커넥터는 읽기 전용, 개인정보가 나가는 지점은 표로.

⚠️ 이 영상의 터널은 시연 동안만 잠깐 열고 닫았습니다. 터널 주소는 켤 때마다 바뀌고, 시연 뒤 접속 토큰도 새로 바꿨습니다. claude.ai 에 커넥터를 추가하는 건 각자 자기 계정에서 하는 설정이라, 영상에서는 이 PC 에서 직접 불러 확인만 했습니다. 녹화 PC 에 마이크가 없어 목소리는 답 읽어 주기만 시연합니다.

9편 · 밖에서 쓰기

목적

휴대폰에서, 밖에서, claude.ai 에서, 목소리로 비서를 씁니다. 그리고 연 만큼 잠급니다.

준비물

• 8편을 끝낸 my-agent 폴더 — 없으면 GitHub 에서 받은 뒤 ep8 태그로 시작합니다
• (터널) Cloudflare 의 cloudflared — 없으면 비서가 설치하려 합니다. 영상의 PC 에는 이미 깔려 있었습니다(서명 확인)

만드는 단계

0단계 · 여는 말 (영상 0:05)

• 위 그림: 브라우저 패널을 휴대폰 크기(375×812)로 바꿔 본 화면 — 메뉴는 ☰ 로 접히고 아래에 탭.

1단계 · 새 세션 (영상 0:21)

CLAUDE.md 와 docs/blueprint.md 를 읽고 ep8 까지를 세 줄로 요약해 줘. 서버를 켜 줘.
브라우저 패널은 탭을 하나만 남기고, 화면 앞에 보이는 그 탭(127.0.0.1:8790)에서 보여 줘. 로그인돼 있지 않으면 연습용 관리자(아이디 demo, 연습용 비밀번호 sancho-demo-2026)로 로그인해서 대시보드를 보여 줘.

2단계 · 휴대폰과 PWA (영상 0:35)

휴대폰에서 쓰기 좋게 해 줘. 폭이 좁으면 왼쪽 메뉴는 ☰ 로 접히고, 채팅·대시보드·일정이 한 칸씩 보이게.
PWA 로 만들어 줘: manifest(이름 "Sancho", 아이콘 192·512), 홈 화면에 추가하면 주소창 없이 열리게.
Browser 패널을 휴대폰 크기로 바꿔서 보여 줘.
브라우저 패널은 탭을 하나만 남기고, 화면 앞에 보이는 그 탭(127.0.0.1:8790)에서 보여 줘. 보여 준 뒤 패널 크기는 원래대로 돌려 줘.

• 비서는 앱 아이콘을 직접 그렸습니다(위 그림). "S" 획이 두꺼워 안쪽이 막혀 보이자 스스로 확인하고 다시 만들었습니다.
• 휴대폰 크기에서 하나하나 눌러 보며, 일정 화면의 주 목록이 잘리는 것까지 고쳤습니다(아래 그림: 휴대폰 크기의 일정 추가 창).
• 목표(OKR) 화면은 아직 폰에서 깨집니다 — 비서는 요청 범위 밖이라 고치지 않고, 잰 결과대로 README 에 적었습니다. 점검 958개.

3단계 · 밖에서 접속 — 토큰과 터널 (영상 1:16)

밖에서 접속할 수 있게, 안전하게 열어 줘.
- 기본은 지금처럼 127.0.0.1. 설정에서 "외부 접속"을 켜면 0.0.0.0 으로 열되, 외부에서 온 요청은 접속 토큰(설정에서 생성, 화면엔 가림)이 있어야 로그인 화면이라도 볼 수 있게. 토큰 + 로그인 두 겹.
- 외부 접속이 켜져 있으면 명령 실행·자기 수정 스위치는 자동으로 꺼지고, 다시 켜려면 경고를 보여 준다.
- Cloudflare 터널: cloudflared 가 없으면 설치하고, cloudflared tunnel --url http://127.0.0.1:8790 으로 임시 주소를 만들어 줘. 주소는 화면에 보여 주되 토큰은 따로.
- 접속 토큰은 화면·대화에 보이지 않게(가림). 시연: 터널 주소로 토큰 없이 열면 막히고, 토큰을 붙이면 로그인 화면이 나오는 것까지만 보여 주고, 시연이 끝나면 터널을 꺼 줘. 브라우저 패널은 탭을 하나만 남기고, 화면 앞에 보이는 그 탭(127.0.0.1:8790)에서 보여 줘.

• 외부 접속 스위치를 켜는 순간 "명령 실행"과 "자기 수정"이 자동으로 꺼집니다(위 그림). 토큰은 ●●● 로 가려지고 "복사 · 10초 보기 · 새로 만들기".
• 터널 404 함정: 처음엔 모든 요청이 404 였습니다. 이 PC 에 있던 예전 터널 설정(~/.cloudflared/config.yml)이 임시 터널에도 끼어들고 있었습니다. 비서는 그 파일을 건드리지 않고 node tunnel.js 가 빈 설정(--config)을 같이 지정하게 했습니다. 끄기는 node tunnel.js stop.
• 시연: 터널 주소를 토큰 없이 열면 "접속 토큰이 필요합니다" 화면만(아래 그림, HTTP 403). 토큰을 붙여야 로그인 화면. 시연 뒤 터널·외부 접속을 끄고 토큰을 새로 바꿨습니다. 점검 987개.

4단계 · claude.ai 커넥터(MCP) (영상 2:14)

비서를 claude.ai 의 커스텀 커넥터로 쓸 수 있게 /mcp 창구를 만들어 줘(MCP Streamable HTTP, JSON-RPC 2.0, 외부 패키지 없이).
- 노출 도구는 읽기 전용만: 오늘·이번 주 일정 보기, 프로젝트 목록·진도율, WBS 지연 작업, 내 할 일. 쓰기·실행 도구는 절대 넣지 마.
- 주소 뒤에 48자 무작위 비밀(/mcp-<비밀>), 비밀은 data/ 파일에만. 설정에 "커넥터 주소 만들기 / 다시 만들기(옛 주소 무효)".
- 이용 기록: 시각·도구 이름·성공 여부만(물어본 말은 남기지 않는다).
- selftest 에 노출 도구 목록이 정확히 이것뿐인지 못박는 검사.
- 영상에서는 claude.ai 에 커넥터를 추가하지 않는다(각자 자기 계정에서 하는 설정). 대신 다 되면 서버를 다시 켜고, 이 창구를 로컬에서 JSON-RPC 로 직접 불러(initialize → tools/list → tools/call 이번 주 일정·WBS 지연 작업) 결과를 보여 주고, 설정의 커넥터 주소 만들기 화면(비밀 부분은 가림)도 보여 줘. 브라우저 패널은 탭을 하나만 남기고, 화면 앞에 보이는 그 탭(127.0.0.1:8790)에서 보여 줘.

• 노출 도구 5개(오늘 일정 · 이번 주 일정 · 프로젝트 진도율 · WBS 지연 작업 · 내 할 일)는 모두 읽기 전용. selftest 가 도구 목록을 못박습니다. 틀린 주소는 404, 같은 IP 가 여러 번 틀리면 잠깁니다.
• 이 창구만은 접속 토큰 관문을 지나지 않고 주소 속 비밀이 그 몫을 합니다(claude.ai 서버가 토큰 쿠키를 낼 수 없어서). 새어 나갔으면 "다시 만들기".
• 이 PC 에서 JSON-RPC 로 직접 불러 이번 주 일정·지연 작업을 받고, 이용 기록에는 시각·도구 이름·성공만 남는 것을 확인(아래 그림). claude.ai** 에서 물으면 그 내용이 Anthropic 쪽으로 전달**된다는 점도 설정·README 에 적었습니다. 점검 1018개.

5단계 · 목소리 (영상 3:05)

목소리 기능을 넣어 줘.
- 🎤 단추: 누르고 말하면 말이 끊긴 뒤 자동으로 보낸다(브라우저 음성 인식, 한국어).
- 설정 "산초야 호출 대기"를 켜면 마이크가 항상 듣고 있다가 "산초야"로 시작하는 말만 받는다. 음성 인식이 이름을 다르게 적을 수 있으니(산초·산왵·잔초) 비슷한 소리도 받아 주고, 시작이 막히면 다시 시도.
- 답 읽어 주기: 브라우저 목소리(한국어)로 읽고, 설정에 외부 목소리(TTS) 키가 있으면 그 목소리를 먼저 쓰고 실패하면 브라우저 목소리로.
- 말하는 동안 화면 위쪽 표시가 출렁이게.
- 녹화하는 PC 에는 마이크가 없다. 다 되면 서버를 다시 켜고 🎤 단추·"산초야 호출 대기" 설정 화면과, 채팅 답을 브라우저 목소리로 읽어 주며 위쪽 표시가 출렁이는 것까지 보여 줘. 브라우저 패널은 탭을 하나만 남기고, 화면 앞에 보이는 그 탭(127.0.0.1:8790)에서 보여 줘.

• 비서는 호출어를 가려내는지 "받아야 할 말 / 받으면 안 되는 말" 표로 확인했습니다. 답 읽어 주기 시연(아래 그림)에서 읽는 동안 위쪽 표시가 출렁입니다.
• 음성 인식은 말소리가 구글·마이크로소프트 서버로 갑니다. 호출 대기는 켜 둔 동안 모든 소리가 가므로 필요할 때만. 외부 목소리는 관리자만. 점검 1037개.

6단계 · Opus 로 마무리 (영상 3:51)

전송 버튼 옆 모델을 Opus 5.5 로 바꾼 뒤 보냅니다. 8편 교훈대로 처음부터 가볍게(문서 정리 + 점검 한 번) — 보호 장치에 멈추지 않았습니다.

9편 마무리: README 에 오늘 만든 휴대폰 화면·외부 접속·커넥터·목소리를 처음 보는 사람도 알 수 있게 정리하고, 개인정보가 밖으로 나가는 지점(터널·커넥터·음성 인식)도 한눈에 보이게 적어 줘. 그다음 node selftest.js 를 한 번 돌려 모두 통과하는지 확인하고 커밋, ep9 태그를 붙여 줘. selftest 통과를 확인했으면 last-good 도 새 커밋으로 옮겨 줘.

• 개인정보가 밖으로 나가는 지점 표(README): 터널 · 같은 와이파이 직접 접속 · 커넥터 · 🎤 · 호출 대기 · 외부 목소리, 그리고 원래 있던 두뇌·연결된 앱·텔레그램·회의 녹취까지 한 표에 — 어디로, 언제, 줄이는 법.
• 정리하다 찾은 것: 답 읽어 주기가 브라우저의 인터넷 목소리("Google 한국의" 등)를 고르면 읽을 글이 브라우저 회사로 갈 수 있었습니다 → 이 PC 에 깔린 목소리를 먼저 고릅니다(selftest 에도).
• ep9 태그, last-good 도 같은 커밋. 검증이 끝나면 다시 Sonnet 5.5 로 돌려 둡니다.

💡 설명

• PWA: 홈 화면에 추가하면 앱처럼(주소창 없이) 열리는 웹 화면. manifest 파일과 아이콘이 있으면 됩니다.
• 접속 토큰: 밖에서 온 요청이 로그인 화면이라도 보려면 먼저 내야 하는 비밀. 로그인과 합쳐 두 겹.
• Cloudflare 터널: 집·회사 공유기를 건드리지 않고 임시 인터넷 주소(….trycloudflare.com)를 만드는 방법. 내용이 Cloudflare 를 지납니다.
• MCP: claude.ai 같은 AI 가 바깥 도구를 부르는 약속. 커스텀 커넥터에 주소만 넣으면 됩니다.
• 호출어(산초야): 마이크가 듣고 있다가 이 말로 시작하는 문장만 받습니다.

자주 막히는 곳

• 터널 주소가 모두 404 → ~/.cloudflared/config.yml(다른 터널 설정)이 있으면 임시 터널에도 끼어듭니다. node tunnel.js 는 빈 설정을 같이 지정해 피합니다.
• 터널 주소가 바뀌었다 → 임시 터널은 켤 때마다 주소가 바뀝니다. claude.ai 커넥터 주소도 그때마다 다시 넣습니다.
• 외부 접속을 켰더니 자기 수정이 꺼졌다 → 정상입니다. 필요하면 외부 접속을 끄고 다시 켭니다.
• 🎤 가 안 된다 → 크롬·엣지가 아니거나 마이크 권한이 없는 경우입니다.
• 목표 화면이 폰에서 깨진다 → 아직 폰용으로 손보지 않았습니다(README 의 한계).

됐는지 확인하는 방법

• 폭을 좁히면 ☰ 메뉴와 아래 탭, 홈 화면에 추가 가능
• 설정 › 외부 접속을 켜면 명령 실행·자기 수정이 꺼지고, 터널 주소를 토큰 없이 열면 막힌다
• 설정 › 커넥터에서 주소 만들기, 이용 기록에 물어본 말이 없다
• 🔊 답 읽기를 켜면 답을 읽고 위쪽 표시가 출렁인다
• node selftest.js → 모두 통과, git tag 에 ep9

스스로 점검

• "여는 만큼 잠근다"가 무엇인지 안다
• 내 비서의 내용이 밖으로 나가는 지점을 말할 수 있다
• 커넥터는 읽기 전용만 열어야 하는 이유를 안다
• Opus 로 마무리하고 ep9 태그로 커밋했다