Solución de problemas y preguntas frecuentes

Encabezados en forma de pregunta para que encuentres tu caso rápido.

Novedades en v1.6.0

Casos nuevos o cambiados: dos copias de odoo-tools (con odoo_version sin bloque policy), un comando /plugin escrito en PowerShell, Failed to connect en Windows sin python3, el contexto pasado por posición, que en Odoo 10 a 12 ya revisa también las claves que no son campos del modelo, un sandbox que nunca arrancaba por una contraseña que empezaba con "-", y el estado not_started de la app en Cowork y Claude chat, con la sesión local de la pestaña Code y quién necesita permisos de administrador.

Novedades en v1.5.1

Casos nuevos o cambiados: el aviso de inicio de sesión sobre Cowork y Claude chat (reemplaza el aviso de opciones faltantes), el aviso de la política bloqueada en el último arranque, el contexto pasado por posición y el reporte de soporte.

Novedades en v1.5.0

Casos nuevos de la política de permisos: un rechazo de la política, las herramientas que ya no aparecen, la política bloqueada, cómo volver al comportamiento de la 1.4, los campos retenidos, los correos de salida, las claves default_ de contexto y el registro de auditoría. Además, odoo_report devuelve un error.

Novedades en v1.4.1

Casos nuevos: el panel vacío «Runs in each session», el aviso de opciones faltantes (reemplazado en la v1.5.1) y el error de hook en Windows sin Git Bash.

Novedades en v1.4.0

Casos nuevos: el transport_notice de Odoo 19, el límite de llamadas (HTTP 429), las importaciones rechazadas en XML-RPC y los PDF de reportes.

Una llamada se rechaza con «the odoo-tools permission policy refuses»

Desde la v1.5.0, la política de permisos decide cada llamada encima de los derechos del usuario de Odoo. El rechazo nombra la operación, el modelo, el perfil y la regla (por ejemplo rule profile:standard o rule tier:security), y dice qué lo cambia. Si termina en Nothing was sent to Odoo., se decidió antes de iniciar sesión; si termina en The call was stopped before Odoo ran it, lo detuvo la revisión de la llamada real, y Odoo no cambió nada.

• Es definitivo para el agente: Claude te lo explica y no busca otro camino (otra herramienta, la CLI de respaldo o la shell). Decides tú.
• Para cambiarlo: elige otro perfil en /plugin → odoo-tools → Configure options → Permission profile, o agrega una regla en tu archivo de política, y reconecta el servidor (/mcp).
• Para saber por qué antes de llamar, revisa la decisión sin conexión: python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-policy "" --profile standard --explain res.partner:unlink.
• odoo_access_check muestra lado a lado lo que permite Odoo y lo que permite la política.
• Un rechazo con regla envelope es un error de odoo-tools, no una decisión de la política: repórtalo a dev@transgenia.org.

No aparecen odoo_unlink, odoo_add_field u odoo_add_automation

Con el perfil por defecto standard, esas tres herramientas no se listan (standard lista 25 de las 28). Para borrar, archiva con odoo_write {"active": false}; para campos y automatizaciones en un sandbox o en staging, elige el perfil builder; para todo lo que permite el usuario de Odoo, full. Con el perfil readonly o con Read-only mode activo, ninguna de las 9 herramientas de escritura se lista. Ver Herramientas que lista cada perfil.

Solo aparece odoo_version: la política está bloqueada

Un perfil desconocido, una ruta de archivo de política relativa o un archivo inválido bloquean el servidor: solo se lista odoo_version, que devuelve el bloque policy con error y error_code sin contactar a Odoo, y las demás herramientas se rechazan. En Claude Code, el hook de inicio de sesión lo lee en el diagnóstico local del último arranque del servidor y te avisa como máximo una vez al día con un mensaje como odoo-tools: the permission policy locked the Odoo tools at the last server start (E15). ...; pídele a Claude que llame a odoo_version para ver el motivo.

1. Revisa el archivo sin conexión: python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-policy /ruta/absoluta/policy.json (sale con 1 y nombra el error, por ejemplo E15 cuando una apertura de un modelo sensible no trae reason).
2. Corrige el archivo, o las opciones Permission profile / Permission policy file (la ruta debe ser absoluta).
3. Reconecta el servidor con /mcp.

La tabla de códigos E1 a E20, W1 a W7 y W10 está en Errores de carga y advertencias.

¿Cómo vuelvo al comportamiento de la 1.4?

