故障排查与常见问题

以问题形式呈现的标题，便于你快速找到自己的场景。

v1.6.0 新增

新增或更新的场景：两个 odoo-tools 副本（包括没有 policy 块的 odoo_version）、 在 PowerShell 中输入的 /plugin 命令、 没有 python3 的 Windows 上的 Failed to connect、 按位置传递的上下文（在 Odoo 10 至 12 上，不是模型字段的键现在也会被检查）、 一个因密码以 "-" 开头而从未启动的沙箱， 以及 Cowork 和 Claude chat 中 应用的 not_started 状态，连同 Code 标签页中的本地会话和谁需要管理员权限。

v1.5.1 新增

新增或更新的场景：关于 Cowork 和 Claude chat 的会话开始提示（取代缺失选项提示）、 上一次启动时被锁定的策略 的提示、 按位置传递的上下文 以及 支持报告。

v1.5.0 新增

权限策略 带来的新场景：策略的拒绝、 不再出现的工具、 被锁定的策略、 如何 恢复 1.4 的行为、 被屏蔽的字段、 外发邮件、 上下文中的 default_ 键 以及 审计日志。此外，odoo_report 会返回错误。

v1.4.1 新增

新增场景：“Runs in each session” 空面板、 缺失选项提示（已在 v1.5.1 中被取代） 以及 没有 Git Bash 时 Windows 上的 hook 错误。

v1.4.0 新增

新增场景：Odoo 19 上的 transport_notice、 调用频率限制（HTTP 429）、 在 XML-RPC 上被拒绝的导入 以及 报表 PDF。

调用被拒绝，提示 “the odoo-tools permission policy refuses”

自 v1.5.0 起，权限策略 会在 Odoo 用户的权限之上对每次调用做出决定。拒绝信息会点名操作、模型、配置档和规则（例如 rule profile:standard 或 rule tier:security），并说明怎样改变它。如果它以 Nothing was sent to Odoo. 结尾，说明决定是在登录之前做出的；如果以 The call was stopped before Odoo ran it 结尾，说明是对实际调用的检查拦下了它，Odoo 没有做任何更改。

• 对智能体而言这是最终结果： Claude 会向你解释，而不会寻找其他途径（其他工具、备用 CLI 或 shell）。由你来决定。
• 要改变它：在 /plugin → odoo-tools → Configure options → Permission profile 中选择另一个配置档，或在你的策略文件中添加一条规则，然后重新连接服务器（/mcp）。
• 要在调用之前了解原因，请离线检查这个决定： python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-policy "" --profile standard --explain res.partner:unlink。
• odoo_access_check 会并排显示 Odoo 允许什么和策略允许什么。
• 规则为 envelope 的拒绝是 odoo-tools 的缺陷，而不是策略的决定：请报告给 dev@transgenia.org。

odoo_unlink、odoo_add_field 或 odoo_add_automation 没有出现

在默认配置档 standard 下，这三个工具不会被列出（standard 列出 28 个中的 25 个）。要删除，请用 odoo_write {"active": false} 归档；要在沙箱或预发布环境中处理字段和自动化，请选择配置档 builder；要获得 Odoo 用户允许的一切，请选择 full。在配置档 readonly 下，或开启 Read-only mode 时，9 个写入工具都不会被列出。参见 每个配置档列出的工具。

只出现 odoo_version：策略被锁定

未知的配置档、相对的策略文件路径或无效的文件会锁定服务器：只列出 odoo_version，它在不联系 Odoo 的情况下返回带有 error 和 error_code 的 policy 块，其他工具都会被拒绝。在 Claude Code 中，会话开始的 hook 会从上一次服务器启动的本地诊断中读到这一点，并每天最多提示你一次，消息类似 odoo-tools: the permission policy locked the Odoo tools at the last server start (E15). ...；请让 Claude 调用 odoo_version 查看原因。

1. 离线检查文件： python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-policy /绝对路径/policy.json （它以 1 退出并点名错误，例如敏感模型的开放项没有 reason 时为 E15）。
2. 修正文件，或 Permission profile / Permission policy file 选项（路径必须是绝对路径）。
3. 用 /mcp 重新连接服务器。

E1 至 E20、W1 至 W7 以及 W10 的代码表见 加载错误与警告。

如何恢复 1.4 的行为？

