Solução de problemas do Devin air-gapped: runbook do doctor

Esta documentação é destinada às implantações federais do Devin. Voltar para a documentação do Devin

devin airgap doctor é o primeiro comando a executar quando o CLI ou o Desktop não inicia, não consegue acessar um modelo ou exibe um código de erro. Ele executa todas as verificações locais e de rede das quais o agente depende, exibe uma linha por verificação e retorna um código de saída diferente de zero se alguma delas falhar. Esta página explica cada verificação e o que fazer em cada caso e, em seguida, descreve o que coletar para abrir uma solicitação de suporte.

Executar o doctor

Execute-o com o mesmo usuário que vai usar o Devin, no mesmo ambiente (as variáveis de chave de API devem estar definidas nesse shell):

devin airgap doctor

pass  license                                seat alice@example.gov (account acme), expires 2027-03-01
pass  models file path                       /etc/devin/models.json
pass  config dir writable                    /home/alice/.config/devin/cli-federal
pass  data dir writable                      /home/alice/.local/share/devin/cli-federal
pass  CA bundle                              not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)
pass  models file parse                      1 model(s) configured
pass  model 'llama-3.3-70b': API key env var  LOCAL_LLAMA_API_KEY is set
pass  custom subagent profiles               none configured
pass  model 'llama-3.3-70b': endpoint reachability  GET https://models.internal:8000/v1/models -> 200 OK
pass  model 'llama-3.3-70b': inference conformance  POST https://models.internal:8000/v1/chat/completions -> 200 OK (412 ms)

10 check(s): 10 passed, 0 warning(s), 0 failure(s)

Cada linha segue o formato <status> <check> <detail>. Falhas e avisos com código trazem o código de erro como prefixo do detalhe, por exemplo FAIL model 'llama-3.3-70b': endpoint reachability NET003: ....

Status	Significado	Status de saída
`pass`	A verificação foi bem-sucedida.
`warn`	O Devin vai funcionar, mas algo requer atenção em breve (licença prestes a expirar, `/models` não implementado, sondagem pulada).	`0`
`FAIL`	O Devin não funcionará corretamente até que isso seja corrigido.	diferente de zero, com `doctor found N failing check(s)`

Para automação, --json imprime {"ok": <bool>, "checks": [...]}, em que cada verificação contém check, status (pass, warn, fail) e detail, além de code em avisos e falhas com código e latency_ms em uma sondagem de inferência bem-sucedida:

devin airgap doctor --json

{
  "ok": true,
  "checks": [
    {
      "check": "license",
      "status": "pass",
      "detail": "seat alice@example.gov (account acme), expires 2027-03-01"
    },
    {
      "check": "model 'llama-3.3-70b': inference conformance",
      "status": "pass",
      "detail": "POST https://models.internal:8000/v1/chat/completions -> 200 OK (412 ms)",
      "latency_ms": 412
    }
  ]
}

O Desktop usa a mesma CLI incluída no pacote, então você também pode executar o doctor em um terminal no host do Desktop para diagnosticar problemas do Desktop.

Referência de verificações

As verificações são executadas na ordem abaixo. Verificações posteriores que dependem de uma etapa anterior que falhou são ignoradas, e não repetidas: se o arquivo de modelos não for encontrado, não haverá a linha models file parse nem sondagens de endpoint.

`license`

Carrega e verifica o arquivo de licença (consulte Licença).

Resultado	Detalhe	Ação
`pass`	`seat <label> (account <id>), expires <YYYY-MM-DD>`	Nenhuma.
`warn`	`... (<n> day(s) left) — contact your administrator to renew it` quando faltam menos de 30 dias; `(less than a day left)`; ou `already expired (within the clock-skew grace period)`	Renove e substitua a licença antes do fim do período de carência de 24 horas.
`FAIL`	`LIC00n: <message>` seguido de `Checked <path> — install a valid license there or point DEVIN_LICENSE_FILE at one.`	Siga as instruções da linha `LIC` em Códigos de erro.

`models file path`

Determina o local do arquivo de modelos (/etc/devin/models.json, C:\ProgramData\Devin\models.json no Windows ou DEVIN_MODELS_FILE) e confirma que há um arquivo nesse local.

