Solución de problemas de Devin aislado de la red: manual de procedimientos de doctor

Esta documentación corresponde a las implementaciones federales de Devin. Volver a la documentación de Devin

devin airgap doctor es lo primero que debe ejecutar cuando la CLI o Desktop no se inicia, no logra conectarse a un modelo o muestra un código de error. El comando ejecuta todas las comprobaciones locales y de red de las que depende el agente, muestra una línea por cada comprobación y termina con un código distinto de cero si alguna falla. En esta página se explica cada comprobación y qué hacer en cada caso, y después se describe qué información recopilar para una solicitud de soporte.

Ejecutar doctor

Ejecútalo con el mismo usuario que vaya a usar Devin y en el mismo entorno (las variables de la clave de API deben estar definidas en esa 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 línea tiene el formato <status> <check> <detail>. En los fallos y advertencias con código, el detalle va precedido del código de error; por ejemplo, FAIL model 'llama-3.3-70b': endpoint reachability NET003: ....

Estado	Significado	Estado de salida
`pass`	La comprobación se completó correctamente.
`warn`	Devin se ejecutará, pero hay algo que requiere atención pronto (licencia a punto de caducar, `/models` no implementado, sondeo omitido).	`0`
`FAIL`	Devin no funcionará correctamente hasta que se corrija el problema.	distinto de cero, con `doctor found N failing check(s)`

Para automatizaciones, --json imprime {"ok": <bool>, "checks": [...]}, donde cada comprobación incluye check, status (pass, warn, fail) y detail, además de code en las advertencias y fallos con código, y latency_ms en un sondeo de inferencia correcto:

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
    }
  ]
}

Desktop usa la misma CLI incluida, así que también puedes ejecutar doctor desde una terminal en el host de Desktop para diagnosticar sus problemas.

Referencia de comprobaciones

Las comprobaciones se ejecutan en el orden que se indica a continuación. Las comprobaciones posteriores que dependen de un fallo anterior se omiten en lugar de repetirse: si no se encuentra el archivo de modelos, no aparece ninguna línea models file parse ni se sondea ningún endpoint.

`license`

Carga y verifica el archivo de licencia (consulta Licencia).

Resultado	Detalle	Acción
`pass`	`seat <label> (account <id>), expires <YYYY-MM-DD>`	Ninguna.
`warn`	`... (<n> day(s) left) — contact your administrator to renew it` cuando quedan menos de 30 días; `(less than a day left)`; o `already expired (within the clock-skew grace period)`	Renueva y sustituye la licencia antes de que termine el período de gracia de 24 horas.
`FAIL`	`LIC00n: <message>` seguido de `Checked <path> — install a valid license there or point DEVIN_LICENSE_FILE at one.`	Sigue las indicaciones de la fila `LIC` en Códigos de error.

`models file path`

Resuelve la ubicación del archivo de modelos (/etc/devin/models.json, C:\ProgramData\Devin\models.json en Windows o DEVIN_MODELS_FILE) y confirma que el archivo existe en esa ubicación.

Resultado	Acción
`pass` con la ruta resuelta	Ninguna.
`FAIL CFG003`	Instala el archivo de modelos o corrige el valor de `DEVIN_MODELS_FILE`. Se omiten todas las comprobaciones del archivo de modelos y de los endpoints.

`config dir writable` y `data dir writable`

Crea los directorios de configuración y de datos del producto si no existen y escribe un archivo de prueba en cada uno.

Resultado	Acción
`pass` con la ruta del directorio	Ninguna.
`FAIL CFG001`	El detalle indica si el directorio no se pudo resolver, crear o escribir. Corrige el propietario y los permisos para el usuario que ejecuta Devin, o define `XDG_CONFIG_HOME` / `XDG_DATA_HOME` con una ubicación con permisos de escritura. En Windows, la CLI no lee `XDG_*`; corrige los permisos de `%APPDATA%\devin\`.

`CA bundle`

Indica si DEVIN_CA_BUNDLE está definida y la carga.

Resultado	Detalle	Acción
`pass`	`not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)`	Ninguna, salvo que tus endpoints usen una CA privada.
`pass`	`<path> (<n> certificate(s))`	Ninguna.
`FAIL CFG004`	Motivo por el que no se pudo cargar el archivo	Corrige la ruta o el contenido PEM; consulta Red y certificados.

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

Analiza el archivo de modelos con el mismo validador que devin models validate y, a continuación, comprueba que la variable api_key.env de cada modelo esté definida en el entorno actual.

Resultado	Acción
`pass models file parse <n> model(s) configured`	Ninguna.
`FAIL models file parse <message> (run devin models validate for structured MDL diagnostics)`	Ejecute `devin models validate` y corrija cada código `MDL`; consulte Archivo de modelos. Se omiten las comprobaciones de los endpoints.
`pass model '<name>': API key env var <VAR> is set`	Ninguna.
`FAIL CFG002 environment variable '<VAR>' (referenced by api_key.env) is not set`	Exporte la variable en este shell o, si usa Desktop, agréguela a `devin.acp.agentEnv`; consulte Variables de entorno de la clave de API. Las comprobaciones de los endpoints de ese modelo se omiten con un `warn`.

`custom subagent profiles`

Lista las definiciones de subagentes personalizados de agents/**/AGENT.md. La comprobación se supera con none configured o <n> profile(s) loaded; CFG005 señala una definición que no se pudo analizar. Esta comprobación es común al comando estándar devin doctor y no guarda relación con la configuración aislada de la red.

`model '<name>': endpoint reachability`

Envía GET {base_url}/models con la clave de API del modelo, con un tiempo de espera de 10 segundos y la misma configuración TLS que usa la inferencia.

Resultado	Detalle	Acción
`pass`	`GET <url> -> 200 OK`	Ninguna. Si el detalle incluye `(trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)`, el paquete es imprescindible: mantenlo configurado en todos los hosts.
`warn NET004`	`GET <url> -> 404 Not Found (server may not implement /models)`	Ninguna; el endpoint es accesible y la prueba de inferencia que se describe a continuación es la verdadera comprobación.
`warn CFG002`	`skipped: API key env var '<VAR>' is not set`	Define la variable (consulta la sección anterior).
`FAIL NET006`	`GET <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	La variable está definida, pero su valor no es válido para este endpoint.
`FAIL NET004`	`GET <url> -> <status>`	Revisa el registro del endpoint y la ruta de `base_url`.
`FAIL NET001` / `NET002` / `NET005`	Cadena de errores de DNS, TCP o tiempo de espera	Comprueba la resolución de nombres, las reglas del firewall y del proxy, y el estado del endpoint desde la misma estación de trabajo.
`FAIL NET003`	Cadena de errores TLS, seguida del certificado que presentó el servidor (sujeto, emisor, caducidad) y, por último, `TLS failed despite the configured DEVIN_CA_BUNDLE (<path>) — verify the bundle contains this endpoint's CA` o `if this endpoint uses a private CA, set DEVIN_CA_BUNDLE=/path/to/ca.pem`	Compara el emisor mostrado con los certificados de tu paquete; consulta Red y certificados.