把 Permission profile 设为 full（在容器或独立模式下为 ODOO_POLICY=full），然后重新连接服务器。full 允许 Odoo 用户允许的一切，但创建、更改或撤销 API keys 以及卸载模块除外。为了执行这两项拒绝，full 还会拒绝它无法确定读懂参数的调用（规则 shape：请按名称传参），或它无法用 fields_get 查询关联模型的调用（规则 unverified）。参见 配置档。

结果中带有 policy_withheld_fields

在 full 之外，类凭据字段（密码、令牌、密钥，例如 l10n_mx_edi_pac_password 或 signup_token）会从读取结果中移除，结果会在 policy_withheld_fields 中点名它们，因此不会有任何东西悄无声息地消失。在字段列表、过滤条件、分组或排序中请求它们会被拒绝。策略文件可以用 fields.allow 加上理由释放一个精确的字段，或用 fields.withhold 屏蔽更多字段。参见 类凭据字段。

message_post 在 standard 下被拒绝

把数据发送出去的方法（发给联系人的 message_post、message_subscribe、send_mail 等）在 readonly、standard 和 builder 下会被拒绝。内部备注可以运行：subtype_xmlid 为 "mail.mt_note"（Odoo 13+；10-12 上为 subtype）且没有 partner_ids 的 message_post。要在 chatter 中回复客户，请使用 full，或在策略文件中用一个精确点名该模型的条目写上 "call": ["message_post"] 并附上理由（参见 示例 中的 sales-team.json）。

某个向导因上下文中的 default_ 键被拒绝

v1.5.0 中的行为

在 readonly、standard 和 builder 下，值为列表或对象的上下文键 default_<字段> 会在向 Odoo 发送任何内容之前被拒绝（规则 context）。例如，通过 odoo_execute 创建制造欠单（backorder）向导并使用其动作的 default_mrp_production_ids 和 default_mrp_production_backorder_line_ids 键时就会如此。请把这些值放在记录的 values 中传入（mrp_production_ids: [(6, 0, [id])]，明细行用 (0, 0, {...})），库存欠单向导则使用 pick_ids: [(4, id)]。参见 上下文键。

库存和制造验证向导所需的上下文键（button_validate_picking_ids、skip_backorder 等）、发票过账按钮的 validate_analytic 以及网页客户端的 uid 都是允许的。

调用因按位置传递的上下文被拒绝

Odoo 10 至 12 还会把紧跟在方法自身参数之后的那个位置参数当作调用的上下文。自 v1.5.1 起，策略把这个参数当作上下文来读取，并对它应用 上下文规则：在 A 层对所有版本系列都适用（此时还不知道版本），在 10 至 12 上还会在受守卫的会话中再检查一次。对于策略不了解的方法（例如 action_confirm），它会检查每个按位置传递的对象中的 default_<字段> 键；自 v1.6.0 起，在 Odoo 10 至 12 上还会用模型的字段检查它的其他键：是模型字段的键会作为该方法的值来检查，允许的上下文键可以通过，其他任何键（例如 tracking_disable）会被拒绝（规则 context）。无法读取模型的字段时，调用会被拒绝（规则 unverified）。拒绝会点名该键，从不显示它的值。

请按名称在 kwargs 中传递上下文（"kwargs": {"context": {...}}），方法的其他参数也按名称传递，或者把这些值放在记录的 values 中。在 Odoo 10 至 12 上剩下的情况，即与模型某个字段同名的上下文键，见 已知限制 10。

如何检查审计日志？

每日文件位于插件的数据文件夹中（~/.claude/plugins/data/…/audit/odoo-tools-audit-YYYY-MM-DD.jsonl）。要检查一个文件的哈希链：

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

链完整时以 0 退出；在第一处被编辑、被调换顺序或被插入的行处（或最后一行不完整时）以 1 退出；无法读取文件时以 2 退出。参见 审计日志。

两个 odoo-tools 副本，或一个早于 1.5.0 的副本

迹象如下：

• odoo_version 的响应中没有 policy 块（也没有 note）：作出响应的是早于 1.5.0 的 odoo-tools，没有权限策略、配置档或审计日志。引导路线和 /odoo-tools:odoo-doctor 会在那里停止，不做任何写入。
• Configure options 中没有 Permission profile：对话框编辑的是一个早于 1.5.0 的副本。
• 插件的 Errors 标签页对一个你从未配置过的副本显示 Plugin option "odoo_url" isn't set。这条消息来自 Claude Code，而不是 odoo-tools：它点名的副本（claude plugin list 中可以看到）没有保存任何选项。

