Como trocar de modelo no Oh My Pi sem perder o progresso: /model, /fork ou /new

Trocar de modelo em uma sessão longa do Oh My Pi não muda apenas a qualidade da resposta. O histórico pode conter IDs de tool calls, assinaturas de raciocínio, blocos de imagem e outros campos específicos do provedor anterior que a API de destino não aceita.

A regra mais segura é: salve separadamente o progresso do código e a evidência da sessão, e leve para o novo modelo apenas o histórico necessário. Use /model quando o histórico for provavelmente compatível, /fork quando precisar de um experimento reversível e /fork com /clear, ou uma sessão limpa com /new, quando o histórico antigo já estiver suspeito.

Salve dois checkpoints antes da troca

O transcript da sessão não substitui um checkpoint do Git, e o Git não preserva a sequência de decisões do agente. Proteja os dois.

1. Registre o estado da árvore de trabalho

Veja exatamente o que mudou:

git status --short
git diff --stat

Crie um commit local, patch ou outro ponto de recuperação aceito pela equipe. O objetivo não é publicar trabalho incompleto, mas garantir que você consiga voltar ao estado anterior caso o próximo modelo altere os arquivos errados.

2. Exporte a sessão

Execute /export. A referência oficial de operações de sessão informa que o comando gera um arquivo HTML sem modificar a sessão. O sinal de sucesso é o caminho exibido; a TUI normalmente também abre o arquivo.

Trate esse HTML como material sensível. A exportação não remove segredos nem usa criptografia e pode conter contexto bruto, imagens e payloads de extensões.

3. Crie um handoff curto

Adicione temporariamente um OMP-HANDOFF.md ao repositório com:

• objetivo atual e o que já foi concluído;
• arquivos alterados;
• verificações executadas e resultados;
• próximo passo pretendido;
• erro completo, modelo, provedor e rota de API envolvidos.

Uma sessão limpa não precisa receber dezenas de mensagens antigas. Ler as instruções do projeto e esse handoff costuma ser mais controlável.

Escolha o comando pelo risco do histórico

Situação	Caminho recomendado	O que preserva	Principal ressalva
Mesmo provedor ou modelo próximo, sem erro de protocolo	/model	Sessão e histórico atuais	O destino ainda recebe o histórico antigo
Testar outro modelo mantendo a sessão original intacta	/fork → /model	Original e uma ramificação com histórico	O histórico incompatível também é copiado
Manter o registro original sem reenviar o contexto antigo	/fork → /clear → /model	Original intacto; o fork mantém trilha de auditoria após o reset	O objetivo deve ser retomado pelo handoff
O histórico já causa 400 ou a troca cruza protocolos	/new → /model	Arquivos e sessão antiga permanecem; a nova conversa começa vazia	Todo, checkpoint e estado de ferramentas não migram automaticamente
Apenas o stream ou a sessão remota travou	/fresh	Conversa visível e conversa enviada ao modelo permanecem	Não remove histórico incompatível

Caminho 1: use /model com histórico compatível

O README do Oh My Pi diz explicitamente que /model troca o modelo ativo no meio da sessão. Use essa opção quando o contexto existente for necessário e não houver motivo para esperar rejeição de tool calls, blocos de raciocínio ou conteúdo multimodal anteriores.

Siga esta ordem:

1. Aguarde a resposta atual terminar ou interrompa-a. Não troque enquanto ferramentas estiverem em execução.
2. Digite /model, escolha o provedor e o modelo de destino e atribua-o ao papel ativo.
3. Confirme o provedor/modelo mostrado pelo seletor ou status do Oh My Pi. Não confie na autoidentificação do modelo.
4. Envie uma tarefa somente leitura, como ler um arquivo conhecido e retornar dois fatos verificáveis.
5. Execute uma pequena tarefa com ferramenta. Só retome o trabalho longo se a chamada, o resultado e o turno seguinte funcionarem.

Se a primeira solicitação retornar HTTP 400, pare de repetir o mesmo histórico. Preserve o erro e o export, depois use um fork limpo ou uma sessão nova.

Caminho 2: use /fork para um experimento reversível

/fork cria um novo arquivo de sessão a partir da sessão atual e muda a identidade ativa. A documentação oficial explica que um fork completo preserva a conversa e a atribuição de uso e tenta copiar o diretório de artefatos. A sessão original continua disponível, o que facilita comparar modelos com rastreabilidade.

Porém, um fork completo também copia todo o histórico. Se o problema estiver no histórico, /fork sozinho repete a falha.

Use esta sequência mais segura:

1. Execute /fork e confirme que a nova identidade está ativa.
2. No fork, execute /clear.
3. Execute /model e escolha o modelo de destino.
4. Peça ao modelo que leia as instruções do projeto e OMP-HANDOFF.md.
5. Valide com uma tarefa somente leitura antes de permitir gravações.

/clear remove o contexto vivo e o contexto enviado ao modelo, mas mantém ID da sessão, título, diretório de trabalho, configurações do modelo e arquivo transcript. Ele adiciona um reset_boundary; o JSONL persistido e a exportação completa continuam contendo o histórico anterior. Assim, a evidência permanece disponível sem ser reenviada ao novo modelo.

