快速开始：引导路线

从这里开始：/odoo-tools:odoo-setup-mcp

自 v1.3.0 起，插件只有一条引导路线。运行 /odoo-tools:odoo-setup-mcp（或其快捷方式 /setup-odoo-tools）：它会检测你已有的配置，并一次一个问题地带你完成五个阶段：

1 配置 → 2 验证 → 3 培训 → 4 日常使用 → 5 部署

每个阶段开始时都会显示你所在的位置。如果你更喜欢手动操作，本页概述了这条路线。

v1.6.0 新增

• 在 第 0 步 中，没有 policy 块的 odoo_version 响应会让路线停止：作出响应的是早于 1.5.0 的副本。在 Claude Code 中，路线会运行一次副本检查，并在保存之后运行选项检查。
• 在 第 0b 步 中，路线会把状态 not_started、原因 user_config_unsupported 识别为 Cowork 和 Claude chat 的情况，为你提供 Code 标签页中的本地会话（云端会话没有你的选项），并告诉你 Claude Code 不需要管理员权限。
• 在 第 3 步 中，路线会先问这个连接的用途；在 Odoo Online 上，它会根据子域名建议数据库。
• 初始检查也会查找 git。在 Windows 上，安装 Claude Code、Git 或 Python 之后，你要打开一个新的 PowerShell 窗口。
• 第 5 阶段 给出每种环境的安装命令：在 Claude Code 中，或在终端中。

v1.5.1 新增

• 在 第 0b 步 中，如果 Odoo 工具没有加载，路线在弄清你在哪里使用 Claude 之前，不运行任何命令，也不检查 Python。在 Cowork 中读到的 Python 版本属于它的虚拟机，而不是你的电脑。
• /odoo-tools:odoo-doctor 也从同样的检查开始，并以一份可以发给 Transgenia 的支持报告结束。

v1.5.0 新增

• 配置中包含两个新选项：Permission profile（默认 standard）和 Permission policy file（可选）。参见 权限策略。
• 在培训中，写入练习会归档测试联系人，而不是删除它，因为 standard 不删除；Studio 风格的练习需要配置档 builder。
• 部署阶段建议在生产环境中使用 standard（或 readonly），并在 Odoo 用户是管理员时从加固示例文件开始。

请在 Claude Code 中运行这条路线

这条路线会配置并使用 Odoo 工具，而这些工具只在你电脑上的 Claude Code（终端、VS Code、JetBrains 或 Claude Desktop 的 Code 标签页中的本地会话）中运行。在 Cowork 和 Claude chat 中，skill 会加载，但工具不会：路线会在 第 0b 步 中检测到这一点，并为你提供可行的路径。参见 适用环境。

第 1 阶段：配置

路线会先问你属于哪种情况：

1. 连接我的 Odoo（生产或测试）：见下面的第 0-4 步。
2. 我没有可练习的 Odoo / 不想触碰生产环境：用 /odoo-tools:deploy-local 启动本地 Odoo Community 沙箱（Transgenia 无法提供 Enterprise 或 Online 实例）。参见 本地部署。
3. 我无法安装 Python 3.9+：容器中的 MCP 服务器（/odoo-tools:deploy-local，容器模式）或 CLI 备用方案。

第 0 步：检测你已有的东西

它首先查看自己的工具列表，不运行任何东西。如果没有 odoo_version，说明 MCP 服务器没有在这个环境中运行：在运行任何 shell 命令之前，先转到 第 0b 步。如果有，就调用它一次，并在说任何话之前先读它的响应：

• 既没有 policy 也没有 note： 作出响应的是早于 1.5.0 的 odoo-tools，没有权限策略；它通常是从别处安装的第二个副本。路线就此停止：不进行培训、日常使用或写入，并帮你只保留一个最新副本。
• 有 note： 权限策略被锁定。这条说明会点名要修正的选项或文件；这不是一个可用的连接。
• plugin： 作出响应的 odoo-tools 版本及其已安装副本（plugin@marketplace）。它会把这些显示给你。

