RisuToki

RisuAI .charx 파일 전용 에디터 + Claude Code 통합 터미널

설치

다운로드 (일반 사용자)

Releases 페이지에서 최신 버전을 다운로드하세요.

RisuToki Setup x.x.x.exe — 설치형
RisuToki-x.x.x-portable.exe — 포터블 (설치 불필요)

소스에서 실행 (개발자)

git clone https://github.com/komodoD/RisuToki.git
cd RisuToki
npm install
npm start

사용 가이드

시작하기
화면 구성
파일 열기 / 저장
사이드바 (항목 트리)
에디터 (Monaco)
TokiTalk 터미널
Claude Code 연동
아바타 패널
설정
드래그 앤 드롭
참고 자료 (Reference)
팝아웃 (패널 분리)
프리뷰 모드
RP 모드 (토키 말투)
단축키 목록
.charx 파일 구조
문제 해결

1. 시작하기

실행

RisuToki 실행 파일(.exe)을 더블클릭하면 됩니다.

사전 요구사항

Claude Code 연동을 사용하려면 claude CLI가 시스템 PATH에 등록되어 있어야 합니다.
- Claude Code가 설치되어 있지 않아도 에디터 자체 기능(편집, 저장 등)은 정상 작동합니다.

2. 화면 구성

사이드바: .charx 파일의 항목 트리 + 참고자료 탭
에디터: Monaco 기반 코드/텍스트 에디터 (VS Code와 동일한 편집 엔진)
TokiTalk 터미널: 내장 터미널 (bash/powershell + Claude Code 실행)
아바타 패널: 토키/아리스 캐릭터 아바타 표시

레이아웃 변경