这通常是第二个副本：例如一个来自 Claude 插件目录、装在某个项目文件夹中，它可能更旧（插件目录在 Anthropic 审核之后才发布一个版本），另一个来自 Transgenia 的 marketplace、装在你的用户范围内。这时你保存的选项可能进入一个副本，而作出响应的却是另一个副本的工具。

1. 在 Claude Code 中运行 /odoo-tools:odoo-doctor：它会点名要保留的副本，并打印只留下一个最新副本的确切命令。自 v1.6.0 起，odoo_version 会点名作出响应的副本（plugin.copy）。
2. 在终端（PowerShell、Terminal 或 bash）中运行这些命令，不要当作 /plugin 命令运行：先 cd 到项目文件夹，再运行 claude plugin uninstall <id> --scope <范围>；对于来自 Transgenia marketplace 的旧副本，则是 claude plugin marketplace update transgenia-odoo-tools 和 claude plugin update odoo-tools@transgenia-odoo-tools --scope <范围>。不借助 doctor 时，claude plugin list 会显示每个副本及其版本和范围。
3. 重启 Claude Code（或在其中运行 /reload-plugins），然后再次调用 odoo_version：响应中会带有 plugin 和 policy。

插件目录的副本是 odoo-tools@anthropic-plugin-directory；不存在 odoo-tools@claude-plugins-official。两项检查以及如何阅读它们的输出：两个 odoo-tools 副本。

PowerShell 无法识别 /plugin 或 claude

/plugin 命令要在 Claude Code 会话中输入，绝不在 PowerShell 中输入：在终端中输入时，它会以“无法识别”（not recognized）的错误失败。在终端中，对应的形式是 claude plugin：

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

如果刚安装 Claude Code 后也无法识别 claude，请打开一个新的 PowerShell 窗口：安装之前打开的窗口看不到新的 PATH。Claude Code 的原生安装程序把 claude.exe 放在 %USERPROFILE%\.local\bin 中。安装 Git 或 Python 之后也是如此（在旧窗口中 where.exe git 什么也找不到）：请打开一个新窗口并重启 Claude Code。参见 安装。

Odoo 工具没有出现（“Runs in each session” 面板为空）

常见症状（在 Cowork 或 claude.ai 上）：插件已安装并显示为启用，它的 Connectors 标签页显示 odoo 一行并带有 Runs in each session 字样，打开后是一个空面板，没有可填写的字段。在 claude.ai 网页版上，插件的三点菜单提供删除、用 Claude 编辑或复制等操作，但没有填写连接选项的地方。这不是安装损坏，你的账户、你的 Odoo 和你的 Python 也都没有问题。 这一行就是插件的本地 MCP 服务器：Anthropic 的文档指出，在网页版中，Connectors 标签页会这样标记本地 MCP 服务器，而聊天并不会启动它；之所以没有表单，是因为这些应用不会提示输入插件选项。根据 Anthropic 的插件支持矩阵，Cowork 会忽略必需选项没有默认值的 MCP 服务器，Claude chat 会忽略插件的本地 MCP 服务器。Skills 和命令会加载，但没有这些工具就无法访问 Odoo。如果应用把插件的服务器显示为状态 not_started、原因 user_config_unsupported，也是同一种情况（参见 下文）。

1. 使用你电脑上的 Claude Code（终端、VS Code 或 JetBrains，或 Claude Desktop 的 Code 标签页中的本地会话）。安装在你 Claude 账户上的插件，会在你用该 claude.ai 账户登录 Claude Code（2.1.273 或更高版本）后的下一次会话开始时，作为同步插件出现在那里；如果没有出现，请运行 /reload-plugins，或使用 安装 中的命令安装它。不需要管理员权限：Claude Code 的原生安装程序把它放在你的主文件夹中（在 macOS 和 Linux 上为 ~/.local/bin/claude），在 Windows 上，Anthropic 的指南说明无需以管理员身份运行它。在 Team 或 Enterprise 计划中，由你的组织决定你能获得哪些插件，以及 Code 标签页是否提供本地会话（如果不提供，你电脑对应的条目会显示为灰色，并带有提示 Disabled by your organization）。
2. 在那里填写选项：在会话中运行 /plugin configure <id>，或 /plugin → odoo-tools → Configure options（在 VS Code 中，点击插件所在行的齿轮图标）。<id> 是 claude plugin list 显示的完整标识符 名称@marketplace（例如 odoo-tools@synced）。在无界面的电脑上（Claude Code 2.1.285 或更高版本），使用 claude plugin configure <id> --json 和 --values-stdin（参见 安装），然后重启 Claude Code。
3. 那台电脑上没有 Claude Code？ 在 Cowork 中，当会话能运行 Node、能访问你的 Odoo，并且你可以编辑 CLI 的 .env 时，备用 CLI（/odoo-tools:odoo-setup-cli）可以工作；请使用专用、最小权限、短期有效的 API key。Claude chat 没有安全的地方来输入 key：请使用 Claude Code。（在没有 Python 的 Claude Code 中，请使用 /odoo-tools:deploy-local 的容器模式。）
4. 仍然受阻？运行 /odoo-tools:odoo-doctor：它最后会给出一份可以发给 Transgenia 的支持报告，Transgenia 也提供协助配置（参见 支持）。Transgenia 绝不会通过聊天或邮件向你索要 API key 或密码。