如果调用成功并带有 policy 块，说明插件选项已经配置好：它会显示版本、版本类型和副本，并让你选择直接跳到培训、日常使用或部署。（它不会读取你机器上的 ODOO_* 变量或凭据文件来判断。）

当 odoo_version 作出响应时，说明这是你电脑上的 Claude Code，路线会运行一次副本检查，即使一切正常也是如此：两个 odoo-tools 副本可能同时处于活动状态，这时选项对话框和工具可能属于不同的副本。它会原样显示输出：点名要保留的副本，并给出移除其他副本（或更新来自 Transgenia marketplace 的旧副本）的确切命令，由你在终端（PowerShell 或 Terminal）中运行，绝不要当作 /plugin 命令运行，然后重启 Claude Code。它绝不会在 Cowork 中运行这些命令：在那里，它的命令到达的是一台虚拟机，而不是你的电脑。参见 两个 odoo-tools 副本。

在可以运行命令的地方，它还会检查 python3（3.9 或更高版本）、git 和 docker 是否可用，以便确定后续阶段适用 Python 路径还是容器路径。

第 0b 步：Odoo 工具是否已加载？

仅当 odoo_version 不作为工具存在时适用。它不会从 Python 开始排查。 它会问你在哪里使用 Claude：1) Claude Code、2) Cowork 或 3) Claude chat。如果你描述的是插件 Connectors 标签页中 odoo 一行带有 Runs in each session 字样的空面板，那么你处于 2 或 3。如果应用把插件的服务器显示为状态 not_started、原因 user_config_unsupported，你也处于 2 或 3：这是 Cowork 和 Claude chat 对这种情况的叫法，在 macOS 和 Windows 上都一样，不是插件或应用的故障，插件的任何更新也都不会改变它。

• Claude Code： 如果会话本身运行在 Anthropic 的云端（Code 标签页的云端会话，或网页版 Claude Code），你保存在自己电脑上的选项不在那里，因此服务器无法启动：路线会像 2 或 3 中那样为你提供本地会话，然后停止。否则，说明服务器没有启动；常见原因是必需选项（URL、数据库、登录名）为空，或者插件有第二个副本。如果它可以运行命令，会运行第 0 步的副本检查，在副本检查点名要保留的副本之后，再对该副本运行选项检查（Claude Code 2.1.285 或更高版本；输出从不显示 key）。它会根据检查列出的内容采取行动：缺少的选项在选项对话框中填写，你在 Claude Code 中用 /plugin configure <id> 打开它。如果缺少 python3，两项检查都无法运行：路线会直接读取 claude plugin list --json（在这里启用的 odoo-tools@... id 不止一个，或版本早于 1.5.0，就是问题所在；同一个 id 列在两个范围中只算一个副本，项目或本地条目只在它自己的文件夹中才算数，即它的 projectPath 或其中的某个文件夹），然后转去检查 Python。之后你重启 Claude。
• Cowork 或 Claude chat： 这些应用不运行插件的本地 MCP 服务器，也没有填写其选项的表单。安装没有问题，你的账户、你的 Odoo 和你的 Python 也都没有问题；路线会为你提供：
  1. 你电脑上的 Claude Code（推荐）：终端、VS Code、JetBrains，或 Claude Desktop 的 Code 标签页中的本地会话（不是云端会话，云端会话没有保存在你电脑上的选项）。安装在你 Claude 账户上的插件，会在你用该 claude.ai 账户登录 Claude Code（2.1.273 或更高版本）后的下一次会话开始时，作为同步插件出现在那里；如果没有出现，运行 /reload-plugins 或使用 安装 中的命令。Claude Code 不需要管理员权限：它的原生安装程序把它放在你的主文件夹中。在 Team 或 Enterprise 计划中，由你的组织决定你能获得哪些插件，以及 Code 标签页是否提供本地会话。
  2. 仅限 Cowork：备用 CLI，前提是会话能运行 Node、能访问你的 Odoo，并且你可以编辑它的 .env。请使用专用、最小权限、短期有效的 API key。不适用于 Claude chat，因为它没有安全的地方来输入 key。
  3. Transgenia 提供协助配置（参见 支持）。