Pon Permission profile en full (ODOO_POLICY=full en un contenedor o en modo standalone) y reconecta el servidor. full permite todo lo que permite el usuario de Odoo, salvo crear, cambiar o revocar API keys y desinstalar módulos. Para hacer cumplir esos dos rechazos, full también rechaza una llamada cuyos argumentos no puede leer con certeza (regla shape: pasa los argumentos por nombre) o cuyos modelos relacionados no puede consultar con fields_get (regla unverified). Ver Perfiles.

Un resultado trae policy_withheld_fields

Fuera de full, los campos con aspecto de credencial (contraseñas, tokens, llaves, como l10n_mx_edi_pac_password o signup_token) se retiran de lo que devuelven las lecturas, y el resultado los nombra en policy_withheld_fields para que nada desaparezca en silencio. Pedirlos en una lista de campos, un filtro, una agrupación o un orden se rechaza. Un archivo de política puede liberar un campo exacto con fields.allow y una razón, o retener más con fields.withhold. Ver Campos con aspecto de credencial.

message_post se rechaza bajo standard

Los métodos que envían datos fuera (message_post a contactos, message_subscribe, send_mail y otros) se rechazan bajo readonly, standard y builder. Una nota interna sí corre: message_post con subtype_xmlid "mail.mt_note" (Odoo 13+; subtype en 10-12), sin partner_ids. Para responder a clientes desde el chatter, usa full, o una entrada del archivo de política que nombre el modelo exacto con "call": ["message_post"] y una razón (ver el ejemplo sales-team.json en Ejemplos).

Un asistente se rechaza por una clave default_ de contexto

Comportamiento en la v1.5.0

Bajo readonly, standard y builder, una clave de contexto default_<campo> cuyo valor es una lista o un objeto se rechaza (regla context) antes de enviar nada a Odoo. Le pasa, por ejemplo, al asistente de backorder de manufactura creado por odoo_execute con las claves default_mrp_production_ids y default_mrp_production_backorder_line_ids de su acción. Pasa esos valores en los values del registro (mrp_production_ids: [(6, 0, [id])] y las líneas con (0, 0, {...})), o pick_ids: [(4, id)] para el asistente de backorder de inventario. Ver Claves de contexto.

Las claves de contexto que necesitan los asistentes de validación de inventario y manufactura (button_validate_picking_ids, skip_backorder, etc.), el validate_analytic del botón de publicar factura y el uid del cliente web están permitidas.

Una llamada se rechaza por un contexto pasado por posición

Odoo 10 a 12 también toman el contexto de una llamada del argumento posicional que sigue a los parámetros del método. Desde la v1.5.1, la política lee ese argumento como contexto y le aplica las reglas de contexto: en la capa A en todas las series, antes de saber la versión, y en 10 a 12 otra vez en la sesión vigilada. Con un método que la política no conoce, como action_confirm, revisa las claves default_<campo> de cada objeto pasado por posición y, desde la v1.6.0, en Odoo 10 a 12 también sus demás claves, con los campos del modelo: una clave que es campo del modelo se revisa como un valor del método, una clave de contexto permitida pasa, y cualquier otra, como tracking_disable, se rechaza (regla context). Si los campos del modelo no se pueden leer, la llamada se rechaza (regla unverified). El rechazo nombra la clave, nunca su valor.

Pasa el contexto por nombre, en kwargs ("kwargs": {"context": {...}}), y los demás argumentos del método también por nombre, o pon los valores en los values del registro. Lo que queda en Odoo 10 a 12, una clave de contexto con el nombre de un campo del modelo, está en el límite conocido 10.

¿Cómo reviso el registro de auditoría?

Los archivos diarios están en la carpeta de datos del plugin (~/.claude/plugins/data/…/audit/odoo-tools-audit-AAAA-MM-DD.jsonl). Para revisar la cadena de hashes de un archivo:

python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --verify-audit ARCHIVO

Sale con 0 si la cadena se sostiene, con 1 en la primera línea editada, reordenada o insertada (o una última línea incompleta), y con 2 si no puede leer el archivo. Ver Registro de auditoría.

Dos copias de odoo-tools, o una anterior a la 1.5.0

Las señales:

• odoo_version responde sin un bloque policy (y sin note): respondió un odoo-tools anterior a la 1.5.0, sin política de permisos, perfil ni registro de auditoría. La ruta guiada y /odoo-tools:odoo-doctor se detienen ahí, antes de cualquier escritura.
• Configure options no muestra Permission profile: el diálogo edita una copia anterior a la 1.5.0.
• La pestaña Errors del plugin dice Plugin option "odoo_url" isn't set para una copia que nunca configuraste. Ese mensaje es de Claude Code, no de odoo-tools: la copia que nombra (la muestra claude plugin list) no tiene opciones guardadas.