Resultado	Ação
`pass` com o caminho resolvido	Nenhuma.
`FAIL CFG003`	Instale o arquivo de modelos ou corrija o valor de `DEVIN_MODELS_FILE`. Todas as verificações do arquivo de modelos e do endpoint são ignoradas.

`config dir writable` e `data dir writable`

Cria os diretórios de configuração e de dados do produto, se necessário, e grava um arquivo de sondagem em cada um.

Resultado	Ação
`pass` com o caminho do diretório	Nenhuma.
`FAIL CFG001`	O detalhe indica se o diretório não pôde ser resolvido, criado ou gravado. Corrija o proprietário e as permissões para o usuário que executa o Devin ou defina `XDG_CONFIG_HOME` / `XDG_DATA_HOME` com um local onde seja possível gravar. No Windows, a CLI não lê `XDG_*`; corrija as permissões em `%APPDATA%\devin\`.

`CA bundle`

Informa se DEVIN_CA_BUNDLE está definida e a carrega.

Resultado	Detalhe	Ação
`pass`	`not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)`	Nenhuma, a menos que seus endpoints usem uma CA privada.
`pass`	`<path> (<n> certificate(s))`	Nenhuma.
`FAIL CFG004`	Motivo pelo qual não foi possível carregar o arquivo	Corrija o caminho ou o conteúdo PEM; consulte Rede e certificados.

`models file parse` and `model '<name>': API key env var`

Analisa o arquivo de modelos com o mesmo validador usado por devin models validate e, em seguida, verifica se a variável api_key.env de cada modelo está definida no ambiente atual.

Resultado	Ação
`pass models file parse <n> model(s) configured`	Nenhuma.
`FAIL models file parse <message> (run devin models validate for structured MDL diagnostics)`	Execute `devin models validate` e corrija cada código `MDL`; consulte Arquivo de modelos. As sondagens de endpoint não são executadas.
`pass model '<name>': API key env var <VAR> is set`	Nenhuma.
`FAIL CFG002 environment variable '<VAR>' (referenced by api_key.env) is not set`	Exporte a variável neste shell ou, no Desktop, adicione-a a `devin.acp.agentEnv`; consulte Variáveis de ambiente de chave de API. As sondagens de endpoint desse modelo são puladas com um `warn`.

`custom subagent profiles`

Lista as definições de subagentes personalizados em agents/**/AGENT.md. none configured ou <n> profile(s) loaded indicam que a verificação passou; CFG005 aponta uma definição que não pôde ser analisada. Esta verificação é compartilhada com o devin doctor padrão e não tem relação com a configuração air-gapped.

`model '<name>': endpoint reachability`

Envia GET {base_url}/models com a chave de API do modelo, usando um tempo limite de 10 segundos e a mesma configuração de TLS usada na inferência.

Resultado	Detalhe	Ação
`pass`	`GET <url> -> 200 OK`	Nenhuma. Se o detalhe incluir `(trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)`, o pacote é indispensável: mantenha-o configurado em todos os hosts.
`warn NET004`	`GET <url> -> 404 Not Found (server may not implement /models)`	Nenhuma; o endpoint está acessível, e a sondagem de inferência abaixo é o teste que realmente importa.
`warn CFG002`	`skipped: API key env var '<VAR>' is not set`	Defina a variável (veja acima).
`FAIL NET006`	`GET <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	A variável está definida, mas o valor dela não é válido para este endpoint.
`FAIL NET004`	`GET <url> -> <status>`	Verifique os logs do endpoint e o caminho em `base_url`.
`FAIL NET001` / `NET002` / `NET005`	Cadeia de erros de DNS, TCP ou tempo limite	Verifique, a partir da mesma estação de trabalho, a resolução de nomes, as regras de firewall e de proxy e a integridade do endpoint.
`FAIL NET003`	Cadeia de erros de TLS, seguida do certificado apresentado pelo servidor (assunto, emissor, validade) e, por fim, de `TLS failed despite the configured DEVIN_CA_BUNDLE (<path>) — verify the bundle contains this endpoint's CA` ou `if this endpoint uses a private CA, set DEVIN_CA_BUNDLE=/path/to/ca.pem`	Compare o emissor exibido com os certificados do seu pacote; consulte Rede e certificados.

`model '<name>': inference conformance`

