상구너의 개발노트

한글(.hwp) 파일을 브라우저에서 바로 PDF 로 — rhwptopdf 만든 이야기

상구너 — Fri, 29 May 2026 16:46:46 +0900

한국에서 일하다 보면 .hwp / .hwpx 를 피할 수가 없습니다. 관공서, 학교, 사내 양식까지 — "PDF 로 좀 바꿔 주세요" 한 줄이 의외로 무겁습니다. 이 글은 그 한 줄을 브라우저 안에서, 업로드 없이, 오프라인으로 해결하려고 만든 오픈소스 rhwptopdf 의 제작기입니다.

온라인 데모 — https://sanguneo.github.io/rhwptopdf/
GitHub — https://github.com/sanguneo/rhwptopdf

왜 만들었나

HWP 파일을 PDF 로 바꿔야 할 때, 보통 선택지는 두 가지입니다.

한컴 오피스를 설치한다. 1인 라이선스도 비싸고, 서버 자동화에는 더 부담스럽습니다.
온라인 변환 사이트에 올린다. 무료 SaaS 는 대체로 어딘가의 서버에 파일을 업로드합니다. 회사 문서나 개인 정보가 든 양식을 그렇게 던지긴 찝찝합니다.

저는 세 번째 선택지를 만들고 싶었습니다. 브라우저 안에서, 네트워크 없이, 사용자 PC 안에서만 끝나는 변환기.

출발점 — `rhwp`

HWP 파서를 제가 처음부터 짠 건 아닙니다.

HWP 5.0 binary spec 은 공개돼 있지만, 실제로 파싱하려면 OLE compound document, record-based 인코딩, 본문 흐름 / 표 / 도형 / 수식까지 — 학습 곡선이 만만치 않습니다.

다행히 edwardkim/rhwp 라는 훌륭한 Rust 구현체가 있었습니다.

HWP 5.0 / HWPX 파서
페이지네이션과 SVG / Canvas 렌더링
WebAssembly 빌드 가능
Apache License 2.0

이미 "브라우저에서 HWP 를 보는" 부분은 이쪽에서 해결돼 있던 거죠. 다만 rhwp 는 뷰어 / 에디터 입니다. PDF 출력 파이프라인이 없습니다.

그래서 결정한 컨셉은 다음과 같습니다.

rhwp 의 파서 + 레이아웃 렌더러 를 cherry-pick 해서, 그 위에 PDF 출력 한 가지 만 얹은 별개 트랙 라이브러리를 만들자.

rhwptopdf 라는 이름이 그대로 의도입니다. "rhwp to pdf", rhwp 가 만든 SVG 출력을 PDF 로 마무리하는 얇은 한 겹.

어떻게 동작하는가 — 5 단계 파이프라인

페이지 한 장당 다음 5 단계를 거칩니다.

1) SvgRenderer — HWP → SVG

rhwp 가 이미 잘 하던 일입니다. HWP 페이지 (본문, 표, 도형, 수식) 를 96 dpi 픽셀 단위의 SVG 로 그립니다. WASM 안에서 메모리 상으로만 일어나고, 디스크로 떨어지지 않습니다.

2) font-family 정규화

여기서 첫 번째 함정. HWP 의 doc_info 안에 들어 있는 폰트명이 가끔 깨져 있습니다. 어떤 문서에는 "신명조■얒a" 같은 식으로 — 한글 + 끔찍한 컨트롤 문자 조합. 이걸 그대로 PDF 폰트 매칭에 쓰면 매칭이 안 됩니다.

처음엔 sanitizer 를 강하게 짰지만, 결국 한 단계 더 단순화했습니다.

바탕 / 명조 / 궁서 / Batang / Myeongjo → serif
돋움 / 고딕 / 굴림 / Dotum  / Gothic   → sans-serif

SVG 안의 모든 font-family 를 두 가지 generic 으로 줄여 버리고, 실제 렌더는 fontdb 에 등록된 폰트가 담당합니다. "정확히 그 폰트로 그린다" 가 아니라 "비슷한 계열의 안 깨지는 폰트로 그린다" 쪽으로 트레이드오프 한 것.

3) usvg text-to-path

PDF 의 텍스트는 "어떤 글자를 어디에" 라는 추상 정보일 뿐이고, 글자가 어떻게 생겼는지는 PDF 뷰어가 가진 폰트에 달려 있습니다. 한글 폰트는 PDF 뷰어마다 다르고 — 특히 모바일 뷰어, 사내 뷰어에서 깨질 가능성이 큽니다.

그래서 usvg 를 써서 글자를 vector path 로 변환 해 버립니다. 모든 글자가 SVG 의 <path> 가 되고, PDF 안에서도 path 로 박힙니다. 뷰어가 어떤 폰트를 가지고 있든 상관없이 똑같이 보입니다.

대가는 fontdb 의존성입니다. 변환 시점에 폰트 데이터가 메모리에 있어야 글리프 outline 을 뽑을 수 있어요. 이게 다음 챕터로 이어집니다.

4) svg2pdf → 5) pdf-writer

svg2pdf::to_chunk() 가 SVG 한 페이지를 PDF XObject 청크로 변환하고, pdf-writer 가 여러 페이지의 청크를 묶어서 page tree 를 짭니다. media_box 는 96 dpi 픽셀을 × 72 / 96 으로 PT 로 환산해서 표준 A4 (595 × 842 pt) 가 되도록 맞췄습니다.

작은 함정 하나 더. 초반에 PT 환산을 빼먹어서 PDF 가 1.33× 부풀어 나왔습니다. SvgRenderer 출력이 픽셀이라는 걸 까먹은 거죠. 한 줄로 끝.

const PX_TO_PT: f32 = 72.0 / 96.0;

가장 오래 걸린 챕터 — 폰트

위 파이프라인의 3) 단계가 잘 동작하려면, fontdb 에 그 문서가 쓰는 글리프를 다 가진 폰트 가 등록돼 있어야 합니다. 한글이라는 게 11,172 자 (KS X 1001 완성형) 라, 부분 폰트만 가지고는 절반은 .notdef 로 나옵니다.

여러 단계를 거쳤습니다.

시도 1 — 한컴 함초롬 Ext 폰트

HAN*Ext 시리즈가 가장 먼저 떠올랐는데, 이름이 "Ext" 인 데에는 이유가 있더군요. 한글 음절 0 / 11172 자 — 확장 한자 / 특수 기호만 든 폰트였습니다. PDF 출력에서 한글이 완전히 사라지는 사태.

시도 2 — 함초롬바탕 / 함초롬돋움 (full)

HANBatang.ttf / HANDotum.ttf 로 교체. 11172 / 11172 자 모두 커버. 이제 글자가 보입니다. 다만 다음 문제 — WASM 번들에 6 MB 짜리 폰트 두 개를 박으면 라이브러리 크기가 폭발합니다.

시도 3 — 시스템 폰트를 먼저 써 보자

Font Access API 라는 게 있습니다. Chrome 105+ 부터 window.queryLocalFonts() 로 OS 에 설치된 폰트 목록을 (사용자 허가 하에) 읽을 수 있어요.

const fonts = await window.queryLocalFonts();
// [
//   { family: "맑은 고딕",
//     fullName: "Malgun Gothic",
//     postscriptName: "MalgunGothic",
//     blob() },
//   ...
// ]

이 흐름이 데모 페이지의 기본값이 됐습니다.

페이지 로드 시 window.queryLocalFonts() 시도
사용자가 local-fonts 권한을 허락하면, 시스템에 설치된 한글 폰트 (맑은 고딕, 나눔고딕, 본고딕 등) 를 그대로 registerPdfFont() 에 넣음
권한 거부 or 미지원 브라우저 (Firefox / Safari) 면 정적 fallback 폰트 로 떨어짐 — 데모에서는 HANBatang.ttf / HANDotum.ttf 를 별도 다운로드

라이브러리 자체 는 폰트를 번들하지 않습니다. registerPdfFont(bytes) API 만 노출해 두고, "그 바이트를 어디서 가져와서 넣는지" 는 호출자에게 맡깁니다. 데모 페이지만 정적 fallback 을 갖고 있을 뿐.

이게 라이브러리 사이즈를 6 MB (.wasm) + 16 KB (.umd.js) 로 유지할 수 있게 한 결정적인 트레이드오프였습니다.

시행착오 모음

PDF 출력이 처음엔 멀쩡해 보였는데, 실제 문서로 테스트해 보니 자잘한 버그가 줄줄이 나왔습니다.

"root2" 가 글자 그대로 박혀 나옴

수능 기출 한 문제로 테스트하다가 발견. HWP 수식이 PDF 에 root2 라는 raw 텍스트로 박혀 있었습니다. 수학 기호 √2 가 되어야 할 자리에. 원인은 rhwp 의 수식 토크나이저였습니다. root / sqrt 같은 키워드 뒤에 숫자가 붙으면 (root2, sqrt9) prefix-split 을 안 하고 통째로 식별자로 잡고 있었어요. 토크나이저에서 prefix 매칭 후 나머지를 별도 토큰으로 잘라내는 한 줄을 끼워 넣어 해결.

데모 페이지

데모 페이지 구현은 아래처럼 진행했습니다.

왼쪽: 드롭존 + "PDF 로 변환" 버튼 + 4-step stepper (분석 → 폰트 → 변환 → 완료)
오른쪽: PDF 미리보기 iframe
아래: 접을 수 있는 실행 로그

내부적으로는 HwpToPdfJob extends EventTarget 이라는 작은 wrapper 클래스가 변환 라이프사이클을 캡슐화합니다. progress / complete / error 이벤트를 발행하고, 데모 UI 는 이걸 구독해서 stepper 상태를 진행합니다. WASM 쪽에는 progress streaming 을 안 넣었습니다 — JS 만으로도 stepper 효과는 충분히 나오고, WASM 표면을 단순하게 유지하고 싶었어요.

사용법 — CDN 한 줄

배포된 UMD 번들을 그대로 끌어다 쓰면 됩니다.

<script src="https://github.com/sanguneo/rhwptopdf/releases/latest/download/rhwptopdf.umd.js"></script>
<script type="module">
  // 1) WASM 초기화
  await RhwpToPdf({ module_or_path: ".../rhwptopdf.umd_bg.wasm" });

  // 2) 변환용 폰트 등록 (한 번씩)
  const ttf = new Uint8Array(await (await fetch("/fonts/HANBatang.ttf")).arrayBuffer());
  RhwpToPdf.registerPdfFont(ttf);

  // 3) HWP → PDF
  const hwpBytes = new Uint8Array(await file.arrayBuffer());
  const pdfBytes = RhwpToPdf.hwpToPdf(hwpBytes);  // Uint8Array
</script>

API 표면은 작습니다.

analyzeHwp(bytes): { pageCount, fontsRequired }   // 메타데이터만 빠르게
hwpToPdf(bytes): Uint8Array                       // 본 변환
registerPdfFont(bytes): string                    // family name 자동 감지
clearPdfFonts(): void
extractThumbnail(bytes): unknown                  // PrvImage 추출 (옵션)

한계 / 솔직한 단점

자랑만 하면 곤란하니까 몇 가지 명확히 짚어 둡니다.

fontdb 가 필수입니다. 글리프를 path 로 박는 트레이드오프의 대가입니다. 사용자가 폰트를 한 번은 넣어 줘야 합니다. (데모에서는 시스템 폰트로 우회했습니다)
font-family 가 generic 으로 단순화됩니다. "이 문서는 굴림체로 통일" 같은 디테일은 보존되지 않습니다. 대신 어떤 환경에서도 깨지지 않습니다.
수식 / 도형 100% 호환 아닙니다. rhwp 의 렌더러가 커버하는 범위가 곧 rhwptopdf 의 한계입니다. 학회지 같은 복잡한 수식은 일부 어긋날 수 있어요.
6 MB WASM. 모바일에서 초기 로딩이 가볍지는 않습니다. 첫 변환 후엔 캐싱되니 두 번째부터는 빠릅니다.

라이선스 — `rhwp` 에 대한 감사

자체 코드는 MIT 입니다.
rhwp 에서 cherry-pick 한 parser / renderer 모듈은 Apache-2.0 그대로 유지됩니다.

Apache-2.0 § 4 는 재배포 시 attribution 과 변경 기록 보존을 요구합니다. NOTICE 파일에 정확히 어떤 모듈이 어디서 왔는지, 어떤 변경을 가했는지 적어 뒀습니다. 같은 영역 (한국어 문서 처리) 에서 이런 토대를 만들어 두신 Edward Kim 님과 rhwp 컨트리뷰터분들께 감사드립니다.

마무리

rhwptopdf 는 "있으면 좋겠다" 가 "있다" 가 된 결과물입니다. 지금은 v0.1.0 이고, 사용 중 발견된 버그 / 한계는 GitHub Issues 로 받습니다.

오프라인 PC 에서, 사내망 안에서, 모바일에서 — 어디서든 .hwp 한 장을 PDF 로 바꿔야 할 일이 생기면, 한 번 써 보고 의견 주세요.

데모 — https://sanguneo.github.io/rhwptopdf/
GitHub — https://github.com/sanguneo/rhwptopdf

읽어 주셔서 감사합니다.

Supertonic TTS 커스텀 프록시에서 공식 serve로 갈아탄 썰

상구너 — Thu, 21 May 2026 17:16:17 +0900

로컬 TTS 서버를 운영한 지 꽤 됐다. Supertonic이라는 한국 회사(Supertone)가 만든 TTS 엔진을 FastAPI로 직접 감싸서 OpenAI 호환 /v1/audio/speech 엔드포인트로 만들어 쓰고 있었는데 — 예전에 썼던 Supertonic 3 업그레이드 후기 — 온디바이스 TTS 프록시를 v2에서 v3로 올리며 에서 다뤘던 그 프록시다 — v1.3.1부터 공식 serve CLI가 나오면서 모든 게 달라졌다.

원래 구조

예전에는 이렇게 생겼었다:

supertonic_openai_tts_proxy/
├── main.py          # FastAPI 앱, 엔드포인트 정의
├── schemas.py       # Pydantic 요청 모델
├── synth.py         # supertonic.TTS 직접 호출
├── audio.py         # ffmpeg 변환
└── frontend/        # 테스트용 플레이그라운드

synth.py에서 supertonic.TTS 객체를 직접 생성하고, 모델을 로딩하고, 음성을 합성해서 WAV로 내보내고, 다시 audio.py에서 ffmpeg로 mp3/opus로 변환했다.

처음에는 재미있었다. TTS 엔진을 직접 다루니까 내부 동작도 이해되고 제어할 수 있다는 만족감도 있었다.

다만 시간이 지나면서 몇 가지 아쉬운 점이 눈에 띄기 시작했다.

한계

Supertonic 버전 올릴 때마다 내 코드도 고쳐야 함 — API 변경이 생기면 synth.py부터 다시 확인
내가 만든 /v1/audio/speech 밖에 없음 — health 체크, 음성 목록 조회, 배치 합성 같은 건 직접 만들기는 귀찮아서 안 만듦
프론트엔드 플레이그라운드도 내가 직접 만듦 — TTS 서비스를 만드는 게 본업은 아니라서
유지보수 포인트가 계속 쌓임 — 시간이 갈수록 신경 써야 할 부분이 늘어남

공식 serve 등장

Supertonic v1.3.1부터 supertonic serve라는 CLI가 생겼다. pip install 'supertonic[serve]' 한 방으로 실행되는, 완전한 OpenAI 호환 /v1/audio/speech 서버였다.

게다가 내가 안 만든 것들도 다 있었다:

/v1/health — 상태 체크
/v1/styles — 음성 목록
/v1/tts — 네이티브 합성
/v1/tts/batch — 배치 합성
/docs — Swagger 문서

딱 하나 빠진 게 있었는데, 바로 mp3/opus 출력이었다. 공식 serve가 지원하는 포맷은 wav, flac, ogg(Vorbis) 뿐이었다. 문제는 텔레그램이 opus를 쓰고, 일반적인 TTS 클라이언트들이 mp3를 자주 요청한다는 점.

그래서 바꾼 구조

serve와 커스텀 프록시를 완전히 분리했다.

supertonic serve (:8788)        ← 공식 serve (Supertone이 관리)
    ↕
supertonic-proxy (:8789)        ← 130줄 ffmpeg 변환 프록시 (내가 관리)
    ↕
Hermes / OpenAI 클라이언트

supertonic serve는 8788번 포트에서 내부 백엔드로만 띄움
8789번 프록시는 들어오는 요청 중 /v1/audio/speech만 가로채서 WAV로 받은 뒤 ffmpeg로 변환
그 외 모든 요청(/v1/health, /v1/styles, /v1/tts 등)은 그냥 통과(패스스루)

프록시 코드는 직접 짰지만 단 130줄. httpx + FastAPI + ffmpeg 서브프로세스 호출이 전부다.

핵심 로직만 보면:

if fmt in ("wav", "flac", "ogg"):
    # 공식 serve가 네이티브로 지원 — 그냥 통과
    return await forward(body)

# 나머지(mp3, opus, aac): WAV로 받아서 ffmpeg 변환
wav = await request_wav(body)
return await ffmpeg_convert(wav, fmt)

이게 끝이다. 변환이 필요 없는 포맷은 serve가 직접 처리하고, 필요한 포맷만 WAV를 받아서 바꿔준다.

뭐가 좋아졌나

항목	전	후
TTS 엔진 코드	내가 직접 호출	serve가 다 해줌
유지보수	synth.py 등 4개 모듈	serve는 Supertone한테 맡김
엔드포인트	/v1/audio/speech 하나	health, styles, batch, docs 전부
프록시 코드	복잡	130줄 (ffmpeg 변환만)
포맷 지원	mp3/opus/wav	serve 네이티브(wav/flac/ogg) + 프록시(mp3/opus/aac)

제일 큰 변화는 "써드파티 TTS 서버 운영"에서 "공식 serve 앞단에 변환기 하나 붙인" 걸로 지위가 바뀐 점이다. 예전엔 Supertonic이 업데이트되면 내 코드도 같이 고쳐야 했는데, 지금은 그냥 pip install --upgrade supertonic[serve] 한 방이다.

근데 왜 굳이

"그냥 serve만 써도 되지 않냐?" — 맞다. wav/flac/ogg만 써도 되는 환경이면 serve 하나로 끝이다.

나는 Hermes Agent 와 텔레그램을 연결해서 쓰고있는데, 이 음성메시지가 opus 포멧으로 해야 올라간다.