Suele ser una segunda copia: por ejemplo una del directorio de plugins de Claude en una carpeta de proyecto, que puede ser más antigua (el directorio publica una versión después de que Anthropic la revisa), y otra del marketplace de Transgenia para tu usuario. Entonces las opciones que guardas pueden ir a una copia mientras responden las herramientas de la otra.

1. Dentro de Claude Code, corre /odoo-tools:odoo-doctor: nombra la copia que conservar e imprime los comandos exactos que dejan una sola copia actual. Desde la v1.6.0, odoo_version nombra la copia que responde (plugin.copy).
2. Corre esos comandos en una terminal (PowerShell, Terminal o bash), no como comandos /plugin: un cd a la carpeta del proyecto y claude plugin uninstall <id> --scope <alcance> o, para una copia antigua del marketplace de Transgenia, claude plugin marketplace update transgenia-odoo-tools y claude plugin update odoo-tools@transgenia-odoo-tools --scope <alcance>. Sin el doctor, claude plugin list muestra cada copia con su versión y su alcance.
3. Reinicia Claude Code (o corre /reload-plugins dentro de él) y vuelve a llamar a odoo_version: la respuesta trae plugin y policy.

La copia del directorio es odoo-tools@anthropic-plugin-directory; no existe odoo-tools@claude-plugins-official. Las dos revisiones y cómo leer su salida: Dos copias de odoo-tools.

PowerShell no reconoce /plugin ni claude

Un comando /plugin se escribe dentro de una sesión de Claude Code, nunca en PowerShell: escrito en la terminal, falla con un error de comando no reconocido (not recognized). En una terminal, la forma es claude plugin:

claude plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online --scope user

Si claude tampoco se reconoce justo después de instalar Claude Code, abre una ventana nueva de PowerShell: una ventana abierta antes de la instalación no ve el PATH nuevo. El instalador nativo de Claude Code deja claude.exe en %USERPROFILE%\.local\bin. Pasa lo mismo después de instalar Git o Python (where.exe git no encuentra nada en la ventana vieja): abre una ventana nueva y reinicia Claude Code. Ver Instalación.

Las herramientas de Odoo no aparecen (panel vacío en «Runs in each session»)

El síntoma habitual, en Cowork o en claude.ai: el plugin se instala y aparece activo, su pestaña Connectors muestra la fila odoo con la leyenda Runs in each session, y al abrirla ves un panel vacío, sin campos que llenar. En claude.ai en la web, el menú de tres puntos del plugin ofrece acciones como quitarlo, editarlo con Claude o duplicarlo, y ningún lugar para las opciones de conexión. No es una instalación rota, y nada está mal con tu cuenta, tu Odoo ni tu Python. Esa fila es el servidor MCP local del plugin: la documentación de Anthropic indica que en la web la pestaña Connectors marca así un servidor MCP local mientras el chat no lo arranca, y no hay formulario porque esas apps no piden opciones de plugin. Según la matriz de soporte de plugins de Anthropic, Cowork ignora un servidor MCP cuyas opciones obligatorias no tienen valor por defecto, y Claude chat ignora el servidor MCP local de un plugin. Las skills y los comandos sí cargan, pero sin las herramientas no alcanzan Odoo. Si la app muestra el servidor del plugin con el estado not_started y el motivo user_config_unsupported, es este mismo caso (ver abajo).

1. Usa Claude Code en tu equipo (terminal, VS Code o JetBrains, o una sesión local de la pestaña Code de Claude Desktop). Un plugin instalado en tu cuenta de Claude aparece ahí como plugin sincronizado al iniciar la siguiente sesión si entras a Claude Code (2.1.273 o posterior) con esa cuenta de claude.ai; si no aparece, corre /reload-plugins o instálalo con los comandos de Instalación. No necesitas permisos de administrador: el instalador nativo de Claude Code lo deja en tu carpeta personal (~/.local/bin/claude en macOS y Linux), y en Windows la guía de Anthropic dice que no hace falta correrlo como administrador. En un plan Team o Enterprise, tu organización decide qué plugins recibes y si la pestaña Code ofrece sesiones locales (si no las ofrece, la entrada de tu equipo aparece en gris, con el aviso Disabled by your organization).
2. Captura ahí las opciones: /plugin configure <id> en una sesión, o /plugin → odoo-tools → Configure options (en VS Code, el engrane en la fila del plugin). <id> es el identificador completo nombre@marketplace que muestra claude plugin list (por ejemplo odoo-tools@synced). En un equipo sin interfaz (Claude Code 2.1.285 o posterior), usa claude plugin configure <id> --json y --values-stdin (ver Instalación) y reinicia Claude Code.
3. ¿Sin Claude Code en ese equipo? En Cowork, la CLI de respaldo (/odoo-tools:odoo-setup-cli) puede funcionar cuando la sesión puede correr Node, alcanzar tu Odoo, y tú puedes editar el .env de la CLI; usa una API key dedicada, de mínimo privilegio y de corta duración. Claude chat no tiene un lugar seguro para capturar la key: usa Claude Code. (En Claude Code sin Python, usa el modo contenedor de /odoo-tools:deploy-local.)
4. ¿Sigues bloqueado? Corre /odoo-tools:odoo-doctor: termina con un reporte de soporte que puedes enviar a Transgenia, que también ofrece configuración asistida (ver Soporte). Transgenia nunca te pide tu API key ni tu contraseña por chat o correo.