Ignorada quando a verificação de alcançabilidade falha no nível de transporte. Envia uma requisição de um token para comprovar que o endpoint é compatível com a API configurada: POST {base_url}/chat/completions com max_tokens: 1 para chat_completions, ou POST {base_url}/responses com max_output_tokens: 16 para responses.

Resultado	Detalhe	Ação
`pass`	`POST <url> -> 200 OK (<n> ms)`	Nenhuma. A latência serve como uma base útil para comparações futuras.
`FAIL NET006`	`POST <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	Corrija a chave.
`FAIL NET004`	`POST <url> -> <status>: <first 200 characters of the response body>`	O corpo da resposta geralmente indica o problema: nome de modelo desconhecido (a requisição usa o `name` do seu arquivo de modelos, que deve corresponder ao que o servidor executa), valor de `api` incorreto para este servidor ou um erro server-side.
`FAIL NET00n`	Cadeia de erros de transporte	O mesmo que na verificação de alcançabilidade.

Problemas comuns

Sintoma	Causa provável	Onde verificar
O Doctor passa em um terminal, mas o Desktop não consegue acessar o modelo	O agente incluído no Desktop não herda o ambiente do seu shell, então a variável da chave de API não está definida	Variáveis de ambiente da chave de API
Todos os usuários de um host passam, exceto um	Estado por usuário: permissões em `~/.config/devin` ou `~/.local/share/devin` (`%APPDATA%\devin` no Windows) ou um `sso_tokens.toml` obsoleto (`IDP006`)	Formatos em disco
`devin auth login` funciona, mas as sessões são encerradas depois de um tempo	A revalidação falhou: o usuário foi removido do `required_group` ou a sessão do IdP foi revogada	SSO e o evento de auditoria `sso_revalidation_failed`
`NET003` apenas em alguns hosts	`DEVIN_CA_BUNDLE` não está definido nesses hosts ou aponta para um pacote diferente	Rede e certificados
`LIC004` após instalar uma atualização ou em um novo ambiente	O build e a licença vêm de ambientes diferentes ou houve uma rotação de chave	Licença: verifique o ID da chave
`MDL014` ao salvar modelos no Desktop	O arquivo de modelos pertence ao root ou a outro usuário (no Windows, a um administrador, enquanto você é um usuário padrão)	Edite o arquivo diretamente em disco como proprietário dele

O que enviar ao suporte

Colete os itens a seguir na estação de trabalho afetada. Revise cada arquivo antes de enviá-lo; nenhum deles é enviado automaticamente.

A saída do doctor:
devin airgap doctor --json > doctor.json
(no output; the command exits nonzero if a check failed)
As strings de detalhes contêm as URLs dos seus endpoints e os seus hostnames, mas nunca os valores das chaves de API.
O relatório de diagnósticos com dados sensíveis ocultados:
devin diagnostics --output devin-diagnostics.txt
Diagnostics written to devin-diagnostics.txt The report is plain text and stays on this machine; review it before sharing.
O relatório registra as versões, se cada arquivo de configuração existe e é analisado corretamente, os nomes dos modelos, se cada variável de chave de API está definida e estatísticas do registro de auditoria. Ele nunca inclui prompts, código, conteúdo de arquivos, valores de segredos, URLs de endpoints nem valores de variáveis de ambiente.
A mensagem de erro exata exibida ao usuário, incluindo o código, e a saída de devin --version.
Para problemas de SSO, os eventos auth relevantes do registro de auditoria (campos error_code e action) e as entradas correspondentes nos logs do seu IdP.

Não envie o arquivo de licença, os valores das chaves de API, sso_tokens.toml nem sessions.db.

​Executar o doctor

​Referência de verificações

​license

​models file path

​config dir writable e data dir writable

​CA bundle

​models file parse and model '<name>': API key env var

​custom subagent profiles

​model '<name>': endpoint reachability

​model '<name>': inference conformance

​Problemas comuns

​O que enviar ao suporte

Executar o doctor

Referência de verificações

`license`

`models file path`

`config dir writable` e `data dir writable`

`CA bundle`

`models file parse` and `model '<name>': API key env var`

`custom subagent profiles`

`model '<name>': endpoint reachability`

`model '<name>': inference conformance`

Problemas comuns

O que enviar ao suporte