Trocar a identidade e o modelo do assistente
Como escolher a identidade do assistente (Koog / Claude Code / Codex), onde trocar o modelo e os quatro erros que aparecem quando a troca falha.
Qual modelo o assistente usa é escolhido em duas etapas: primeiro a identidade do assistente (quem executa) e depois o modelo (o que é executado). A maioria trava por tratar as duas como uma só.
Passo 1: escolha a identidade do assistente
Vá em Configurações da conta → Assistente de IA. O primeiro campo do formulário é o tipo de identidade do assistente, com três opções:
| Identidade | O que é | Qual credencial precisa |
|---|---|---|
| Koog | O motor embutido: chama LLMs comuns direto por provedor + modelo. É a opção padrão. | Uma chave de API desse provedor (OpenAI, Anthropic, OpenRouter, DeepSeek etc.) |
| Claude Code | Roda a linha de comando do Claude Code como o próprio assistente. | Um token de assinatura do Claude — salve com o provider claude_code_oauth |
| Codex | Roda a linha de comando do Codex como o próprio assistente. | O auth.json do Codex — salve com o provider codex_subscription |
Ao mudar para Claude Code ou Codex sem a credencial de assinatura correspondente, a página avisa «nenhuma credencial de assinatura utilizável para esta identidade» e recusa salvar — de propósito, para não guardar uma configuração que não roda. A saída: adicione a credencial em Integrações → Provedores de modelos e volte para trocar a identidade.
Passo 2: escolha o modelo
Com a identidade Koog
- Primeiro escolha o modo de configuração: modelo predefinido (um ajuste pronto) ou configuração personalizada (você preenche cada campo).
- Escolha o provedor — a lista de modelos é buscada por provedor, então depois de trocar reabra o menu de modelos para recarregar.
- Escolha o modelo de LLM. Se o desejado não estiver na lista, digite o ID do modelo manualmente.
- Opcionalmente, fixe qual credencial cada provedor deve usar. Em branco, ele busca uma credencial do mesmo provedor na ordem pessoal e depois equipe.
Com a identidade Claude Code / Codex
Os modelos candidatos vêm do que a sua própria conta de assinatura suporta, não do menu de provedores. Siga as dicas do bloco de configuração daquele runtime — no lado do Codex, por exemplo, nomes como gpt-5.6-sol são comuns.
O ponto que mais se confunde
Na identidade Koog há, mais abaixo, outro bloco: «Claude Code / Codex (como subagente externo chamado como ferramenta)». É algo completamente diferente do tipo de identidade do assistente:
- Função — Define quem executa a conversa inteira. Ao escolher Claude Code, o próprio assistente passa a ser o Claude Code.
- Subagente externo — O assistente continua sendo o Koog e apenas chama o Claude Code ou o Codex como ferramenta quando precisa. Este bloco só aparece se external_agent estiver marcado no conjunto de ferramentas.
Para trocar o próprio assistente, mude a identidade acima; para que ele apenas use uma CLI externa de vez em quando, configure o subagente abaixo.
A identidade também decide se ele pode editar fluxos
A identidade Koog cria e altera fluxos na conversa nativamente. Com Claude Code ou Codex isso depende de um canal de edição configurado no lado da implantação; se faltar, pedir para montar um fluxo devolve um aviso claro: esta identidade de assistente não suporta as ferramentas internas de edição de fluxo, volte para o Koog.
Se o seu objetivo principal é que o assistente monte fluxos, ficar no Koog dá menos trabalho. Troque quando precisar especificamente da capacidade de codificação do Claude Code ou do Codex — ou simplesmente selecione-os para uma etapa de agente dentro do fluxo, como mostra a próxima página.
Erros comuns e o que significam
| O que você vê | A causa real | O que fazer |
|---|---|---|
| Nenhuma credencial de assinatura encontrada para a identidade atual | Você mudou para uma identidade externa, mas o centro de credenciais não tem uma credencial de assinatura desse provedor. | Adicione primeiro uma credencial claude_code_oauth ou codex_subscription e depois troque a identidade. |
| Esta identidade de assistente não suporta as ferramentas internas de edição de fluxo | O canal de edição usado pelas identidades externas não está pronto nesta implantação. | Volte para o Koog para concluir a edição ou peça ao administrador que verifique a configuração da implantação. |
| O menu de modelos está vazio | A lista de modelos daquele provedor não carregou, ou você acabou de trocar de provedor e ela ainda não recarregou. | Feche e reabra o menu para forçar nova busca; se continuar vazio, digite o ID do modelo direto. |
| Salva normalmente, mas na primeira mensagem reclama de chave ausente | Há um provedor selecionado, mas nenhuma credencial é resolvida — nem a pessoal nem a da equipe têm uma desse provedor. | Adicione uma credencial desse provedor no centro de credenciais, ou escolha explicitamente uma existente na configuração. |
Leia a seguir
- Trocar o modelo de um agente do fluxo — Os modelos dentro de um fluxo são uma configuração à parte e não afetam o assistente.
- BYOK: traga sua própria chave — Onde obter a chave de cada provedor e em qual conta o custo cai.
- Credenciais — Como as credenciais são guardadas e como a resolução pessoal e de equipe funciona.