Cowork y Claude chat sí aceptan conectores MCP que agregas tú (un servidor MCP remoto por URL https, o una extensión de escritorio en la app de Claude Desktop), pero este plugin no provee ninguno: sus herramientas necesitan el servidor local.

La app muestra not_started con el motivo user_config_unsupported

La app de Claude puede reportar el servidor de este plugin con el estado not_started y el motivo user_config_unsupported. Es el caso de Cowork y Claude chat de la matriz de soporte de plugins de Anthropic: Cowork no pide opciones de plugin e ignora un servidor MCP local cuyas opciones no tienen valor por defecto, y Claude chat ignora el servidor MCP local de un plugin. Es lo esperado, igual en macOS que en Windows: no es una falla del plugin ni de la app, y ninguna actualización del plugin lo cambia. /odoo-tools:odoo-doctor lo reconoce y pone en su reporte de soporte el estado tal como lo mostró la app, con la versión de la app.

La salida es una sesión local de la pestaña Code de Claude Desktop, o Claude Code en tu equipo (terminal, VS Code o JetBrains), con los pasos de arriba. Una sesión en la nube de la pestaña Code (o claude.ai/code) no sirve: el plugin se sincroniza desde tu cuenta, pero sus opciones no, porque Claude Code las guarda en el equipo donde las capturaste (la API key y la contraseña, en el almacén seguro de credenciales de ese equipo), así que el servidor no arranca en la nube.

Quién necesita permisos de administrador:

• Claude Code, no: su instalador nativo lo deja en tu carpeta personal (~/.local/bin/claude en macOS y Linux), y en Windows la guía de Anthropic dice que no hace falta correrlo como administrador.
• macOS: python3 viene con las Command Line Tools de Apple (xcode-select --install). Si tu Mac pide un administrador para instalarlas y no lo eres, tu equipo de TI puede instalarlas, o pide a Transgenia una configuración asistida.
• Planes Team o Enterprise: tu organización decide qué plugins recibes y si la pestaña Code ofrece sesiones locales. Si no las ofrece, la entrada de tu equipo aparece en gris, con el aviso Disabled by your organization.

Buscar una actualización no cambia este caso. El directorio de plugins de Claude publica una versión solo después de que Anthropic la revisa, así que buscar actualizaciones en las apps de Claude no encuentra una versión más nueva hasta entonces; y en Cowork y Claude chat ninguna versión corre las herramientas de Odoo.

Al iniciar sesión: «In Cowork and Claude chat this plugin's Odoo tools do not run»

Desde la v1.5.1, el hook de inicio de sesión del plugin (hooks/session_start.py, que reemplaza a hooks/check_options.py) revisa el diagnóstico local del servidor MCP. Cuando los últimos 14 días no registran ni una conexión exitosa a Odoo ni un arranque del servidor con todos los datos de conexión (URL, base de datos, login y una API key o contraseña), te muestra este aviso al iniciar una sesión nueva, como máximo una vez al día:

odoo-tools: In Cowork and Claude chat this plugin's Odoo tools do not run, whatever Python or options. Open a local session of the Code tab of Claude Desktop (the plugin is synced there when you sign in with the same account) or Claude Code, or ask for assisted setup by Transgenia: dev@transgenia.org, WhatsApp +52 55 8034 0405. In Claude Code, set the connection in /plugin > odoo-tools > Configure options. /odoo-tools:odoo-doctor diagnoses.

En cada inicio de sesión también se lo explica a Claude: que nada está mal con tu cuenta, tu Odoo ni tu Python, que ninguna actualización del plugin cambia este caso, y que te ofrezca, en este orden, una sesión local de la pestaña Code de Claude Desktop o Claude Code, y la configuración asistida de Transgenia; después, dónde se capturan las opciones en Claude Code y el doctor. Termina con una línea odoo-tools session diagnostics: que /odoo-tools:odoo-doctor usa para su reporte de soporte.

