> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Runbook do devin airgap doctor no Devin CLI e no Devin Desktop air-gapped: o que cada verificação confere, o que significam pass, warn e FAIL e o que enviar ao suporte.

> [!NOTE]
>
> Esta documentação é destinada às implantações federais do Devin. [Voltar para a documentação do Devin](/pt-BR/get-started/devin-intro)

`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):

```sh theme={null}
devin airgap doctor
```

```text theme={null}
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](/pt-BR/federal/air-gapped/error-codes) 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:

```sh theme={null}
devin airgap doctor --json
```

```json theme={null}
{
  "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](/pt-BR/federal/air-gapped/license)).

| 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](/pt-BR/federal/air-gapped/error-codes#lic-license). |

### `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](/pt-BR/federal/air-gapped/network-and-certificates). |

### `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](/pt-BR/federal/air-gapped/models-file). 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](/pt-BR/federal/air-gapped/models-file#api-key-environment-variables). 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](/pt-BR/federal/air-gapped/network-and-certificates). |

### `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](/pt-BR/federal/air-gapped/models-file#api-key-environment-variables) |
| 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](/pt-BR/federal/air-gapped/on-disk-formats) |
| `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](/pt-BR/federal/air-gapped/sso#revalidation-in-running-sessions) 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](/pt-BR/federal/air-gapped/network-and-certificates) |
| `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](/pt-BR/federal/air-gapped/license#check-the-key-id) |
| `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.

1. A saída do doctor:

   ```sh theme={null}
   devin airgap doctor --json > doctor.json
   ```

   ```text theme={null}
   (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.

2. O relatório de diagnósticos com dados sensíveis ocultados:

   ```sh theme={null}
   devin diagnostics --output devin-diagnostics.txt
   ```

   ```text theme={null}
   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.

3. A mensagem de erro exata exibida ao usuário, incluindo o código, e a saída de `devin --version`.

4. Para problemas de SSO, os eventos `auth` relevantes do [registro de auditoria](/pt-BR/federal/air-gapped/on-disk-formats#audit-log) (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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.