跳转至

连接与发现

v1.6.0 新增

odoo_version 会点名作出响应的 odoo-tools 副本（plugin 块），策略被锁定时也是如此。没有 policy 的响应来自早于 1.5.0 的副本，/odoo-doctor 会在那里停止；在 Claude Code 中，它还会运行副本检查。参见 识别环境。当 Odoo 工具没有加载时，/odoo-doctor 会把应用的 not_started 状态识别为 Cowork 和 Claude chat 的情况，能分辨出云端会话；缺少 python3 时，它会给出适用于你的系统的解决办法。参见 健康检查。

v1.5.1 新增

/odoo-doctor 首先检查 Odoo 工具是否已在它运行的地方加载，只有在 Odoo 拒绝连接之后才给出 Odoo 方面的建议，并且总是以一份不含 key、URL、登录名或记录数据的支持报告结束。参见 健康检查。

v1.5.0 新增

odoo_version 还会返回一个 policy 块，其中是当前生效的权限策略，/odoo-doctor 会报告它。odoo_list_models 会略去策略在其上不允许任何操作的模型，odoo_access_check 会在 Odoo 的回答旁边加上策略的回答。参见 权限策略。

在对一个新实例进行操作之前，先识别它的版本、版本类型和部署方式。兼容层会用这些数据来解析模型名和字段名，因此你几乎从不需要为每个版本分叉你的查询。

1. 识别环境

调用 odoo_version。它会返回：

  • version：主版本整数（10-19）
  • raw_version：Odoo 报告的完整版本字符串
  • edition：community | enterprise | unknown
  • deployment：onprem | saas
  • transport：当前生效的传输方式：在配置了 API key 的 Odoo saas~18.4 / 19.0+ 上为 json2；其他情况下为 jsonrpc(auto)，或在一次回退后为 jsonrpc / xmlrpc
  • transport_notice：null，或说明为什么在 Odoo 19+ 上使用已弃用的端点 /xmlrpc 或 /jsonrpc，以及如何切换到 JSON-2（例如创建一个 API key 并填入插件选项）
  • policy（自 v1.5.0 起）：配置档（profile）、策略文件（file）、digest、Read-only mode 是否开启（readonly）、被隐藏的工具（hidden_tools）、带理由和过期时间的敏感模型开放项（opened_sensitive）、被释放的字段（released_fields）、警告（warnings），以及在策略无法加载时的 error 和 error_code。参见 工具报告的内容。
  • plugin（自 v1.6.0 起）：作出响应的 odoo-tools 版本（version），以及在 Claude Code 中它的已安装副本（copy，plugin@marketplace，例如 odoo-tools@transgenia-odoo-tools），它是从 Claude Code 为每个副本分配的数据文件夹名称中读出的。安装了两个副本时，它会告诉你运行的是哪一个。

自 v1.4.0 起，odoo_version 会在响应之前先登录：错误的 API key 或密码会返回认证错误，而不会被当作连接正常。

当 Odoo 用户是管理员（base.group_system）时，policy.warnings 会带有警告 W10：Odoo 的访问权限不做任何限制，权限策略是唯一起限制作用的一层。请优先使用一个专用用户，只给它能工作的最少的组。如果策略被锁定，odoo_version 只返回 plugin 和 policy 块，以及一条点名要修正的选项或文件的说明（note），不联系 Odoo。

没有 policy 块（也没有 note）的响应来自早于 1.5.0 的 odoo-tools 副本，它没有权限策略；它通常是从别处安装的第二个副本。引导路线和 /odoo-doctor 会在那里停止，不做任何写入。参见 两个 odoo-tools 副本。

仅限 Claude Code

如果工具列表中没有 odoo_version，说明 MCP 服务器没有在这个环境中运行。在 Cowork 和 Claude chat 中它从不运行（参见 适用环境）；在 Claude Code 中，请检查插件选项并参阅 故障排查与常见问题。/odoo-doctor 会先做这项检查。

2. 使用 /odoo-doctor 进行健康检查