En la primera sesión después de instalar o actualizar el plugin, cuando todavía no hay registros del hook, el aviso va solo a Claude, porque el servidor de esa sesión quizá no escribió aún su arranque; lo mismo pasa donde el hook no tiene una carpeta de datos del plugin para limitar el aviso a una vez al día.

• En Cowork o Claude chat: las herramientas de Odoo no corren ahí. Abre una sesión local de la pestaña Code de Claude Desktop (o Claude Code), donde el plugin aparece sincronizado cuando entras con la misma cuenta, o pide a Transgenia una configuración asistida (ver Soporte).
• En Claude Code: captura la URL, la base de datos, el login y la API key en /plugin → odoo-tools → Configure options y reinicia Claude. El aviso deja de aparecer cuando el diagnóstico registra un arranque del servidor con todos los datos de conexión o una conexión exitosa.
• El hook no lee ninguna opción del plugin ni credencial: solo la carpeta de datos del plugin (el diagnóstico del servidor) y el nombre de la app de Claude que inició la sesión. Ver Seguridad.
• Si llegas a Odoo por otro conector de Odoo, aparte de este plugin, el aviso no aplica.
• Con el modo contenedor de /odoo-tools:deploy-local, una marca en la carpeta de datos del plugin lo calla (ver Despliegue local).

Windows: error de hook SessionStart al iniciar sesión

Los hooks de inicio de sesión del plugin son comandos de shell y necesitan Git for Windows (Git Bash). Sin él, Claude Code los corre en PowerShell, donde fallan con un error de hook SessionStart. Instala Git for Windows; si ya lo tienes y Claude Code no lo encuentra, define CLAUDE_CODE_GIT_BASH_PATH con la ruta de Git Bash. El servidor MCP no se ve afectado: las herramientas de Odoo siguen funcionando, solo faltan los avisos de inicio de sesión.

Windows: claude mcp list dice Failed to connect con Connection closed

Es la señal de que falta el comando python3: el instalador de python.org solo crea python.exe y py.exe, Claude Code lanza el servidor del plugin con python3, y nada en el mensaje menciona a Python. Pon un python3.exe junto a python.exe con un enlace duro, en PowerShell:

$python = (Get-Command python -ErrorAction Stop).Source
New-Item -ItemType HardLink -Path (Join-Path (Split-Path $python) "python3.exe") -Target $python

• Necesita permiso de escritura en la carpeta de Python: para una instalación en C:\Program Files, abre PowerShell como administrador.
• Si Get-Command python no encuentra nada, o encuentra un archivo dentro de WindowsApps, Python no está en el PATH: vuelve a correr el instalador de python.org y marca "Add python.exe to PATH", o instala el Python de Microsoft Store, que incluye python3.exe.

Después reinicia Claude Code. La CI comprueba esta solución en Windows (windows-launch.yml, con Claude Code 2.1.314): con el enlace duro, claude mcp list muestra el servidor conectado; sin python3.exe, muestra Failed to connect con Connection closed. Más casos en python3 no se encuentra o es demasiado antiguo.

¿Las API keys funcionan con /jsonrpc en Odoo 17 o superior?

Sí. Odoo acepta las API keys igual en /jsonrpc que en XML-RPC: ambos endpoints pasan por el mismo dispatch_rpc (Odoo 14 a 19), y se comprobó en vivo en un Odoo 18.0. Si un proxy o gateway delante de Odoo bloquea o altera /jsonrpc, el transporte auto hace fallback a XML-RPC (lo fija tras el primer fallback y avisa una vez). Para forzarlo, pon la opción del plugin Transport preference en xmlrpc (en modo standalone: ODOO_TRANSPORT_PREF=xmlrpc). En Odoo saas~18.4 / 19.0+ con una API key, auto usa primero JSON-2 (ver Compatibilidad).

Si la key falla por los dos caminos, el problema es la key: revisa que no haya caducado ni se haya revocado, y que el Odoo login sea el del usuario que la creó.

XML-RPC y JSON-RPC, obsoletos desde Odoo 19

Odoo 19 marca /xmlrpc, /xmlrpc/2 y /jsonrpc como obsoletos y los retira en Odoo 22 y en Odoo Online saas~21.1; su reemplazo es la API JSON-2, que el plugin usa desde la v1.4.0 cuando hay una API key. Los endpoints clásicos funcionan en todas las versiones que soporta el plugin (10 a 19).

odoo_version devuelve un transport_notice en Odoo 19

La conexión usa los endpoints obsoletos /xmlrpc o /jsonrpc en Odoo 19+, y cada llamada deja una advertencia en el log de Odoo. El aviso trae su propia solución; normalmente es una de estas:

• crea una API key (Preferencias → Account Security) y ponla en la opción Odoo API key del plugin (JSON-2 no acepta contraseña);
• quita user:pass@ de la Odoo URL (esa autenticación básica ocupa la cabecera Authorization que JSON-2 necesita);
• vuelve a poner Transport preference en auto.

Desde Odoo 22 / saas~21.1 una conexión solo con contraseña deja de funcionar (ConfigError).

Recibo "database not found"

El nombre de la base de datos es incorrecto. Revísalo en Settings → Database o en la URL de login. La opción Odoo database del plugin (o ODOO_DB en modo standalone) debe coincidir exactamente.

Mi Odoo Online/SaaS no conecta con credenciales correctas

El acceso RPC externo solo existe en suscripciones con API habilitada (planes Custom). En planes sin API externa verás errores de conexión/autenticación aunque usuario y key sean correctos: confirma tu plan con tu panel de Odoo y verifica con odoo_version.

• En Odoo Online la única credencial que funciona es una API key: los usuarios entran por odoo.com, a menudo con 2FA.
• Desde Odoo 18 las API keys caducan: un usuario que no es administrador obtiene como máximo 1 día, salvo que alguno de sus grupos permita más. Si la conexión dejó de funcionar de un día para otro, crea una key nueva. odoo_online_profile muestra cuándo caduca cada key (solo nombres y fechas).

Un campo aparece en dropped_fields y no en el resultado

Ese campo no existe en la versión destino. Es el comportamiento esperado: en lugar de fallar toda la consulta, el servidor descarta el campo no disponible y lo reporta. Consulta la tabla de Compatibilidad para el nombre moderno equivalente (p. ej. analytic_account_id → analytic_distribution en v16).

Obtengo un CompatError sobre un modelo Enterprise

Estás consultando un modelo exclusivo de Enterprise (p. ej. helpdesk.ticket, sign.request) contra una instancia detectada como Community. El sondeo de módulos en tiempo de ejecución es la autoridad: si el módulo no está instalado, el modelo no está disponible.

¿Necesito API key o puedo usar contraseña?

• Odoo ≥ 14: usa una API key (recomendado): opción Odoo API key del plugin (ODOO_API_KEY en modo standalone).
• Odoo < 14: no hay API keys; usa la opción Odoo password (ODOO_PASSWORD en modo standalone).

Define una de las dos.

Actualicé desde la v1.0.0 y el plugin ya no conecta

Desde la v1.1.0 el plugin ya no lee variables ODOO_* de tu shell: usa opciones del plugin. Captura tus valores una vez en /plugin → odoo-tools → Configure options y reinicia Claude. Después puedes quitar los export ODOO_* de tu perfil de shell (siguen siendo válidos solo para el servidor standalone). Ver Instalación.

python3 no se encuentra o es demasiado antiguo

Desde la v1.2.0 el plugin lanza el servidor MCP con python3 (ya no con uv) y necesita Python 3.9 o superior, sin paquetes adicionales. Si el servidor odoo no arranca (o aparece como fallido en /mcp), corre python3 --version en una terminal:

• El comando no existe: instala Python 3.9+. En macOS, xcode-select --install (Command Line Tools) trae python3; si tu Mac pide un administrador para instalarlas y no lo eres, tu equipo de TI puede instalarlas, o pide a Transgenia una configuración asistida. En Linux, instala el paquete python3 de tu distribución.
• Versión menor a 3.9: el servidor termina con odoo-tools: Python 3.9 or newer is required (found X.Y.Z). Actualiza Python o pon una versión más nueva antes en el PATH desde el que arrancas Claude.
• Windows: el comando debe llamarse python3. El Python de Microsoft Store incluye python3.exe; los instaladores de python.org solo crean python.exe y el lanzador py.exe, así que python3 no existe, y claude mcp list reporta el servidor como Failed to connect con Connection closed. Instala el Python de Microsoft Store o pon un python3.exe en el PATH (una copia o enlace duro de python.exe en la misma carpeta; el comando está en Windows: claude mcp list dice Failed to connect). Un alias de PowerShell o doskey no basta: Claude Code lanza el comando directamente, no a través de tu shell. Si al escribir python3 se abre la Microsoft Store en lugar de mostrar una versión, es el alias de ejecución de aplicaciones de Windows: instala el Python de Microsoft Store o desactiva la entrada python3.exe en Alias de ejecución de aplicaciones (Configuración de Windows) para que se encuentre tu propio python3.exe.

Después reinicia Claude para que el servidor MCP se lance con ese python3. Si no puedes instalar Python, usa la CLI de respaldo.