변환 단계가 하나 더 끼면:

포트 하나 더 씀 (8788, 8789)
ffmpeg 서브프로세스 오버헤드 (작지만 무시할 순 없음)
고장 포인트가 하나 더 생김

대신 mp3/opus/aac를 쓸 수 있고, serve가 커버 못 하는 포맷을 유연하게 추가할 수 있다. 트레이드오프는 명확하다.

Supertonic 3 업그레이드 후기 — 온디바이스 TTS 프록시를 v2에서 v3로 올리며

상구너 — Sat, 16 May 2026 16:40:31 +0900

들어가며

며칠 전 Supertonic 3가 릴리즈되었다는 소식을 들었다. Supertonic은 한국 스타트업 Supertone이 만든 온디바이스 TTS 엔진으로, ONNX Runtime 기반으로 로컬에서 구동되어 클라우드 의존성이 전혀 없다. 나는 이걸 OpenAI /v1/audio/speech 규격으로 감싸는 프록시(supertonic-openai-tts-proxy)를 만들어 Hermes Agent의 TTS 백엔드로 쓰고 있었는데, 이번에 v3로 업그레이드하면서 경험한 내용을 정리해본다.참고로 이 작업에는 Hermes Agent를 쓰고 있고, 백엔드 모델로 이번에는`deepseek/deepseek-v4-flash`를 사용했다. AI 에이전트한테 "Supertonic 3 나왔대, 비교해봐"부터 시작해서 모델 다운로드, 코드 수정, 서비스 재시작까지 전반적인 도움을 받았다.

Supertone? 한국의 AI 음성 스타트업. 음성 합성 기술로 유명하며,
Supertonic은 그들의 오픈웨이트 온디바이스 TTS 프로젝트다.

v2 → v3, 뭐가 달라졌나?

항목	Supertonic 2	Supertonic 3
출시일	2026.01.06	2026.04.29
지원 언어	5개 (en, ko, ja 등)	31개로 대폭 확장
읽기 정확도	기본 양호	반복/건너뛰기(skip/repeat) 실패 대폭 감소
화자 유사도	기준	동일 언어군에서 향상
모델 크기	~252MB	~381MB (vector_estimator가 127M→245M)
샘플레이트	24000 Hz (추정)	44100 Hz
ONNX 호환성	v2 전용	v2 인터페이스 호환 유지
표현 태그	-	`<laugh>`, `<breath>`, `<sigh>` 지원

가장 체감되는 변화

언어가 5개에서 31개로 — 한국어/영어/일본어만 되던 게 갑자기 독일어, 프랑스어, 스페인어, 러시아어, 베트남어, 힌디어, 아랍어 등등 유럽어 + 아시아어까지 커버
읽기 안정성 — v2에서 가끔 단어를 건너뛰거나 반복해서 읽던 문제가 거의 사라짐
샘플레이트 44100 Hz — CD 음질로 업그레이드
v2와 호환되는 ONNX 인터페이스 — 기존 연동 코드를 거의 안 건드려도 됨

업그레이드 과정

1. 모델 다운로드

v3는 아직 pip install supertonic에서 기본 모델로 제공되지 않는다. (AVAILABLE_MODELS에 supertonic-3가 아직 없음) 그래서 Hugging Face에서 직접 받았다.

# git-lfs 설치
sudo apt install git-lfs
git lfs install

# v3 모델을 ~/.cache/supertonic3에 클론
cd ~/.cache && git clone https://huggingface.co/Supertone/supertonic-3 supertonic3

v2는 252MB였는데 v3는 381MB로 약 1.5배 커졌다. 특히 vector_estimator.onnx가 127MB → 245MB로 거의 두 배.

2. 프록시 코드 수정

이전에 supertonic 2 tts 를 디바이스에 설치하고 헤르메스에 tts 엔진으로 구축했는데 이번에 3로 판올림을 진행했다.

# Before: auto_download로 v2 모델 사용
def get_tts():
    return TTS(auto_download=True)

# After: v3 모델 디렉토리를 직접 지정
V3_MODEL_DIR = os.path.expanduser("~/.cache/supertonic3")

def get_tts():
    return TTS(auto_download=False, model_dir=V3_MODEL_DIR, model="supertonic-2")

포인트는 auto_download=False로 하고 model_dir에 v3 경로를 직접 박는 것. model 파라미터는 어차피 하위호환성을 위해 supertonic-2로 남겨도 정상 동작한다. (내부적으로 multilingual 플래그만 확인)

3. 엔드포인트 및 기본값 업데이트

/v1/models → supertonic-2에서 supertonic-3로
total_steps 기본값 3 → 6 (음질 향상, 속도와 트레이드오프)

4. Hermes Config 업데이트

tts:
  provider: openai
  openai:
    model: supertonic-3    # ← 이거 한 줄
    voice: F1
    speed: 1.3
    base_url: http://127.0.0.1:8789/v1

5. 서비스 재시작

systemctl --user restart supertonic-openai-tts-proxy

테스트

# 한국어 테스트
curl -X POST http://127.0.0.1:8789/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model":"supertonic-3","input":"안녕하세요, Supertonic 3 테스트입니다.","voice":"F1","lang":"ko"}' \
  -o test.wav

# 영어 테스트
curl -X POST http://127.0.0.1:8789/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model":"supertonic-3","input":"Hello, this is Supertonic 3.","voice":"M1","lang":"en","response_format":"mp3"}' \
  -o test.mp3

둘 다 깔끔하게 200 OK. 44100 Hz WAV, 128kbps MP3 모두 정상.

알게 된 점 / 팁

pip 패키지가 아직 v3를 공식 지원하지 않는다 — AVAILABLE_MODELS가 ['supertonic', 'supertonic-2'] 뿐. model_dir로 우회해야 함. pip 패키지 업데이트를 기다리거나 직접 PR을 넣을 수도 있을 듯.
v2 ONNX 인터페이스와 완전 호환 — text_encoder.onnx, duration_predictor.onnx, vector_estimator.onnx, vocoder.onnx 구조가 v2와 동일해서 Drop-in replacement 가능.
모델 크기 증가 — 252MB → 381MB (약 50% 증가). 하지만 그래도 0.7B~2B급 대형 TTS 모델들에 비하면 엄청 가벼운 편. 라즈베리파이에서도 돌아간다는 게 증명됨.
total_steps로 품질/속도 조절 — 기본값 3에서 6 정도면 음질 눈에 띄게 좋아지고, 속도도 실사용에 무리 없는 수준.
Hermes TTS와의 연동 — OpenAI 호환 API 덕분에 base_url만 프록시 주소로 바꾸면 끝. 프록시가 중간에서 Supertonic을 OpenAI 규격으로 감싸주는 구조.

결론

Supertonic 3는 단순한 마이너 업데이트가 아니라 언어 지원 대폭 확장과 읽기 안정성 개선이 확실히 체감되는 메이저 업데이트다. v2에서 v3로의 마이그레이션은 ONNX 인터페이스 호환성 덕분에 아주 순조로웠고, 거의 Drop-in 수준이었다.

온디바이스 TTS의 퀄리티가 이 정도면, 클라우드 TTS를 대체할 만한 실용적인 선택지가 된 것 같다. 특히 Supertonic은 무료 + 프라이버시 완전 보장 + 오프라인이라는 세 가지를 다 잡은 게 가장 큰 강점.

참고: 프록시 코드 : https://github.com/sanguneo/supertonic-openai-tts-proxy
*Supertone 공식: https://github.com/supertone-inc/supertonic
Hugging Face 모델: https://huggingface.co/Supertone/supertonic-3

Smart Drop Point 개발기 - 하차 지점을 추천하는 모바일 웹앱 만들기

상구너 — Fri, 15 May 2026 16:40:16 +0900

Smart Drop Point는 같이 차를 탔을 때 “어디서 내리면 좋을지”를 추천하는 모바일 웹앱입니다.

처음에는 아이디어가 꽤 단순했습니다.

운전자는 자기 목적지로 가야 하고, 승객은 다른 곳으로 가야 할 때.
둘 사이에서 적당한 하차 지점을 찾아주면 되지 않을까?

그런데 막상 만들기 시작하니 단순한 길찾기 앱과는 조금 다른 문제였습니다.

이번 글은 Smart Drop Point를 만들면서 어떤 기준으로 구조를 잡았는지 정리한 개발기입니다.

사용한 기술 스택

기본 구조는 Next.js App Router 기반으로 잡았습니다.

전체적으로는 모바일 웹/PWA를 먼저 생각했고, 추천 계산과 UI 상태가 섞이지 않도록 도메인 로직을 분리하는 방향으로 구성했습니다.

Next.js App Router
React
TypeScript strict mode
Tailwind CSS
Zustand persist
TanStack Query
Yup
Kakao Map / Kakao Local
Tmap / ODsay 연동을 고려한 어댑터 구조
Vitest 기반 테스트 구조

프론트엔드 앱처럼 보이지만, 내부적으로는 입력 검증, 좌표 정규화, 후보 필터링, 추천 점수화, 외부 API fallback 같은 서버/도메인 로직이 꽤 들어갑니다.

그래서 화면 컴포넌트 안에 계산 로직을 넣지 않고, features, adapters, types, constants 영역으로 나눠서 관리했습니다.

대략 이런 식입니다.

src/
├── adapters/          지도, 경로, 대중교통, 장소 검색 어댑터
├── app/               Next.js App Router 페이지와 API 라우트
├── components/        홈/결과 화면 UI 컴포넌트
├── constants/         앱 상수와 역 데이터
├── features/          추천 계산, 입력 흐름, URL 직렬화 같은 도메인 로직
├── stores/            사용자 설정과 최근 검색 상태
└── types/             도메인 타입

이렇게 나눠두면 UI를 바꾸는 작업과 추천 품질을 바꾸는 작업이 서로 덜 엉킵니다.

문제를 좁게 잡기

처음부터 모든 카풀 문제를 풀 생각은 없었습니다.

낯선 사람을 매칭하거나, 결제를 붙이거나, 실시간 위치를 추적하는 쪽으로 가면 제품의 범위가 너무 커집니다.

제가 잡은 문제는 훨씬 좁았습니다.

이미 같은 차를 탄 상태
출발지는 같음
운전자 목적지와 승객 목적지가 다름
중간에 어디서 내리면 좋을지 정해야 함

이 네 가지 조건에만 집중했습니다.

이렇게 좁히고 나니 앱의 목적도 분명해졌습니다.

“새로운 이동을 만들어주는 앱”이 아니라,
“이미 같이 이동 중인 사람들이 어디서 자연스럽게 갈라질지 정하게 도와주는 앱”입니다.

기존 지도 앱과 다른 계산

일반 지도 앱은 보통 A에서 B까지의 최적 경로를 계산합니다.

하지만 이 앱은 조금 다릅니다.

A에서 출발해서 운전자는 B로 가고, 승객은 C로 가야 합니다.
여기서 궁금한 건 A → B 또는 A → C가 아니라, A → ? → B에서 ?가 어디면 좋을지입니다.

이 후보 지점은 운전자만 기준으로 봐도 안 되고, 승객만 기준으로 봐도 안 됩니다.

운전자 입장에서는 우회 시간이 짧아야 하고,
승객 입장에서는 하차 후 대중교통이나 도보 이동이 괜찮아야 합니다.

그래서 추천 엔진은 크게 이런 흐름으로 잡았습니다.

운전자 출발지, 운전자 목적지, 승객 목적지의 좌표를 확정한다
후보가 될 수 있는 전철역이나 환승 거점을 추린다
운전자가 해당 지점을 경유했을 때 얼마나 우회하는지 본다
승객이 그 지점에서 목적지까지 얼마나 걸리는지 본다
우회 시간, 도보 시간, 환승 횟수, 총 이동 시간을 기준으로 점수를 낸다
상위 후보를 카드로 보여준다

말로 쓰면 간단하지만, 실제로는 “후보를 얼마나 많이 계산할 것인가”가 중요했습니다.
전국 역을 모두 대상으로 매번 외부 API를 호출하면 비용도 크고 느려집니다.

그래서 먼저 공간적으로 후보를 줄이고, 그다음 필요한 후보에만 경로 계산을 붙이는 방향으로 설계했습니다.

좌표를 먼저 믿기

이 프로젝트에서 계속 중요하게 본 건 좌표입니다.

장소 이름만 가지고 계산하면 애매한 경우가 많습니다.
동명이인처럼 같은 이름의 장소가 여러 개 있을 수도 있고, 역명이나 동 이름만으로는 실제 위치가 흔들릴 수도 있습니다.

그래서 입력 단계에서 가능한 한 좌표를 확정하고, 이후 추천 계산은 좌표를 기준으로 흐르게 했습니다.

장소 자동완성도 이 목적에 맞춰 붙였습니다.
사용자가 동 이름이나 역 이름을 입력하면 실제 좌표를 얻고, 그 좌표를 URL에도 실어 결과 페이지가 같은 입력을 재현할 수 있게 했습니다.

공유 링크를 열었을 때도 다시 검색 결과가 달라지면 안 되기 때문입니다.

URL을 상태 저장소처럼 쓰기

결과 페이지는 URL 쿼리만으로도 다시 열릴 수 있게 만들었습니다.

처음에는 상태를 전역 store에만 넣어도 될 것 같았는데, 이 앱은 공유가 중요했습니다.
상대에게 링크를 보냈을 때 같은 결과가 열려야 하고, 새로고침해도 같은 후보가 유지되어야 합니다.

그래서 입력값은 이런 형태로 URL에 직렬화했습니다.

driverOrigin
driverOriginLat
driverOriginLng
driverDestination
driverDestinationLat
driverDestinationLng
passengerDestination
passengerDestinationLat
passengerDestinationLng
maxDetourMinutes
maxWalkMinutes
priority
picked

장소명뿐 아니라 위도/경도를 같이 싣는 이유는 재현성 때문입니다.
장소명을 다시 검색하면 같은 이름의 다른 장소가 나올 수도 있고, 자동완성 결과가 시간이 지나며 바뀔 수도 있습니다.

반대로 좌표가 URL에 있으면 결과 페이지는 다시 장소 검색을 하지 않아도 같은 추천 계산을 시작할 수 있습니다.

폼 입력과 URL 경계에서는 Yup 스키마로 값을 검증하고, 내부 도메인에서는 TypeScript 타입을 기준으로 다루도록 나눴습니다.
폼 검증 스키마가 도메인 타입을 대체하지 않게 한 점도 의도한 부분입니다.

어댑터로 외부 의존성 분리

지도나 경로 계산, 대중교통 정보는 외부 API에 의존합니다.

현재 구조에서는 각각을 바로 코드에 박아 넣지 않고 어댑터 뒤에 두었습니다.

운전 경로
대중교통 경로
지도 SDK
장소 검색

이 네 영역을 분리해두면, 처음에는 mock으로 시작하고 나중에 Tmap, ODsay, Kakao 같은 실제 API로 바꾸기 쉽습니다.

이 방식이 마음에 들었던 이유는 개발 단계에서도 앱의 흐름을 먼저 만들 수 있다는 점이었습니다.
외부 키가 없거나 API가 잠깐 실패해도, 최소한 핵심 화면은 확인할 수 있어야 했습니다.

그래서 fallback 구조도 같이 넣었습니다.
키가 없으면 mock으로 돌아가고, 지도나 자동완성처럼 실제 키가 필요한 기능은 가능한 범위에서만 켜지게 했습니다.

실제 API와 mock을 같은 인터페이스로 맞추기

외부 API는 붙이는 것보다 바꾸기 쉽게 만드는 쪽이 더 중요하다고 봤습니다.

운전 경로는 Tmap, 대중교통은 ODsay, 지도는 Kakao Map, 장소 검색은 Kakao Local을 염두에 두었지만, 코드 곳곳에서 직접 호출하지는 않았습니다.

대신 각각을 이런 식의 역할로 분리했습니다.

IRoutingAdapter: 운전 경로와 우회 시간 계산
ITransitAdapter: 하차 후 대중교통/도보 이동 계산
IMapAdapter: 지도 렌더링과 마커/폴리라인 갱신
IPlaceSearchAdapter: 장소 자동완성과 좌표 확정

실제 구현체와 mock 구현체는 같은 인터페이스를 따릅니다.

덕분에 개발 중에는 API 키 없이도 화면과 추천 흐름을 계속 볼 수 있고, 실제 키가 들어오면 같은 도메인 로직을 유지한 채 어댑터만 바꿔서 정밀도를 올릴 수 있습니다.

또 하나 좋았던 점은 장애 대응입니다.

외부 API가 실패해도 앱 전체가 멈추는 대신, 가능한 범위에서 fallback 결과를 보여줄 수 있습니다.
지도나 자동완성은 비활성화될 수 있어도, 핵심 추천 화면은 mock 데이터로 확인할 수 있게 했습니다.

작은 사이드 프로젝트라도 이런 분리선을 미리 잡아두면, 나중에 실제 서비스를 붙일 때 훨씬 덜 흔들립니다.

모바일이 먼저인 UI

이 앱은 PC에서 오래 보는 서비스가 아닙니다.
대부분 차 안에서 잠깐 열어볼 가능성이 높습니다.

그래서 처음부터 모바일 웹을 기준으로 잡았습니다.

홈 화면에서는 운전자 출발지, 운전자 도착지, 승객 목적지를 하나의 여정 클러스터처럼 묶었습니다.
각 입력이 따로 흩어져 있으면 관계가 잘 안 보이기 때문입니다.

결과 화면에서는 1순위 후보를 크게 보여주고, 나머지 후보는 압축해서 비교할 수 있게 했습니다.
후보가 너무 많으면 오히려 결정이 늦어지니, 빠르게 고를 수 있는 카드 구성이 더 맞다고 봤습니다.

시간 비교도 숫자만 보여주기보다 가로 막대로 같이 표현했습니다.
차 안에서 작은 글씨를 오래 읽기보다, 대략 어느 후보가 더 유리한지 바로 보이게 하고 싶었습니다.

결과 UI는 “설명”보다 “비교”에 가깝게

결과 화면을 만들 때 가장 신경 쓴 건 후보 간 비교였습니다.

사용자는 이 앱을 오래 읽으려고 여는 게 아닙니다.
지금 차 안에서 빨리 정해야 하니까 여는 겁니다.

그래서 결과 카드에는 많은 설명을 넣기보다, 의사결정에 필요한 숫자를 최대한 같은 위치에 반복해서 배치했습니다.