在这些应用中，路线不会带你去检查 Python 或插件选项，因为它们在那里无法起作用。在 Cowork 中，shell 命令运行在一台虚拟机里，而不是你的电脑上：在那里读到的 Python 版本说明不了你电脑的任何情况。在工具运行起来且 Odoo 拒绝连接之前，它也不会给出 Odoo 方面的建议（订阅计划、API key、数据库）。如果 Claude 的上下文中有一行以 odoo-tools session diagnostics: 开头，那是插件的会话开始 hook 在你的电脑上写下的，/odoo-tools:odoo-doctor 会把它整理成一份可以发给 Transgenia 的支持报告。

第 1 步：选择接口

• MCP 服务器（推荐）：完整工具 + 兼容层。只需要 PATH 中有 python3 3.9+（无第三方依赖；启动时不安装、不下载任何东西）。
• 备用 CLI：轻量，仅需 Node。如果你无法运行 MCP，请使用它。

如果缺少 Python，路线会给出适合你系统的解决办法。在 Windows 上，命令必须名为 python3（参见 要求）；安装 Claude Code、Git 或 Python 之后，你要打开一个新的 PowerShell 窗口并重启 Claude Code：之前打开的窗口看不到新的 PATH。

第 2 步：Odoo 的版本与版本类型（可选）

Community · Enterprise · Online (odoo.com/SaaS) · 不确定。兼容层会自动覆盖 10-19 各版本；此信息仅作为上下文。

第 3 步：连接数据

在填写这些数据之前，路线会先问你这个连接的用途：

• 用于学习或练习： 最好使用沙箱（第 1 阶段，选项 2）。如果使用真实实例，它建议开启 Read-only mode 并使用 Permission profile readonly。

• 用于实际工作： Permission profile standard，并在最初几天开启 Read-only mode。只有在你确认需要写入时才开启写入。

• Odoo 的 URL：例如 https://my-company.odoo.com（协议 + 主机，不带结尾路径）。

• 数据库名称：Settings → Database，或在登录 URL 中可见。在 Odoo Online（*.odoo.com）上，它通常就是子域名（https://my-company.odoo.com 对应 my-company）：路线会建议它，并请你确认。
• 登录邮箱：你用来登录的账户。
• 凭据：一个 API key（Odoo 14+，推荐）或一个密码（Odoo < 14）。获取 API key：Preferences → Account Security → New API Key（只显示一次，请复制下来）。在 Odoo 19+ 中，正是 API key 让你能够使用 JSON-2。

Odoo Online

在 Odoo Online 上，唯一可用的凭据是 API key（用户通过 odoo.com 登录，通常启用了 2FA），并且只有 Custom 计划允许访问 API。自 Odoo 18 起 key 会过期：非管理员用户最多只能获得 1 天，除非其所属的某个组允许更长时间。请记下过期日期；之后 odoo_online_profile 会显示它。

这些值在插件的选项对话框中输入，而不是在聊天中输入。

安全

切勿将密钥粘贴到聊天中，也不要写入受仓库跟踪的文件中。为智能体使用一个最小权限 的 Odoo 用户。参见 安全。

第 4 步：持久化配置

对于 MCP 服务器：

1. 运行 /plugin，打开 odoo-tools，选择 Configure options（或 /plugin configure <id>）。
2. 填写 URL、数据库、登录名和 API key（Odoo < 14 则填写密码）。可选：Transport preference（默认 auto：在 Odoo 19+ 上有 API key 时使用 JSON-2；也可选 json2、jsonrpc 或 xmlrpc）、Request timeout（默认 120 秒）、 Read-only mode（建议在最初几天和演示时开启）、Permission profile（默认 standard：不删除、不做 Studio 风格的改动、除内部备注外不发送外发邮件、不更改用户或权限，也不读取已保存的密钥；也可选 readonly、用于沙箱和预发布环境的 builder，或保留 1.4 行为的 full）以及 Permission policy file（可选：按模型定义规则的文件的绝对路径，参见 权限策略）。
3. 重启 Claude，让 MCP 服务器读取这些选项。