Al iniciar sesión, el primer hook del plugin también te avisa cuando python3 no se puede ejecutar (odoo-tools: python3 is not runnable on this computer. ...). En Cowork y Claude chat las herramientas de Odoo no corren con ni sin Python: ahí la solución no es instalarlo (ver ¿Funciona en Cowork o en Claude chat?).

Error de certificado TLS (CERTIFICATE_VERIFY_FAILED)

Desde la v1.2.0 ambos transportes verifican el certificado de tu Odoo contra el almacén de confianza del sistema (respetan SSL_CERT_FILE) y, si el paquete opcional certifi está instalado para ese python3, también contra su lista de CA. Si tu Python no tiene un archivo de CA propio (p. ej. los builds de python.org para macOS antes de correr Install Certificates.command), el servidor carga automáticamente el paquete de CA del sistema operativo. Si aun así falla (p. ej. tu Odoo usa una CA interna), agrega esa CA al almacén del sistema, apunta SSL_CERT_FILE a un paquete de CA o instala certifi. No desactives la verificación TLS.

Recibo Input validation error: ...

La herramienta recibió argumentos incorrectos o con otro nombre: falta uno requerido, hay uno desconocido o mal escrito, o su tipo no coincide. Desde la v1.2.0 el servidor valida los argumentos contra el esquema de cada herramienta y rechaza la llamada antes de tocar Odoo. Revisa nombres y tipos en la Referencia de herramientas y vuelve a intentarlo.

Un error de transporte termina en "may or may not have been applied in Odoo; check before retrying"

La llamada (crear, modificar o cualquier otro execute_kw) pudo haberse aplicado en Odoo aunque no llegó la respuesta: se agotó el tiempo de espera, o Odoo (o un proxy delante de él) respondió HTTP 5xx. En modo auto, el servidor ya no la repite por XML-RPC, para no duplicar registros. Antes de reintentar, revisa en Odoo si el registro se creó o cambió.

Las llamadas largas fallan por tiempo de espera

Cada llamada a Odoo espera como máximo ODOO_TIMEOUT segundos (120 por defecto, el limit_time_real por defecto de Odoo). Para operaciones más largas (reportes, exportaciones grandes), sube la opción del plugin Request timeout (de 5 a 3600 s; en modo standalone: ODOO_TIMEOUT) y reinicia Claude. Si la llamada que agotó el tiempo era una escritura, revisa primero el punto anterior.

Recibo HTTP 429 o «retry later»

Odoo (sobre todo Odoo Online, con alrededor de 1 llamada por segundo) limitó las llamadas. Desde la v1.4.0 un HTTP 429 nunca cambia de transporte: las lecturas esperan lo que indica Retry-After (máximo 30 s, 3 intentos) y reintentan por el mismo transporte; las escrituras se reportan para que las reintentes más tarde. Dosifica el trabajo masivo, sin llamadas en paralelo, y usa odoo_import (máximo 500 filas por llamada) en lugar de un odoo_create por registro.

odoo_import u odoo_import_preview se rechazan en XML-RPC

Las herramientas de importación solo corren por JSON-RPC o JSON-2: el XML-RPC de Odoo no puede devolver los valores vacíos que trae el resultado de una importación, y una importación guardada podría reportarse como error. Una sesión en XML-RPC (Odoo 10-11, o Transport preference en xmlrpc) las rechaza antes de enviar nada. Vuelve a auto o usa jsonrpc/json2. odoo_import_preview necesita Odoo 16+ y odoo_import Odoo 12+. Con Read-only mode activo, o con el perfil readonly, ambas dejan de listarse y se rechazan.

odoo_report devuelve un error

Desde la v1.5.0, odoo_report está obsoleta y siempre devuelve un error sin llamar a Odoo: usaba el método privado _render_qweb_pdf, que Odoo rechaza por RPC en todas las versiones, así que nunca funcionó. Se retira en la 2.0.0. Usa odoo_record_documents: lista los adjuntos del registro y devuelve los documentos que Odoo ya guardó, como el PDF de una factura generado al enviarla o imprimirla (marcado desde Odoo 17), hasta 5 MiB. Ver la Referencia de herramientas.

¿Puedo usar una ODOO_URL con user:pass@?

