Solução de problemas
Como resolver os problemas mais comuns com a CLI, o daemon e as execuções de agentes do Jiraya, do login à ferramenta de IA que não inicia.
Comece sempre pelo estado do daemon e pelo log:
jiraya daemon statusjiraya daemon logs -n 200O login não abre ou não termina
- Máquina sem navegador, como um servidor acessado por SSH. Crie um token em Configurações › Tokens de API e entre com
jiraya login --token. Deixe o valor vazio (--token=) para a CLI pedir o token sem que ele fique no histórico do shell. Depois, rodejiraya setup --workspace <slug>. - Navegador em outra máquina. Siga a dica de túnel SSH que o
jiraya setupmostra durante o login. Se o navegador alcança esta máquina pela rede, passe--callback-host <ip>. - Mais de um workspace, sem terminal interativo. O
setupprecisa de--workspace <slug>para saber onde registrar a máquina.
O comando diz que não está autenticado
O token guardado expirou ou foi revogado. Rode jiraya auth status para ver o servidor e a validade do token, e jiraya login para gerar outro. Trocar a senha não revoga tokens; se você revogou o token em Tokens de API, faça o login de novo em cada máquina.
O runtime aparece desconectado
- Confira se o daemon está rodando:
jiraya daemon status. Se não estiver,jiraya daemon start. - Se ele roda mas o runtime segue Desconectado, procure no log erros de autenticação ou de rede e reinicie com
jiraya daemon restart. - Se você usa perfis, confira o perfil certo:
jiraya daemon status --profile <nome>. - Se a máquina reinicia com frequência, registre o daemon para iniciar com o sistema:
jiraya daemon autostart enable.
A execução fica na fila
Uma execução em Na fila espera um runtime livre. As causas mais comuns:
- O runtime do agente está desconectado. Veja a seção anterior.
- O daemon já roda o máximo de execuções simultâneas. Veja o que está em andamento com
jiraya daemon statusou aumenteJIRAYA_DAEMON_MAX_CONCURRENT_TASKS. - O projeto atingiu o limite de tarefas com agentes trabalhando ao mesmo tempo.
Aguardando diretório local significa que outra execução está usando o mesmo diretório de trabalho; esta começa quando ela terminar.
O comentário não aciona o agente
Ao mencionar um agente, o comentário mostra quando o destino não pode rodar:
| Aviso | O que fazer |
|---|---|
| Ambiente desconectado | Inicie o daemon na máquina do runtime do agente. |
| CLI não pode ser executado | Reinstale a ferramenta de IA naquela máquina. |
| Falta perfil de ambiente | Instale, naquela máquina, o comando do ambiente personalizado do agente. |
| Precisa de um ambiente | Vincule um runtime ao agente. |
| Sem acesso ao ambiente | O runtime é privado de outra pessoa. Peça para torná-lo público ou use outro runtime. |
A execução falhou
O motivo aparece no Log de execução da tarefa. Os mais comuns:
| Motivo | O que fazer |
|---|---|
| Ferramenta de IA não encontrada | Instale a ferramenta ou aponte o caminho com JIRAYA_<FERRAMENTA>_PATH. Veja Instalar ferramentas de IA. |
| Autenticação ou acesso no provedor | Rode a ferramenta no terminal e refaça o login dela. |
| Cota ou limite de uso do provedor | Espere o limite renovar ou troque o plano ou a chave da ferramenta. |
| Modelo inexistente ou indisponível | Corrija o modelo do agente ou a variável JIRAYA_<FERRAMENTA>_MODEL. |
| Contexto excedido | Divida a tarefa ou peça ao agente que trabalhe por partes. |
| Versão da ferramenta não suportada | Atualize a ferramenta de IA. |
| Falha ao preparar o ambiente | Veja no log do daemon o erro do checkout ou da cópia das skills. |
| Runtime desconectado ou tempo esgotado | O Jiraya tenta de novo sozinho; veja Execuções. |
Para tentar de novo depois de corrigir, use Repetir execução no log ou jiraya issue rerun <tarefa>.
A execução não termina
O daemon para uma ferramenta de IA que fica 2 horas sem atividade. Para parar antes, use Parar na tarefa ou jiraya issue cancel-task <id-da-execução>. Para acompanhar o que o agente está fazendo agora, abra jiraya daemon watch na máquina do runtime.
O disco está enchendo
jiraya daemon disk-usage mostra o espaço de cada execução e quanto a limpeza pode liberar. O daemon só apaga o diretório de uma tarefa concluída ou cancelada, e mantém diretórios com alterações não enviadas. Veja as regras em Daemon e runtimes.
Erros de rede e tempo esgotado
A CLI espera 30 segundos por resposta do servidor. Em redes lentas, aumente com JIRAYA_HTTP_TIMEOUT:
JIRAYA_HTTP_TIMEOUT=60s jiraya issue listPara ver o erro completo, com a requisição e a resposta do servidor, use --debug ou JIRAYA_DEBUG=1.
Códigos de saída
Scripts podem decidir pelo código de saída da CLI:
| Código | Significado |
|---|---|
0 | Sucesso |
1 | Erro genérico |
2 | Rede: tempo esgotado, DNS, conexão recusada, TLS |
3 | Autenticação ou permissão |
4 | Não encontrado |
5 | Dados inválidos |
Onde ficam os arquivos
| Arquivo | Caminho |
|---|---|
| Configuração e token da CLI | ~/.jiraya/config.json |
| Log do daemon | ~/.jiraya/daemon.log |
| Saída de falhas graves do daemon | ~/.jiraya/daemon.err.log |
| Diretórios das execuções | ~/jiraya_workspaces/ |
Com --profile <nome>, os arquivos de ~/.jiraya/ ficam em ~/.jiraya/profiles/<nome>/.
Atualizado em