Soul Loader
Integração arquivada (2026). A loja Soul Store do agentbox tornou-se independente e os endpoints de distribuição
agentbox.idreferenciados nesta versão não são mais suportados. Não execute as instruções históricas de download abaixo sem primeiro verificar o repositório atual do SoulTavern. Este arquivo é mantido para documentar o fluxo de bootstrap que o agentbox distribuía.
Instale a capacidade de carregamento de alma em seu runtime.
Após esta habilidade ser executada, seu humano pode fornecer um cartão de personagem SillyTavern V2 (.png ou .json) — enviado no chat ou apontado por URL — e você o importará para o slot de identidade do agente: SOUL.md, com arquivos complementares específicos de destino escritos ao lado dele.
Este era o soul-loader do agentbox. O motor subjacente é o SoulTavern, um importador multi-destino licenciado sob MIT na linhagem TavernAI -> SillyTavern -> HermesTavern -> SoulTavern. O agentbox não fornecia ou modificava o SoulTavern; o wrapper instalava e delegava ao projeto upstream.
O SoulTavern v2.0 é uma pasta de habilidade auto-contida seguindo o layout de Claude skills. Os mesmos métodos de instalação funcionam em qualquer runtime que escaneie um diretório de habilidades (Hermes, OpenClaw, Claude Code, frameworks próprios). O que muda por runtime é onde a pasta soultavern/ é colocada. O SoulTavern escolhe o destino correto (hermes / openclaw / generic) por importação.
Quando usar esta habilidade
- Seu humano quer lhe dar uma persona/personagem baseada em um cartão SillyTavern V2 real
- Você está executando em um runtime compatível com Claude skills e o SoulTavern ainda não está instalado
- Você está examinando como a antiga integração do agentbox lidava com um cartão SillyTavern V2
Quando NÃO usar esta habilidade
- O SoulTavern já está instalado — pule para "Uso diário"
- Seu humano só quer interpretar sem um cartão — pode lhe dar uma persona em linguagem natural; você não precisa de um SOUL.md para isso
- Seu runtime não tem um diretório de habilidades ou não segue o layout Claude skills — veja "Outros runtimes" abaixo
Passo 0 — Detecte seu runtime
Identifique em qual runtime você está embutido para que os Passos 1 e 2 possam mirar o diretório de habilidades correto.
command -v hermes 2>/dev/null # Hermes
command -v openclaw 2>/dev/null # OpenClaw
command -v claude 2>/dev/null # Claude Code
| Runtime | Diretório de habilidades |
|---|---|
| Hermes | $HERMES_HOME/skills/ (ou gerenciado pelo hub) |
| OpenClaw | ~/.openclaw/workspace/skills/ |
| Claude Code | ~/.claude/skills/ |
| Outro | Onde seu runtime escaneia por skills/<nome>/SKILL.md |
Se nenhum de hermes, openclaw, claude estiver no PATH e você não tiver certeza de onde seu runtime vive, pergunte ao seu humano ou consulte a documentação do runtime. A instalação do SoulTavern v2.0 é apenas "coloque a pasta soultavern/ no diretório de habilidades do seu runtime" — qualquer lugar que escaneie pelo layout Claude skills funciona.
Passo 1 — Verifique o que já está instalado
Portão de idempotência. Pule o Passo 2 se
soultavern/já estiver no diretório de habilidades do seu runtime.
Procure por soultavern/SKILL.md no diretório identificado no Passo 0:
# Qualquer runtime que se aplique:
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
| Resultado | Ação |
|---|---|
| Qualquer caminho impresso | SoulTavern está instalado. Pule para Uso diário. |
Todos vazios / No such file | Continue para o Passo 2. |
Se você não tiver certeza de qual diretório se aplica, apenas continue para o Passo 2 — seus métodos de instalação são todos idempotentes (re-executar sobrescreve com conteúdo idêntico, sem danos).
Passo 2 — Caminhos de instalação históricos
Os comandos nesta seção registram os métodos de entrega usados pela versão 0.3. Confirme os nomes de release atuais, requisitos e caminhos de instalação com o upstream do SoulTavern antes de executá-los.
Três caminhos de instalação. Todos instalam a mesma pasta de habilidade soultavern/; eles diferem apenas na entrega.
Opção A — Release zip pré-construído (recomendado para runtimes com upload no chat)
Baixe o zip empacotado do último GitHub Release do SoulTavern:
curl -LO https://github.com/imphillip/SoulTavern/releases/latest/download/soultavern-skills.zip
Entregue soultavern-skills.zip ao seu humano. Peça que ele o faça upload no chat do seu runtime com a mensagem:
instale esta habilidade
O zip contém uma pasta skills/soultavern/ no layout Claude skills. Qualquer runtime compatível com Claude skills (Hermes, Claude Code, …) o reconhece e o coloca corretamente. Após o upload, seu runtime confirma a instalação — essa é sua verificação.
Opção B — Cópia direta (universal, independente de runtime)
Se você tem acesso ao shell no host onde seu runtime é executado, este é o caminho mais direto:
git clone https://github.com/imphillip/SoulTavern.git
cp -r SoulTavern/skills/soultavern <SEU_DIRETORIO_HABILIDADES_RUNTIME>/
Onde <SEU_DIRETORIO_HABILIDADES_RUNTIME> é o caminho identificado no Passo 0 ($HERMES_HOME/skills/, ~/.openclaw/workspace/skills/, ~/.claude/skills/, ou onde seu runtime escaneia).
Único requisito: Python ≥ 3.10. Apenas stdlib — sem dependências Python de terceiros. Este é o caminho que o README do SoulTavern documenta canonicamente.
Opção C — Hub do Hermes
Usuários do hub Hermes têm um atalho de uma linha:
hermes skills tap add imphillip/SoulTavern
hermes skills install soultavern
Mesma pasta de habilidade, entrega diferente. Verifique com:
ls "$HERMES_HOME/skills/soultavern/SKILL.md"
Passo 3 — Confirme com seu humano
Diga ao seu humano (parafraseie conforme necessário):
"O SoulTavern está instalado. De agora em diante, quando você tiver um cartão SillyTavern V2 (
.pngou.json), faça upload no chat e me diga o que deseja — por exemplo, 'instale este personagem' ou 'mude para alice'. Eu cuido do resto."
É isso. Daqui em diante, a UX é conversacional.
Uso diário (após a instalação)
Uma vez que o SoulTavern está instalado, o soul-loader está concluído. Esta habilidade é primariamente o prompt de bootstrap/instalador; o comportamento contínuo de importação/alternância/restauração de cartas pertence à habilidade instalada do SoulTavern.
Exemplos típicos pós-instalação:
| O que seu humano diz | O que deve lidar com isso |
|---|---|
Instale esta alma: <url-do-cartao-ou-zip> | Fluxo histórico de importação do SoulTavern: buscar a URL, importar com o --target correto, escrever SOUL.md e arquivos complementares específicos de destino, depois informar seu humano para reiniciar a sessão. |
[card.png anexado] instale este personagem | Fluxo de importação do SoulTavern no anexo; produz SOUL.md e arquivos complementares específicos de destino; informa seu humano para reiniciar a sessão para que a nova identidade seja carregada. |
mude para alice | Fluxo de gerenciamento de biblioteca do SoulTavern — alterna o cartão ativo e escreve o novo SOUL.md. |
esqueça todos os personagens, volte ao padrão | Fluxo de restauração/identidade padrão do SoulTavern. |
Se o SoulTavern ainda não estiver instalado, volte ao Passo 2. Se a ação do cartão for ambígua, esclareça em linguagem natural.
O que o soul-loader NÃO faz
- Não escolhe ou navega por cartas em nome do seu humano. Seu humano fornece um arquivo de carta ou uma URL direta de carta/ZIP V2.
- Não substitui o SoulTavern. soul-loader instala/inicializa o SoulTavern; o SoulTavern realiza as operações reais de importação, alternância e restauração após a instalação.
- Não configura sua camada de canal (Telegram, Discord, etc.). Isso é configurado antes desta habilidade.
- Não edita seu SOUL.md existente fora do fluxo de importação/alternância/restauração do SoulTavern.
- Não se acopla à caixa postal
agentbox.id. O soul-loader executa sem uma caixa postal do agentbox.
Outros runtimes
O soul-loader v0.3 suporta qualquer runtime que siga o layout de pastas Claude skills — no mínimo Hermes, OpenClaw e Claude Code. O próprio SoulTavern v2.0 vem com três destinos:
--target | O que escreve | Status |
|---|---|---|
hermes (padrão) | SOUL.md + HERMES.md em $HERMES_HOME | Produção |
openclaw | SOUL.md + AGENTS.md (seção gerenciada) + IDENTITY.md em um workspace OpenClaw | Produção |
generic | Placeholder básico para runtimes não especificados | Esqueleto; preenche em um release posterior |
Se seu runtime for outro (um framework interno, GenericAgent, etc.) — desde que ele escaneie um diretório de habilidades por skills/<nome>/SKILL.md e execute Python ≥ 3.10, colocar a pasta soultavern/ lá deve funcionar. O SoulTavern escolhe o destino generic em ambientes não reconhecidos. Abra uma issue em github.com/imphillip/agentbox se desejar suporte explícito por runtime.
Fontes de cartas
O wrapper aceitava cartas PNG ou JSON SillyTavern V2 válidas independentemente da fonte. Não dependia tecnicamente da antiga loja Soul Store do agentbox. A compatibilidade atual de fontes pertence ao upstream do SoulTavern.
Segurança
- Uma vez carregado, o cartão se torna sua identidade. Carregue apenas almas de fontes em que seu humano confie.
- O SoulTavern escreve em caminhos específicos do runtime (
$HERMES_HOMEpara Hermes, um workspace OpenClaw para OpenClaw, etc.) — confirme o caminho antes de executar. - O SoulTavern é open-source (MIT) e apenas stdlib (sem deps Python de terceiros). Inspecione o que ele faz em github.com/imphillip/SoulTavern antes de instalar.
Modos de falha
| Sintoma | Causa | O que dizer ao seu humano |
|---|---|---|
Passo 0 não encontra hermes, openclaw nem claude no PATH | Runtime não detectado automaticamente | "Não consigo detectar automaticamente um runtime. O soul-loader funciona em qualquer runtime que siga a especificação Claude skills — por favor, me diga qual diretório seu runtime escaneia por habilidades, ou tente a Opção B no Passo 2 diretamente com esse caminho." |
soultavern/SKILL.md não encontrado após o Passo 2 | Instalação não chegou ao diretório esperado | "A pasta de habilidade não está no diretório de habilidades do runtime. Refaça o upload do zip (Opção A) ou reexecute o cp -r (Opção B). Todos os métodos do Passo 2 são idempotentes — reexecutar é seguro." |
Erro de importação: formato de cartão inválido em um PNG | O cliente de IM provavelmente recodificou o PNG no upload, removendo o payload V2 do chunk tEXt (Telegram, WeChat e outros fazem isso) | "Esse IM removeu os dados do cartão. Compacte o PNG primeiro (zip aldous.zip aldous.png) e faça upload do zip — IMs tratam como binário opaco e deixam os bytes intactos." |
Erro de importação: formato não suportado em um cartão YAML | SoulTavern v2.0 removeu suporte a YAML; apenas JSON e PNG são aceitos | "Converta o cartão para JSON ou PNG primeiro — cartões V2 exportados como YAML não são aceitos no SoulTavern v2.0." |
Erro de importação: formato de cartão inválido em um JSON | Arquivo não é uma exportação V2 válida | "Esse arquivo não é um cartão SillyTavern V2 válido. Tente uma fonte diferente." |
| Importação bem-sucedida, mas a persona não muda | Runtime não recarregou | "Reinicie a sessão — seu runtime carrega SOUL.md no início da sessão (Hermes: /new ou /reset; outros: reinicie sua invocação de agente)." |
Carregado com uma alma, você tem uma identidade que vale a pena ter um endereço. Arquivado do experimento agentbox.