보기 메뉴에서 사이드바/터미널 위치를 좌우/상하로 변경 가능
각 패널 사이의 경계선을 드래그하여 크기 조절
사이드바 접기: ◀ 버튼 또는 Ctrl+B
터미널 접기: ━ 버튼 또는 Ctrl+`

3. 파일 열기 / 저장

동작	방법
새로만들기	`Ctrl+N` 또는 파일 → 새로만들기
열기	`Ctrl+O` 또는 파일 → 열기 (.charx 파일 선택)
저장	`Ctrl+S` 또는 파일 → 저장
다른이름저장	`Ctrl+Shift+S` 또는 파일 → 다른이름저장

수정된 탭은 탭 이름 옆에 점(●) 표시가 나타납니다.
창을 닫을 때 저장 확인 다이얼로그가 표시됩니다 (모모톡 스타일 팝업).
자동 저장: 설정에서 활성화하면 일정 간격으로 임시 저장됩니다.

4. 사이드바 (항목 트리)

사이드바는 항목 / 참고자료 두 탭으로 나뉩니다.

항목 탭

.charx 파일을 열면 다음 항목들이 표시됩니다:

기본 항목

항목	설명	편집 언어
Lua	Lua 트리거 스크립트	Lua
글로벌노트	시스템 프롬프트 뒤에 삽입되는 인스트럭션	일반 텍스트
첫 메시지	대화 시작 시 표시되는 첫 번째 메시지	HTML
CSS	RisuAI 채팅 UI에 적용되는 커스텀 스타일	CSS
기본변수	기본 변수 값	일반 텍스트
설명	캐릭터 설명	일반 텍스트

Lua 섹션 시스템

Lua 코드는 -- ===== 섹션명 ===== 구분자로 섹션 분할됩니다.
통합 보기: 전체 Lua 코드를 하나의 탭에서 편집
개별 섹션: 각 섹션을 별도 탭에서 편집
우클릭 메뉴:
- Lua 폴더 우클릭 → 새 하위항목 추가
- 섹션 우클릭 → 이름 변경 / 백업 불러오기 / 삭제

로어북

폴더 구조 지원 (folder 속성으로 그룹핑)
항목 클릭 → 전용 폼 에디터에서 편집 (comment, key, content, mode 등)
우클릭 → 이름 변경 / 백업 불러오기 / 삭제
로어북 폴더 우클릭 → 새 항목 추가 / 새 폴더 추가 / JSON 파일 가져오기

정규식

각 정규식 항목을 전용 폼 에디터에서 편집 (find, replace, type, flag 등)
커스텀 플래그 지원 (기본 닫힘, 비표준 플래그 있을 때 자동 열림)
우클릭 → 이름 변경 / 백업 불러오기 / 삭제
정규식 폴더 우클릭 → 새 항목 추가 / JSON 파일 가져오기

에셋 (이미지)

.charx에 포함된 이미지 파일 목록
클릭 → 이미지 뷰어에서 미리보기 (확대/축소/드래그 지원)
우클릭 → 이름 변경 / 삭제
폴더 우클릭 → 이미지 추가

참고자료 탭

가이드: 내장 문법 가이드 (Lua, CBS, 로어북, 정규식, HTML/CSS 등)
참고 파일: 다른 .charx 파일을 읽기 전용으로 로드
파일을 열지 않아도 가이드와 참고자료는 사용 가능

백업 시스템

편집 시작 시 자동으로 원본 백업 생성 (Lua, 로어북, 정규식 모두 지원)
탭 전환 시, Claude MCP 덮어쓰기 시에도 자동 백업
탭당 최대 20개 버전 유지
항목 우클릭 → 백업 불러오기 → 날짜/시간별 버전 선택 팝업 + 미리보기

5. 에디터 (Monaco)

VS Code와 동일한 Monaco 편집 엔진을 사용합니다.

기본 기능

구문 강조 (Lua, HTML, CSS, JSON 등)
자동 완성
찾기/바꾸기 (Ctrl+F / Ctrl+H)
마우스 휠 줌 (Ctrl + 마우스 휠)
미니맵 (우측 스크롤 미리보기)

탭 관리

여러 항목을 동시에 탭으로 열 수 있습니다
탭 드래그로 순서 변경 가능
탭의 × 버튼으로 닫기, Ctrl+W로 현재 탭 닫기
탭의 ↗ 버튼으로 별도 창에서 열기 (팝아웃)

6. TokiTalk 터미널

하단의 TokiTalk 영역은 내장 터미널입니다.

기본 사용

일반 셸 명령어 실행 가능 (bash/powershell)
복사: 텍스트 선택 후 Ctrl+C
붙여넣기: Ctrl+V 또는 우클릭

헤더 버튼

버튼	기능
🐰	RP 모드 토글 (토키/아리스 말투로 Claude 응답)
🔇	BGM ON/OFF (우클릭으로 파일 변경)
🖼	터미널 배경 이미지 설정
⚙	설정 패널 열기
━	터미널 패널 접기/펼치기

터미널 메뉴

Claude Code 시작: 현재 파일 컨텍스트와 함께 Claude Code 실행
터미널 지우기: 화면 초기화
터미널 재시작: 셸 프로세스 재시작

7. Claude Code 연동

RisuToki의 핵심 기능입니다. 터미널에서 Claude Code를 실행하면 열려 있는 .charx 파일의 구조와 내용을 자동으로 Claude에 전달합니다.

시작 방법

.charx 파일을 연 상태에서
터미널 메뉴 → Claude Code 시작 클릭
Claude Code가 현재 파일의 컨텍스트(이름, 구조, 편집 가능 필드 목록)를 자동으로 인식하고 시작됩니다.

MCP 도구 연동

Claude Code 시작 시 MCP(Model Context Protocol) 서버가 자동으로 연결됩니다. Claude는 다음 도구들로 에디터 데이터를 직접 읽고 쓸 수 있습니다:

도구	설명
`list_fields`	편집 가능한 필드 목록 + 크기 확인
`read_field` / `write_field`	필드 내용 읽기/쓰기
`list_lorebook` / `read_lorebook` / `write_lorebook`	로어북 조회/읽기/수정
`add_lorebook` / `delete_lorebook`	로어북 추가/삭제
`list_regex` / `read_regex` / `write_regex`	정규식 조회/읽기/수정
`add_regex` / `delete_regex`	정규식 추가/삭제
`list_references` / `read_reference_field`	참고 자료 조회/읽기 (읽기 전용)

write / add / delete 도구 사용 시 에디터에서 모모톡 스타일 확인 팝업이 표시됩니다.
"이번 작업 동안 전부 허용" 토글로 반복 확인 생략 가능
Claude가 수정한 내용은 에디터에 실시간으로 반영됩니다.

사용 예시

"글로벌노트에 시스템 프롬프트 추가해줘"
"로어북에서 키워드가 '세이버'인 항목 찾아서 내용 수정해줘"
"Lua 코드에서 버그 찾아줘"
"이 정규식 패턴이 맞는지 확인해줘"

8. 아바타 패널

터미널 좌측에 토키/아리스 캐릭터 아바타가 표시됩니다.

대기 상태: 기본 아이콘 (💤 대기중~)
작업 중: 춤추는 GIF 애니메이션 (✨ 작업중~)
우클릭: 아바타 이미지 변경 (대기/작업 중 각각 설정 가능)
이미지 추가: 커스텀 이미지 등록 가능
크로마키: GIF의 초록 배경을 자동으로 투명 처리
접기: ✕ 버튼으로 아바타 패널 숨기기
다크 모드: 토키(라이트) ↔ 아리스(다크) 자동 전환

9. 설정

메뉴바의 설정 또는 터미널 헤더의 ⚙ 버튼으로 설정 패널을 엽니다. 클로드코드를 키고 첫채팅을 치기 전에 페르소나를 설정해 놔야합니다.

설정	설명
자동저장 ON/OFF	일정 간격으로 임시 파일 자동 저장
저장 간격	1분 / 5분 / 10분 / 20분 / 30분
자동저장 경로	기본(파일 옆) 또는 커스텀 폴더 지정
다크 모드	라이트(토키) ↔ 다크(아리스) 전환
BGM	배경 음악 ON/OFF
RP 모드	토키/아리스/커스텀 말투 선택
페르소나 편집	RP 모드 페르소나 텍스트 수정

10. 드래그 앤 드롭

사이드바에 파일을 드래그 앤 드롭하여 빠르게 추가할 수 있습니다.

파일 유형	동작
.charx	참고 자료로 추가 (읽기 전용)
.json	로어북 또는 정규식으로 자동 판별하여 추가
.png / .jpg / .gif 등	에셋(이미지)으로 추가

.charx 파일은 메인 파일 없이도 참고 자료로 추가 가능
JSON/이미지는 메인 파일이 열려 있어야 추가 가능
중복 파일 자동 방지

11. 참고 자료 (Reference)

다른 .charx 파일을 읽기 전용으로 로드하여 참고할 수 있습니다.

추가 방법

사이드바 참고자료 탭 → 파일 추가
.charx 파일을 사이드바에 드래그 앤 드롭

사용

참고 자료의 각 필드(Lua, 글로벌노트, 첫 메시지, CSS, 설명, 로어북, 정규식)를 읽기 전용 탭에서 열람
Lua: 섹션 분할 지원 (통합 보기 + 개별 섹션)
로어북: 폴더 구조 + 폼 에디터 (읽기 전용)
정규식: 폼 에디터 (읽기 전용)
탭 이름에 [참고] 접두사 표시
우클릭 → 이름 복사 / 경로 복사

관리

우클릭 → 개별 제거 / 모두 제거
Claude Code에서 MCP 도구(list_references, read_reference_field)로도 접근 가능

12. 팝아웃 (패널 분리)

각 패널을 별도 창으로 분리할 수 있습니다.

버튼 구분

버튼	기능
`↗`	팝아웃 — 별도 외부 창으로 분리
`⧉`	슬롯 분리 — 메인 창 내 다른 슬롯으로 이동

에디터 탭 팝아웃

탭의 ↗ 버튼 클릭 → 해당 탭을 별도 창에서 편집
팝아웃 창에서 편집한 내용은 메인 창에 실시간 동기화
팝아웃 창에서 Ctrl+S → 메인 창에서 저장 실행
📌 버튼 또는 창 닫기 → 메인 창으로 복귀

터미널 / 사이드바 팝아웃

헤더의 ↗ 버튼 또는 우클릭 → 팝아웃 옵션 사용

참고자료 팝아웃

참고자료 헤더의 ↗ 버튼 → 가이드 + 참고 파일 트리를 별도 창으로 분리
외부 창에서 항목 클릭 → 메인 에디터에 탭 열림
📌 도킹 / ✕ 닫기 → 사이드바로 복귀
⧉ 버튼은 기존 슬롯 분리 기능 (메인 창 내 좌/우/상/하 이동)

13. 프리뷰 모드

F5 키로 프리뷰 테스트 패널을 실행합니다. RisuAI와 동일한 렌더링 파이프라인으로 채팅 화면을 시뮬레이션합니다.

채팅 시뮬레이션

firstMessage 자동 표시 → 유저 입력 → AI 응답(직접 입력) 순서로 대화 테스트
CBS(Conditional Block System) 실행 — 변수 조건분기, 버튼 클릭 처리
정규식 스크립트 적용 (editOutput → editDisplay → editInput)
Lua 트리거 실행 (editOutput, editDisplay, editInput)
실제 api키를 입력해서 ai 대답을 받아보는 기능은 아직 없음

에셋 해석

{{raw::name}}, {{asset::name}} — .charx 내 에셋 참조
ccdefault:, embeded:// — RisuAI 호환 에셋 경로 자동 변환

디버그 패널

변수 탭: chatVars, globalVars, tempVars 실시간 확인
로어북 탭: 현재 매칭된 로어북 항목 표시
Lua 탭: Lua 실행 로그
정규식 탭: 적용된 정규식 결과

기타

프리뷰 초기화(리셋) — 변수/대화 기록 초기화 후 처음부터 다시 테스트
팝아웃(↗) — 프리뷰를 별도 외부 창으로 분리 가능

14. RP 모드 (토키 말투)

Claude Code의 응답을 토키(아스마 토키) 또는 아리스(텐도 아리스) 말투로 변경하는 기능입니다.

터미널 헤더의 🐰 버튼으로 토글
설정 패널에서 상세 모드 선택 가능 (토키/아리스/커스텀)
활성화 시 버튼 배경이 밝아집니다
다음 번 Claude Code 시작 시부터 적용
앱 재시작 후에도 상태 유지

15. 단축키 목록

파일

단축키	동작
`Ctrl+N`	새로만들기
`Ctrl+O`	열기
`Ctrl+S`	저장
`Ctrl+Shift+S`	다른이름저장
`Ctrl+W`	탭 닫기

편집

단축키	동작
`Ctrl+Z`	실행취소
`Ctrl+Y`	다시실행
`Ctrl+F`	찾기
`Ctrl+H`	바꾸기
`Ctrl+A`	모두선택

보기

단축키	동작
`Ctrl+B`	사이드바 토글
Ctrl+`	터미널 토글
`Ctrl++`	에디터 확대
`Ctrl+-`	에디터 축소
`Ctrl+0`	에디터 기본 크기
`F5`	프리뷰 모드
`F12`	개발자 도구