Cowork 和 Claude chat 确实接受你自行添加的 MCP 连接器（通过 https URL 访问的远程 MCP 服务器，或 Claude Desktop 应用中的桌面扩展），但本插件不提供其中任何一种：它的工具需要本地服务器。

应用显示 not_started，原因为 user_config_unsupported

Claude 应用可能会把本插件的服务器报告为状态 not_started、原因 user_config_unsupported。这是 Anthropic 的插件支持矩阵 中 Cowork 和 Claude chat 的情况：Cowork 不会提示输入插件选项，并会忽略选项没有默认值的本地 MCP 服务器；Claude chat 则会忽略插件的本地 MCP 服务器。这是预期行为，在 macOS 和 Windows 上都一样：它不是插件或应用的故障，插件的任何更新也都不会改变它。/odoo-tools:odoo-doctor 能识别它，并把应用显示的状态按原样、连同应用的版本写进它的支持报告。

出路是 Claude Desktop 的 Code 标签页中的本地会话，或你电脑上的 Claude Code（终端、VS Code 或 JetBrains），按照 上文 的步骤操作。Code 标签页的云端会话（或 claude.ai/code）不行：插件会从你的账户同步过去，但它的选项不会，因为 Claude Code 把选项保存在你填写它们的那台电脑上（API key 和密码保存在那台电脑的安全凭据存储中），所以服务器不会在云端启动。

哪些需要管理员权限：

• Claude Code 不需要： 它的原生安装程序把它放在你的主文件夹中（在 macOS 和 Linux 上为 ~/.local/bin/claude），在 Windows 上，Anthropic 的指南说明无需以管理员身份运行它。
• macOS： python3 随 Apple 的 Command Line Tools 一起提供（xcode-select --install）。如果你的 Mac 在安装它们时要求管理员，而你不是管理员，可以由你的 IT 团队来安装，或请 Transgenia 提供协助配置。
• Team 或 Enterprise 计划： 由你的组织决定你能获得哪些插件，以及 Code 标签页是否提供本地会话。如果不提供，你电脑对应的条目会显示为灰色，并带有提示 Disabled by your organization。

查找更新不会改变这种情况。Claude 插件目录只在 Anthropic 审核之后才发布一个版本，因此在此之前，在 Claude 应用中检查更新找不到更新的版本；而且在 Cowork 和 Claude chat 中，任何版本都不会运行 Odoo 工具。

会话开始时提示 “In Cowork and Claude chat this plugin's Odoo tools do not run”

自 v1.5.1 起，插件的会话开始 hook（hooks/session_start.py，取代 hooks/check_options.py）会检查 MCP 服务器的本地诊断。当最近 14 天既没有记录到与 Odoo 的成功连接，也没有记录到带齐全部连接设置（URL、数据库、登录名，以及 API key 或密码）的服务器启动时，它会在新会话开始时向你显示这条提示，每天最多一次：

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.

在每次会话开始时，它也会向 Claude 说明同样的内容：你的账户、你的 Odoo 和你的 Python 都没有问题，插件的任何更新都不会改变这种情况，并按以下顺序为你提供 Claude Desktop 的 Code 标签页中的本地会话或 Claude Code，以及 Transgenia 的协助配置；然后是在 Claude Code 中填写选项的位置和 doctor。最后附上一行 odoo-tools session diagnostics:，供 /odoo-tools:odoo-doctor 用于它的支持报告。

安装或升级插件后的第一次会话中（此时还没有 hook 记录），这条提示只发给 Claude，因为该会话的服务器可能还没有写下它的启动记录；在 hook 没有插件数据文件夹、因而无法把提示限制为每天一次的地方，情况也是如此。