운전자 추가 시간
승객 총 이동 시간
도보 시간
환승 횟수
추천 사유
여정 타임라인

시간 스택바도 이 맥락에서 넣었습니다.

승객 이동 시간을 대기, 대중교통, 도보처럼 나눠서 보여주면 “총 30분”이라는 숫자만 볼 때보다 더 판단하기 쉽습니다.
예를 들어 같은 30분이라도 도보가 긴 30분과 지하철 한 번 타는 30분은 체감이 다릅니다.

1순위 후보는 크게 보여주고, 2·3순위는 압축 카드로 두었습니다.
그리고 다른 후보가 더 마음에 들면 바로 promote해서 지도와 카드 상태가 같이 바뀌도록 했습니다.

이 부분은 단순 UI라기보다, 추천 결과를 사용자가 납득하는 과정이라고 생각했습니다.

결과 페이지는 공유 가능해야 한다

이 앱은 혼자만 보는 도구가 아닐 가능성이 큽니다.
운전자에게 보여주거나, 같이 탄 사람에게 링크를 보내야 할 수도 있습니다.

그래서 결과 상태가 URL에 담기도록 했습니다.
선택한 후보도 picked 값으로 직렬화해서, 링크를 다시 열었을 때 같은 후보를 볼 수 있게 했습니다.

나중에는 카카오톡이나 SNS에 공유했을 때 선택한 후보의 이름과 시간이 들어간 미리보기 이미지도 만들 수 있도록 구조를 잡았습니다.

결국 이 앱의 결과는 “내가 보는 화면”이면서 동시에 “상대에게 보여줄 근거”이기도 합니다.

성능과 호출 수 줄이기

추천 계산은 여러 외부 정보를 섞기 때문에 호출 수가 쉽게 늘어날 수 있습니다.

특히 개발 환경에서는 React StrictMode나 새로고침 때문에 같은 요청이 반복될 수 있습니다.
이 부분은 runRecommendation 쪽에 캐시를 두는 방식으로 줄였습니다.

같은 입력에 대해서는 일정 시간 동안 결과를 재사용하고,
이미 진행 중인 요청이 있으면 같은 Promise를 공유하도록 했습니다.

작은 앱이라도 이런 부분을 초기에 잡아두면, 나중에 실제 API를 붙였을 때 비용과 속도 면에서 훨씬 안정적입니다.

후보를 줄이는 방식

전국 전철역과 환승 거점을 모두 후보로 두면 보기에는 좋아 보이지만, 실제 계산에서는 부담이 큽니다.

그래서 처음부터 전체 후보에 대해 외부 API를 호출하지 않고, 먼저 가벼운 공간 계산으로 후보를 줄였습니다.

기본 아이디어는 이렇습니다.

운전자 출발지와 도착지 주변 영역을 잡는다
승객 목적지와 너무 동떨어진 후보를 제외한다
운전자 출발지와 너무 가까운 지점은 제외한다
남은 후보를 직선거리와 대략적인 위치 관계로 정렬한다
그중 상위 후보에 대해서만 routing/transit 계산을 수행한다

이때 haversine 거리 계산과 bounding box를 사용했습니다.
정밀 경로 계산은 비싸지만, 후보를 줄이는 단계에서는 직선거리 기반 계산만으로도 충분히 의미가 있습니다.

이렇게 prefilter를 먼저 거치면 실제 API 호출 수를 줄일 수 있고, 결과 응답도 빨라집니다.
사용자 입장에서는 그냥 빠르게 결과가 뜨는 것처럼 보이지만, 내부적으로는 “비싼 계산을 하기 전에 싼 계산으로 줄이는” 흐름입니다.

이런 구조는 나중에 후보 데이터가 1천 개, 1만 개로 늘어나도 그대로 확장할 수 있습니다.

개인정보는 최소로

이 앱은 위치를 다루기 때문에 개인정보에 대한 기준도 단순하게 잡았습니다.

초기에는 서버에 입력한 출발지나 목적지를 저장하지 않습니다.
최근 검색이나 즐겨찾기는 사용자 브라우저의 localStorage에만 둡니다.

서버 키가 필요한 API는 Next API 라우트 뒤로 숨기고, 브라우저에는 공개 가능한 키만 노출되도록 했습니다.

회원가입 없이 쓰는 도구이기 때문에, 데이터 저장을 최소화하는 쪽이 제품 성격에도 맞았습니다.

지금 상태와 다음 단계

현재는 모바일 웹앱 형태로 흐름을 볼 수 있는 상태입니다.

입력 화면, 추천 결과 카드, 지도 미리보기, 후보 비교, 공유를 고려한 URL 구조까지 잡아두었습니다.
전국 전철·도시철도역 데이터를 기반으로 후보를 만들고, 외부 API가 있으면 실제 경로 계산을 쓰고, 없으면 mock fallback으로 화면을 확인할 수 있게 했습니다.

다음에 더 다듬고 싶은 부분은 이런 것들입니다.

시간대별 가중치 자동 조정
막차나 심야 안전성을 반영한 추천
결과 공유용 이미지 카드
여러 명의 승객을 동시에 고려하는 모드
추천이 좋았는지 피드백을 받는 UX

처음부터 다 넣기보다는, 지금은 “한 명의 운전자와 한 명의 승객”이라는 기본 문제를 제대로 푸는 데 집중하고 있습니다.

정리

Smart Drop Point는 거대한 이동 플랫폼을 만들려는 프로젝트는 아닙니다.

오히려 아주 작고 구체적인 순간을 보고 있습니다.

같이 차를 탔는데 서로 목적지가 다를 때,
어디서 내리면 운전자도 덜 부담스럽고 승객도 편할까?

이 질문에 좌표, 경로, 대중교통 정보를 얹어서 빠르게 답해보는 앱입니다.

만들면서 느낀 건, 작은 문제라도 실제 생활의 맥락이 들어가면 설계할 게 꽤 많다는 점이었습니다.
입력은 짧아야 하고, 결과는 바로 비교돼야 하고, 숫자는 신뢰할 수 있어야 하고, 모바일에서 흔들리는 손으로도 쓸 수 있어야 했습니다.

아직 더 다듬을 부분은 많지만, 문제를 좁게 잡고 구조를 나눠두니 다음 단계로 확장하기는 좋아졌습니다.

이제는 실제 사용 사례를 더 넣어보면서 추천 품질을 조금씩 올려봐야겠습니다.

같이 탄 차에서 어디서 내릴지 정해주는 앱

상구너 — Fri, 15 May 2026 16:26:34 +0900

같이 차를 타고 가다 보면 은근 애매한 순간이 있습니다.
출발지는 같은데, 도착지는 서로 다를 때요.
친구 차를 얻어 탔거나, 회식 끝나고 동료 차를 탔거나, 여행지에서 일행이랑 택시를 같이 탔는데 숙소가 다른 경우가 그렇습니다.
이럴 때 보통은 이렇게 됩니다.

“그럼 어디서 내리지?”

운전자는 너무 돌아가면 부담스럽고, 승객은 아무 데서나 내리면 집까지 가는 길이 복잡해집니다. 그런데 이걸 차 안에서 지도 앱 여러 개 열어가며 비교하기는 꽤 번거롭습니다.

Smart Drop Point는 이 작은 결정을 줄이기 위해 만든 모바일 웹앱입니다.

어디서 내리면 좋을까?

Smart Drop Point가 풀려는 문제는 단순합니다.
운전자와 승객이 같은 차에 탔지만, 최종 목적지가 다를 때.
운전자는 덜 돌아가고, 승객은 하차 후 이동이 편한 지점을 찾아주는 것입니다.

예를 들면 이런 상황입니다.

강남에서 같이 출발함
운전자는 송파 쪽으로 감
승객은 강변역 쪽으로 가야 함

이때 그냥 감으로 정하면 “잠실역 어때?” 정도에서 끝나기 쉽습니다.
물론 그게 맞을 수도 있지만, 정말 운전자가 많이 안 돌아가는지, 승객 입장에서 대중교통이 편한지, 다른 후보는 없는지 바로 알기는 어렵습니다.

Smart Drop Point는 이런 후보를 계산해서 보여줍니다.

입력은 세 가지만

사용법은 복잡하지 않게 잡았습니다.
기본적으로 세 가지 위치만 넣으면 됩니다.

운전자가 출발하는 곳
운전자가 도착하는 곳
승객이 최종적으로 가야 하는 곳

여기에 우회 허용 시간이나 도보 허용 시간, 우선순위 정도만 고르면 됩니다.
예를 들면 “운전자는 너무 돌아가지 않게”, “승객 환승을 줄이게”, “둘 다 적당히 균형 있게” 같은 방향입니다.
차 안에서 잠깐 쓰는 도구라서 입력이 길어지면 안 된다고 봤습니다.
회원가입을 하거나, 여러 단계를 거치거나, 설정을 많이 만지는 앱이면 이 상황에서는 잘 안 쓰게 될 것 같았습니다.

그래서 모바일에서 한 손으로 빠르게 입력하고 바로 결과를 볼 수 있는 흐름을 우선했습니다.

결과는 후보 카드로 비교

결과 화면에서는 추천 후보를 카드로 보여줍니다.

각 후보에는 이런 정보가 들어갑니다.

운전자가 얼마나 더 돌아가는지
승객이 내린 뒤 목적지까지 얼마나 걸리는지
도보와 대중교통 시간이 어느 정도인지
환승이 얼마나 필요한지
왜 이 지점이 괜찮은지

숫자를 길게 나열하기보다, 후보끼리 바로 비교할 수 있게 보여주는 게 중요했습니다.
특히 이 앱은 “가장 정확한 경로 탐색 앱”이라기보다 “차 안에서 빨리 결정하게 도와주는 앱”에 가깝습니다.
그래서 1순위 후보를 크게 보여주고, 나머지 후보는 비교할 수 있게 압축해서 보여주는 방향으로 구성했습니다.

기존 지도 앱과 다른 점

카카오맵이나 네이버지도는 이미 훌륭합니다.
A에서 B까지 가는 길을 찾는 용도라면 그걸 쓰면 됩니다.

하지만 Smart Drop Point가 보는 문제는 조금 다릅니다.

일반 지도 앱은 보통 한 사람의 이동을 기준으로 합니다.

내가 어디서 출발해서
어디까지 갈지
어떤 경로가 빠른지

Smart Drop Point는 두 사람의 이동을 동시에 봅니다.

운전자는 자기 목적지로 가야 하고
승객은 중간 어딘가에서 내려야 하고
그 지점이 둘 모두에게 납득 가능해야 합니다

즉, “A에서 B로 가는 길”이 아니라 “A에서 출발한 두 사람이 어디서 자연스럽게 갈라질지”를 찾는 문제입니다.

이 차이가 생각보다 큽니다.

감 대신 숫자로 말하기

이 앱에서 중요하게 생각한 건 객관적인 근거입니다.

같이 탄 차에서 하차 지점을 정하는 일은 단순한 길찾기만은 아닙니다.
관계의 문제가 조금 섞여 있습니다.

너무 멀리 데려다 달라고 하긴 미안하고,
아무 데서나 내리자니 내 이동이 너무 불편하고,
그렇다고 차 안에서 오래 고민하기도 애매합니다.

이럴 때 “여기가 제일 좋아요”라고만 말하면 설득력이 약합니다.

대신 이렇게 보여주는 편이 낫습니다.

운전자는 3분만 더 돌아가면 됨
승객은 하차 후 14분이면 도착함
환승이 적고 도보가 짧음

이렇게 숫자로 보이면 대화가 조금 쉬워집니다.

“여기서 내려도 될까요?”라는 말에 근거가 생기는 느낌입니다.

모바일 웹앱으로 만든 이유

Smart Drop Point는 모바일 웹앱으로 만들었습니다.

이 앱을 쓰는 순간은 대부분 이동 중일 거라고 봤습니다.
차 안에서, 약속이 끝난 직후에, 누군가 “같이 타고 가자”라고 말한 뒤에 잠깐 열어보는 식입니다.
그래서 설치가 필요하면 안 되고, 데스크톱보다 모바일이 먼저여야 했습니다.
브라우저에서 바로 열고, 필요하면 홈 화면에 추가해서 앱처럼 쓸 수 있는 정도가 적당하다고 봤습니다.

이런 상황에 잘 맞습니다

Smart Drop Point는 모든 이동 문제를 해결하려는 앱은 아닙니다.
오히려 아주 좁은 상황 하나를 보고 있습니다.

퇴근길에 동료 차를 같이 탔을 때
회식 후 누군가 차로 데려다 준다고 했을 때
여행지에서 같은 택시를 탔지만 숙소가 다를 때
가족이나 지인이 태워줬는데 목적지가 완전히 같지는 않을 때

이런 순간에 “어디서 내리는 게 제일 괜찮지?”를 빠르게 정하는 도구입니다.

낯선 사람과 카풀을 매칭하거나, 실시간 차량을 추적하거나, 결제를 붙이는 서비스는 아닙니다.
이미 같이 탄 사람들끼리 결정을 쉽게 하는 데 집중했습니다.

정리

Smart Drop Point는 길 위에서 자주 생기는 작은 결정을 줄이기 위한 앱입니다.

같이 차를 탔지만 도착지가 다를 때,
운전자에게는 덜 부담스럽고 승객에게는 이동이 편한 하차 지점을 찾아줍니다.

기능 자체는 작아 보이지만, 실제 상황에서는 꽤 자주 마주치는 문제라고 생각했습니다.

어디서 내릴지 감으로 정하지 않고,
운전자 우회 시간과 승객 이동 시간을 같이 보면서 결정할 수 있으면 대화가 조금 더 편해질 수 있습니다.

아직 계속 다듬는 중이지만, “같이 탔는데 어디서 내릴까?”라는 질문 하나만큼은 빠르게 줄여주는 도구로 만들어보려고 합니다.

서비스는 여기

아래 주소로 접속하시면 사용할 수 있습니다.
아직은 초기라서 에러가 있을수도 있습니다.

https://sdp.sanguneo.com/

사내 그룹웨어 Daou GW 자동화: 브라우저 대신 CLI와 MCP로 연결하기

상구너 — Mon, 11 May 2026 17:31:25 +0900

요즘 Hermes Agent를 쓰면서 반복되는 작업을 하나씩 스킬로 정리하고 있습니다.

그중에서 꽤 실사용에 가까웠던 게 Daou GW 작업이었어요. 메일 확인, 캘린더 조회, 전자결재 상태 확인 같은 그룹웨어 작업을 매번 브라우저로 열고 클릭하는 게 은근 귀찮아서, 아예 CLI와 MCP로 처리할 수 있게 정리해봤습니다.

이번 글은 그 작업을 만들면서 어떤 식으로 접근했는지 기록해보려고 합니다.

처음 목표는 간단했습니다

“메일 최신 5개 보여줘”라고 말하면 최근 메일을 확인하고,
“오늘 일정 보여줘”라고 말하면 캘린더 일정을 바로 가져오는 것.

브라우저를 자동화해서 화면을 클릭하는 방식도 생각할 수 있지만, 저는 가능하면 HTTP/API 중심으로 가고 싶었습니다. 브라우저 자동화는 눈에 보이는 화면을 따라가기 때문에 편할 때도 있지만, 사내 시스템처럼 자주 쓰는 작업에는 조금 무겁게 느껴졌습니다.

그래서 방향을 이렇게 잡았습니다.

브라우저 자동화는 분석이나 임시 확인용으로만 사용
실제 반복 작업은 CLI/API로 처리
Hermes에서는 스킬을 통해 “어떤 명령을 우선 써야 하는지” 기억하게 만들기

Go 코드에서 TypeScript CLI로

처음에는 로컬에 있던 Go 코드로 Daou GW 로그인과 일부 HTTP API 처리를 해보려고 했습니다. 왜냐면 Go는 따로 npm 같은 패키지 설치 없이 사용할수있도록 쉽게 패키징 할수 있었거든요,

이걸 그대로 확장할 수도 있었지만, npm 배포와 MCP 연동까지 생각하면 TypeScript 쪽이 더 다루기 편했습니다. 그래서 별도 저장소로 daou-gw-cli를 만들고, CLI와 MCP를 같이 제공하는 구조로 정리했습니다. 무엇보다, 오픈소스로 확장하기엔 ts만한게 없었지요.

현재 저장소는 GitHub에 올려두었습니다.

https://github.com/sanguneo/daou-gw-mcp

구조는 대략 이렇습니다.

{
  "bin": {
    "daou-gw-cli": "dist/index.js",
    "daou-gw-mcp": "dist/mcp.js"
  },
  "scripts": {
    "build": "tsup && node scripts/postbuild.mjs",
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  }
}

CLI로는 직접 명령을 실행할 수 있고,
MCP로는 Hermes 같은 에이전트가 도구처럼 호출할 수 있게 만들었습니다.

개발은 브라우저에서 시작했습니다

먼저 Hermes Agent에서 CDP로 브라우저에 연결했습니다. 이미 로그인된 브라우저 세션을 그대로 활용할 수 있어서, 로그인 흐름을 매번 다시 만들 필요가 없었습니다.

그다음에는 브라우저에서 실제로 필요한 행동을 해봤습니다.

예를 들면 메일 목록을 열어보고, 검색을 해보고, 캘린더 화면을 이동해보고, 결재 상태를 확인하는 식입니다. 사용자가 실제로 누르는 흐름을 먼저 브라우저에서 재현했습니다.

그 다음은 브라우저에서 행동을 하는 동안 Network 요청을 캡처했습니다. 어떤 버튼을 눌렀을 때 어떤 API가 호출되는지, method가 GET인지 POST인지, query string과 request body가 어떻게 생겼는지 확인했습니다.

그렇게 확인한 요청을 하나씩 HTTP 메소드로 옮겼습니다.

대략 이런 흐름이었습니다.

브라우저에서 실제 동작 수행
→ Network 요청 확인
→ 필요한 URL / method / payload 정리
→ TypeScript HTTP client로 재현
→ CLI 명령으로 감싸기
→ MCP tool로 노출하기

브라우저는 “어떤 API를 써야 하는지 알아내는 도구”로만 쓰고, 실제 반복 작업은 HTTP 요청으로 처리했습니다. 그래서 나중에 실행할 때는 브라우저를 띄우지 않아도 되고, 에이전트 입장에서도 훨씬 가볍게 호출할 수 있었습니다.

스킬에는 “어떻게 행동해야 하는지”를 적었다

