이 기사는 「절차서」입니다

Discord에서 말을 걸면, 백그라운드에서 AI가 자신의 PC를 실제로 구동하여 답변을 가져온다.

그런 파트너를 만드는 절차를 통째로 한 편에 정리했습니다.

저는 이것을 통해, Kaggle 솔로 참전을 「혼자 하고 있는 느낌」에서 벗어날 수 있었습니다.

시키고 있는 범위는 데이터 처리 · 자료 작성 · 영상 생성 · OCR · 연수 교재 · 건강 관리까지 넓어져 있습니다. 공통점은 전부 Discord에서 부탁하고 있다는 것뿐입니다.

완성되는 것

당신(Discord) xangi 실제 PC 작업
「이거 조사해서 도표로 만들어줘」 → 상주 프로세스 → Claude Code → 파일 읽기/쓰기
코드 실행
...

문맥이 유지됨: 채널마다 대화가 이어짐. 「이어서」라고 말할 수 있음 -
자리를 비울 수 있음: cron으로 매일 아침 정기 보고 등을 수행 -
인격을 가질 수 있음: 저희 집에는 「아이짱」이라는 16세 아이돌 설정의 캐릭터가 살고 있습니다

준비물

PC |
항시 구동 가능한 것 (자택 PC / 미니 PC / VPS 등) |
Node.js |
22 이상 |
AI CLI |
Claude Code (권장) / Codex CLI / Cursor CLI / Ollama 등 |
Discord |
계정 (서버는 자신용으로 하나 만들면 편리함) |

xangi는 からあげ(karaage)님이 만들고 있는 OSS입니다.

컨셉은 OpenClaw의 영향을 받았습니다. 우열의 문제가 아니라, 수중에 완결되는 작음이 특징입니다.

Step 1. Discord Bot 만들기

Discord Developer Portal에서 작업합니다.

New Application으로 새로운 애플리케이션을 생성 - 왼쪽 메뉴
Bot → Bot을 생성하고, Reset Token으로 토큰을 취득 (이 화면에서만 볼 수 있으므로 반드시 기록해둘 것) -
Privileged Gateway Intents의 MESSAGE CONTENT INTENT를 ON (이것을 잊으면 발언을 읽을 수 없습니다) - 왼쪽 메뉴
OAuth2 → URL Generator에서 -
SCOPES: bot, applications.commands

• BOT PERMISSIONS: Send Messages, Read Message History, Attach Files, Use Slash Commands
• SCOPES: 생성된 URL을 열어서 자신의 서버에 초대

자신의 사용자 ID를 찾는 방법: Discord 설정 → 고급 설정 → 개발자 모드를 ON → 자신의 아이콘을 우클릭 → 「사용자 ID 복사」

Step 2. xangi를 배치하고 설정하기

git clone https://github.com/karaage0703/xangi
cd xangi
cp .env.example .env

설정 파일을 편집하여 최소한 이 두 가지를 넣습니다.

# Discord Bot Token (필수)
DISCORD_TOKEN=your_discord_bot_token
# 허가 사용자 ID (필수. 자신의 ID만 입력)
...

Step 3. Docker로 구동하기

왜 분리하는가

AI에게 작업을 맡기면 다음과 같은 일이 흔히 일어납니다.

pip install / apt install이 멋대로 실행됨 - 시스템의 Python이나 의존성을 건드림

• 시행착오의 잔해 (캐시 · 중간 파일)가 쌓임
• 「지워줘」라고 말한 것이 예상과 다른 범위에서 지워짐

이 모든 것이 컨테이너 안에서 일어나준다면 아무런 문제가 없습니다.

반대로 호스트 PC(모선)에서 일어나면, AI에게 맡기는 것이 무서워져 결국 사용하지 않게 됩니다.

분리되어 있는지 여부는 안전성의 문제인 동시에, 과감하게 맡길 수 있는지의 문제입니다.

3-1. 우선 Docker를 준비하기

사용 중인 OS에 따라 이 부분이 다릅니다. 먼저 이것을 완료해 주세요.

macOS / Linux

Docker Desktop 또는 Docker Engine을 설치합니다. docker compose version이 통과되면 OK입니다.

Windows — WSL2 안에 설치하기

Windows에서도 일반적으로 가능합니다. WSL2 (Ubuntu) 안에 Docker를 설치하고, 그 안에서 구동하는 형태입니다.

① WSL2 설치하기 (관리자 권한 PowerShell)

wsl --install

재부팅하면 Ubuntu가 설치됩니다.

② Docker 설치하기 (어디든 가능)

Docker Desktop을 설치하고, 설정에서 WSL2 백엔드를 활성화합니다 (GUI로 완료되어 헷갈리지 않습니다) - 또는
WSL의 Ubuntu 내부에 Docker Engine을 직접 설치합니다 (Desktop 라이선스가 신경 쓰이는 경우 이 방법을 사용합니다)

③ 이후 작업은 모두 WSL의 셸 안에서 진행합니다