• 在 Cowork 或 Claude chat 中： Odoo 工具不会在那里运行。请打开 Claude Desktop 的 Code 标签页中的本地会话（或 Claude Code），用同一账户登录后插件会作为同步插件出现在那里；也可以请 Transgenia 提供协助配置（参见 支持）。
• 在 Claude Code 中： 在 /plugin → odoo-tools → Configure options 中填写 URL、数据库、登录名和 API key，然后重启 Claude。当诊断记录到一次带齐全部连接设置的服务器启动，或一次成功的连接后，这条提示就不再出现。
• 该 hook 不读取任何插件选项或凭据：它只读取插件的数据文件夹（服务器的诊断）以及启动会话的 Claude 应用的名称。参见 安全。
• 如果你通过本插件之外的另一个 Odoo 连接器访问 Odoo，此提示不适用。
• 使用 /odoo-tools:deploy-local 的容器模式时，插件数据文件夹中的一个标记会让它保持沉默（参见 本地部署）。

Windows：会话开始时出现 SessionStart hook 错误

插件的会话开始 hooks 是 shell 命令，需要 Git for Windows（Git Bash）。没有它时，Claude Code 会在 PowerShell 中运行它们，并以 SessionStart hook 错误失败。请安装 Git for Windows；如果已经安装但 Claude Code 找不到它，请把 CLAUDE_CODE_GIT_BASH_PATH 设置为 Git Bash 的路径。MCP 服务器不受影响：Odoo 工具仍然可用，只是缺少会话开始时的提示。

Windows：claude mcp list 显示 Failed to connect 和 Connection closed

这是缺少 python3 命令的迹象：python.org 安装程序只提供 python.exe 和 py.exe，Claude Code 用 python3 启动插件的服务器，而这条消息中没有任何地方提到 Python。请在 PowerShell 中用硬链接在 python.exe 旁边放一个 python3.exe：

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

• 它需要对 Python 文件夹的写入权限：对于安装在 C:\Program Files 下的 Python，请以管理员身份运行 PowerShell。
• 如果 Get-Command python 什么也找不到，或找到的是 WindowsApps 下的文件，说明 Python 不在 PATH 中：请重新运行 python.org 安装程序并勾选 "Add python.exe to PATH"，或安装提供 python3.exe 的 Microsoft Store 版 Python。

然后重启 Claude Code。CI 会在 Windows 上检查这个修正方法（windows-launch.yml，使用 Claude Code 2.1.314）：有了硬链接，claude mcp list 显示服务器已连接；没有 python3.exe 时，它显示 Failed to connect 和 Connection closed。更多情况见 找不到 python3 或版本太旧。

在 Odoo 17 或更高版本中，API key 能通过 /jsonrpc 使用吗？

可以。Odoo 在 /jsonrpc 上与在 XML-RPC 上一样接受 API keys：两个端点都经过同一个 dispatch_rpc（Odoo 14 至 19），并已在一个 Odoo 18.0 上实测确认。如果 Odoo 前面的代理或网关拦截或改动了 /jsonrpc，auto 传输方式会 回退 到 XML-RPC（在第一次回退后固定为 XML-RPC，并提示一次）。如需强制，请将插件选项 Transport preference 设为 xmlrpc（独立模式下：ODOO_TRANSPORT_PREF=xmlrpc）。在有 API key 的 Odoo saas~18.4 / 19.0+ 上，auto 会优先使用 JSON-2（参见 兼容性）。

如果 key 在两条路径上都失败，问题在于 key 本身：请确认它没有过期或被撤销，并且 Odoo login 是创建它的那个用户。

XML-RPC 与 JSON-RPC 自 Odoo 19 起已弃用

Odoo 19 将 /xmlrpc、/xmlrpc/2 和 /jsonrpc 标记为弃用，并在 Odoo 22 和 Odoo Online saas~21.1 中移除它们；替代方案是 JSON-2 API，自 v1.4.0 起，有 API key 时插件就会使用它。经典端点在插件支持的所有版本（10 至 19）上都可用。

odoo_version 在 Odoo 19 上返回 transport_notice

连接在 Odoo 19+ 上使用的是已弃用的端点 /xmlrpc 或 /jsonrpc，每次调用都会在 Odoo 日志中留下一条警告。该提示自带解决办法；通常是以下之一：

• 创建一个 API key（Preferences → Account Security），并填入插件的 Odoo API key 选项（JSON-2 不接受密码）；
• 从 Odoo URL 中去掉 user:pass@（这种基本认证会占用 JSON-2 需要的 Authorization 请求头）；
• 把 Transport preference 改回 auto。