이번에 중요했던 건 단순히 CLI를 만드는 것보다, 에이전트가 헷갈리지 않게 행동 규칙을 정리하는 일이었습니다.

예를 들어 사용자가 “메일 최신 5개 보여줘”라고 했을 때 에이전트가 먼저 저장소를 뒤지거나, 브라우저를 열거나, UI 상태를 추측하기 시작하면 답답합니다.

그래서 Daou GW 스킬에는 이런 원칙을 넣었습니다.

메일 목록은 mail list
메일 검색은 mail search
메일 삭제는 mail delete
캘린더는 calendar list
결재는 전자결재 상태 조회 명령 사용
실패했을 때만 세션이나 설정을 확인하고 1회 재시도
비밀번호, 쿠키, 세션 토큰은 절대 출력하지 않기

이게 별것 아닌 것 같지만, 실제로 에이전트를 쓰다 보면 이런 규칙이 꽤 중요합니다.

사람은 “메일 보여줘”라고 했을 때 바로 결과를 기대하는데, 에이전트는 가끔 너무 착실하게 주변 정보를 먼저 확인하려고 하거든요. 그래서 스킬에 “불필요한 탐색을 하지 말라”고 명시했습니다.

CLI와 MCP는 같은 의미를 갖게 했다

CLI 명령과 MCP 도구 이름도 최대한 같은 의미로 맞췄습니다.

CLI에서는 이런 식입니다.

daou-gw-cli mail list --size 5
daou-gw-cli mail search --query AWS --size 20
daou-gw-cli calendar list
daou-gw-cli approval status

MCP에서는 이런 도구로 대응됩니다.

mail_list
mail_search
mail_delete
calendar_list
approval_status

이렇게 맞춰두면 사람이 터미널에서 쓰는 방식과 에이전트가 MCP로 호출하는 방식이 크게 다르지 않습니다.

나중에 문제가 생겼을 때도 “CLI로 재현해보고 MCP 쪽을 확인하는” 흐름이 자연스럽습니다.

실제로 신경 쓴 부분: 세션과 실패 처리

Daou GW 같은 사내 시스템은 로그인 세션이 중요합니다.

매번 로그인 정보를 다시 입력하는 방식은 불편하고, 그렇다고 인증 정보를 대화에 노출하는 방식은 위험합니다. 그래서 로컬에 세션을 저장하고, 명령 실행 시 세션을 먼저 재사용하도록 정리했습니다.

세션이 유효하면 그대로 명령을 실행하고, 만료된 경우에는 가능한 범위에서 다시 로그인한 뒤 원래 명령을 한 번만 재시도하는 흐름입니다.

여기서 중요한 건 무한 재시도를 하지 않는 것입니다.

사내 시스템은 실패 원인이 다양합니다. 세션이 만료됐을 수도 있고, 네트워크가 막혔을 수도 있고, API 응답 구조가 바뀌었을 수도 있습니다. 그래서 실패하면 원인을 짧게 보고하고, 필요한 경우에만 상태를 확인하도록 했습니다.

세션과 민감 정보는 로컬에만

로컬 상태는 ~/.daou/ 아래에 두는 방식으로 정리했습니다.

~/.daou/config.json
~/.daou/session.json
~/.daou/vault.key

스킬에도 민감값을 출력하지 말라고 명시했습니다.

에이전트가 편해도, 비밀번호나 쿠키 같은 값이 대화에 그대로 나오는 건 피해야 합니다. 이 부분은 도구를 만들 때부터 계속 신경 써야 할 지점인 것 같습니다.

만들고 나니 좋은 점

이걸 만들고 나니 그룹웨어 작업을 훨씬 짧게 처리할 수 있게 됐습니다.

예전에는 브라우저를 열고, 로그인 상태를 보고, 메뉴를 찾아가고, 필요한 화면을 찾아야 했습니다.

지금은 그냥 이렇게 말하면 됩니다.

메일 최신 5개 보여줘
AWS 메일 찾아줘
오늘 캘린더 일정 보여줘
결재 상태 확인해줘

그리고 Hermes는 Daou GW 스킬을 보고 CLI/MCP를 우선 사용합니다.

이게 제가 원했던 형태였습니다. 에이전트가 모든 걸 똑똑하게 추론하는 것보다, 자주 쓰는 업무는 명확한 도구와 규칙으로 고정해두는 방식이 훨씬 안정적이었습니다.

정리

이번 Daou GW 스킬 개발은 단순히 브라우저 화면을 자동으로 누르는 것이 아니라, 사내 시스템을 에이전트가 안전하고 반복 가능하게 다루도록 만드는 작업에 가까웠습니다.

만들면서 느낀 점은 이렇습니다.

반복 업무는 브라우저 자동화보다 API/CLI가 편하다
MCP를 붙이면 에이전트가 도구처럼 호출할 수 있다
스킬에는 기능 설명보다 행동 규칙을 명확히 적는 게 중요하다
민감 정보는 절대 대화에 노출되지 않게 해야 한다
실패 케이스도 스킬에 기록해두면 다음에 덜 헤맨다

아직 더 다듬을 부분은 있지만, 메일이나 일정처럼 자주 확인하는 작업이 말 한마디로 처리되는 건 꽤 만족스럽습니다.

다음에는 메일 정리나 전자결재, 게시판 글 작성 쪽도 조금 더 안정적으로 정리 해봐야 겠습니다.

종합소득세 신고 방법: 직장인 개발자의 홈택스 신고가이드 (feat. 크몽)

상구너 — Fri, 8 May 2026 17:30:40 +0900

직장에 다니면서 크몽에서 개발 외주, 자동화 작업, 웹사이트 제작, 기술 상담 같은 부업을 했다면 매년 5월 종합소득세 신고 대상이 될 수 있습니다.

많은 직장인 개발자는 이렇게 생각합니다.

회사에서 이미 연말정산 했는데, 또 신고해야 하나?

결론부터 말하면, 크몽에서 부업 수익이 있었다면 별도로 종합소득세 신고를 해야 할 수 있습니다.
회사에서 진행한 연말정산은 근로소득에 대한 정산입니다. 즉, 회사에서 받은 월급에 대한 세금 정리입니다.

하지만 크몽에서 발생한 수익은 회사 급여와 별개의 소득입니다. 따라서 직장인이라도 크몽 부업 수익이 있다면 종합소득세 신고 때 직접 반영해야 합니다.

특히 크몽은 일반적인 프리랜서 지급 구조와 조금 다릅니다.
보통 프리랜서 용역은 3.3% 원천징수를 하고 지급됩니다. 이 경우 홈택스에서 사업소득 자료가 자동으로 잡히는 경우가 많습니다.
하지만 크몽은 3.3%를 원천징수해서 신고해주는 구조가 아니라, 플랫폼 수수료를 제외하고 판매자에게 정산해주는 방식입니다.
그래서 홈택스에 들어가도 크몽 수익이 자동으로 깔끔하게 불러와지지 않을 수 있습니다.
즉, 크몽에서 번 돈은 내가 직접 매출을 확인하고, 직접 입력해야 합니다.

이 글은 직장인 개발자가 크몽 부업 수익을 종합소득세 신고에 어떻게 반영하면 되는지 정리한 진입 가이드입니다.

세무 전문 글은 아닙니다.
실제 신고 전에는 본인의 상황에 맞게 홈택스 안내와 세무 전문가 의견을 함께 확인하는 것이 좋습니다.

1. 홈택스에서 종합소득세 신고로 들어갑니다

먼저 홈택스에 접속합니다.
상단 메뉴에서 종합소득세 신고 화면으로 이동합니다.

신고 화면에 들어가면 여러 신고 방식이 보입니다. 처음 신고하는 직장인 부업 개발자라면 우선 모두채움 정기신고를 눌러 시작하면 됩니다.
모두채움은 국세청이 이미 보유한 근로소득, 일부 사업소득, 공제 정보 등을 미리 채워주는 신고 방식입니다.
직장인의 경우 회사에서 연말정산한 근로소득 정보가 자동으로 들어와 있기 때문에, 처음부터 전부 입력하는 것보다 진입 장벽이 낮습니다.

다만 앞서 언급한대로 크몽 수익은 일반적인 3.3% 원천징수 사업소득으로 잡히지 않아서,
모두채움으로 시작하더라도, 부업 매출은 이후 단계에서 직접 추가로 입력해야 합니다.

정리하면 이렇습니다.

모두채움 정기신고는 시작점이고, 크몽 수익은 직접 확인해서 보완 입력해야 합니다.

2. 기본정보 입력에서 내 정보를 불러옵니다

모두채움 정기신고로 들어가면 먼저 기본정보 입력 화면이 나옵니다.
여기서 주민등록번호 입력란 오른쪽에 있는 확인 버튼을 누릅니다.
확인을 누르면 홈택스에 등록된 기본 인적사항이 자동으로 불러와집니다.

이 단계에서 확인할 내용은 다음과 같습니다.

이름
주민등록번호
주소
휴대전화번호
이메일
거주 구분
내·외국인 여부

대부분 자동으로 채워지지만, 연락처나 이메일이 예전 정보일 수 있으니 한 번 확인해두는 것이 좋습니다.
신고서의 기본 주체가 나인지 확인하고, 다음 단계로 넘어가기 위한 기본 확인 단계입니다.

3. 종합소득금액에서 사업소득을 추가합니다

기본정보 입력을 마치고 다음 단계로 넘어가면 종합소득금액을 작성하는 화면이 나옵니다.
직장인 부업자의 경우 회사에서 받은 근로소득은 대부분 자동으로 입력되어 있습니다.
회사에서 이미 연말정산을 했기 때문에, 홈택스에서 근로소득 자료를 불러와 보여주는 것입니다.

이제 누락된 크몽 수익을 직접 입력해야 합니다.
화면에서 사업소득 항목을 찾은 뒤, 소득명세 작성하기 버튼을 누릅니다.

여기서부터가 크몽 부업 수익을 신고서에 직접 반영하는 핵심 단계입니다.

4. 비어 있는 사업소득 명세를 새로 작성합니다

사업소득 - 소득명세 작성하기를 누르면 사업장명세, 소득금액명세 등 여러 항목이 나오는 화면으로 이동합니다.
처음 들어오면 대부분의 내용이 비어 있을 수 있습니다.

당황하지 않아도 됩니다.

이 화면이 비어 있는 것은 자연스러운 상황입니다.
우측에 있는 작성하기 버튼을 눌러서 크몽 부업 수익에 대한 사업소득 명세를 새로 입력합니다.

여기서부터는 내가 크몽에서 정산받은 금액과 업종 정보를 기준으로 직접 사업소득을 만들어 넣는 단계입니다.

5. 사업장명세에서 사업자등록번호 없음으로 입력합니다

작성하기를 누르면 먼저 사업장명세를 입력하는 화면이 나옵니다.
직장인 부업자로 크몽에서 개발 외주를 하는 경우, 별도의 사업자등록을 하지 않은 상태일 수 있습니다.

이 경우 사업자등록번호를 입력할 수 없으므로, 사업자등록번호 존재여부에서 없음을 선택합니다.
없음을 선택하면 사업자등록번호 입력란은 사라지고, 주로 업종코드를 입력하는 형태로 바뀝니다.

업종코드는 본인이 크몽에서 제공한 대표 업무와 가장 유사한 코드를 선택하면 됩니다.
아마 다음 코드를 사용하시게 될거에요.

업종코드	설명
940926	SW 프리랜서
940600	프로그래머
940909	기타 자영업

개발 외주, 자동화, 웹 개발, 프로그램 제작 등을 했다면 보통 940926 또는 940600 중 본인 업무에 가까운 쪽을 검토하면 됩니다.
그 외에 명확히 맞는 코드가 애매하다면 940909 기타 자영업으로 입력하는 경우도 있습니다.

업종코드를 입력한 뒤 검색 버튼을 누르면 업종명 등 나머지 칸이 자동으로 업데이트됩니다.

내용이 정상적으로 채워진 것을 확인했다면 저장하기를 눌러 사업장명세 입력을 완료합니다.

6. 사업장을 추가한 뒤 업종별 총 수입금액을 입력합니다

사업장명세를 저장하면 방금 입력한 사업장이 목록에 추가됩니다.
크몽에서 한 부업이 하나의 업종으로 정리된다면, 방금 추가한 사업장 하나만 두고 다음 단계로 넘어가면 됩니다.

만약 크몽에서 수행한 일이 여러 업종으로 나뉜다고 판단된다면, 같은 방식으로 업종을 추가할 수 있습니다.
예를 들어 개발 외주, 강의·컨설팅, 디자인 등 성격이 다른 수익이 섞여 있다면 각각에 맞는 업종코드를 추가하는 식입니다.

다만 대부분의 직장인 개발자 부업은 하나의 대표 업종으로 정리해도 크게 무리가 없는 경우가 많습니다.
핵심은 본인의 실제 업무 성격과 가장 가까운 업종코드를 선택하는 것입니다.

사업장 추가가 끝났다면 이제 업종별 총 수입금액을 입력합니다.
여기서 말하는 총 수입금액은 크몽에서 발생한 매출을 기준으로 정리해야 합니다.
크몽 정산 내역을 확인해서 해당 과세기간 동안 발생한 수입을 업종별로 합산해 입력하면 됩니다.

즉, 이 단계에서는 “내가 어떤 업종으로 얼마를 벌었는지”를 홈택스에 직접 적어 넣는다고 보면 됩니다.

6-1. 핵심: 크몽 세금계산서의 월합계를 모두 더합니다

이 단계가 크몽 부업 신고에서 가장 중요합니다.

크몽 수익은 홈택스에서 자동으로 사업소득으로 불러와지지 않을 수 있기 때문에, 직접 수입금액을 계산해서 입력해야 합니다.
이때 기준으로 삼을 수 있는 자료가 크몽에서 발행된 월별 세금계산서입니다.

세금계산서 화면을 보면 공급가액, 세액, 수수료 등 여러 금액이 보여서 헷갈릴 수 있습니다.

하지만 여기서 봐야 할 핵심은 월합계입니다.

각 월별 세금계산서에는 해당 월의 합계 금액이 표시되어 있습니다.
이 월합계 금액을 모두 더하면 해당 연도의 크몽 총 수입금액이 됩니다.

정리하면 다음 순서입니다.

크몽에서 월별 세금계산서를 확인합니다.
각 세금계산서에서 월합계 금액을 찾습니다.
신고 대상 연도에 해당하는 월합계를 모두 더합니다.
합산한 금액을 홈택스의 총 수입금액란에 입력합니다.

예를 들어 1월부터 12월까지 크몽에서 수익이 있었다면, 각 월의 월합계를 모두 더한 금액이 올해 신고할 크몽 부업 수입금액입니다.

여기서 주의할 점이 있습니다.
실제로 통장에 들어온 금액만 보면 안 됩니다.

크몽은 플랫폼 수수료를 차감한 뒤 정산해주기 때문에, 통장 입금액만 기준으로 보면 매출을 과소 입력할 수 있습니다.
따라서 홈택스에는 통장 입금액이 아니라, 크몽 세금계산서 기준으로 정리한 전체 수입금액을 입력해야합니다.

6-2. 월합계 계산이 귀찮다면 GPT를 활용해도 됩니다

월별 세금계산서를 하나씩 열어서 월합계를 더하는 작업이 은근히 귀찮습니다.

이럴 때는 각 월별 세금계산서 이미지나 금액 내용을 GPT에 넣고 이렇게 요청하면 됩니다.

소득신고에 사용할 총 수입금액을 계산해야하니, 
각 월별 세금계산서의 월합계만 기준으로 모두 더해서 총 수입금액을 계산해줘

핵심은 GPT에게 월합계만 기준으로 계산하라고 명확히 말하는 것입니다.

세금계산서에는 공급가액, 세액, 수수료 등 여러 금액이 함께 보이기 때문에, 그냥 “합계 계산해줘”라고 하면 엉뚱한 금액을 기준으로 계산할 수 있습니다.

요청할 때는 기준을 분명히 잡아주는 것이 좋습니다.

월합계만 볼 것
신고 대상 연도에 해당하는 월만 더할 것
최종 결과는 총 수입금액으로 알려줄 것

다만 최종 신고 금액이기 때문에 GPT가 계산한 결과를 그대로 믿기보다는, 마지막에 한 번은 직접 월별 금액과 합계가 맞는지 확인하는 것이 좋습니다.

6-3. 단순경비율은 일반율로 선택합니다

업종별 총 수입금액을 입력하면 경비율을 선택하는 항목이 나옵니다.

여기서는 기본적으로 단순경비율 - 일반율을 선택합니다.

여기서 말하는 경비는 부업 수익을 만들기 위해 들어간 비용을 의미합니다.
크몽 부업 개발자라면 예를 들어 이런 것들이 경비에 해당할 수 있습니다.

크몽 플랫폼 수수료
크몽 이용료
작업에 사용한 소프트웨어 구독료
서버비
외주 작업에 직접 들어간 기타 비용

다만 이 화면에서는 내가 실제 경비를 하나씩 증빙해서 입력하는 방식이 아닙니다.

국세청이 정한 단순경비율을 적용합니다.
쉽게 말하면 “이 업종은 보통 이 정도 비율의 비용이 들어간다고 보고, 일정 비율을 경비로 인정해주는 방식”입니다.

그래서 별도로 복잡하게 비용을 하나하나 입력하지 않고, 총 수입금액에 단순경비율을 적용해 소득금액을 계산합니다.

직장인 부업자로 크몽 수익을 신고하는 경우에는 자동으로 선택된 일반율 그대로 진행하시면 됩니다.

7. 입력완료 후 공제 항목을 확인합니다

사업소득 입력까지 끝났다면 입력완료를 누릅니다.
이후에는 아래 항목들을 차례대로 확인합니다.

소득공제금액
세액공제·감면금액
가산세
기납부세액

직장인이라면 대부분의 내용은 이미 입력되어 있을 가능성이 높습니다.
회사에서 연말정산을 했고, 홈택스에 관련 자료가 남아 있기 때문입니다.

그래도 그냥 넘기지는 않는 것이 좋습니다.
화면을 보다 보면 항목별로 불러오기 버튼이 활성화되어 있는 경우가 있습니다.

저는 혹시 빠진 자료가 있을까 봐, 활성화된 불러오기 버튼은 하나씩 눌러서 다시 확인했습니다.
특히 연말정산 간소화 자료에서 불러오기가 가능한 항목은 한 번씩 더 불러와서 채워 넣었습니다.