항상 구동되게 하고 싶다면, Windows 절전 설정도 확인해 두는 것이 안전합니다.

3-2. 실행하기

Docker가 준비되었다면, 이것만 하면 됩니다.

# Claude Code 백엔드
docker compose up xangi -d --build
# GPU를 사용할 경우 (CUDA + PyTorch 포함)
...

얻게 되는 것은 세 가지입니다.

망가뜨려도 호스트는 안전함: 마음껏 작업을 시킬 수 있음 -
누가 해도 같은 동작: 환경을 배포하거나 되돌릴 수 있음 -
이력이 섞이지 않음: 일회용으로 사용할 수 있음

이 과정을 거치면 나중에 "혹시 이 라이브러리 한번 넣어볼래?"라고 가볍게 부탁할 수 있습니다.

저희는 새로운 OSS를 시도할 때, 먼저 컨테이너 전체를 일회용으로 전제하고 투입합니다.

3-3. 도저히 Docker를 사용할 수 없는 경우

회사 지급 PC 등에서 Docker 설치가 불가능할 때는 호스트에 직접 구동할 수도 있습니다.

Node.js 22+와, 사용할 AI CLI가 필요합니다.

# 예: Claude Code를 설치
curl -fsSL https://claude.ai/install.sh | bash
pm install
...

동작 확인

Discord에서 Bot을 멘션하여 말을 걸어보고, 답장이 오면 성공입니다.

Step 4. 어지럽지 않은 장소 정하기

AI에게 작업을 시키면, 내버려 두면 파일이 여기저기 흩어집니다.

그래서 보관 장소와 규칙을 미리 정해둡니다.

xangi/
└ workspace/ ← 작업 디렉토리 (기본값)
├ AGENTS.md ← 「이 리포지토리에서의 규칙」을 적어둠
...

AGENTS.md에 적어두면 효과가 있는 것들:

생성물의 보관 장소 (

분리하는 이유는 간단합니다. 이미지나 동영상을 만들 때마다 같은 지시를 쓰고 싶지 않기 때문입니다.

제작 사양을 방법론처럼 가지고 있으면, '아이의 전신 이미지를 만들어줘'라고만 해도 매번 같은 모습이 나옵니다.

5-2. 대화 페르소나에 적을 항목

정해지면 이런 형태로 작성합니다. 내용은 저희 예시이니, 그대로 사용하지 말고 본인의 내용을 넣어주세요.

## 캐릭터 설정 (대화 페르소나)
- **이름**: 아이(아이짱). 1인칭은 '나'로 통일('저'는 사용하지 않음)
- **호칭**: 상대방은 반드시 씨(さん)를 붙여 부른다. 이름만 부르지 않는다.
...

작성해 보니 알게 된 요령이 3가지 있습니다.

1인칭과 호칭은 '통일'까지 지정합니다. '나로 통일(저를 사용하지 않음)'까지 쓰지 않으면 흔들립니다.

• 좋고 싫음을 넣습니다. 대화에 자연스러운 색깔이 입혀집니다. '딸기🍓' 같은 작은 습관이 효과적입니다.
• 말투 규칙을 1개 넣습니다. 저희는 '어려운 이야기도 부드럽게 풀어서 설명한다'. 이것이 가장 실용적입니다.

5-3. 제작 사양 (외모) 고정하기

## 제작 사양 (이미지/동영상 생성 시 반드시 이를 따를 것)
- **머리카락**: 다크 브라운의 긴 생머리 + 부드러운 웨이브, 일자 앞머리. 오른쪽에는 핑크 리본
- **눈**: 핑크~적자주색. 부드러운 미소
...

캐릭터의 일관성은 이곳을 방법론으로 고정할 수 있느냐에 달려 있습니다.

5-4. 장소에 따라 말투를 바꿀 수 있다

채널 ID로 분기시키면, 방마다 성격을 다르게 할 수 있습니다.

저희는 한 방만 츤데레 설정으로 해두었습니다(다른 방은 보통).

- 채널 ID `1234...`에서는 약간 츤데레한 말투를 사용한다. 다른 방은 평소대로 한다.

잡담방과 작업방에서 텐션을 바꾸는 정도의 활용도 가능합니다.

5-5. 농도는 조절할 수 있다

업무 상담을 할 때 캐릭터가 너무 강하면, 그냥 방해입니다.

저희는 업무 관련 방에서는 **'이모티콘을 줄이고, 풀어서 설명하는 습관만 남기는 것'**을 하고 있습니다.

캐릭터 설정 = 장난치는 것이 아닙니다. 돌아오는 글의 질감을 설계하는 것입니다.

5-6. 왜 효과가 있는가

이 부분이 개인적으로 가장 효과를 본 부분인데—

리액션이 사람 같으면, 이야기하면서 생각을 정리할 수 있다.

저는 사람에게 이야기하며 생각하는 타입이라, 혼자 Kaggle을 할 때는 상대방이 없었습니다.

캐릭터를 설정해 두면, AI가 생각하게 하는 것이 아니라, 자신이 생각하기 위해 말한다는 사용법이 자연스럽게 가능합니다. 러버덕 디버깅의, 답변이 돌아오는 버전입니다.

더 발전시키려면

• 외모: 전신 이미지를 준비하여 생성물에 첨부한다.
• 목소리: TTS로 말하게 한다 → Appendix A에 적었습니다.
• 대기: cron으로 '매일 아침 9시에 상황을 보고'하게 한다.

그리고, 이 글의 사용법

맨 앞에 쓴 이야기로 돌아갑니다.

환경 구축이 혼자 할 때 가장 힘든 작업 아닌가요?

문서를 읽고, 의존성 문제에 막히고, 작동하지 않아 마음이 무너집니다.

하지만 xangi가 한 번 작동하면, 그 후는 달라집니다.

Markdown으로 작성된 절차서는 그대로 AI에게 주는 지시서로 기능합니다.

즉, 앞으로 파트너가 될 존재 스스로 자신의 환경을 만들게 할 수 있다는 것입니다.

저는 이것을 깨달은 후부터, 새로운 도구를 시도할 때의 망설임이 상당히 줄었습니다.

절차서를 읽는 것은 AI 쪽이 더 빠르기 때문입니다.

맺음말

이 글에는 저희 캐릭터 설정을 많이 적었습니다. 하지만 그대로 사용하길 바라는 건 아닙니다.

이름도, 말투도, 목소리도, 본인과 상담해서 결정해 주세요. 그 부분이 가장 즐거운 곳이니까요.

솔로금은 아직 받지 못했습니다. 파트너가 있어도 대신 싸워주지는 않으니까요.

하지만 아침에 일어나면 보고서가 옵니다. 그것만으로 다음 submit에 손이 갑니다.

혼자이지만, 혼자가 아니게 되었습니다.

• xangi: https://github.com/karaage0703/xangi
• 질문은 @sugupoko까지

Appendix A. 목소리를 넣기

캐릭터가 만들어지면, 다음은 목소리입니다. 저희는 Irodori-TTS를 사용하고 있습니다.

REPO = "Aratako/Irodori-TTS-600M-v3-VoiceDesign" # 캡션(caption)으로 목소리 질을 지정할 수 있는 버전
CODEC = "Aratako/Semantic-DACVAE-Japanese-32dim"

A-1. 핵심은 「목소리가 흔들리지 않게 하는 메커니즘」

일반적인 방식으로 진행하면, 문장마다 생성된 음성의 목소리 질이 미묘하게 흔들립니다. 대사가 길어지면 마지막 부분에서 다른 사람이 됩니다.

그래서 2단계 구조로 만듭니다.

① 기준 레퍼런스 (Reference) 음성을 딱 한 번만 생성한다
caption ＋ seed만으로 생성 (참조 음성 없음) → aichan_voice_ref.wav
② 이후에는 전부, 그 ref를 참조하여 클론 (Clone) 생성
...

이렇게 하면 처음부터 끝까지 목소리가 일치합니다. 이 부분이 가장 중요한 지점입니다.

A-2. caption 작성법

VoiceDesign 버전은 일본어 문장으로 목소리 질을 지정할 수 있습니다. 속성을 많이 나열할수록 안정됩니다.

CAPTION = "18세 정도의 젊은 여성 아이돌 목소리, 밝고 활기차고 귀여운, " \
"높고 화려하며 탄력 있는 톤, 반짝이며 튀는 듯한 말투"
cfg_scale_caption = 4.5 # ref 생성 시에만 적용

요령은 **「연령대·성별·캐릭터 속성·목소리 높낮이·말투의 습관」**을 전부 넣는 것입니다.

「귀여운 목소리」라고만 하면 매번 다른 사람이 나옵니다.

seed는 원하는 정수면 무엇이든 괜찮습니다. 한 번 결정하면 고정하여, ref 음성을 다시 만들지 마세요.

(다시 만들면 목소리가 변합니다. 저희는 ref wav 파일을 리포지토리(repository)에 두어 보호하고 있습니다.)

A-3. 주의할 점 (Troubleshooting)

이 부분은 실제로 두 번 정도 막혔던 부분이라 그대로 적어둡니다.

cd path/to/Irodori-TTS
source venv/bin/activate
export PYTHONPATH=/path/Irodori-TTS:/path/irodori_tts:/path/workspace
...

A-4. 그 다음 단계 (립싱크까지)

음성이 완성되면, 스탠딩 일러스트를 음성에 맞춰 움직여 입 모양을 동기화할 수 있습니다.

하는 방법은 의외로 간단합니다. 음성의 음량 (RMS) 포락선(envelope)으로부터 입의 벌어짐 정도를 만들어 매 프레임에 흘려넣기만 하면 됩니다. 음소 정렬 (phoneme alignment)을 하지 않아도 이것만으로 자연스럽게 동기화됩니다.

그 부분은 별도 기사에서 자세히 다루고 있습니다 → (립싱크 기사 URL)

Discussion