自 Odoo 22 / saas~21.1 起，只使用密码的连接将无法工作（ConfigError）。

我收到 "database not found"

数据库名称不正确。请在 Settings → Database 或登录 URL 中核对它。插件选项 Odoo database（独立模式下为 ODOO_DB）必须完全匹配。

我的 Odoo Online/SaaS 用正确的凭据也连不上

只有启用了 API 访问的订阅（Custom 计划）才支持外部 RPC 访问。在没有外部 API 访问的计划上，即使用户名和密钥正确，你也会看到连接/认证错误：请在 Odoo 面板中确认你的订阅计划，并用 odoo_version 验证。

• 在 Odoo Online 上，唯一可用的凭据是 API key：用户通过 odoo.com 登录，通常启用了 2FA。
• 自 Odoo 18 起，API keys 会过期：非管理员用户最多只能获得 1 天，除非其所属的某个组允许更长时间。如果连接隔天就失效了，请创建一个新的 key。odoo_online_profile 会显示每个 key 何时过期（只有名称和日期）。

某个字段出现在 dropped_fields 中，而不在结果里

该字段 在目标版本中不存在。这是预期行为：服务器不会让整个查询失败，而是丢弃不可用的字段并将其报告出来。请查阅 兼容性 表格，找到等价的现代名称（例如在 v16 中 analytic_account_id → analytic_distribution）。

我得到一个关于某个 Enterprise 模型的 CompatError

你正在针对一个被检测为 Community 的实例查询一个 Enterprise 专属模型（例如 helpdesk.ticket、sign.request）。运行时的模块探测是权威依据：如果该模块未安装，则该模型不可用。

我需要 API key，还是可以使用密码？

• Odoo ≥ 14：使用 API key（推荐）：插件选项 Odoo API key（独立模式下为 ODOO_API_KEY）。
• Odoo < 14：没有 API keys；使用插件选项 Odoo password（独立模式下为 ODOO_PASSWORD）。

定义两者中的 一个。

我从 v1.0.0 升级后插件无法连接

从 v1.1.0 起，插件不再读取你 shell 中的 ODOO_* 变量，而是使用插件选项。请在 /plugin → odoo-tools → Configure options 中 一次性 填入你的值，然后重启 Claude。之后你可以从 shell 配置文件中删除 export ODOO_*（它们仅对独立服务器仍然有效）。参见 安装。

找不到 python3 或版本太旧

从 v1.2.0 起，插件使用 python3（不再使用 uv）启动 MCP 服务器，需要 Python 3.9 或更高版本，无需额外的软件包。如果 odoo 服务器无法启动（或在 /mcp 中显示为失败），请在终端中运行 python3 --version：

• 命令不存在： 安装 Python 3.9+。在 macOS 上，xcode-select --install（Command Line Tools）会带来 python3；如果你的 Mac 在安装它们时要求管理员，而你不是管理员，可以由你的 IT 团队来安装，或请 Transgenia 提供协助配置。在 Linux 上，安装发行版的 python3 软件包。
• 版本低于 3.9： 服务器会以 odoo-tools: Python 3.9 or newer is required (found X.Y.Z) 退出。请升级 Python，或在你启动 Claude 时所用的 PATH 中把更新的版本放在前面。
• Windows： 命令必须名为 python3。Microsoft Store 版 Python 提供 python3.exe；python.org 安装程序只会创建 python.exe 和启动器 py.exe，因此不存在 python3，claude mcp list 会把服务器报告为 Failed to connect 并带有 Connection closed。请安装 Microsoft Store 版 Python，或在 PATH 中放一个 python3.exe（在同一文件夹中放一个 python.exe 的副本或硬链接；命令见 Windows：claude mcp list 显示 Failed to connect）。PowerShell 或 doskey 别名 不够用：Claude Code 会直接启动该命令，而不是通过你的 shell。如果输入 python3 打开的是 Microsoft Store 而不是显示版本号，那是 Windows 的应用执行别名：请安装 Microsoft Store 版 Python，或在 Windows 设置的 应用执行别名 中关闭 python3.exe 条目，以便找到你自己的 python3.exe。

然后重启 Claude，让 MCP 服务器使用该 python3 启动。如果你无法安装 Python，请使用 备用 CLI。

会话开始时，插件的第一个 hook 也会在 python3 无法运行时提示你（odoo-tools: python3 is not runnable on this computer. ...）。在 Cowork 和 Claude chat 中，无论有没有 Python，Odoo 工具都不会运行：在那里，解决办法不是安装 Python（参见 它能在 Cowork 或 Claude chat 中使用吗？）。