이 과정에서 생각보다 빠진 항목이 발견될 수 있습니다.
제 경우에는 기부금 내역이 제대로 반영되지 않은 부분이 있어서, 이 단계에서 추가로 챙길 수 있었습니다.

크몽 수익 입력만큼이나 공제 항목 확인도 중요합니다.
소득을 정확히 신고하는 것도 중요하지만, 받을 수 있는 공제와 감면을 빠뜨리지 않는 것도 세금을 줄이는 데 차이를 만듭니다.
(혹시 모르니까..?)

8. 저장 후 작성완료, 그리고 신고까지 진행합니다

공제 항목과 기납부세액까지 확인했다면 이제 마지막 단계입니다.
먼저 저장하기를 눌러 지금까지 입력한 내용을 저장합니다.

저장하지 않고 이동하면 입력한 내용이 날아갈 수 있으니, 중간중간 저장하는 습관을 들이는 것이 좋습니다.
저장 후에는 작성완료를 누릅니다.

작성완료 단계에서는 지금까지 입력한 신고 내용이 요약되어 표시됩니다.
여기서 아래 내용을 한 번 더 확인합니다.

근로소득이 정상 반영되어 있는지
수입금액이 제대로 입력되어 있는지
소득공제와 세액공제가 빠지지 않았는지
최종 납부세액 또는 환급세액이 예상과 크게 다르지 않은지

내용에 문제가 없다면 최종적으로 신고하기를 눌러 종합소득세 신고를 제출합니다.

9. 신고 후 납부서와 접수 내역을 저장합니다

신고하기까지 완료했다면 바로 끝내지 말고, 납부서와 신고 접수 내역을 저장해둡니다.
납부할 세금이 있다면 홈택스에서 납부서를 확인할 수 있습니다.

이 납부서는 PDF로 저장하거나 인쇄물로 보관해두는 것이 좋습니다.
물론 나중에도 홈택스에서 다시 조회할 수 있습니다.

하지만 막상 필요할 때 메뉴를 다시 찾는 것도 번거롭고, 신고 직후에는 내가 제출한 내용과 납부 금액을 바로 확인할 수 있으니 그때 저장해두는 편이 안전합니다.

10. 지방소득세 신고까지 이어서 진행합니다

종합소득세 신고를 마치면 이어서 지방소득세 신고 단계로 넘어갑니다.

여기서부터는 비교적 간단합니다.
앞에서 홈택스에 입력한 종합소득세 신고 정보가 지방소득세 신고 화면으로 연동되기 때문에, 대부분의 내용은 이미 채워져 있습니다.

따라서 화면에 표시된 내용을 확인하면서 안내에 따라 진행하면 됩니다.
확인할 부분은 주로 다음 정도입니다.

인적사항
종합소득세 신고 내역 연동 여부
지방소득세 납부세액
납부 또는 환급 계좌 정보

내용에 이상이 없다면 지방소득세도 그대로 신고합니다.

종합소득세와 마찬가지로, 지방소득세 신고가 끝난 뒤에도 납부서를 PDF로 저장하거나 인쇄해두는 것이 좋습니다.

지방소득세 역시 나중에 조회할 수는 있지만, 신고 직후에 종합소득세 자료와 함께 정리해두면 훨씬 편합니다.

마무리

직장인 개발자가 부업을 하면, 신고가 조금 헷갈릴 수 있습니다.

특히 크몽은 3.3% 원천징수로 자동 반영되는 구조가 아니라서 홈택스에서 사업소득이 비어 있습니다.

그래서 다시 정리하면.

홈택스 모두채움 정기신고로 시작합니다.
근로소득은 자동 입력된 내용을 확인합니다.
크몽 수익은 사업소득으로 직접 추가합니다.
크몽 월별 세금계산서의 월합계를 모두 더해 총 수입금액을 입력합니다.
단순경비율 일반율을 적용합니다.
공제 항목을 다시 확인합니다.
종합소득세 신고 후 지방소득세 신고까지 마무리합니다.

처음에는 어렵게 느껴지지만, 흐름을 알고 보면 결국 “수입금액을 빠뜨리지 않고 직접 입력하는 것”이 핵심입니다.

부업을 하는 직장인 개발자라면, 5월 종합소득세 신고 때 이 부분만큼은 꼭 챙겨두는 것이 좋습니다.

갑자기 끝나버린 오라클 미환불 사태의 결말

상구너 — Wed, 6 May 2026 17:07:16 +0900

지난번 글에서 이어지는 글입니다
>> https://blog.sanguneo.com/75

오라클 클라우드 결제 환불 진행중 (feat. 오라클 고객지원, 문의하기)

이 이야기는 떼인돈을 받으려 고군분투한 어떤 IT너드의 이야기 입니다. 오라클 클라우드 빈자리가 너무 안나서.. PAY TO GO로 업그레이드 하려고 했던 때 였습니다 결제수단을 추가하고 업그레이

blog.sanguneo.com

지난글에 이어서...

그 이후로도 라이브챗을 몇 번 더 해봤는데, 사실 별 소득은 없었습니다.
대신 collections_sg@oracle.com 쪽에서는 텀이 길긴 했지만 꾸준히 답장이 오고 있었습니다.

"우리는 당연히 바로 환불처리했고, 은행에 문의해라 우린 더 할거없다." 라는 형식적인 답변이었고

"아니, 알지 아는데, 한번만 더 봐줘" 하고 답변을 보냈습니다.

그랬더니, 이번에는 " "알겠다. 4~5일이 지났는데도 안 돌아왔다는 거지?
그럼 거래내역을 보내주면 payment team 쪽으로 확인해볼게." 하고
드디어.. 사건발생 8일 만에 맘에드는 답변이 왔습니다.

그래서 보냈습니다. 4월 30일 밤이 었습니다
토스에서 거래내역 캡쳐도 하고, 은행 거래 증빙 PDF도 발급받아서 같이 첨부했습니다.

여기서부터는 또다시 기다림이었습니다. 그런데...

정확히 11일 이 되는 5월 4일 오후 4시 41분, 그러니까 사건이 발생하고 정확히 11일이 지난 시점에 갑자기 취소 환불이 들어왔습니다. 진짜 말 그대로 아무 예고 없이, 아무 설명 없이, 그냥 갑자기 풀렸습니다.

그리고 다음날..

"payment team에 전달해서 검토 요청하겠다"
=> (이제서야..?)

후기

이번 일을 겪으면서 , 생각보다 Oracle 쪽에서도 이 상황을 정확히 모르고 있었을 수도 있었겠다는 생각이 듭니다.

제가 계속 문의를 하긴 했지만, 상담 흐름을 보면 실제 결제 세션이나 상태를 바로 조회해서 확인해주는 느낌은 아니었습니다. 국내 지원에서는 상상하기는 어렵지만 정말 형식적인 답변에 지치더라구요. 문의창구 찾는것도 너무 어려웠고요

결제 세션 상태를 즉시 확인하거나, 실제 오라클측에서 release 여부를 확인할 수 있는 창구가 있었다면 훨씬 덜 불안했을 텐데,

결국 이번 일은 시간이 지나 해결되긴 했지만, 문제가 해결되는 과정 자체는 꽤 즐겁지 않았네요

Oracle Cloud A1 Flex 4 cpu / 24GB mem 성공기

상구너 — Mon, 27 Apr 2026 16:02:01 +0900

오라클 클라우드에는 평생 무료로 쓸 수 있는 VM이 있다고 해서 Free Tier로 VM.Standard.E2.1.Micro 인스턴스를 하나 만들었다.
스펙은 AMD 1 OCPU / 1GB RAM.
생각보다 잘 돌아가서 열심히 쓰고 있었는데, 어느 날 커뮤니티에서 이런 이야기를 봤다.

ARM 인스턴스는 4 OCPU / 24GB RAM까지 무료로 쓸 수 있다.

사람들이 다들 그걸 쓰고 있다고 자랑하고 있었다.
“아니, 그런 게 있으면 나도 안 할 수 없지?”

그래서 기존에 쓰던 E2 인스턴스는 그대로 두고, A1 Flex 인스턴스를 새로 하나 만들어서 운영해보기로 했다.

그런데 막상 만들려고 보니 목표였던 4/24 스펙은 바로 잡히지 않았다.
OCI에서 흔히 보는 Out of capacity가 떴다.
말 그대로 그 시점에는 원하는 자원을 바로 할당받기 어렵다는 뜻이었다.

내가 사용 중인 춘천 리전에는 자리가 없다는 말이기도 했다.

그래서 이 이야기는 처음부터 “원하는 스펙을 한 번에 만들고 세팅 끝!” 같은 찬란한 이야기는 아니다.
이 이야기는 어떻게 원하는 스펙까지 결국 올렸는가에 대한 이야기다.

0. A1 Flex를 새로 만들기로 함

다른 블로그 글, Reddit, ChatGPT, Gemini 등 여러 채널을 돌아다니며 A1 Flex 인스턴스를 만드는 방법을 다시 찾아봤다.
방법 자체는 예전에 E2 인스턴스를 만들었던 것과 크게 다르지 않았다.
문제는 4 OCPU / 24GB RAM 스펙이 죽어도 생성되지 않는다는 점이었다.
오라클 데이터센터에 물리적인 가용량이 없어서 그렇고, 결국 될 때까지 시도해야 한다는 이야기가 많았다.
또 Pay-As-You-Go 계정으로 업그레이드하면 바로 만들 수 있다는 이야기도 있어서 계정도 업그레이드했다.

이때 오라클 결제 오류 때문에 마음고생한 이야기는 아직 진행 중이다. ㅠㅠ

문제는 여기서부터였다.
계정을 업그레이드했는데도 여전히 4/24 스펙은 가용량 부족으로 생성되지 않았다.
OCI 콘솔에서는 Out of capacity 메시지가 떴다.
실제로는 이것보다 훨씬 긴 메시지였지만, 요지는 간단했다.

지금 이 리전/가용성 도메인에는 해당 자원이 부족하다.

계정도 업그레이드했고, 결제 문제로 마음고생까지 했는데, 정작 원하는 스펙을 못 올리는 상황.
이쯤 되니 이상하게 승부욕이 생겼다.

그럼 전략을 바꿔야 했다.
군자의 도리는 그런 것이다.

처음부터 무리해서 4/24를 만들려고 하지 않고, 일단 생성 가능한 최소 수준으로 먼저 띄우는 방향으로 가기로 했다.

1. A1 Flex를 최소 스펙으로 먼저 만들었다

일단 A1 Flex를 최소 스펙으로 따로 만들었다.
1 OCPU / 6GB RAM
최소 스펙이라 그런지 이건 바로 만들어졌다. (운이 좋았던걸수도 있고)
그리고 확보된 인스턴스를 단계적으로 업그레이드하는 전략을 세웠다.
다행히 OCI는 인스턴스의 CPU와 메모리를 나중에 조정할 수 있는 기능을 제공한다.

2. 2/12, 3/18, 4/24로 단계적으로 올리기로 했다

그다음부터는 단계적으로 스펙을 올리기로 했다.
한 번에 4/24로 훅 올리는 게 아니라,
2/12 → 3/18 → 4/24
이렇게 나눠서 올리는 방식이다.

이렇게 한 이유는 단순했다.
VM.Standard.A1.Flex는 고정된 서버 상품을 하나 통째로 받는 구조가 아니라, 오라클의 ARM 호스트 풀에서 필요한 만큼 자원을 할당받는 구조라고 봤기 때문이다.

즉, 4 OCPU / 24GB RAM이 한 번에 비는 경우는 드물 수 있다.
하지만 이미 1/6 인스턴스를 만들어둔 상태에서 한 단계씩 올리면, 매번 추가로 필요한 자원은 1 OCPU / 6GB RAM뿐이다.
한 번에 큰 자리를 기다리는 것보다, 작은 빈자리를 여러 번 잡는 쪽이 가능성이 더 높을 거라고 생각했다.
그래서 일단 인스턴스를 만든 뒤, 인스턴스 편집 화면에서 2/12로 변경하고 저장을 눌렀다.

3. 웹 콘솔에서 CLI 자동화로 전환

처음에는 웹 콘솔에서 직접 시도했는데.대여섯 번쯤 누르니 이런 생각이 들었다.

이걸 언제까지 누르고 있어야 하지?

10번이 넘어가자 괜히 시작했다는 생각도 들었다.
분명 이걸 자동화하는 방법이 있을 것 같았다.
실제로 성공한 사람들의 이야기를 보면, 설정 스택을 저장해두고 Terraform을 이용해서 몇 분마다 4/24 생성 명령을 반복했다고 했다.
그때 본 것이 oci cli였다.
이걸 이용하면 Python이나 다른 스크립트로 자동화할 수 있겠다는 생각이 들었다.

Terraform은 잘 모르니까.
그래서 이번에는 OpenAI Codex와 연결된 내 에이전트에게 이 작업을 자동화하고, 로그까지 남기는 스크립트를 만들어달라고 했다.
시행착오는 있었지만, 최종적으로 정착한 조건은 다음과 같았다.

    재시도 주기: 3분
    성공 시 다음 단계 시도 간격: 30초
    텔레그램 보고: 08시 ~ 23시까지 매시 정각에 실행 상황 브리핑

중간 로그를 보면 재시도 흔적이 꽤 많이 남아 있다.
특히 2/12로 올라갈 때 정말 많이 시도했는데, 로그가 제대로 남아 있지 않은 게 조금 아쉽다.

4. 로그로 보면 시도는 꽤 많이 했다

이 과정에서 남은 로그를 정리해보면, 변경 시도만 해도 꽤 여러 번 반복됐다.

2/12로 올라갈 때 로그 정리가 잘 안 되어 있어서 정확히 보이지는 않지만, 체감상 거의 400번 넘게 시도했던 것 같다.

5. 결국 총 800번 정도의 시도 끝에 4 OCPU / 24GB에 안착

최종적으로는 4 OCPU / 24GB RAM까지 올리는 데 성공했다.
처음 1/6으로 시작했을 때는 금방 되겠지 싶었다.
하지만 2/12로 올라갈 때는 “이거 아닌가?” 싶을 정도로 오래 걸렸다.
그런데 3/18까지 올라간 뒤에는 생각보다 금방 4/24까지 올라갔다.
그 순간은 꽤 짜릿했다.

6. 정리

정리하면, 이번 작업은 OCI A1 Flex에서 원하는 스펙이 바로 잡히지 않을 때 사용한 단계적 확장기였다.
처음부터 4 OCPU / 24GB RAM을 만들려고 하면 Out of capacity에 막혔다.

그래서 먼저 가능한 최소 스펙인 1 OCPU / 6GB RAM으로 인스턴스를 만들고, 이후에 2/12 → 3/18 → 4/24 순서로 조금씩 키웠다.
한 번에 큰 자원을 기다리는 대신, 작은 단위의 빈자리를 여러 번 잡는 방식이었다.
결과적으로 약 800번 정도의 시도 끝에 원하는 스펙까지 도달했다.

OCI A1 Flex는 무료 스펙이 매력적이지만, 리전 상황에 따라 가용량 문제가 꽤 심하다.
그래도 바로 포기하지 않고, 가능한 스펙부터 확보한 뒤 단계적으로 올리는 방식은 충분히 시도해볼 만한 전략이었다.

Hermes Agent core 수정 없이 Supertonic2 TTS 붙이기

상구너 — Fri, 24 Apr 2026 14:07:05 +0900

Hermes에서 TTS 엔진을 조금 바꿔보고 싶어서 작은 프록시 서버를 만들었습니다.

저장소는 여기입니다.
https://github.com/sanguneo/supertonic-openai-tts-proxy

GitHub - sanguneo/supertonic-openai-tts-proxy: OpenAI-compatible local TTS proxy for supertonic

OpenAI-compatible local TTS proxy for supertonic. Contribute to sanguneo/supertonic-openai-tts-proxy development by creating an account on GitHub.

github.com

이 프로젝트는 supertone-inc/supertonic을 실제 음성 합성 엔진으로 사용합니다.
다만 Supertonic을 Hermes에 직접 붙인 건 아니고, 중간에 작은 프록시를 하나 둔 방식입니다.
Hermes 입장에서는 OpenAI TTS API를 호출하는 것처럼 보이지만,
실제로는 로컬에서 실행 중인 Supertonic 프록시로 요청이 갑니다.

왜 프록시로 만들었나

처음에는 Hermes 내부 TTS 코드를 직접 수정하는 방법도 생각했습니다.

그런데 그렇게 하면 나중에 Hermes를 업데이트할 때 귀찮아질 수 있습니다.
수정한 부분이 충돌날 수도 있고, 계속 신경 써야 할 부분이 생깁니다.

그래서 Hermes core는 그대로 두고, OpenAI 호환 API처럼 동작하는 프록시를 만드는 쪽으로 잡았습니다.

Hermes는 이미 tts.provider: openai 설정을 지원하고, base_url도 바꿀 수 있습니다.
그러면 Hermes 설정만 바꿔서 로컬 프록시를 바라보게 만들 수 있습니다.

Hermes / client
      │
      │ OpenAI-compatible request
      ▼
/v1/audio/speech
      │
      │ proxy adapter
      ▼
Supertonic
      │
      │ synthesized audio
      ▼
mp3 / ogg / wav

대충 이런 구조입니다.

Hermes는 그대로 두고,
중간에서 Supertonic을 OpenAI TTS API처럼 보이게 감싸는 방식입니다.

지원하는 기능

현재 넣어둔 기능은 이 정도입니다.

OpenAI 호환 POST /v1/audio/speech
GET /v1/models
GET /health
Supertonic 기반 로컬 TTS 합성
mp3, ogg, wav 출력
긴 문장 분할 처리
Supertonic quality steps 설정
브라우저 테스트용 playground
WSL user systemd 서비스 스크립트
Hermes 설정/복원 스크립트

처음에는 그냥 연결만 해보려고 했는데, 실제로 계속 쓰려면 서비스 등록이나 설정 복원도 필요해서 같이 정리했습니다.

요청 예시

요청은 OpenAI TTS와 비슷한 형태로 보냅니다.

{
  "model": "supertonic-2",
  "voice": "F1",
  "input": "안녕하세요. Supertonic TTS 테스트입니다.",
  "response_format": "mp3",
  "speed": 1.3,
  "total_steps": 3
}

여기서 total_steps는 Supertonic의 품질 설정에 해당합니다.

현재 기본값은 3으로 잡아두었습니다.
빠른 응답을 우선한 설정입니다.

