Pular para o conteúdo principal

Use um agente de programação instalado como modelo de chat

Se você já paga por um agente de programação e ele está conectado na máquina que executa o Libre WebUI, pode conversar com ele em um chat normal em vez de adicionar outra chave de API. O Libre WebUI detecta a interface de linha de comando do agente e a oferece no seletor de modelos como qualquer outro modelo.

O que é detectado​

A cada solicitação da lista de modelos, o Libre WebUI procura estes comandos no PATH do servidor:

ModeloComandoFornecido por
Claude CodeclaudeAnthropic
CodexcodexOpenAI
Kirokiro-cliAWS
OpenCodeopencodeSST
PipiMario Zechner

Tudo o que for encontrado aparecerá em um grupo Agentes no seletor de modelos. Nada é instalado para você e nenhum arquivo de configuração é necessário — se o comando for executado no shell do servidor, ele aparecerá.

Configurações → Chat → Padrões também identifica essas entradas como Agente, incluindo o Strands quando sua conta pode usá-lo. Modelos de plugins mantêm o nome do provedor, e apenas modelos Ollama usam o rótulo Ollama. Desativar Ollama não oculta agentes ou plugins configurados. O cartão de informações mostra nome e provedor, e só exibe tamanho, família e formato quando o catálogo os fornece.

Como escolher um modelo, e não apenas uma CLI​

Cada CLI pode oferecer várias opções no grupo Agentes:

  • O Claude Code oferece seu padrão conectado, além de Sonnet, Opus e Haiku. Também oferece opções explícitas Sonnet 5.5 (claude-sonnet-5-5), Opus 5.5 (claude-opus-5-5) e Haiku 5.5 (claude-haiku-5-5). O Sonnet 5.5 exige Claude Code 2.1.284 ou posterior, o Opus 5.5 exige Claude Code 2.1.280 ou posterior e o Haiku 5.5 exige Claude Code 2.1.293 ou posterior, todos com acesso pela conta conectada; execute claude update para atualizar a CLI. Os aliases Sonnet, Opus e Haiku existentes continuam seguindo o mapeamento atual de modelos da CLI.
  • O Codex oferece seu padrão configurado, além da família documentada de login do ChatGPT: GPT-6 Astra, GPT-6.1 Sol (gpt-6.1-sol), GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, Terra, Luna, GPT-5.5 e GPT-5.3 Codex Spark. A disponibilidade depende do login da CLI e do acesso a modelos da conta.
  • O Kiro lista os modelos que a conta conectada pode usar (a partir de kiro-cli chat --list-models) ao lado do padrão configurado. Cada interação roda de forma não interativa no motor de agentes V3 da CLI com o agente padrão integrado (vibe) fixado, então um chat.defaultAgent personalizado não se aplica. Exige Kiro CLI 2.27 ou posterior.
  • O Pi é executado com o modelo configurado na própria CLI.
  • O OpenCode lista os modelos de todos os provedores nos quais está autenticado (a partir de opencode models) e sempre exige uma escolha explícita — seu padrão no nível da CLI pode apontar para um servidor local inacessível pelo host do Libre WebUI.

O motor Strands integrado também aparece no grupo Agentes quando sua conta pode usá-lo. Ele não é uma CLI: roda dentro do backend e usa seus modelos do Ollama e de plugins de provedor. A entrada simples Strands (strands) usa o seu modelo de chat padrão. As outras entradas (strands:<route>) aparecem uma por modelo disponível, como Strands · gpt-5.6-sol (Codex (ChatGPT)), e fixam o modelo e o provedor dele para a conversa; outro provedor disponível não pode substituí-lo em uma falha. Listar as opções não inicia o motor.

As mesmas entradas Strands funcionam como modelo de tarefa em Configurações → Chat → Padrões para títulos automáticos e resumos de raciocínio. Usar modelo atualmente em execução usa a seleção Strands salva na conversa. Essas solicitações curtas de texto chamam diretamente o modelo do provedor subjacente, sem executar as ferramentas do agente nem criar sessão de agente. Outros perfis CLI exigem um modelo de tarefa Ollama, de plugin ou Strands para essas solicitações auxiliares.

O Pi executa cada interação sem estado (--no-session), com as ferramentas locais desativadas e um prompt de sistema neutro; assim, as respostas não são influenciadas pela configuração pessoal do Pi do usuário do sistema operacional do servidor, e as conversas nunca a acessam.

O Kiro é o oposto nos dois pontos: ele roda com a configuração do Kiro do usuário do servidor, em que o agente padrão integrado fica fixado, mas as regras de permissão (~/.kiro/settings/permissions.yaml), os servidores MCP e o modelo padrão configurado continuam valendo. Além disso, cada interação é salva como uma nova sessão no armazenamento de sessões do Kiro desse usuário (kiro-cli chat --list-sessions a mostra, com a transcrição recente do chat dentro). Não há opção para desligar isso, então o conteúdo do chat também fica no diretório pessoal do usuário do backend, fora do banco de dados do Libre WebUI. As ferramentas do Kiro continuam ativadas: tudo em que essas regras de permissão confiam (por padrão, leituras e comandos somente leitura como date) roda sem perguntar, e qualquer chamada de ferramenta que precise de aprovação é recusada, porque uma interação de chat não consegue responder ao pedido.