TLS 证书错误（CERTIFICATE_VERIFY_FAILED）

从 v1.2.0 起，两种传输都会使用系统信任存储来验证你的 Odoo 证书（遵循 SSL_CERT_FILE）；如果该 python3 安装了可选的 certifi 包，也会同时使用其 CA 列表。如果你的 Python 没有自带的 CA 文件（例如 python.org 的 macOS 版本在运行 Install Certificates.command 之前），服务器会自动加载操作系统的 CA 证书包。如果仍然失败（例如你的 Odoo 使用内部 CA），请将该 CA 加入系统信任存储、让 SSL_CERT_FILE 指向一个 CA 证书包，或安装 certifi。不要关闭 TLS 验证。

我收到 Input validation error: ...

工具收到了错误或名称不对的参数：缺少必需参数、有未知或拼错的参数，或者类型不匹配。从 v1.2.0 起，服务器会按各工具的模式（schema）校验参数，并在访问 Odoo 之前拒绝该调用。请在 工具参考 中核对参数名称和类型，然后重试。

传输错误以 "may or may not have been applied in Odoo; check before retrying" 结尾

即使没有收到响应，这次调用（创建、修改或任何其他 execute_kw）也可能已经在 Odoo 中生效：调用超时了，或者 Odoo（或其前面的代理）返回了 HTTP 5xx。在 auto 模式下，服务器 不会再 通过 XML-RPC 重放它，以免产生重复记录。重试之前，请 在 Odoo 中检查 该记录是否已被创建或修改。

耗时较长的调用因超时而失败

每次 Odoo 调用最多等待 ODOO_TIMEOUT 秒（默认 120，即 Odoo 默认的 limit_time_real）。对于更长的操作（报表、大批量导出），请调高插件选项 Request timeout（5 到 3600 秒；独立模式下为 ODOO_TIMEOUT），然后重启 Claude。如果超时的调用是一次写入，请先参阅上一条。

我收到 HTTP 429 或 “retry later”

Odoo（尤其是 Odoo Online，大约每秒 1 次调用）限制了调用频率。自 v1.4.0 起，HTTP 429 从不切换传输方式：读取会等待 Retry-After 指示的时间（最多 30 秒，3 次尝试），并在同一传输方式上重试；写入会被报告，以便你稍后重试。请控制批量工作的节奏，不要并行调用，并使用 odoo_import（每次调用最多 500 行），而不是为每条记录调用一次 odoo_create。

odoo_import 或 odoo_import_preview 在 XML-RPC 上被拒绝

导入工具只通过 JSON-RPC 或 JSON-2 运行：Odoo 的 XML-RPC 无法返回导入结果中携带的空值，一次已保存的导入可能会被报告为错误。处于 XML-RPC 的会话（Odoo 10-11，或 Transport preference 设为 xmlrpc）会在发送任何内容之前拒绝它们。请改回 auto，或使用 jsonrpc/json2。odoo_import_preview 需要 Odoo 16+，odoo_import 需要 Odoo 12+。开启 Read-only mode 时，或在配置档 readonly 下，两者都不再被列出，并且会被拒绝。

odoo_report 返回错误

自 v1.5.0 起，odoo_report 已弃用，总是不调用 Odoo 就返回错误：它使用的是私有方法 _render_qweb_pdf，而 Odoo 在所有版本上都拒绝通过 RPC 调用它，因此它从来没有成功过。它将在 2.0.0 中移除。请使用 odoo_record_documents：它列出记录的附件，并返回 Odoo 已经保存的文档，例如发送或打印发票时生成的发票 PDF（自 Odoo 17 起会被标出），最大 5 MiB。参见 工具参考。

我可以使用带 user:pass@ 的 ODOO_URL 吗？

可以。如果你的 Odoo 位于 HTTP 基本认证之后，请把凭据放在 URL 中（https://user:pass@odoo.example.com，填在 Odoo URL 选项或 ODOO_URL 中）。JSON-RPC 会将其作为 Authorization 请求头发送，并且密码绝不会出现在错误信息或日志中。请注意，Odoo URL 不是 sensitive 选项：该密码会保存在插件配置中，而不是安全凭据存储中。JSON-2 需要同一个请求头来传递它的 API key，因此这样的 URL 会停留在经典端点上（在 Odoo 19+ 上会附带 transport_notice），并且自 Odoo 22 / saas~21.1 起无法工作，因为那里已经没有这些端点。

