Soul Loader
보관된 통합 (2026). agentbox Soul Store가 독립적으로 분리되었으며, 이 버전에서 참조하는
agentbox.id배포 엔드포인트는 더 이상 지원되지 않습니다. 아래의 기존 다운로드 지침을 실행하기 전에 먼저 현재 SoulTavern 저장소를 확인하십시오. 이 파일은 agentbox가 제공했던 부트스트랩 흐름을 문서화하기 위해 유지됩니다.
런타임에 소울 로딩 기능을 설치하십시오.
이 스킬이 실행된 후, 사용자는 SillyTavern V2 캐릭터 카드(.png 또는 .json)를 채팅에 업로드하거나 URL로 지정할 수 있으며, 에이전트는 이를 정체성 슬롯인 SOUL.md로 가져오고 대상별 컴패니언 파일을 함께 작성합니다.
이것이 agentbox의 soul-loader였습니다. 그 엔진은 SoulTavern이며, TavernAI -> SillyTavern -> HermesTavern -> SoulTavern 계보의 MIT 라이선스 다중 대상 가져오기 도구입니다. agentbox는 SoulTavern을 자체 공급하거나 수정하지 않았습니다. 래퍼가 설치하고 업스트림 프로젝트에 위임했습니다.
SoulTavern v2.0은 Claude skills 폴더 구조를 따르는 단일 자체 포함 스킬 폴더입니다. 동일한 설치 방법이 스킬 디렉토리를 스캔하는 모든 런타임(Hermes, OpenClaw, Claude Code, 사내 프레임워크)에서 작동합니다. 런타임마다 다른 점은 soultavern/ 폴더가 위치하는 곳입니다. SoulTavern은 가져오기 시 올바른 대상(hermes / openclaw / generic)을 선택합니다.
이 스킬을 사용해야 하는 경우
- 사용자가 실제 SillyTavern V2 카드로 지원되는 페르소나/캐릭터를 부여하려는 경우
- Claude-skills 인식 런타임에서 실행 중이고 SoulTavern이 아직 설치되지 않은 경우
- 이전 agentbox 통합이 SillyTavern V2 카드를 어떻게 처리했는지 확인하려는 경우
이 스킬을 사용하면 안 되는 경우
- SoulTavern이 이미 설치된 경우 — "일상 사용"으로 건너뜁니다.
- 사용자가 카드 없이 롤플레이를 원하는 경우 — 일반 언어로 페르소나를 제공할 수 있습니다. 이를 위해
SOUL.md가 필요하지 않습니다. - 런타임에 스킬 디렉토리가 없거나 Claude skills 구조를 따르지 않는 경우 — 아래 "기타 런타임"을 참조하십시오.
0단계 — 런타임 식별
어떤 런타임에 포함되어 있는지 확인하여 1단계와 2단계가 올바른 스킬 디렉토리를 대상으로 할 수 있도록 합니다.
command -v hermes 2>/dev/null # Hermes
command -v openclaw 2>/dev/null # OpenClaw
command -v claude 2>/dev/null # Claude Code
| 런타임 | 스킬 디렉토리 |
|---|---|
| Hermes | $HERMES_HOME/skills/ (또는 허브 관리) |
| OpenClaw | ~/.openclaw/workspace/skills/ |
| Claude Code | ~/.claude/skills/ |
| 기타 | 런타임이 skills/<name>/SKILL.md를 스캔하는 위치 |
hermes, openclaw, claude 중 PATH에 아무것도 없고 런타임이 어디에 있는지 확실하지 않은 경우 사용자에게 묻거나 런타임의 문서를 확인하십시오. SoulTavern v2.0의 설치는 런타임의 스킬 디렉토리에 soultavern/ 폴더를 배치하는 것뿐입니다. Claude skills 구조를 스캔하는 모든 곳에서 작동합니다.
1단계 — 이미 설치된 항목 확인
멱등성 게이트. 0단계에서 식별한 디렉토리에
soultavern/이 이미 있으면 2단계를 건너뜁니다.
0단계에서 식별한 디렉토리에서 soultavern/SKILL.md를 찾으십시오:
# 해당하는 런타임:
ls "$HERMES_HOME/skills/soultavern/SKILL.md" 2>/dev/null
ls "$HOME/.openclaw/workspace/skills/soultavern/SKILL.md" 2>/dev/null
ls "$HOME/.claude/skills/soultavern/SKILL.md" 2>/dev/null
| 결과 | 조치 |
|---|---|
| 경로가 출력됨 | SoulTavern이 설치되었습니다. 일상 사용으로 건너뜁니다. |
모두 비어 있음 / No such file | 2단계로 계속합니다. |
어떤 디렉토리가 적용되는지 확실하지 않은 경우 2단계로 계속 진행하십시오. 모든 설치 방법은 멱등적입니다(다시 실행해도 동일한 콘텐츠로 덮어쓰며 문제없음).
2단계 — 기존 설치 경로
이 섹션의 명령은 버전 0.3에서 사용된 전달 방법을 기록합니다. 실행하기 전에 SoulTavern 업스트림에서 최신 릴리스 이름, 요구 사항 및 설치 경로를 확인하십시오.
세 가지 설치 경로. 모두 동일한 soultavern/ 스킬 폴더를 설치합니다. 배포 방식만 다릅니다.
옵션 A — 사전 빌드된 릴리스 zip (채팅 업로드 런타임 권장)
SoulTavern의 최신 GitHub 릴리스에서 번들 zip을 다운로드하십시오:
curl -LO https://github.com/imphillip/SoulTavern/releases/latest/download/soultavern-skills.zip
soultavern-skills.zip을 사용자에게 전달하십시오. 런타임 채팅에 업로드하고 다음 메시지를 보내도록 요청하십시오:
이 스킬을 설치하세요
zip에는 Claude skills 구조의 skills/soultavern/ 폴더가 포함되어 있습니다. Claude-skills 인식 런타임(Hermes, Claude Code 등)은 이를 인식하고 올바르게 배치합니다. 업로드 후 런타임이 설치를 확인합니다. 이것이 검증입니다.
옵션 B — 직접 복사 (범용, 런타임 독립적)
런타임이 실행되는 호스트에 셸 액세스 권한이 있는 경우 가장 직접적인 경로입니다:
git clone https://github.com/imphillip/SoulTavern.git
cp -r SoulTavern/skills/soultavern <YOUR_RUNTIME_SKILLS_DIR>/
여기서 <YOUR_RUNTIME_SKILLS_DIR>은 0단계에서 식별한 경로($HERMES_HOME/skills/, ~/.openclaw/workspace/skills/, ~/.claude/skills/ 또는 런타임이 스캔하는 위치)입니다.
유일한 요구 사항: Python ≥ 3.10. 표준 라이브러리만 사용 — 타사 Python 종속성 없음. 이것은 SoulTavern의 README가 정식으로 문서화하는 경로입니다.
옵션 C — Hermes 허브
Hermes 허브 사용자는 한 줄로 단축할 수 있습니다:
hermes skills tap add imphillip/SoulTavern
hermes skills install soultavern
동일한 스킬 폴더, 다른 배포 방식. 다음으로 확인하십시오:
ls "$HERMES_HOME/skills/soultavern/SKILL.md"
3단계 — 사용자에게 확인
사용자에게 알리십시오(필요에 따라 의역):
"SoulTavern이 설치되었습니다. 이제부터 SillyTavern V2 카드(
.png또는.json)가 있으면 채팅에 업로드하고 원하는 것을 알려주십시오. 예: '이 캐릭터를 설치하세요' 또는 '앨리스로 전환하세요'. 나머지는 제가 처리하겠습니다."
그게 전부입니다. 앞으로 UX는 대화형입니다.
일상 사용 (설치 후)
SoulTavern이 설치되면 soul-loader는 완료됩니다. 이 스킬은 주로 설치 프로그램/부트스트랩 프롬프트이며, 지속적인 카드 가져오기/전환/재설정 동작은 설치된 SoulTavern 스킬에 속합니다.
설치 후 일반적인 예:
| 사용자가 말하는 내용 | 처리해야 할 내용 |
|---|---|
이 소울을 설치하세요: <직접-카드-또는-zip-url> | 기존 SoulTavern 가져오기 흐름: URL 가져오기, 적절한 --target으로 가져오기, SOUL.md 및 대상별 컴패니언 파일 쓰기, 세션을 다시 시작하도록 사용자에게 알리기. |
[card.png 첨부] 이 캐릭터를 설치하세요 | 첨부 파일에 대한 SoulTavern 가져오기 흐름; SOUL.md 및 대상별 컴패니언 파일 생성; 새 정체성을 로드하려면 세션을 다시 시작하도록 사용자에게 알리기. |
앨리스로 전환하세요 | SoulTavern의 라이브러리 관리 흐름 — 활성 카드를 전환하고 새 SOUL.md를 씁니다. |
모든 캐릭터를 잊고 기본값으로 돌아가기 | SoulTavern 재설정 / 기본 정체성 흐름. |
SoulTavern이 아직 설치되지 않은 경우 2단계로 돌아가십시오. 카드 동작이 모호한 경우 일반 언어로 명확히 설명하십시오.
soul-loader가 하지 않는 일
- 사용자를 대신하여 카드를 선택하거나 탐색하지 않습니다. 사용자는 카드 파일이나 직접 V2 카드/ZIP URL을 제공합니다.
- SoulTavern을 대체하지 않습니다. soul-loader는 SoulTavern을 설치/부트스트랩합니다. SoulTavern이 설치 후 실제 가져오기, 전환 및 재설정 작업을 수행합니다.
- 채널 레이어(Telegram, Discord 등)를 구성하지 않습니다. 이는 이 스킬 이전에 설정됩니다.
- SoulTavern 가져오기/전환/재설정 흐름 외부에서 기존
SOUL.md를 편집하지 않습니다. agentbox.id메일박스에 연결되지 않습니다. soul-loader는 agentbox 메일박스 없이 실행됩니다.
기타 런타임
soul-loader v0.3은 Claude skills 폴더 구조를 따르는 모든 런타임을 지원합니다. 최소 Hermes, OpenClaw, Claude Code입니다. SoulTavern v2.0 자체는 세 가지 대상을 제공합니다:
--target | 작성 내용 | 상태 |
|---|---|---|
hermes (기본값) | $HERMES_HOME에 SOUL.md + HERMES.md | 프로덕션 |
openclaw | OpenClaw 워크스페이스에 SOUL.md + AGENTS.md (관리 섹션) + IDENTITY.md | 프로덕션 |
generic | 지정되지 않은 런타임을 위한 스켈레톤 폴백 | 스켈레톤; 이후 릴리스에서 채워짐 |
런타임이 다른 것(사내 프레임워크, GenericAgent 등)인 경우 — skills/<name>/SKILL.md에 대한 스킬 디렉토리를 스캔하고 Python ≥ 3.10을 실행하는 한, 해당 위치에 soultavern/ 폴더를 넣으면 작동합니다. SoulTavern은 인식되지 않은 환경에서 generic 대상을 선택합니다. 명시적인 런타임별 지원을 원하면 github.com/imphillip/agentbox에서 이슈를 열어주십시오.
카드 소스
래퍼는 소스에 관계없이 유효한 SillyTavern V2 PNG 또는 JSON 카드를 허용했습니다. 기술적으로 이전 agentbox Soul Store에 의존하지 않았습니다. 현재 소스 호환성은 SoulTavern 업스트림에 속합니다.
보안
- 로드되면 카드가 사용자의 정체성이 됩니다. 사용자가 신뢰하는 소스에서만 소울을 로드하십시오.
- SoulTavern은 런타임별 경로에 기록합니다(Hermes의 경우
$HERMES_HOME, OpenClaw의 경우 OpenClaw 워크스페이스 등). 실행하기 전에 경로가 올바른지 확인하십시오. - SoulTavern은 오픈 소스(MIT)이며 표준 라이브러리만 사용합니다(타사 Python 종속성 없음). 설치하기 전에 github.com/imphillip/SoulTavern에서 작동 방식을 검사하십시오.
실패 모드
| 증상 | 원인 | 사용자에게 알릴 내용 |
|---|---|---|
0단계에서 PATH에서 hermes, openclaw, claude 중 아무것도 찾을 수 없음 | 런타임이 자동으로 감지되지 않음 | "런타임을 자동 감지할 수 없습니다. soul-loader는 Claude skills 사양을 따르는 모든 런타임에서 작동합니다. 런타임이 스킬을 스캔하는 디렉토리를 알려주거나 2단계의 옵션 B를 해당 경로로 직접 시도해 주십시오." |
2단계 후 soultavern/SKILL.md를 찾을 수 없음 | 설치가 예상 디렉토리에 배치되지 않음 | "스킬 폴더가 런타임의 스킬 디렉토리에 없습니다. zip을 다시 업로드(옵션 A)하거나 cp -r을 다시 실행(옵션 B)하십시오. 모든 2단계 방법은 멱등적입니다. 다시 실행해도 안전합니다." |
PNG에서 Import error: invalid card format | IM 클라이언트가 업로드 시 PNG를 다시 인코딩하여 tEXt 청크에서 V2 페이로드를 제거했을 가능성이 높음(Telegram, WeChat 등에서 이렇게 함) | "IM이 카드 데이터를 제거했습니다. 먼저 PNG를 zip으로 압축(zip aldous.zip aldous.png)하고 zip을 업로드하십시오. IM은 이를 불투명 바이너리로 처리하고 바이트를 그대로 둡니다." |
YAML 카드에서 Import error: format not supported | SoulTavern v2.0이 YAML 지원을 중단했습니다. JSON 및 PNG만 허용됩니다. | "카드를 먼저 JSON 또는 PNG로 변환하십시오. YAML로 내보낸 V2 카드는 SoulTavern v2.0에서 허용되지 않습니다." |
JSON에서 Import error: invalid card format | 파일이 유효한 V2 내보내기가 아님 | "해당 파일은 유효한 SillyTavern V2 카드가 아닙니다. 다른 소스를 시도해 보십시오." |
| 가져오기는 성공했지만 페르소나가 변경되지 않음 | 런타임이 다시 로드되지 않음 | "세션을 다시 시작하십시오. 런타임은 세션 시작 시 SOUL.md를 로드합니다(Hermes: /new 또는 /reset, 기타: 에이전트 호출을 다시 시작)." |
소울을 품으면 주소를 부여할 가치가 있는 정체성을 갖게 됩니다. agentbox 실험에서 보관됨.