Se /fork for rejeitado, espere o streaming terminar e confirme que a sessão é persistente. Um fork completo não funciona em sessão somente em memória.

Caminho 3: use /new quando o histórico já não é seguro

/new cria uma nova identidade e uma conversa vazia. A referência oficial informa que o modelo e as configurações atuais permanecem, mas filas de conversa, todo, checkpoint, estado de ferramentas, identidade de cache herdada e parte da memória promovida são limpos. Para trocar também o modelo, a sequência comum é /new e depois /model.

Fluxo recomendado:

1. Confirme que o export e o checkpoint da árvore de trabalho existem.
2. Execute /new.
3. Execute /model e selecione o modelo de destino.
4. Faça o modelo ler as instruções do projeto, os arquivos relevantes e OMP-HANDOFF.md.
5. Comece com uma verificação somente leitura e depois uma gravação mínima.
6. Compare o resultado com o checkpoint Git e as verificações anteriores.

Quando o replay do histórico já quebra as solicitações, esse caminho costuma ser mais rápido que insistir. Você perde o contexto automático do chat, não os arquivos do projeto. Fatos importantes devem estar no código, testes, documentação e handoff.

/fresh não quer dizer “apagar o histórico”

O nome pode enganar. Segundo a referência oficial, /fresh reinicia o estado do stream do provedor, os handles da sessão remota e o estado relacionado ao prompt cache sem tocar no transcript local. O próximo turno é reconstruído a partir da conversa local; a conversa visível e a enviada ao modelo continuam presentes.

Portanto:

• use /fresh para stream travado, prompt cache obsoleto ou ID remoto desviado;
• não espere que ele remova IDs de ferramentas, assinaturas de raciocínio ou imagens incompatíveis com o novo provedor;
• a frase “start a fresh session” em um issue pode ser inglês comum, não o comando /fresh. Para histórico vazio, use /new; para preservar o original e cortar o contexto, use /fork seguido de /clear.

O que dois erros 400 reais mostram

Um modo de falha envolve IDs de tool calls entre provedores. No issue #15056, o autor e um mantenedor reproduziram um ID assinado de Vertex/Gemini sendo reenviado para um destino OpenAI-compatible Chat Completions. O ID excedia o limite de 64 caracteres, a solicitação retornava HTTP 400 e o valor inválido permanecia no histórico.

Em 10 de outubro de 2026, o issue continua aberto e a correção proposta no PR #15059 também está aberta. Um comentário dizendo “fix is up” não prova que a sua versão instalada contém a mudança. Verifique a versão ou o changelog; caso contrário, recupere com histórico limpo.

Outro caso, o issue #15015, descreveu um Google 400 por meio de um proxy HAI e atribuiu o erro a um thoughtSignature antigo. Um mantenedor explicou que skip_thought_signature_validator é usado de propósito em partes functionCall sem assinatura e é exigido pela API pública do Google, enquanto aquele proxy rejeitava o valor antes de a solicitação chegar ao Google. O issue foi fechado com a label wontfix.

A conclusão não é que toda troca para Google falha. É que o mesmo 400 pode vir da conversão de histórico no cliente ou de um gateway intermediário. Registre provedor, modelo, api, endpoint, erro completo e origem do histórico antes de escolher entre sessão limpa, atualização do cliente ou correção do proxy.

Aplicando o fluxo a um provedor OpenAI-compatible personalizado

O Oh My Pi aceita provedores personalizados em ~/.omp/agent/models.yml, inclusive com api: openai-completions. O README recomenda executar omp models <provider> para verificar a descoberta antes de escolher o modelo em /model.

Por exemplo, a documentação oficial de Chat Completions do BetterToken informa https://www.bettertoken.ai/v1 como Base URL OpenAI-compatible e https://www.bettertoken.ai/v1/chat/completions como URL completa. A autenticação usa o Bearer API Key do usuário, e o modelo deve ser o Model ID completo e atual do serviço.

Trate-a como uma candidata compatível em protocolo, não como garantia para todos os modelos, ferramentas ou históricos. Teste em /new: primeiro uma solicitação curta sem ferramentas e depois uma tarefa somente leitura. Mantenha a chave real em configuração protegida de credenciais, não no chat, no export ou em logs públicos.

Trocar a Base URL ou o provedor não corrige um 400 que já está gravado no histórico. Isole o histórico primeiro e valide o novo endpoint separadamente.

Verificação final antes de retomar a tarefa longa

Continue somente quando estes resultados forem observáveis:

• /export gerou um arquivo em local controlado;
• existe um checkpoint recuperável da árvore de trabalho anterior à troca;
• o caminho escolhido corresponde ao objetivo: mesma sessão, fork reversível, contexto limpo ou sessão nova;
• o Oh My Pi mostra o provedor/modelo pretendido;
• uma tarefa somente leitura funciona e o resultado chega ao turno seguinte;
• a sessão original ainda pode ser encontrada com /resume, ou você decidiu conscientemente não usá-la;
• após um 400, foram registrados erro, versão, provedor, modelo, api e endpoint, em vez de escondê-los sob novas tentativas.

A regra é direta: quanto mais valioso e claramente compatível for o histórico, mais sentido faz /model. Quanto maior o risco entre provedores, mais importante é preservar a sessão original e continuar com contexto limpo.