Como usar​

  1. Entre como administrador.
  2. Inicie uma conversa e abra o seletor de modelos.
  3. Escolha uma opção em Agentes.
  4. Envie mensagens normalmente. As respostas chegam em streaming, token por token.

A conversa é armazenada como qualquer outro chat; portanto, você pode sair e voltar a ela, renomeá-la e pesquisá-la pela paleta de comandos. A cada interação, uma transcrição da conversa recente é enviada ao agente, e a resposta volta em streaming.

Quem pode usar e o que pode ser acessado​

Este recurso é exclusivo para administradores, por um motivo importante. O agente é executado como o mesmo usuário do sistema operacional que o backend do Libre WebUI, no host — e não dentro de um contêiner do Work. Portanto, ele herda as credenciais do agente desse usuário e todo o acesso que esses agentes normalmente têm, incluindo a possibilidade de ler arquivos e executar comandos no servidor, caso decida fazê-lo.

Considere a ativação equivalente a conceder ao agente acesso ao shell da máquina. Por isso, o recurso vem desativado: um administrador precisa ativá-lo em Configurações → Gerenciamento de Usuários → Acesso e políticas → Modelos de agentes CLI. A escolha é persistida e aplicada imediatamente, sem reiniciar.

Alterar esse controle atualiza o catálogo de modelos imediatamente. A categoria Agentes contém entradas CLI diretas; Modelos de plugins contém integrações de API de provedores, como Codex (ChatGPT). Strands aparece na mesma categoria, mas segue a própria configuração de acesso Motor Strands, e não esta chave, então pode aparecer com os modelos de agentes CLI desligados. A descoberta de modelos dele não pode bloquear a descoberta dos agentes CLI instalados.

Instalações existentes herdam a decisão anterior de Agentes até salvar uma configuração CLI independente.

Para fixar a decisão no nível da implantação, independentemente da opção do ambiente de execução, defina a variável de ambiente como desejar (isso também bloqueia a opção na interface):

AGENT_CLI_MODELS_ENABLED=false   # or true

Para usar um modelo que possa atuar sobre arquivos, mas permaneça dentro de um sandbox, use Work: ele executa modelos compatíveis com ferramentas em um contêiner restrito com espaço de trabalho isolado.

Os mesmos agentes no Work​

O Work oferece os mesmos agentes, com as mesmas opções de modelo e os mesmos logins, mas os executa dentro do sandbox da tarefa em vez de no host, atrás de um proxy de saída que mantém os tokens reais fora do sandbox. Eles têm o próprio modo de acesso, CLIs de agentes no Work, e não precisam da chave acima. Consulte CLIs de agentes no Work.

Acompanhamento de uso​

Abra Uso de Fornecedores (/usage) e encontre Agentes perto do topo. Claude Code, Codex, Kiro, OpenCode, Pi e Strands têm entradas explícitas, inclusive uma mensagem clara quando o período não tem chamadas registradas.

Chamadas CLI feitas pelo LWUI registram resultado, duração e tokens informados. Cada execução gera um evento; snapshots repetidos e relatórios por etapa não duplicam eventos ou tokens. Contadores ausentes permanecem não informados. Interromper uma resposta registra cancelamento, e uma saída malsucedida não vira sucesso apenas por ter produzido texto parcial. Chamadas CLI feitas fora do LWUI não são importadas.

As chamadas do Strands são atribuídas ao agente Strands. Consulte Uso dos agentes para detalhes e limites.

Configuração​

VariávelPadrãoFinalidade
AGENT_CLI_MODELS_ENABLEDunsetFixa o recurso em true/false; unset delega à opção do administrador (desativada por padrão)
AGENT_CLI_TIMEOUT_MS600000Tempo máximo de uma interação do agente antes de ser encerrada

Solução de problemas​

O grupo Agentes não aparece. Confirme a ativação em Configurações → Gerenciamento de Usuários → Acesso e políticas → Modelos de agentes CLI (desativado por padrão) e o login como administrador. Depois confirme que o comando está no PATH do processo do backend, não apenas do shell interativo. Um gerenciador de serviços, contêiner Docker ou inicializador desktop costuma usar um PATH menor do que o terminal de login.

A resposta falha imediatamente. Execute o mesmo comando manualmente como o usuário do servidor (claude -p "hello", codex exec "hello" ou echo hello | kiro-cli chat --no-interactive --output-format stream-json --agent-engine v3 --agent vibe). É necessário o Kiro CLI 2.27 ou posterior; uma CLI mais antiga falha primeiro aqui, onde o erro fica visível. No chat, a mesma falha aparece apenas como Kiro exited unsuccessfully. Na maioria das vezes, a falha indica que o agente solicita um login expirado ou que a assinatura subjacente atingiu um limite de taxa. Em particular, o OpenCode informa um login de provedor expirado somente nos próprios logs; execute novamente opencode auth login como o usuário do servidor. O Kiro faz login com kiro-cli login; uma sessão expirada falha da mesma forma.

As respostas param no meio. Uma interação longa pode ter atingido AGENT_CLI_TIMEOUT_MS. Aumente esse valor ou divida a solicitação em etapas menores.

Relacionados​