Low     = 3
Normal  = 6
High    = 10

품질을 더 올리고 싶으면 total_steps 값을 올리면 됩니다.
대신 합성 시간은 조금 더 걸릴 수 있습니다.

ogg 출력

출력 포맷은 mp3, ogg, wav를 지원합니다.

일반 오디오 파일로 쓰려면 mp3가 편하고,
원본 확인이나 디버깅에는 wav가 편합니다.

ogg는 Telegram voice message 때문에 넣었습니다.

Telegram 음성 메시지는 보통 Ogg 컨테이너 + Opus 코덱 조합을 사용합니다.

그래서 아래처럼 요청하면:

{
  "response_format": "opus"
}

audio/ogg 형태로 반환합니다.

이렇게 만들어두면 단순 파일 첨부가 아니라, Telegram에서 음성 메시지처럼 다루기 좋습니다.

Hermes 설정

Hermes 설정은 대략 이렇게 바꾸면 됩니다.

tts:
  provider: openai
  openai:
    base_url: http://127.0.0.1:8789/v1
    model: supertonic-2
    voice: F1
    speed: 1.3
    max_text_length: 2000

그리고 .env에는 dummy key를 넣습니다.

VOICE_TOOLS_OPENAI_KEY=dummy

실제 OpenAI API key가 필요한 것은 아닙니다.
로컬 프록시를 쓰는 것이기 때문에 값 자체는 dummy여도 됩니다.

다만 Hermes의 OpenAI TTS provider 경로를 타려면 환경 변수가 필요해서 넣어둔 값입니다.

gateway를 쓰고 있다면 설정 변경 후 재시작합니다.

hermes gateway restart

설정 백업과 복원

Hermes 설정을 바꾸는 작업이라 백업 스크립트도 같이 넣었습니다.

설정 적용은 아래 스크립트로 합니다.

./scripts/setup-hermes-config.sh

이 스크립트는 적용 전에 기존 설정을 백업합니다.

~/.hermes/config.yaml.bak.<timestamp>
~/.hermes/.env.bak.<timestamp>

복원은 아래처럼 할 수 있습니다.

./scripts/restore-hermes-config.sh --list
./scripts/restore-hermes-config.sh --latest
./scripts/restore-hermes-config.sh 20260424_105304

복원할 때도 현재 설정을 바로 덮어쓰지 않고, 먼저 한 번 더 백업합니다.

~/.hermes/config.yaml.pre-restore.<timestamp>
~/.hermes/.env.pre-restore.<timestamp>

설정 파일은 한 번 꼬이면 귀찮아서, 되돌릴 수 있게 만들어두는 편이 마음이 편합니다.

테스트용 playground

프록시 서버 안에 간단한 playground도 넣었습니다.

서버를 실행한 뒤 아래 주소로 들어가면 됩니다.

http://127.0.0.1:8789/

여기서 텍스트, voice, 출력 포맷, 속도, quality steps를 바꿔가며 테스트할 수 있습니다.

별도 프론트엔드 프로젝트를 만든 건 아니고, FastAPI에서 정적 HTML 하나를 서빙하는 정도입니다.

간단히 확인하기에는 이 정도면 충분했습니다.

실행 방법

설치는 uv 기준입니다.

uv sync

개발 서버 실행은 이렇게 합니다.

./scripts/run-dev.sh

기본 주소는 아래입니다.

http://127.0.0.1:8789

상태 확인은 /health로 할 수 있습니다.

curl http://127.0.0.1:8789/health

테스트는 이렇게 실행합니다.

uv run pytest -q

현재 기준 테스트는 통과하는 상태입니다.

13 passed

마무리

이번 작업은 Hermes에 Supertonic을 직접 박아 넣는 방식이 아니라, 중간에 OpenAI 호환 프록시를 두는 방식으로 정리했습니다.

Hermes core를 건드리지 않아도 되고,
문제가 생기면 설정만 되돌리면 됩니다.

그리고 OpenAI TTS API와 비슷한 모양으로 맞춰두면 Hermes 외의 다른 클라이언트에서도 가져다 쓰기 쉽습니다.

로컬 TTS를 Hermes에 붙여보고 싶거나,
Supertonic을 OpenAI 호환 TTS endpoint처럼 써보고 싶은 분들은 참고해보셔도 좋겠습니다.

오라클 클라우드 결제 환불 진행중 (feat. 오라클 고객지원, 문의하기)

상구너 — Thu, 23 Apr 2026 23:41:17 +0900

이 이야기는 떼인돈을 받으려 고군분투한 어떤 IT너드의 이야기 입니다.

오라클 클라우드 빈자리가 너무 안나서.. PAY TO GO로 업그레이드 하려고 했던 때 였습니다 결제수단을 추가하고 업그레이드 하는데 갑자기 프레임 내부 에러가 뜨고, 세션이 만료되고, 그 와중에 138.19 싱가포르 달러가 실제로 빠져나갔습니다. 이전에 한번 시도(해외결제 차단) 으로 실패했을때는 돈이 일단 나갔다 바로 취소프로세스를 타서 들어왓는데, 이번엔 아니었습니다. 체크카드였어서 돈이 현금으로 그냥 빠져나가버리고, 돌아오질 않으니 그때부터는 뭔가 제대로 잘못됐다는 느낌이 왔습니다.

처음엔 저도 "승인 보류겠지" 하고 넘기려고 했습니다. 오라클 쪽도 그렇게 말했으니까요. 그런데 카드 명세에는 이미 돈이 빠져나간 것처럼 보였고, 오라클 화면에서는 그 결제 내역은 어디서도 볼수가 없엇습니다.. 이 상태가 사람을 제일 미치게 합니다. 어디서 잘못된 건지, 누구 말을 믿어야 하는지 안 보이거든요...

처음엔 그냥 기다리면 풀릴 줄 알았습니다

처음엔 진짜 대수롭지 않게 생각했습니다. 잠깐 잡아두는 보류고, 시간이 지나면 정리되겠지 싶었습니다.
그런데 금액은 애매하지 않았습니다. 테스트용으로 넘기기엔 138.19 싱가포르 달러 그러니까 당시 환율로 16 만원이 넘는 금액은, 결코 작은금액도 아니고, 보류처럼만 보이지 않았습니다. 무엇보다 결제 과정에서 에러가 먼저 났습니다. 이 조합이면 "괜찮겠지" 하고 넘기기 어려웠습니다.
그때부터는 마음이 좀 급해졌습니다. 기다리는 시간 동안에도 계속 카드 명세를 들여다보고, 오라클 화면을 다시 확인하고, 혹시 내가 뭘 잘못 눌렀나 돌아보고, 또 다시 같은 화면을 보는 식이었으니까요.

문제를 결제 사고로 봐야 했습니다

이게 승인 보류인지, 매출인지
오라클 시스템에 기록이 남았는지
언제 어떤 상태로 바뀌는지

이 질문으로 들어가니까 대응도 달라졌습니다. 막연히 "도와주세요"가 아니라, 문제를 구조적으로 짚어야 했습니다. 그런데...

이 일에서 제일 중요했던 건 문제를 다시 정의한 거였습니다. 그냥 "결제가 안 된다"가 아니라, "이건 결제 사고처럼 보인다"로 봐야 했습니다.
그렇게 봐야 해야 할 질문도 또렷해집니다.

오라클에 문의넣는 여정부터 만만치 않았습니다

오라클 문의 방법 찾는 것만 네시간을 허비했습니다.
우선 오라클 클라우드 콘솔 내 문의하기는 AI챗봇이고, 실제상담원으로 전환되거나 하는 기능은 전혀 없습니다. 클라우드 안에서는 방법이 없어요... 커스토머 서포트가 있긴 한데 유료회원인지 기업회원인지.. 저같은 개인은 불가능한 일이었어요

흘러흘러 my oracle support이라는걸 찾아 가입했습니다. 근데 가입한 다음 할수있는건 아무 것도 없었습니다. 오라클 클라우드 콘솔이랑 연결하는 정도.. 그외는 아무기능도 없는 사이트였어요...

그래서 오라클 스토어쪽으로 어떻게 또 타고 들어왔습니다. 여기에는 문의 폼이 있네요 그래서 여기 먼저 남겼습니다.
https://store-oracle.custhelp.com/app/CP_CP

Ask a Question

What can we help you with? *

store-oracle.custhelp.com

일단 문의를 남겼는데.. 문의가 잘 남겨졌다고 자동응답이 왔네요

그리고 우연히 네이버/구글 여기저기 검색중 환불관련 문의는
collections_sg@oracle.com 에 이메일 남기라는 글을 만났습니다.

이메일 보냈는데 여기도 자동응답이네요,

찾다찾다 오라클 한국 전화번호가 있었는데, 여기는 영업일에 전화준대놓고 안줍니다 여긴 포기하세요.

그러다 오라클 라이브챗 을 알게되었습니다. 나중에 알게된건데 아까 문의남긴 그 사이트에 있던건데, 저는 구글에서 직통 url을 찾았어요

https://store-oracle.custhelp.com/app/chat/chat_launch

요롷고롬 생겼습니다. 기본적인 인적사항과, (company는 그냥 none 해도됨) 문의내용 요약본을 우리의 ai친구에게 부탁해 넣었습니다.

이렇게 넣으면 일단 라이브 챗이 시작되는데 일단은 여기도 챗봇으로 시작은 합니다.
근데 이상하게 스타트 챗이 활성화가 안될때가 있어요 , 그럴땐 다른방법이 있습니다.
https://customercenter.oracle.com/

https://customercenter.oracle.com/

customercenter.oracle.com

여기 들어가면 우측하단에 메시지 아이콘을 누르면 바로 시작됩니다.

근데 말씀드렸듯 둘다 챗봇으로 시작하는데요, 이때 뭐 선택하고 뭐 하고 할필요 없고 바로 한마디 칩니다.

I want to chat with real agent

그럼 진짜 원하냐고 물어보는데 yes 를 누르면 잠시후 연결이 됩니다. 이제 문의하면 됩니다.
영어 할줄은 아는데 정확하게 안하면 문제될듯 하니, 우리의 ai친구에게 대화를 전달하면서 꾹꾹 눌러 써 나갑니다. 저는 지피티한테 시켰는데 중간중간 "[내정보입력]" 이런식으로 적어놨는데 이거 처음에 그냥 보냈다가 당황했어요.. 근데 스무스하게 넘어갔습니다. 어쨋건 사간발생 4시간만에 라이브 상담사와 연결이 되어 이것저것 문의하고 확인요청을 했습니다. 근데 은행에 확인해보라 말하기도 하고... 해서 토스카드 고객센터는 24시간이니 물어보면서 대화했어요

오라클이랑 은행이 서로 다르게 말하더군요

오라클은 승인 보류 쪽으로 설명했고, 은행 쪽에서는 실제 반영 상태를 따져봐야 했습니다. 문제는 이 둘이 같은 말을 하지 않는다는 겁니다.
오라클은 "기다려라" 쪽이고, 은행은 "아직 환불전표가 안들어왔다" 쪽이었습니다. 결국 저만 중간에서 계속 확인하고, 또 확인하고, 또 확인해야 했습니다. 이게 제일 피곤합니다.

그래서 저는 오히려 질문을 좁혔습니다. "이게 승인 보류냐, 매출이냐". 이 한 문장이 제일 중요했습니다. 다른 설명보다 이걸 먼저 확인해야 했습니다.

아직 끝난 건 아니지만, 방향은 보였습니다.

지금도 완전히 해결된 상태는 아닙니다. 그래서 이 글은 후기가 아니라 진행 기록에 가깝습니다.
다만 이번 일로 하나는 확실히 배웠습니다. 결제는 됐는데 기록이 없으면, 그때부터는 그냥 기다리는 문제가 아니더군요.
오라클 쪽에서는 3~5일 정도 기다려보라는 식으로 말했지만, 저는 일단 기록을 남겨두고 지켜보는 쪽으로 가려고 합니다. 괜히 혼자만 조급해지면 더 꼬일 것 같아서요.

아마 이 글도 한 번에 끝나지는 않을 겁니다. 나중에 진짜로 정리되면, 그때는 결론까지 이어서 다시 적어보려고 합니다.

완료되면 다시 돌아오겠습니다.

insane-search-hermes를 공개했습니다

상구너 — Wed, 22 Apr 2026 11:16:45 +0900

최근에 blocked-site retrieval 쪽을 조금 더 실전적으로 써보고 싶어서, insane-search-hermes라는 스킬을 따로 정리했습니다.

원본은 fivetaku/insane-search이고, 저는 그 문제의식과 접근 방식을 Hermes 흐름에 맞게 다시 구성해봤습니다. 그냥 웹 검색이 안 되는 순간 포기하는 게 아니라, 어떤 경로로 한 번 더 뚫어볼지 순서를 잡아주는 쪽에 가깝습니다.

어떤 걸 하려고 만든 스킬인가요?

사이트가 막혔을 때 보통은 여기서 끝나는 경우가 많습니다.

403
WAF
CAPTCHA
빈 SPA
로그인 벽

이럴 때 web_extract 하나만 보고 끝내지 않고, 다음 순서로 다시 시도해보도록 정리했습니다.

Jina Reader
공개 JSON API
RSS / Atom
curl_cffi 기반 TLS impersonation
browser / CDP escalation

특히 네이버, Reddit, X, Hacker News, Bluesky처럼 접근 방식이 조금씩 다른 서비스는 전용 스크립트까지 같이 넣어뒀습니다.

이번에 같이 넣은 것들

문서형 스킬로만 끝내지 않고, 실행형 스크립트도 붙였습니다.

fetch_with_cffi.py
naver_search.py
reddit_json.py
hn_fetch.py
bluesky_fetch.py
wayback_lookup.py
insane_router.py

insane_router.py는 URL, 핸들, 키워드를 구분해서 어떤 경로를 먼저 써볼지 자동으로 실행해보는 라우터 역할을 합니다. 완전히 원본 플러그인처럼 동작하는 수준까지는 아니지만, 실전에서는 꽤 바로 써먹을 수 있는 정도까지는 왔다고 느꼈습니다.

skills hub에는 왜 바로 못 올렸나

이건 조금 아쉬웠던 부분입니다.

Hermes skills hub로 publish도 바로 해보려고 했는데, 스캔 단계에서 막혔습니다. 이유는 대체로 아래 세 가지였습니다.

없으면 설치하고 계속 가는 auto-install 문구
스크립트 내부의 subprocess 실행
bootstrap / env 처리 로직

실전성은 좋아졌지만, registry publish 관점에서는 위험 판정이 나는 구조였던 거죠. 그래서 지금은 hub 배포는 보류했습니다.

대신 GitHub에는 올려뒀습니다

코드는 아래에 정리해뒀습니다.

https://github.com/sanguneo/insane-search-hermes

README도 한글/영문으로 나눠뒀고, 스킬 본문과 reference, scripts까지 같이 넣어뒀습니다.

설치 방법은

## 자동
hermes skills install sanguneo/insane-search-hermes:skill/SKILL.md

## 수동
git clone https://github.com/sanguneo/insane-search-hermes.git
cp -R ./insane-search-hermes/skill ~/.hermes/skills/research/insane-search-hermes/

써보면서 느낀 점

아직 더 다듬을 부분은 남아 있지만, 지금도 막힌 URL을 다룰 때 꽤 유용하게 쓰고 있습니다. 다음에는 browser/CDP 단계까지 조금 더 자연스럽게 이어지는 쪽으로 정리해보려고 합니다.

Google AI Studio, 구독만으로 더 넓어진 실험 한도

상구너 — Tue, 21 Apr 2026 13:55:30 +0900

최근 Google이 AI Studio의 진입 장벽을 꽤 낮췄습니다.

Google AI Studio의 사용 한도가 넓어졌습니다.

Google AI Pro와 Ultra 구독자는 이제 AI Studio에서 더 높은 사용 한도를 받을 수 있고, Nano Banana Pro와 Gemini Pro 모델도 바로 활용할 수 있게 됐습니다.

겉으로 보면 단순히 "쓸 수 있는 범위가 넓어졌다"는 정도로 보일 수 있습니다. 하지만 실제로는 아이디어를 더 자주, 더 오래 실험할 수 있게 해준다는 점에서 의미가 큽니다.

예전에는 무료 한도를 넘기면 테스트 흐름이 쉽게 끊겼습니다. 조금 더 써보려는 순간 종량제 API 세팅으로 넘어가야 해서, 초반 탐색이 번거롭게 느껴질 때가 있었거든요.

이번 변화는 그 중간을 더 자연스럽게 이어줍니다.

구독 환경에서 먼저 충분히 써보고
괜찮다 싶으면
AI Studio 안에서 API 기반으로 확장하는 흐름이 가능해진 겁니다.

이 구조가 좋은 이유는

시작이 쉽습니다.
복잡한 결제나 설정을 처음부터 붙잡지 않아도 됩니다.

실험이 빨라집니다.
떠오른 아이디어를 바로 확인할 수 있어서, 프로토타입 검증 속도가 빨라집니다.

확장도 자연스럽습니다.
처음부터 운영 구조를 고민하기보다, 먼저 만들어 보고 이후에 정리하는 방식이 가능해집니다.

결국 이번 변화는 AI Studio를 단순한 체험 공간이 아니라,
"구독만으로도 충분히 실험해볼 수 있는 작업 공간"에 더 가깝게 바꿔준 업데이트라고 볼 수 있습니다.

AI를 쓰는 입장에서는 반가운 변화고, 무언가를 만드는 입장에서는 훨씬 가벼운 출발점이 하나 생긴 셈입니다.

천천히 써보면서, 어디까지 구독 환경에서 충분히 해결되는지도 한번 확인해봐야겠어요.

Vercel 보안 이슈 정리

상구너 — Mon, 20 Apr 2026 22:27:16 +0900

Vercel 보안 이슈 정리

Vercel이 최근 보안 공지를 공개했습니다. 평소처럼 조용히 지나가는 이슈가 아니라, 실제로 내부 시스템 일부에 대한 무단 접근이 확인된 사건입니다.

처음 제목만 보면 “어디가 털렸나?” 싶을 수 있는데, 공식 bulletin을 읽어보면 핵심은 꽤 명확합니다. 시작점은 Vercel 자체 서버가 아니라, Vercel 직원이 사용하던 서드파티 AI 도구 Context.ai 계정이 침해된 것이었습니다. 그 계정 접근을 통해 공격자가 직원의 Google Workspace 계정까지 들어갔고, 그 결과 일부 Vercel 환경과 환경변수에 접근한 것으로 설명하고 있습니다.