Sí. Si tu Odoo está detrás de autenticación HTTP básica, pon las credenciales en la URL (https://user:pass@odoo.example.com, en la opción Odoo URL o en ODOO_URL). JSON-RPC las envía como cabecera Authorization, y la contraseña nunca aparece en los errores ni en los logs. Ten en cuenta que Odoo URL no es una opción sensitive: esa contraseña se guarda en la configuración del plugin, no en el almacén seguro de credenciales. JSON-2 necesita esa misma cabecera para su API key, así que una URL así se queda en los endpoints clásicos (con un transport_notice en Odoo 19+) y no puede funcionar desde Odoo 22 / saas~21.1, donde esos endpoints ya no existen.

Las herramientas de Odoo aparecen dos veces

Tienes configurados el servidor propio del plugin y el servidor en contenedor odoo-tools-docker de /odoo-tools:deploy-local. Conserva uno: para quitar el contenedor, claude mcp remove odoo-tools-docker, y quita también su marca con rm "${CLAUDE_PLUGIN_DATA}/diagnostics/container-mode", para que el hook de inicio de sesión vuelva a avisar si el servidor del plugin no llega a Odoo.

No tengo Python, solo Node

Usa la CLI de respaldo: /odoo-tools:odoo-setup-cli (Node.js 18+). Si tienes Docker, también puedes correr el servidor MCP como contenedor: /odoo-tools:deploy-local, modo contenedor (Despliegue local).

El sandbox local no arranca

• Docker with Compose is required: instala Docker Desktop o Docker Engine con el plugin compose.
• the Docker engine is not running: abre Docker Desktop (o sudo systemctl start docker) y reintenta.
• Port 8069 ... is already in use: otro Odoo usa el puerto; repite con --port 8070 y usa esa URL en las opciones del plugin.
• Odoo did not answer ...: revisa sandbox logs; en equipos lentos, la primera vez tarda más (sube --timeout).
• already holds an Odoo 18.0 database: cambiaste de versión; usa sandbox destroy --yes o --dir para otra carpeta.
• This sandbox was created with a database password that the Odoo image cannot use: antes de la 1.6.0, alrededor de un sandbox nuevo de cada 64 recibía una contraseña de base de datos que empieza con "-". Desde la 11.0, la imagen de Odoo se la pasa a wait-for-psql.py en su línea de comandos, que la leía como una opción, así que el contenedor de Odoo se reiniciaba sin fin y sandbox up se agotaba con Odoo did not answer. Este mensaje solo sale en un sandbox de Odoo 11.0 o posterior que nunca arrancó: corre sandbox destroy --yes y luego sandbox up otra vez, y no se pierde nada. En la 10.0, la imagen le pasa esa contraseña a Odoo, que la acepta, y un sandbox que ya funcionó nunca se rechaza. Desde la 1.6.0 ninguna contraseña generada empieza con "-", y el mensaje no muestra ninguna parte de la contraseña.

El error menciona /odoo-tools:odoo-setup-mcp y a Transgenia

Desde la v1.3.0, los errores de configuración, autenticación y transporte terminan con el comando para repararlos y los canales oficiales de soporte. Sigue la ruta guiada; si aún falla, escribe a dev@transgenia.org o por WhatsApp al +52 55 8034 0405.

¿Qué envío a soporte cuando algo falla?

Corre /odoo-tools:odoo-doctor: revisa primero si las herramientas de Odoo corren donde estás, luego la conexión, y termina con un reporte de soporte sin API keys, contraseñas, URLs, logins ni datos de registros. Envíalo a dev@transgenia.org o por WhatsApp al +52 55 8034 0405. Ver El reporte de soporte.

¿Cómo verifico que todo quedó bien?

Corre /odoo-doctor o llama a odoo_version. Una respuesta con versión, edición, despliegue y transporte confirma la conexión de extremo a extremo. Desde la v1.4.0 odoo_version inicia sesión primero, así que una API key o contraseña equivocada ya no pasa por conexión correcta. Desde la v1.6.0 la respuesta trae también plugin, con la versión y la copia que respondió; sin un bloque policy, respondió una copia anterior a la 1.5.0 (ver Dos copias de odoo-tools). Ver Conexión y descubrimiento.

¿Los datos de mi empresa se envían a Anthropic?

Dos rutas: el servidor MCP habla directamente con tu Odoo (Transgenia no hace de proxy, no almacena ni ve tus datos), pero los resultados devueltos al agente de IA se envían al proveedor del modelo (p. ej. Anthropic en el caso de Claude) para su procesamiento. Ver Seguridad y Privacidad.

¿Funciona en Cowork o en Claude chat?

Las skills y los comandos del plugin sí cargan ahí, pero las herramientas de Odoo no: corren como servidor MCP local solo en Claude Code. Nada está mal con tu cuenta, tu Odoo ni tu Python: abre una sesión local de la pestaña Code de Claude Desktop, donde el plugin aparece sincronizado con la misma cuenta, o pide a Transgenia una configuración asistida. Ver Dónde funciona, el caso del panel vacío y el estado not_started.

¿Funciona con otros agentes además de Claude?

Sí: con cualquier cliente que implemente el protocolo MCP. Claude Code es el entorno de referencia para el que está empaquetado el plugin.