Odoo 工具出现了两次

你同时配置了插件自带的服务器和 /odoo-tools:deploy-local 的容器服务器 odoo-tools-docker。请只保留一个：要移除容器服务器，运行 claude mcp remove odoo-tools-docker，并用 rm "${CLAUDE_PLUGIN_DATA}/diagnostics/container-mode" 删除它的标记，这样当插件的服务器无法访问 Odoo 时，会话开始 hook 会重新给出提示。

我没有 Python，只有 Node

使用 备用 CLI：/odoo-tools:odoo-setup-cli（Node.js 18+）。如果你有 Docker，也可以用容器运行 MCP 服务器：/odoo-tools:deploy-local 的容器模式（本地部署）。

本地沙箱无法启动

• Docker with Compose is required：安装 Docker Desktop，或带 compose 插件的 Docker Engine。
• the Docker engine is not running：打开 Docker Desktop（或 sudo systemctl start docker）后重试。
• Port 8069 ... is already in use：端口被另一个 Odoo 占用；用 --port 8070 重新运行，并在插件选项中使用该 URL。
• Odoo did not answer ...：查看 sandbox logs；较慢的电脑首次运行耗时更长（调大 --timeout）。
• already holds an Odoo 18.0 database：你更换了版本；运行 sandbox destroy --yes，或用 --dir 指定另一个文件夹。
• This sandbox was created with a database password that the Odoo image cannot use：在 1.6.0 之前，大约每 64 个新沙箱中就有一个得到以 "-" 开头的数据库密码。从 11.0 起，Odoo 镜像在命令行上把它传给 wait-for-psql.py，后者把它当作一个选项来读取，因此 Odoo 容器不停地重启，sandbox up 最终以 Odoo did not answer 超时。只有从未启动过的 Odoo 11.0 或更高版本的沙箱才会出现这条消息：请运行 sandbox destroy --yes，然后再运行一次 sandbox up，不会丢失任何东西。在 10.0 上，镜像把这个密码交给 Odoo，Odoo 可以接受它；已经正常运行过的沙箱也从不会被拒绝。自 1.6.0 起，生成的密码都不再以 "-" 开头，而且这条消息不会显示密码的任何部分。

错误信息提到 /odoo-tools:odoo-setup-mcp 和 Transgenia

自 v1.3.0 起，配置、认证和传输错误的末尾会给出修复命令和官方支持渠道。请按引导路线操作；如果仍然失败，请发邮件至 dev@transgenia.org，或通过 WhatsApp 联系 +52 55 8034 0405。

出问题时，我应该向支持团队发送什么？

运行 /odoo-tools:odoo-doctor：它先检查 Odoo 工具是否在你所在的地方运行，再检查连接，最后给出一份不含 API key、密码、URL、登录名或记录数据的支持报告。请把它发送到 dev@transgenia.org，或通过 WhatsApp 发送到 +52 55 8034 0405。参见 支持报告。

我如何验证一切都没问题？

运行 /odoo-doctor 或调用 odoo_version。一个包含版本、版本类型、部署方式和传输方式的响应即可确认端到端的连接。自 v1.4.0 起，odoo_version 会先登录，因此错误的 API key 或密码不会再被当作连接正常。自 v1.6.0 起，响应中还带有 plugin，即作出响应的版本和副本；没有 policy 块时，说明作出响应的是早于 1.5.0 的副本（参见 两个 odoo-tools 副本）。参见 连接与发现。

我公司的数据会发送给 Anthropic 吗？

分两条路径看：MCP 服务器直接与你的 Odoo 通信（Transgenia 不代理、不存储、不查看你的数据），但返回给 AI 智能体的工具结果会被发送给模型提供方（例如 Claude 背后的 Anthropic）进行处理。参见 安全 和 隐私。

它能在 Cowork 或 Claude chat 中使用吗？

插件的 skills 和命令会在那里加载，但 Odoo 工具不会：它们作为本地 MCP 服务器只在 Claude Code 中运行。你的账户、你的 Odoo 和你的 Python 都没有问题：请打开 Claude Desktop 的 Code 标签页中的本地会话（插件会以同一账户同步到那里），或者请 Transgenia 提供协助配置。参见 适用环境、 空面板的情况 和 not_started 状态。

除了 Claude，它能与其他智能体一起工作吗？

可以：能与任何实现了 MCP 协议的客户端一起工作。Claude Code 是本插件所打包面向的参考环境。