/odoo-doctor 命令会按以下顺序进行一次完整诊断，且不写入任何内容，并在第一个能解释问题的步骤处停止：

  1. Odoo 工具是否已加载？ 在运行任何东西之前，它先查看自己的工具列表。如果其中没有 odoo_version，说明 MCP 服务器没有在本次会话中运行，因此在知道你在哪里使用 Claude 之前，它不运行任何 shell 命令、不检查 Python（在 Cowork 中，命令运行在一台虚拟机里，而不是你的电脑上），也不给出 Odoo 方面的建议（订阅计划、API key、传输方式、数据库）。它会读取会话开始 hook 在你的电脑上写下的 odoo-tools session diagnostics: 这一行（Cowork 会在你的电脑上、虚拟机之外运行插件的 hooks；Claude chat 不运行任何 hook）；如果还不知道，就询问你在哪里使用 Claude。如果应用把插件的服务器显示为状态 not_started、原因 user_config_unsupported，它就知道你在 Cowork 或 Claude chat 中。在 Cowork 或 Claude chat 中，它会告诉你 Odoo 工具按照这些应用的设计不会在那里运行，你的账户、你的 Odoo 和你的 Python 都没有问题；这个状态是预期的，不是错误，任何更新都不会改变它。它会为你提供 Claude Desktop 的 Code 标签页中的本地会话或 Claude Code（插件会以同一账户同步到那里），以及 Transgenia 的协助配置。在云端会话中（Code 标签页的云端会话，或网页版 Claude Code），插件可能已经同步过去，但它的选项留在你填写它们的那台电脑上，因此服务器不会启动：它不会在那里向你索要选项，而是为你提供同样的选择。在你电脑上的 Claude Code 中，说明服务器没有启动。常见原因是 URL、数据库或登录名为空，插件有第二个副本，或者没有 python3 命令（在 Windows 上，这时 claude mcp list 会把服务器报告为 Failed to connect 并带有 Connection closed，而不会提到 Python；在 macOS 上，python3 随 Apple 的 Command Line Tools 一起提供）。它会运行副本检查，并对它保留的副本运行选项检查：这两项检查读取 Claude Code 打印的内容，不联系任何地方，也从不显示 key（参见 两个 odoo-tools 副本）。如果找不到 python3 或它不显示版本号，原因就在这里：它会给出适用于你的系统的解决办法并停止。否则，它会原样显示两项输出，并引导你去引导路线的 第 0b 步。副本检查打印的命令要在终端（PowerShell 或 Terminal）中运行，而不是作为 /plugin 命令。
  2. 调用 odoo_version。它先读取 plugin 块：作出响应的 odoo-tools 版本及其副本（plugin@marketplace）。如果响应中没有 policy，说明作出响应的是早于 1.5.0 的副本，没有权限策略：它会告诉你，运行副本检查，并在此停止。否则，它会报告 版本 / 版本类型 / 部署方式 / 传输方式，如果 transport_notice 不为 null，还会报告它及其解决办法。它也会报告 policy 块：配置档、是否有策略文件、摘要、被隐藏的工具、带理由和过期时间的开放项，以及每一条警告；它会醒目地显示 W10，并建议使用专用的最小权限用户。如果 error 有值，说明策略被锁定：它会告诉你，在你修正文件或 Permission profile / Permission policy file 选项并重新连接（/mcp）之前，其他 Odoo 工具都处于关闭状态，然后在此停止。之后它会运行一次副本检查，并把结果加入表格：连接正常时也可能有两个副本同时处于活动状态，这时选项对话框和工具可能属于不同的副本。
  3. 调用 odoo_connections 并列出活动会话。
  4. 进行一次受限的读取测试：odoo_search_read { "model": "res.partner", "fields": ["name"], "limit": 1 }。 之后调用 odoo_online_profile（只读），并在表格中加入版本线（例如 Odoo Online 上的 saas~19.2）、部署方式检测的可信程度（deployment_confidence）以及任何提示，例如即将过期的 API key。如果部署方式为 saas，还会加入 Odoo Online 的限制。只有到这一步，如果 Odoo 拒绝了连接，才需要检查 Odoo 方面：在 Odoo Online 上，外部 API 访问需要 Custom 计划；API key 已过期或被撤销；数据库名称。
  5. 如果某个步骤失败，它会指出确切的错误，并引导你去 /odoo-tools:odoo-setup-mcp（或 odoo-setup-cli）。它总是以一份可以发给 Transgenia 的支持报告结束，其中不含 key、URL、登录名或记录数据：在 Claude Code 中，它对插件的本地文件夹运行 --diagnose；在 Cowork 中，它根据第 1 步的结果来写这份报告；在 Claude chat 中，报告只写明所在的环境。参见 支持。

3. 探索模式

每个实例都不同。在查询你不了解的字段之前：

  • odoo_list_models：列出已安装的模型，可选择按名称片段（like）过滤。自 v1.5.0 起，它会略去权限策略在其上不允许任何操作的模型，并给出数量（hidden_by_policy）。
  • odoo_fields_get：返回一个模型的字段定义（带缓存）。它接受历史名称或现代名称；兼容层会解析到正确的那个。
  • odoo_module_info：按技术名称获取一个模块的安装状态和元数据（用于了解某个 Enterprise 模块是否存在）。
  • odoo_access_check：已登录用户是否可以在某个模型上读取、写入、创建和删除（在 Odoo 18+ 上可用 ids 按记录检查），以及是否可以导出。当一次调用因权限被拒绝时很有用。自 v1.5.0 起，它还会返回 policy（权限策略允许什么），当 Odoo 允许而策略拒绝时附上一条说明。
  • odoo_api_catalog：一个模型的方法及其按顺序排列的参数名称，用于 JSON-2 和 odoo_execute。

它们都在 工具参考 中有说明。

示例：发现联系人的字段

odoo_fields_get {
  "model": "res.partner",
  "attributes": ["string", "type", "required"]
}

4. 选择正确的接口

  • 如果你使用 Claude Code 且 python3 3.9+ 可用 → MCP 服务器（所有工具 + 兼容层；无第三方依赖）。
  • 如果你使用 Claude Code、没有 Python 但有 Docker → 容器中的 MCP 服务器（/odoo-tools:deploy-local，参见 本地部署）。
  • 如果你只有 Node → 备用 CLI（参见 备用 CLI）。

继续阅读 工具参考。