选项对话框不会说明它编辑的是插件的哪个副本。如果第 0 步的副本检查发现了不止一个副本，路线会先解决这个问题；保存之后，它会对该副本运行选项检查，并根据它列出的内容采取行动。

在远程或无界面的电脑上，claude plugin configure <id> --values-stdin 可以不经对话框保存选项（参见 安装）。请从受保护的文件或你的密钥管理器传入 JSON；Claude 绝不会向你索取、读取或复述 key。

API key 和密码是 sensitive 选项：以掩码方式输入，并保存在操作系统的安全凭据存储中，而不是 settings.json 或你的 shell 配置文件中。对于插件，不要 在 ~/.bashrc/~/.zshrc 中或通过 setx 导出 ODOO_*。

对于 CLI，运行 /odoo-tools:odoo-setup-cli：它会安装 CLI 并在 ~/.claude/tools/odoo-cli 中创建一个仅你的用户可读、带占位符的本地 .env。请由你自己在自己的编辑器中粘贴密钥；Claude 绝不会在聊天中向你索取它。

第 2 阶段：验证（完成的定义）

• MCP： 调用 odoo_version。它的响应必须带有 plugin 和 policy：没有 policy，说明作出响应的是早于 1.5.0 的副本（回到 第 0 步 并停止）；有 note，说明策略被锁定（修正它点名的内容并重新连接）。成功 = 返回版本 + 版本类型 + 部署方式 + 传输方式，以及作出响应的副本（plugin.copy）。在 Odoo 19+ 上，传输方式应为 json2；transport_notice 表示正在使用已弃用的端点（通常是因为没有 API key），并说明如何修正。它的 policy 块显示当前生效的配置档和被隐藏的工具。然后测试：odoo_search_read { "model": "res.partner", "fields": ["name"], "limit": 1 }。
• Odoo Online（部署方式为 saas，或版本为 saas~，例如 saas~19.2）：还要调用 odoo_online_profile，查看版本线、你的 API key 何时过期以及计划的限制。
• CLI： node ~/.claude/tools/odoo-cli/dist/cli.js contacts '{"limit":1}'。

如果失败，根据错误进行诊断：

• odoo_version 不作为工具存在 → MCP 服务器没有启动。请先按 第 0b 步 操作：在 Cowork 和 Claude chat 中它从不启动，解决办法也不是 Python。在 Claude Code 中，检查选项，然后运行 python3 --version（3.9+）并重启 Claude。在 Windows 上，claude mcp list 中的 Failed to connect 加 Connection closed 是缺少 python3 的迹象；参见 故障排查。
• odoo_version 的响应中没有 policy 块 → 作出响应的是早于 1.5.0 的副本；参见 两个 odoo-tools 副本
• 认证错误 → 检查 DB / login / API key
• 传输错误 → 检查 URL（协议 + 主机）
• "database not found" → 检查数据库的准确名称
• 只出现 odoo_version，且它的 policy 块带有 error → 配置档或策略文件无效，服务器以锁定状态启动；参见 故障排查

第 3 阶段：培训（15-20 分钟，动手）

路线提供八个练习。你用自己的话输入请求，Claude 会解释是哪个工具回答的以及原因。练习 1-5 为只读；练习 6 至 8 会写入，只在沙箱或测试数据库中进行，每次写入前都会请求确认。

1. 了解你的实例：“我的 Odoo 是哪个版本和版本类型？” → odoo_version、odoo_module_info。
2. 查找记录：“给我看 5 个墨西哥客户” → 带域条件的 odoo_search_read。
3. 理解模型：“销售订单有哪些字段？” → odoo_list_models、odoo_fields_get。
4. 汇总：“今年每月开票总额” → odoo_read_group。
5. 导出：“把在售产品导出为 CSV” → /odoo-export。
6. 确认后写入（沙箱/测试）：创建一个测试联系人，修改它的电话，然后归档它 → odoo_create、odoo_write（用 {"active": false} 归档）。在默认配置档 standard 下，删除会被拒绝，odoo_unlink 也不会被列出：归档是可逆的途径。如果要练习删除，请在沙箱中（绝不要在生产环境中）把 Permission profile 设为 full 并重新连接（/mcp）；之后 odoo_unlink 就会删除该联系人。
7. 低代码（Studio 风格）（沙箱/测试）：一个字段或一个自动化 → Studio 风格。需要 Permission profile builder（仅限沙箱和预发布环境）。
8. 先预演再导入（沙箱/测试）：“导入这 3 个联系人” → odoo_import_preview（Odoo 检查每一行，不保存任何内容），在你确认后 → odoo_import（所有行全部保存或全部不保存）。id 列存放外部标识符，并会更新已拥有这些标识符的记录。