`model '<name>': inference conformance`

Se omite si la comprobación de accesibilidad falló a nivel de transporte. Envía una solicitud de un solo token para verificar que el endpoint admite la API configurada: POST {base_url}/chat/completions con max_tokens: 1 para chat_completions, o POST {base_url}/responses con max_output_tokens: 16 para responses.

Resultado	Detalle	Acción
`pass`	`POST <url> -> 200 OK (<n> ms)`	Ninguna. La latencia sirve como línea base para comparaciones posteriores.
`FAIL NET006`	`POST <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	Corrige la clave.
`FAIL NET004`	`POST <url> -> <status>: <first 200 characters of the response body>`	El cuerpo de la respuesta suele indicar el problema: un nombre de modelo desconocido (la solicitud usa el `name` de tu archivo de modelos, que debe coincidir con lo que ejecuta el servidor), un valor de `api` incorrecto para este servidor o un error server-side.
`FAIL NET00n`	Cadena de errores de transporte	Igual que en la comprobación de accesibilidad.

Problemas comunes

Síntoma	Causa probable	Dónde consultar
Doctor se completa correctamente en un terminal, pero Desktop no puede conectarse con el modelo	El agente incluido en Desktop no hereda el entorno de tu shell, por lo que la variable de la clave de API no está definida	Variables de entorno de la clave de API
Todos los usuarios de un host pasan la comprobación excepto uno	Estado por usuario: permisos de `~/.config/devin` o `~/.local/share/devin` (`%APPDATA%\devin` en Windows), o un `sso_tokens.toml` obsoleto (`IDP006`)	Formatos en disco
`devin auth login` funciona, pero las sesiones terminan al cabo de un tiempo	La revalidación ha fallado: se eliminó al usuario de `required_group` o se revocó la sesión del IdP	SSO y el evento de auditoría `sso_revalidation_failed`
`NET003` solo en algunos hosts	`DEVIN_CA_BUNDLE` no está definida en esos hosts o apunta a un paquete distinto	Red y certificados
`LIC004` después de instalar una actualización o en un entorno nuevo	La compilación y la licencia proceden de entornos distintos, o se ha producido una rotación de clave	Licencia: comprueba el ID de clave
`MDL014` al guardar modelos en Desktop	El archivo de modelos pertenece a root o a otro usuario (en Windows, a un administrador, mientras que tú eres un usuario estándar)	Edita el archivo en disco como su propietario

Qué enviar al soporte

Recopila lo siguiente en la estación de trabajo afectada. Revisa cada archivo antes de enviarlo; ninguno se sube automáticamente.

La salida de doctor:
devin airgap doctor --json > doctor.json
(no output; the command exits nonzero if a check failed)
Las cadenas de detalle contienen las URL de tus endpoints y tus nombres de host, pero nunca los valores de las claves de API.
El informe de diagnósticos con datos confidenciales ocultos:
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.
El informe recoge las versiones, si cada archivo de configuración existe y se puede analizar, los nombres de los modelos, si cada variable de clave de API está definida y estadísticas del registro de auditoría. Nunca incluye prompts, código, contenido de archivos, valores secretos, URL de endpoints ni valores de variables de entorno.
El mensaje de error exacto que se mostró al usuario, incluido su código, y la salida de devin --version.
Para problemas de SSO, los eventos auth pertinentes del registro de auditoría (campos error_code y action) y las entradas correspondientes del registro de tu IdP.

No envíes el archivo de licencia, los valores de las claves de API, sso_tokens.toml ni sessions.db.

​Ejecutar doctor

​Referencia de comprobaciones

​license

​models file path

​config dir writable y 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 comunes

​Qué enviar al soporte

Ejecutar doctor

Referencia de comprobaciones

`license`

`models file path`

`config dir writable` y `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 comunes

Qué enviar al soporte