무슨 일이 있었나

Vercel은 4월 보안 공지를 통해 내부 시스템의 일부에 대한 무단 접근을 확인했다고 밝혔습니다. 동시에 외부 보안업체와 법집행기관도 함께 대응 중이라고 했고, 서비스는 현재 운영 중이라고 덧붙였습니다.

중요한 건 “모든 고객 데이터가 다 유출됐다”는 식의 단정이 아니라는 점입니다. Vercel은 처음에는 일부 고객만 영향이 있었고, 연락을 받은 고객에게는 즉시 자격 증명 교체를 권고했다고 설명합니다. 아직까지는 노출 범위와 실제 반출 데이터가 조사 중입니다.

어디가 위험했나

공식 문서에서 특히 눈에 들어온 부분은 환경변수입니다. Vercel은 sensitive로 표시되지 않은 환경변수에 접근했을 가능성을 언급했고, sensitive로 표시된 값은 읽기 어렵게 저장되어 있어 현재까지 접근 증거는 없다고 밝혔습니다.

실무적으로 보면 이게 꽤 중요합니다. 개발자는 종종 API 키, 토큰, DB 비밀번호를 환경변수로만 넣어두고 끝내기 쉬운데, “어디까지 보호되는지”는 서비스마다 다릅니다. 이번 공지는 그 차이를 다시 한 번 보여줍니다.

Vercel이 권고한 대응

계정과 환경의 activity log 확인
환경변수 중 민감한 값은 우선 교체
최근 배포 중 수상한 항목 점검
Deployment Protection 설정 확인
Deployment Protection token 사용 중이면 교체

개인적으로는 이 순서가 꽤 현실적이라고 봅니다. “혹시 모르니 다 바꾸자”보다, 로그 → 환경변수 → 최근 배포 → 보호 설정 순으로 보는 편이 훨씬 빠릅니다.

내가 보는 포인트

이번 건은 단순한 한 서비스의 해킹 소식이라기보다, 서드파티 도구와 계정 연결 지점이 얼마나 큰 리스크가 되는지 다시 보여준 사례에 가깝습니다.

특히 개발 환경은 협업 도구, 자동화 도구, 배포 플랫폼, 메신저, 클라우드가 전부 얽혀 있어서 한 군데만 느슨해도 전체가 흔들릴 수 있습니다. 그래서 보안은 늘 “서버만 단단하면 끝”이 아니고, 연결된 계정과 권한까지 같이 봐야 합니다.

Vercel을 쓰는 팀이라면 이번 공지 한 번쯤 읽어보고, 환경변수와 배포 보호 설정은 바로 점검해두는 게 좋아 보입니다.

정리

이번 Vercel 보안 이슈는 아직 조사 중인 부분이 남아 있지만, 실무자가 바로 챙길 건 이미 나와 있습니다. 민감한 비밀값은 다시 점검하고, 최근 배포와 접근 로그를 확인하고, 외부 도구에 연결된 권한도 한 번 정리해두는 것. 이 정도만 해도 피해를 꽤 줄일 수 있습니다.

보안은 늘 귀찮지만, 한 번 터지고 나면 더 귀찮아집니다. 그래서 미리 보는 쪽이 결국 제일 싸게 먹히는 것 같아요.

도리식탁 후기｜신정동 즉석떡볶이 전문점

상구너 — Sun, 19 Apr 2026 14:30:06 +0900

신정동에서 즉석떡볶이 먹을 곳을 찾다가 도리식탁에 들렀다. 사진처럼 간판부터 꽤 귀엽고 깔끔해서 처음 보는 순간 바로 기억에 남았다. 흰 바탕에 붉은 글씨로 도리식탁, 영어로는 DORI’S TABLE이라고 적혀있다

간판만 봐도 분식집 특유의 편한 분위기가 느껴졌고, 귀여운 곰 캐릭터 덕분에 동네 맛집 같은 친근함도 있었다.사장님 별명이 곰돌이라 도리라고한다

메뉴판도 꽤 재밌었다. 맵도리, 반도리, 짜도리처럼 선택지가 나뉘어 있어서 취향 따라 고르기 좋았다.

사리나 사이드 메뉴도 다양해서 한 끼를 꽉 채워 먹기 좋겠다는 느낌이었다. 나는 맵도리에 쫄면 추가해서 치즈넣고 먹었다

전체적으로 도리식탁은 깔끔한 첫인상과 분명한 메뉴 컨셉이 강한 곳이었다.

신정동이나 오목교 근처에서 즉석떡볶이 생각날 때 한 번쯤 가볼 만한 집으로 기억해둘 만하다.

한줄평

귀엽고 깔끔한 간판 근데 맛도 꽤 괜찮은 즉석떡볶이집.

볶음밥은 먹어야지

한국어 TTS 비교 후기: EdgeTTS를 거쳐 Supertonic-2로 정착하기까지

상구너 — Thu, 16 Apr 2026 16:04:41 +0900

들어가며

텔레그램에서 바로 보낼 한국어 음성메시지용 TTS가 필요했습니다. 조건은 비교적 분명했습니다. WSL에서 돌아가야 했고, 외장 GPU 없이도 실사용 가능해야 했으며, 무엇보다 한국어가 어색하지 않아야 했습니다. 단순히 음성이 생성되는 정도가 아니라, 실제로 계속 쓸 수 있을 정도의 품질이 필요했습니다.

처음에는 EdgeTTS로 시작했습니다. 붙이기 쉽고 결과도 빨리 나와서 시작점으로는 나쁘지않았습니다. 다만 쓰다 보니 욕심이 생겼습니다. “조금 더 자연스럽고, 조금 더 만족스러운 한국어 TTS가 없을까?”라는 생각이 들었고, 그다음으로 Kokoro를 직접 붙여봤습니다. 이후 여러 모델 데모를 더 비교해 본 끝에, 최종적으로는 Supertonic-2에 정착하게 됐습니다.

참고로 ElevenLabs도 꽤 궁금했습니다. 실제로 한 번 써보고 싶기도 했습니다. 다만 GPU가 없는 환경에서 직접 구축해서 계속 돌리는 쪽에 더 무게를 두고 있었기 때문에, 결과적으로는 그 방향 대신 로컬에 가까운 쪽으로 계속 비교하게 됐습니다. 그리고 결론적으로는 지금 정착한 조합에 매우 만족하고 있습니다.

이번에 비교할 때 중요하게 본 기준

이번에 TTS를 고를 때 제가 중요하게 본 기준은 아래 네 가지였습니다.

WSL에서 무리 없이 돌릴 수 있는가
GPU 없이도 실사용 가능한가
한국어가 외국어 억양처럼 들리지 않는가
텔레그램 음성메시지로 바로 쓰기에 충분한가

여기서 특히 중요했던 건 세 번째였습니다. 많은 TTS가 “한국어 지원”은 하지만, 실제로 들어보면 자연스러운 한국어와는 거리가 있는 경우가 생각보다 많았습니다. 문서를 보면 좋아 보이는데, 직접 들어보면 바로 탈락하는 경우가 적지 않았습니다.

1단계: EdgeTTS는 빠르게 시작하기에 좋았습니다

가장 먼저 사용한 것은 EdgeTTS였습니다. 이유는 단순했습니다. 바로 붙이기 쉽고, 결과를 빠르게 볼 수 있기 때문입니다. 한국어 문장을 읽히고, 파일로 뽑고, 음성메시지로 보내는 흐름을 확인하는 데는 정말 편했습니다.

2단계: Kokoro는 기대가 컸지만, 한국어 스피치는 아쉬웠습니다

Kokoro는 꽤 기대하고 붙였습니다. 모델 자체에 대한 평도 좋았고, 한 번 직접 비교해 볼 가치가 충분해 보였습니다. 그래서 실제로 WSL 환경에 설치하고, 문장을 넣어서 음성을 생성해 봤습니다.

그런데 여기서 느낀 점은 꽤 분명했습니다. 모델 평판과 실제 한국어 TTS 경험은 다를 수 있다는 점이었습니다.

문제는 단순히 품질이 낮다기보다, 한국어가 자연스러운 한국어처럼 들리지 않는다는 점이었습니다. 전체적으로는 외국인이 한국어를 따라 읽는 느낌이 강했습니다. 문장이 부드럽게 흘러가기보다, 한국어 음절을 외국어 화자가 조심스럽게 흉내 내는 듯한 인상이 있었습니다.

특히 일본어 계열 보이스는 더 그랬습니다. 거의 한본어에 가까운 느낌이었습니다. 조금 과장해서 말하면, “독도”라고 넣었을 때 “다케시마”라고 해도 이상하지 않을 것 같은 수준의 이질감이 있었습니다. 한국어 TTS를 기대하고 들었는데, 실제로는 한국어 발음을 흉내 내는 외국어 보이스에 가까웠습니다.

이 부분은 단순한 취향 문제라기보다, 제가 원하는 용도와 맞지 않는 문제였습니다. 저는 실험용 샘플이 아니라, 실제 텔레그램 음성메시지에 바로 붙일 수 있는 결과가 필요했기 때문입니다. 그 기준에서는 Kokoro를 기본 TTS로 정착시키기 어려웠습니다.

왜 Kokoro를 포기했는가

Kokoro를 제 기준에서 정리하면 이렇습니다.

장점: 기대하게 만드는 모델이고, 직접 써볼 가치는 충분했습니다
단점: 제가 원하는 “자연스러운 한국어 TTS”와는 거리가 있었습니다
결론: 비교 대상으로는 의미 있었지만, 기본 TTS로 정착하긴 어려웠습니다

즉, "모델이 나쁘다"기보다, 제가 필요한 한국어 음성메시지 용도에는 맞지 않았다 에 더 가까웠습니다.

그다음은 문서보다 데모를 더 많이 봤습니다

Kokoro에서 한 번 아쉬움을 느끼고 나니 기준이 더 분명해졌습니다. 그 뒤로는 모델 카드 설명이나 평판만 보기보다, 가능한 한 데모를 직접 들어보는 쪽으로 방향을 바꿨습니다. Hugging Face 쪽도 계속 참고했고, 설명이 좋아 보여도 실제 청감이 별로면 바로 제외했습니다.

이 과정에서 다시 확인한 건 단순했습니다.

"한국어 인식"이라고 적혀 있는 것과
"실제로 한국어가 자연스럽게 들리는 것"은 전혀 다르다는 점입니다

문서만 보면 괜찮아 보이는 모델도, 실제 샘플을 몇 개만 들어보면 금방 감이 옵니다. 특히 텔레그램처럼 짧은 음성메시지로 바로 들리는 환경에서는 어색한 억양이 더 잘 드러났습니다.

직접 써본 흐름 기준 비교

후보	접근 방식	장점	아쉬운 점
EdgeTTS	가장 먼저 실제 사용	붙이기 쉽고 빠르게 결과를 볼 수 있었습니다	예민하게 들으면 너무 음성합성 티가 많이나는거같았습니다.
Kokoro	직접 설치 후 한국어 음성 생성 테스트	기대하게 만드는 모델이었고 비교 가치는 충분했습니다	외국인이 한국어를 읽는 듯한 느낌이 강했고, 특히 일본어 계열 보이스는 "한본어"에 가까웠습니다
Supertonic-2	여러 데모 비교 후 실제 정착	한국어 청감이 가장 납득 가능했고 실사용 방향이 분명했습니다	처음부터 바로 도달한 후보는 아니었습니다
ElevenLabs	관심은 있었지만 이번 방향에서는 보류	품질 기대치가 높았습니다	당시에는 GPU 없는 환경에서 직접 구축해 운용하는 방향에 더 집중했습니다

최종적으로 Supertonic-2에 정착한 이유

여러 데모를 듣고 비교한 뒤, 결국 정착한 것은 Supertonic-2였습니다. 이 모델이 좋았던 이유는 단순히 “소리가 괜찮다” 수준이 아니었습니다.

한국어가 상대적으로 훨씬 자연스럽게 들렸습니다
WSL + GPU 없는 환경에서도 현실적인 선택지였습니다
텔레그램 음성메시지 용도로 붙였을 때 거슬림이 적었습니다

무엇보다 중요했던 건, 처음으로 “아, 이건 계속 써도 되겠다”는 느낌이 들었다는 점입니다. EdgeTTS는 편했고, 시작점으로도 좋았습니다. Kokoro는 기대를 안고 갔지만 실제 한국어 청감에서는 아쉬움이 컸습니다. 반면 Supertonic-2는 적어도 제가 원하는 사용처에서는 가장 균형이 좋았습니다.

그리고 지금 기준으로는 이 조합에 매우 만족하고 있습니다. 처음에는 단순히 TTS 하나를 붙이는 작업이라고 생각했는데, 막상 해보니 “어떤 모델이 실제 내 환경에서 가장 덜 어색한가”를 찾는 과정에 가까웠습니다. 그 기준에서 현재까지는 Supertonic-2가 가장 납득 가능한 답이었습니다.

이번 비교를 한 줄로 정리하면

EdgeTTS: 빠르게 시작하기 좋았고 실제로도 만족스러웠습니다
Kokoro: 기대는 컸지만, 제 기준의 한국어 TTS로는 외국어처럼 들렸습니다
Supertonic-2: 여러 데모를 비교해 본 끝에 가장 만족스럽게 정착한 선택지였습니다

이번 구축에서 얻은 결론

이번에 가장 크게 느낀 건, 한국어 TTS는 모델 평판보다 실제 청감이 훨씬 중요하다는 점입니다. “좋다고 들었다”는 말만 믿고 가기엔 실제 결과 차이가 꽤 컸습니다. 특히 한국어는 어색하면 바로 티가 납니다.

결국 이번 선택은 이렇게 정리할 수 있습니다.

빠르게 시작한 것은 EdgeTTS였습니다
더 나은 결과를 기대하고 Kokoro까지 갔습니다
하지만 실제 한국어 청감에서는 실망한 부분이 있었습니다
그 뒤 여러 데모를 더 비교해 본 끝에 Supertonic-2로 정착했습니다

지금 기준에서 제 결론은 명확합니다. WSL에서, GPU 없이, 한국어 음성메시지를 꾸준히 만들려면 결국 “제 귀에 가장 덜 어색한 모델”이 정답이었습니다. 그리고 현재 제 기준에서 그 답은 Supertonic-2입니다.

이제 여기에 더해서 합성된 음성을 따로 플레이버튼 누르지 않아도, 필요할때 "띵동" 하고 말해주는 시스템을 구축해볼 생각입니다.

긴글 읽어주셔서 감사합니다.

Zlack: Slack을 더 가볍게 쓰기 위한 Tauri 데스크톱 클라이언트

상구너 — Wed, 15 Apr 2026 17:11:37 +0900

소개

Zlack은 Slack을 조금 더 가볍고 안정적으로 쓰기 위해 만든 Tauri 기반 데스크톱 클라이언트입니다. Windows와 macOS에서 모두 사용할 수 있도록 만들었고, Slack 웹을 바탕으로 알림과 멀티 워크스페이스 사용 흐름을 최대한 자연스럽게 유지하는 데 집중했습니다.

윈도우 설치 앱 기준으로 비교했을 때 Slack은 약 1.24GB, Zlack은 6.49MB 정도로 차이가 났습니다. 물론 단순한 숫자만으로 모든 사용성을 설명할 수는 없지만, 처음부터 체감되는 가벼움은 꽤 분명했습니다.

직접 보실 수 있는 링크도 함께 남겨둡니다.

Zlack: Tauri로 만든 경량 데스크톱 Slack 클라이언트 | GeekNews

Zlack은 Slack 웹을 기반으로 하면서, Electron 대신 Tauri로 구현한 경량 데스크톱 Slack 클라이언트입니다.웹 Slack의 사용성은 그대로 유지하면서도, 데스크톱 환경에서 필요한 네이티브 알림과 안정적

news.hada.io

GitHub - sanguneo/zlack: A lightweight, optimized desktop wrapper for Slack, built with Tauri.

A lightweight, optimized desktop wrapper for Slack, built with Tauri. - sanguneo/zlack

github.com

이 글은 Zlack을 소개하는 글이기도 하지만, 왜 이런 형태로 다시 만들었는지까지 같이 정리해보는 글입니다.

개발기

Zlack은 Electron 대신 Tauri를 선택하면서 시작했습니다. 이유는 단순했습니다. Slack을 전체 Chromium 번들로 다시 감싸기보다, 필요한 부분만 더 가볍게 가져가고 싶었기 때문입니다. 그 덕분에 메모리와 설치 용량에서 확실한 차이를 낼 수 있었습니다.

기술적으로는 Slack 웹 클라이언트를 그대로 활용하되, preload.js와 Rust 백엔드를 연결해 데스크톱 앱으로서 필요한 부분만 보강하는 방식으로 구성했습니다. 알림, 딥링크, 윈도우 포커스 복원 같은 부분이 핵심이었습니다.

특히 Windows에서는 알림 클릭 후 창이 잘 복원되지 않는 문제가 꽤 까다로웠습니다. 그래서 Rust 쪽에서 시스템 트레이 복원과 포커스 전환을 안정적으로 처리했고, Slack의 네트워크 트래픽에서 Team ID와 Channel ID를 잡아내서 알림이 정확한 곳으로 이동하도록 했습니다.

구조를 조금 더 풀어보면 다음과 같습니다.

Slack 웹 클라이언트 + preload.js 브리지
/traces/v1/list_of_spans 트래픽에서 알림 맥락 추출
Rust 백엔드에서 Windows 토스트 알림 처리
최소한의 웹뷰 구조로 멀티 워크스페이스 지원
작은 설치 용량과 빠른 초기 실행

이 프로젝트는 아직도 실사용 피드백을 받으면서 계속 다듬어가는 중입니다. 처음 목표는 분명했지만, 실제 사용 환경에서 생기는 자잘한 문제까지 잡아가야 완성도가 올라간다고 생각했습니다.

인한사전 InKrKamus v3 소개 + 개발기

상구너 — Wed, 15 Apr 2026 16:21:26 +0900

소개

인한사전(InKrKamus) v3는 인도네시아어-한국어 사전을 브라우저에서 빠르고 가볍게 사용하실 수 있도록 다시 정리해 만든 버전입니다. 모바일과 PC에서 모두 부담 없이 검색하실 수 있게 만들었고, 오프라인 캐시까지 함께 챙겨서 재방문도 더 빠르게 보실 수 있게 구성했습니다.