터미널

단축키	동작
`Ctrl+C` (선택 시)	복사
`Ctrl+V`	붙여넣기
우클릭	붙여넣기

16. .charx 파일 구조

example.charx (ZIP 아카이브)
├── card.json          ← V3 캐릭터 카드 스펙 (name, description, firstMessage 등)
├── module.risum       ← RPack 인코딩 바이너리 (Lua 트리거, 정규식, 로어북)
└── assets/            ← 이미지 리소스
    ├── icon/          ← 캐릭터 아이콘
    └── other/image/   ← 기타 이미지

편집 가능 필드

필드	설명
`lua`	Lua 5.4 트리거 스크립트 (RisuAI CBS API 사용)
`globalNote`	포스트 히스토리 인스트럭션
`firstMessage`	첫 메시지 (HTML/마크다운)
`description`	캐릭터 설명
`css`	커스텀 CSS
`defaultVariables`	기본 변수
`lorebook[]`	로어북 항목 배열
`regex[]`	정규식 스크립트 배열

17. 문제 해결

Claude Code가 시작되지 않음

claude CLI가 PATH에 등록되어 있는지 확인하세요.
터미널에서 직접 claude 명령어를 입력해 보세요.

MCP 연결 실패

Claude Code 시작 시 MCP 설정 파일(.mcp.json)이 자동 생성됩니다.
에디터를 재시작하면 포트가 변경될 수 있으며, 자동으로 새 포트가 반영됩니다.
Claude Code를 에디터에서 시작해야 MCP 도구가 연동됩니다.

파일이 열리지 않음

.charx 확장자 파일인지 확인하세요.
파일이 손상되지 않았는지 확인하세요 (유효한 ZIP 형식이어야 함).

GIF 아바타가 움직이지 않음

아바타 패널이 숨겨져 있지 않은지 확인하세요 (보기 → 아바타 토글).

저장 후에도 수정 표시가 남음

모든 탭의 변경사항이 한 번에 저장됩니다. Ctrl+S로 저장 후 표시가 사라집니다.

자동 저장이 안 됨

설정에서 자동 저장이 ON인지 확인하세요.
새 파일(한 번도 저장 안 한 파일)은 자동저장 경로를 지정해야 합니다.

Name		Name	Last commit message	Last commit date
assets		assets
build		build
guides		guides
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
main.js		main.js
package-lock.json		package-lock.json
package.json		package.json
popout-preload.js		popout-preload.js
preload.js		preload.js
toki-mcp-server.js		toki-mcp-server.js

Latest commit

History

Folders and files

Repository files navigation