第 4 阶段：日常使用

需求	使用
询问你的数据	直接提问：odoo 智能体和 MCP 工具会回答
连接健康检查与支持报告	/odoo-doctor
导出记录	/odoo-export
10-19 版本差异	/odoo-tools:odoo-crossversion
字段与自动化	/odoo-tools:odoo-studio-style
规划迁移	odoo-migrator 智能体
沙箱：状态、停止、启动	/odoo-tools:deploy-local status
没有 Python 的电脑	/odoo-tools:odoo-setup-cli（CLI）或 /odoo-tools:deploy-local container
Odoo Online：版本线、API key 过期时间、计划限制	odoo_online_profile
为什么一次调用被拒绝？这个用户能做什么？	odoo_access_check
一条记录的附件或一张发票已保存的 PDF	odoo_record_documents
一次加载大量记录	odoo_import_preview，确认后再用 odoo_import
一个方法的参数名称（JSON-2、odoo_execute）	odoo_api_catalog
当前生效的是哪个权限配置档，它隐藏了哪些工具	/odoo-doctor 或 odoo_version 的 policy 块
离线检查策略文件	--check-policy（参见 权限策略）

好习惯：除非任务需要写入，否则保持只读模式；每次写入都要确认；批量修改先在沙箱中测试。当 odoo-tools 的权限策略拒绝一次调用时，这个拒绝是最终结果：Claude 会向你解释，并告诉你改变它的选项，而不会寻找其他途径（其他工具、备用 CLI 或 shell）。/odoo-doctor 会显示当前生效的配置档。

第 5 阶段：部署（团队或生产）

路线会和你一起逐项检查：

1. 每人一个 Odoo 用户，最小权限，各自的 API key。
2. 默认只读；只为需要的人开启写入。在生产环境中把 Permission profile 保持为 standard（或 readonly），builder 只用于沙箱和预发布环境，full 只用于你决定保留 Odoo 用户全部权限的地方。如果生产环境使用的是管理员用户，请从 ${CLAUDE_PLUGIN_ROOT}/docs/policy-examples/production-hardened.json 的一个副本开始，把它保存在所有项目之外（例如 ~/.config/odoo-tools/policy.json，其绝对路径填入 Permission policy file），并先用 python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-policy <文件> 检查该副本。参见 示例。
3. HTTPS URL，除非有理由，否则使用 auto 传输。
4. 先试点：在沙箱或副本上重复关键流程。
5. 批量写入或 Studio 风格修改前先备份。
6. 每台电脑只安装一次插件，从 Transgenia 的 marketplace 安装：在 Claude Code 中用 /plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online；或在终端中用 claude plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online --scope user（在 2.1.275 之前的 Claude Code 中，先添加 marketplace）。然后走一遍路线，它会检查是否只有一个副本处于活动状态；没有 Python 的电脑使用容器模式。
7. 通过 /plugin 更新，更新生产用户前先阅读 CHANGELOG。
8. Odoo Online： 规划 API key 的轮换（自 Odoo 18 起会过期；odoo_online_profile 会告诉你何时过期），控制批量工作的节奏（大约每秒 1 次调用，每次导入最多 500 行），并预期每隔几个月就会出现一条新的 saas~X.Y 版本线。

Transgenia 的陪伴服务

在最需要的时刻（配置受阻、培训结束、沙箱与部署），插件会提醒你：Transgenia 提供维护、支持、培训与协助部署，仅通过其官方渠道：dev@transgenia.org · WhatsApp +52 55 8034 0405。参见 支持。