직접 사용해보실 분은 아래 주소로 들어가시면 됩니다.

https://inkrkamus.sanguneo.com/

인한사전 InKrKamus v3

인도네시아어-한국어 사전 InKrKamus. 빠른 검색, 모바일/PC 반응형, 오프라인 캐시를 지원합니다.

inkrkamus.sanguneo.com

이 글은 단순한 기능 소개를 넘어서, 제가 이 프로젝트를 어떻게 다시 정리했는지도 함께 적어보는 글입니다.

개발기

InKrKamus의 시작은 꽤 오래전입니다. v1은 2010년에 만들었던 윈도우용 아주 작고 가벼운 프로그램이었습니다. 다만 메모리 최적화 같은 부분이 전혀 되어 있지 않아서, 겉보기에는 가벼워 보여도 실제로는 결코 가볍지만은 않은 프로그램이었습니다. 로고와 디자인도 당시에는 하나하나 직접 손으로 다듬었습니다.

이후 2016년에 만든 v2는 두 가지 버전으로 운영되었습니다. 하나는 Electron 기반 데스크탑 앱이었고, 다른 하나는 Heroku 환경의 Express로 운영하던 웹앱이었습니다. 두 버전은 섞여 있지 않았고, 각각 별도의 형태로 존재했습니다.

당시의 v2는 나름의 역할을 잘 해냈지만, 지금 기준으로 보면 오래된 스택이 되었습니다. 데스크탑 쪽은 Electron, 웹 쪽은 Heroku + Express, 프론트는 Vue1 기반이었기 때문에 유지보수와 확장성 측면에서 한계가 분명했습니다. 그래서 v3에서는 이 구조를 그대로 끌고 가기보다, 새로 설계하는 방향을 택했습니다.

개발 레포는 아래에서 보실 수 있습니다.

https://github.com/sanguneo/inkrkamus

GitHub - sanguneo/inkrkamus

Contribute to sanguneo/inkrkamus development by creating an account on GitHub.

github.com

이번 버전은 React + Vite + TypeScript + IndexedDB 조합으로 다시 만들었습니다. Electron 의존성을 덜고, 정적 호스팅에 맞는 구조로 바꾸었으며, 로컬 IndexedDB를 먼저 읽어 즉시 화면을 띄운 뒤 뒤에서 최신 데이터를 갱신하는 방식으로 정리했습니다.

첫 화면은 로컬 데이터로 빠르게 띄우기
재방문은 IndexedDB 캐시로 더 빠르게 처리하기
원격 데이터 갱신은 백그라운드에서 조용히 반영하기
검색과 리스트는 캐시, 정규화, 가상 스크롤로 가볍게 유지하기

관련 흐름은 이전 글에서도 이어서 보실 수 있습니다.

v1 소개: https://blog.sanguneo.com/35
v2 소개: https://blog.sanguneo.com/38

결국 이번 v3는 이전 버전을 단순히 보강한 것이 아니라, 오래된 구조를 정리하고 다시 출발하는 작업이었습니다. 예전 버전들이 없었다면 지금의 v3도 없었을 것이고, 그런 의미에서 이 프로젝트는 계속 이어져 온 제 작업 기록이라고 생각합니다.

사설

이 프로젝트는 제가 무엇을 위해 개발을 하는지를 한번씩 생각하게 해주는듯 합니다. 지금은 대기업에서 워낙 사전을 잘 만들어놓았고, AI한테 물어보면 인도네시아 어 뿐아니라 자바어도, 수마트라어도, 아주 깔끔하게 잘 나오더라구요. 저부터도 생각안나는 단어 있으면 inkrkamus보다 ai한테 물어보니까요.

그럼에도 저는 계속 이 프로젝트를 유지하려고 합니다. 앞으로 새로운 뭔가가 나오거나 하면 계속 또 뚝딱뚝딱 만지겠죠, 그리고 내가 왜 개발을 하는지 다시한번 상기할거같습니다. 앞으로도 많은 관심 부탁드립니다 :)

OpenClaw 에이전트로 민방위 인터넷 교육 이수

상구너 — Wed, 15 Apr 2026 15:39:04 +0900

OpenClaw 에이전트를 실제 브라우저 작업에 연결해 처음 제대로 검증해본 사례가 있었다. 테스트 페이지 수준이 아니라, 실제로 수행해야 하는 작업에 에이전트를 붙여본 것이다. 이번 대상은 민방위 인터넷 교육 이수였다.

이 작업은 단순 클릭 자동화가 아니라, 브라우저 세션 상태 유지, 화면 전환, 진행 상황 확인이 모두 필요한 흐름이었다. 즉, 에이전트가 "작동한다"는 것과 "실제 작업에 쓸 수 있다"는 것은 다르다는 걸 확인하기에 적절한 사례였다.

WSL2 환경과 브라우저 연결 문제

작업 환경은 WSL2였다. 문제는 WSL2가 윈도우 호스트와 분리된 실행 환경이라는 점이다. 이 때문에 에이전트가 로컬 브라우저 인스턴스에 바로 연결되기 어렵고, 별도의 브리지 구성이 필요했다. WSL내부에서도 동일하게 크롬을 깔고 실행할 수 있지만 굳이 추가로 설치하고싶지도 않았다.

여기서 사용한 방식은 PowerShell 기반 포트포워딩과 CDP(Chrome DevTools Protocol) 연결이다. 즉, 윈도우에서 실행 중인 브라우저 디버그 포트를 WSL2 쪽에서 접근 가능하도록 열어두고, 에이전트가 그 세션에 붙도록 만든 것이다.

headful 브라우저 기반 검증

민방위 인터넷 교육은 완전 비가시성 자동화로 끝낼 수 있는 작업이 아니었다. 직접 콘텐츠를 확인해야 하고, 진행 상태도 사람이 봐야 했기 때문에 headless 로는 진행하지 않았다.

headful 모드의 장점은 명확하다. 에이전트가 어떤 URL에 있는지, 어떤 요소를 조작하는지, 다음 단계로 정상적으로 전환됐는지를 화면에서 바로 확인할 수 있다. 이번 작업에서는 이 가시성이 매우 중요했다.

실제로는 브라우저를 띄워둔 상태에서 에이전트의 동작을 지켜보는 방식으로 진행했다. 백그라운드에서 무작정 돌리는 형태가 아니라, 중간중간 UI 상태와 흐름을 확인하면서 수행했다. + 교육을 듣기는 해야하니까.

성능과 반응성

체감상 가장 아쉬웠던 부분은 반응 속도였다. 윈도우-WSL2 환경 특성상 응답이 다소 느렸고, 아직 브라우저 자동화 작업에 대해 최적화가 충분히 이루어지지 않아 불필요한 대기 시간이 꽤 발생했다.

이건 단순 성능 문제라기보다 작업 파이프라인의 마찰에 가까웠다. 에이전트가 명령을 받아도 즉시 다음 단계로 이어지지 않는 구간들이 있었고, 그만큼 전체 체감 속도가 떨어졌다.

다만 이 과정 덕분에 병목이 어디서 생기는지는 명확히 보였다. 브라우저 연결 자체보다는 환경 지연, 세션 전환, 동기화 타이밍이 중요한 포인트였다.

확인한 점

WSL2 환경에서는 브라우저 자동화 연결을 별도로 설계해야 한다
PowerShell 포트포워딩 + CDP 연결이 실사용에 유효하다
headful 모드에서 상태 확인이 필요한 작업은 에이전트 검증에 적합하다

결론적으로, 에이전트는 실제 브라우저 기반 업무에 붙일 수 있는 가능성을 보여줬다. 다만 완성도는 환경 최적화와 연결 구조 정리에 크게 좌우된다.

다음 계획

현재 진행 중인 제주도 여행 계획 짜기에도 같은 흐름을 적용해볼 생각이다. 여행 계획은 여러 웹 페이지를 오가며 정보를 수집하고 비교해야 해서, 브라우저 기반 에이전트의 활용도를 확인하기 좋은 작업이다.

이번 민방위 교육이 "연결과 검증"의 첫 실전이었다면, 제주도 여행 계획은 "실사용성"을 보는 다음 단계가 될 것이다.

OpenClaw 에서 Hermes 로 옮겨오기까지

상구너 — Tue, 14 Apr 2026 15:38:04 +0900

다들 에이전트 얘기하길래, 나도 못 버티고 깔아봤다

솔직히 말하면 시작은 별로 우아하지 않았다. 주변에서 다들 에이전트, 에이전트 하니까 괜히 위기감이 들었다. "이거 또 나만 늦는 거 아닌가" 싶은 그 감정. 예전 같았으면 보안 때문에 더 쫄았을 텐데, 요즘은 그래도 예전보단 낫다는 얘기도 많았고, 내가 그냥 좀 무뎌진 건지도 모르겠다. 어쨌든 예전처럼 겁부터 먹고 안 건드리진 않았다.

그래서 그냥 깔았다. 남들 후기 열 개 읽는 것보다, 내 손으로 한 번 설치해보고 굴려보는 게 훨씬 빨랐다. 이 글은 그렇게 OpenClaw 를 먼저 써보고, 결국 Hermes로 옮겨오게 된 얘기다.

써보니까, 이건 프롬프트 몇 줄 치는 도구가 아니었다

에이전트를 실제로 써보면서 제일 먼저 든 생각은 명확했다. 이건 그냥 ChatGPT 나 Gemini 에 프롬프트 넣는 경험이 아니다. 물론 겉으로 보면 비슷해 보일 수 있다. 하지만 막상 써보면 질문하고 끝나는 게 아니라, 내가 하려는 일을 따라오고, 중간에 이어받고, 어느 정도는 대신 굴러가는 느낌이 있다.

조금 웃기게 표현하면 나를 0.25 정도 복제해둔 느낌이다. 완전히 대체하는 건 아닌데, 내가 평소 하던 판단과 흐름 일부를 떼다가 옆에 붙여둔 감각이 있다. 그래서 이것저것 막 던져도 된다. 오히려 그런 점 때문에, 일반 챗봇을 프롬프트로 다루는 것과는 결이 꽤 다르게 느껴졌다.

왜 시작은 OpenClaw 였냐면

이유는 단순하다. 생태계가 제일 커 보였다. 직접 깔아보려는 입장에서는 이게 진짜 크다. 자료가 많고, 검색하면 뭔가 나오고, 누가 먼저 부딪혀본 흔적이 있다. 처음엔 내가 뭘 모르는지도 잘 모르는데, 그럴수록 참고할 게 많은 쪽이 확실히 편하다.

그 점에서 OpenClaw는 시작점으로 괜찮았다. 적어도 혼자 삽질하다가 완전히 길을 잃는 느낌은 덜했다.

근데 써보면 바로 느껴진다. 좀 무겁다

OpenClaw를 쓰면서 좋았던 점은 명확했다. 참고할 게 많다. 생태계가 크니까 자료 찾기가 쉽다. 처음 굴려보는 입장에서는 이게 은근히 큰 장점이다.

반대로 아쉬운 점도 엄청 명확했다. 무겁다. ZeroClaw 나 GoClaw 보다는 빨랐지만, 그래도 전체적으로 묵직하다는 느낌이 계속 있었다. 내가 아직 구조를 덜 알아서 그런 걸 수도 있다. 그런데 사용자 입장에선 그건 별로 중요하지 않다. 그냥 느리게 느껴지면 느린 거다.

특히 툴을 사용할 때 체감상 더 느리다고 느꼈다. 에이전트는 어차피 한두 번 신기해서 눌러보는 장난감이 아니라, 계속 붙여서 쓰는 도구다. 그러면 결국 중요한 건 정답률만이 아니라 템포다. 내 리듬이랑 안 맞으면 손이 멀어진다.

Hermes로 옮긴 이유는 의외로 단순했다

아직 Hermes를 엄청 깊게 안다고 하긴 어렵다. 그런데도 넘어온 이유는 있었다.

일단 이름이 맘에들었다.
스킬을 능동적으로 만들고 활용하는 흐름이 꽤 마음에 들었다.
내 작업 방식을 점점 누적해갈 수 있다는 점이 좋았다.
무엇보다 마이그레이션이 엄청 쉬웠다.

특히 마지막이 생각보다 컸다. 보통 이런 전환은 귀찮고, 중간에 끊기고, 한 번 미루면 다시 손대기 싫어진다. 그런데 이번엔 생각보다 너무 매끄러웠다. 그래서 "일단 옮겨서 써보자"가 가능했다.

지금 기준에선 Hermes 쪽이 더 내 스타일이다

Hermes에서 지금 가장 좋게 보는 건 역시 스킬이다. 그냥 그때그때 답 잘하는 모델이라기보다, 내가 반복해서 원하는 흐름을 쌓고 다시 꺼내 쓰는 구조가 보였다. 이건 꽤 다르다.

결국 오래 쓰게 되는 도구는 순간적으로 똑똑한 도구가 아니라, 내 방식을 축적할 수 있는 도구다. 그런 면에서 Hermes는 지금 기준에선 더 운영에 가깝고, 그래서 더 마음에 든다.

그리고 지금 시점에서 딱히 큰 아쉬움은 없다. 더 오래 쓰면 보일 문제는 있겠지만, 적어도 전환 직후의 첫인상은 꽤 좋다.

직접 깔아볼 사람한테 굳이 한마디 하자면

이 글은 누가 더 우월한지 판정하는 리뷰는 아니다. 오히려 직접 설치해서 굴려볼 사람 입장에서 쓴 기록에 가깝다. 그래서 내 기준도 단순하다. 참고할 게 많은가, 무겁지 않은가, 작업 리듬이 맞는가, 내 방식이 쌓이는가.

그 기준으로 보면 OpenClaw는 확실히 시작점으로 의미가 있었다. 반면 Hermes 는 그 다음 단계로 넘어가 보기 좋은 선택지였다. 결국 이런 건 남이 좋다 나쁘다 해봐야 별 의미 없다. 직접 깔아보고, 내 손에 맞는지 보는 게 제일 빠르다.

결론: 둘 다 써봤고, 지금은 Hermes 가 더 잘 맞는다

지금의 내 결론은 이거다. 둘 다 써봤지만 현재는 Hermes 가 더 잘 맞는다.

OpenClaw 는 생태계가 커서 시작하기 좋았고, 직접 써보면서 에이전트를 어떤 식으로 봐야 하는지 감을 잡게 해 줬다. 대신 내 사용 리듬에서는 조금 무겁고, 툴 사용할 때 체감 속도도 아쉬웠다.

반면 Hermes는 지금 내 기준에서 더 가볍게 붙고, 스킬을 쌓아가면서 내 방식으로 운영하기 좋았다. 그래서 적어도 현재 시점의 나는, Hermes 쪽에 조금 더 마음이 간다.

그외

오래전부터 헤르메스라는 이름을 좋아했다.
전에 재밌게 봤던 일본 만화에서 "헤르메스의 새" 라는 용어가 등장하고, "신들의 전령" 이라는 역할이나
유명한 명품브랜드(없음, 갖고싶음)
아무튼 헤르메스, 아직 알아가는 중이지만 괜찮은것같다. 모델만 잘 쓰면 더 좋을거같다.

상구너의 개발노트

한글(.hwp) 파일을 브라우저에서 바로 PDF 로 — rhwptopdf 만든 이야기

왜 만들었나

출발점 — rhwp

어떻게 동작하는가 — 5 단계 파이프라인

1) SvgRenderer — HWP → SVG

2) font-family 정규화

3) usvg text-to-path

4) svg2pdf → 5) pdf-writer

가장 오래 걸린 챕터 — 폰트

시행착오 모음

데모 페이지

사용법 — CDN 한 줄

한계 / 솔직한 단점

라이선스 — rhwp 에 대한 감사

마무리

Supertonic TTS 커스텀 프록시에서 공식 serve로 갈아탄 썰

원래 구조

한계

공식 serve 등장

그래서 바꾼 구조

뭐가 좋아졌나

근데 왜 굳이

Supertonic 3 업그레이드 후기 — 온디바이스 TTS 프록시를 v2에서 v3로 올리며

들어가며

v2 → v3, 뭐가 달라졌나?

가장 체감되는 변화

업그레이드 과정

1. 모델 다운로드

2. 프록시 코드 수정

3. 엔드포인트 및 기본값 업데이트

4. Hermes Config 업데이트

5. 서비스 재시작

테스트

알게 된 점 / 팁

결론

Smart Drop Point 개발기 - 하차 지점을 추천하는 모바일 웹앱 만들기

사용한 기술 스택

문제를 좁게 잡기

기존 지도 앱과 다른 계산

추천 엔진을 파이프라인으로 나누기

좌표를 먼저 믿기

URL을 상태 저장소처럼 쓰기

어댑터로 외부 의존성 분리

실제 API와 mock을 같은 인터페이스로 맞추기

모바일이 먼저인 UI

결과 UI는 “설명”보다 “비교”에 가깝게

결과 페이지는 공유 가능해야 한다

성능과 호출 수 줄이기

후보를 줄이는 방식

개인정보는 최소로

지금 상태와 다음 단계

정리

같이 탄 차에서 어디서 내릴지 정해주는 앱

어디서 내리면 좋을까?

입력은 세 가지만

결과는 후보 카드로 비교

기존 지도 앱과 다른 점

감 대신 숫자로 말하기

모바일 웹앱으로 만든 이유

이런 상황에 잘 맞습니다

정리

서비스는 여기

사내 그룹웨어 Daou GW 자동화: 브라우저 대신 CLI와 MCP로 연결하기

처음 목표는 간단했습니다

Go 코드에서 TypeScript CLI로

개발은 브라우저에서 시작했습니다

스킬에는 “어떻게 행동해야 하는지”를 적었다

CLI와 MCP는 같은 의미를 갖게 했다

실제로 신경 쓴 부분: 세션과 실패 처리

세션과 민감 정보는 로컬에만

만들고 나니 좋은 점

정리

종합소득세 신고 방법: 직장인 개발자의 홈택스 신고가이드 (feat. 크몽)

1. 홈택스에서 종합소득세 신고로 들어갑니다

2. 기본정보 입력에서 내 정보를 불러옵니다

3. 종합소득금액에서 사업소득을 추가합니다

4. 비어 있는 사업소득 명세를 새로 작성합니다

5. 사업장명세에서 사업자등록번호 없음으로 입력합니다

6. 사업장을 추가한 뒤 업종별 총 수입금액을 입력합니다

출발점 — `rhwp`

라이선스 — `rhwp` 에 대한 감사