跳转至

本地部署（沙箱与容器）

v1.6.0 新增

  • 在 Odoo 14.0 至 19.0 上为插件提供 API key： sandbox up 会让 Odoo 为 admin 用户创建一个 API key，并把它以 ODOO_API_KEY 保存在 .env 中，从不打印。它填入插件的 Odoo API key 选项，Odoo password 留空。参见 将插件连接到沙箱。
  • 已修复，一个从未启动的沙箱： 大约每 64 个新沙箱中就有一个得到以 "-" 开头的数据库密码，11.0 及更高版本的 Odoo 镜像会把它当作一个选项来读取。生成的密码不再以 "-" 开头。只有用这种密码创建、且从未启动过的 Odoo 11.0 或更高版本的沙箱，才会提示你运行 sandbox destroy --yes，然后运行 sandbox up，不会丢失任何东西。10.0 的沙箱，或已经正常运行过的沙箱，保持不变。参见 故障排查。
  • 容器模式的镜像为 ghcr.io/transgenia/odoo-mcp-tools:1.6.0。

v1.5.1 新增

  • 容器模式的镜像为 ghcr.io/transgenia/odoo-mcp-tools:1.5.1。
  • 容器模式会创建标记 ${CLAUDE_PLUGIN_DATA}/diagnostics/container-mode，因此在你使用容器服务器期间，插件的会话开始 hook 会保持沉默。

v1.5.0 新增

  • 容器模式的镜像为 ghcr.io/transgenia/odoo-mcp-tools:1.5.0。
  • 容器模式的 odoo.env 文件可以设置权限配置档（ODOO_POLICY，默认 standard）、策略文件（ODOO_POLICY_FILE）和审计文件夹（ODOO_AUDIT_DIR）。参见 权限策略。
  • 在沙箱中，删除练习和 Studio 风格的改动需要 standard 以外的配置档：删除需要 full，字段、视图和自动化需要 builder。

v1.4.1 新增

容器模式的镜像为 ghcr.io/transgenia/odoo-mcp-tools:1.4.1。容器模式适用于没有 Python 的 Claude Code。

v1.4.0 新增

沙箱覆盖 Odoo Community 10.0 至 19.0（之前为 16.0 至 19.0），每个版本系列使用一个兼容的 PostgreSQL 版本。

v1.3.0 新增

/odoo-tools:deploy-local 会启动由 Transgenia 提供的本地基础设施。只有在你 调用并确认后才会运行：没有任何 hook 会自行运行 Docker。

通常你会从引导路线 /odoo-tools:odoo-setup-mcp 进入这里（第 1 阶段，“我没有可练习的 Odoo”或“我无法安装 Python”）。该命令也可以单独使用。

要求

  • Docker 与 Compose v2（docker compose；不支持旧版 docker-compose 程序）：Docker Desktop（Windows/macOS）或 Docker Engine + compose 插件（Linux）。参见 docs.docker.com/get-docker。
  • 沙箱需要：python3 3.9+（插件本来就需要）以及约 2 GB 磁盘空间。

模式 A：本地 Odoo 沙箱

仅限 Odoo Community（CE）

沙箱为 Odoo Community。Transgenia 无法提供 Odoo Enterprise 实例（由 Odoo S.A. 按订阅授权）或 Odoo Online 实例（Odoo S.A. 在 odoo.com 的 SaaS）。如需使用，请连接你自己的 Enterprise 实例或 Online 数据库。对于 Online，其套餐必须包含外部 API 访问：否则即使凭据正确也无法连接（参见 故障排查）。

在你的电脑上启动 PostgreSQL + Odoo Community 10.0 至 19.0，并准备好一个数据库（可选演示数据），让你在不触碰生产环境的情况下练习。

Odoo 10.0 至 16.0：仅用于测试和迁移

Odoo S.A. 只维护最新的三个版本（17.0、18.0 和 19.0）；10.0 至 16.0 已不再获得安全补丁。15.0 及以前的官方镜像仅支持 amd64：Docker Desktop（Apple Silicon、Windows ARM）会以模拟方式运行，速度较慢；在 ARM Linux 上使用 Docker Engine 时，需先注册 amd64 模拟（binfmt/QEMU，例如 docker run --privileged --rm tonistiigi/binfmt --install amd64），否则容器会因 "exec format error" 而失败。每个版本使用其兼容的 PostgreSQL：

Odoo PostgreSQL
10.0、11.0 10
12.0、13.0 12
14.0、15.0 13
16.0 至 19.0 16

每周都有一个工作流启动全部十个版本，并通过插件的 MCP 服务器进行验证；服务器按下文所述的方式登录：在 14.0 至 19.0 上使用 API key（在 19.0 上通过 JSON-2），在 10.0 至 13.0 上使用密码。

命令会一次问一件事：Odoo 版本（推荐 18.0）、演示数据、语言（例如 zh_CN）和端口（默认 8069）。然后运行：

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox up --odoo 18.0 --lang zh_CN --port 8069

它按顺序执行：

  1. 在 ~/.odoo-tools/sandbox 中写入 docker-compose.yml、odoo.conf 和 .env（文件夹 0700，.env 0600）。密码（PostgreSQL、Odoo 主密码和 admin 用户）在本地生成，并且从不打印；自 v1.6.0 起，它们都不以 "-" 开头，11.0 及更高版本的 Odoo 镜像曾把这样的密码当作一个选项来读取。
  2. 从 ghcr.io/transgenia/odoo 和 ghcr.io/transgenia/postgres 拉取镜像：这些是官方镜像的原样副本，由 Transgenia 每周更新。如果该仓库无法访问，则使用 Docker Hub 上的官方镜像。
  3. 启动容器，Odoo 仅发布在 127.0.0.1。
  4. 创建数据库（默认 sandbox）并验证登录。
  5. 在 Odoo 14.0 及更高版本上，让 Odoo 为 admin 用户创建一个 API key：通过沙箱的一次性容器中的 odoo shell，并使用 Odoo 自己的 res.users.apikeys。它会检查这个 key 能否登录，并把它以 ODOO_API_KEY 保存在同一个 .env 中，从不打印。Odoo 在 Preferences > Account Security 中把它列为 "odoo-tools sandbox"。之后的运行会复用它；如果它在 Odoo 中被删除了，就会替换它。Odoo 10.0 至 13.0 没有 API key，继续使用密码；无法创建 key 的沙箱也是如此：脚本会说明原因，下一次 sandbox up 会再试一次。

完成后会显示 URL、数据库、登录名，以及密码（~/.odoo-tools/sandbox/.env 中的 ODOO_ADMIN_PASSWORD）和在 14.0 及更高版本上的 API key（同一文件中的 ODOO_API_KEY）所在位置；其中的 plugin_credential 字段说明哪项凭据要填入插件选项。请你自己用编辑器打开该文件：Claude 不会读取它，也不会复制密码或 key。切勿把 key 或密码粘贴到聊天中。

将插件连接到沙箱

/plugin → odoo-tools → Configure options：

选项 值
Odoo URL http://localhost:8069（或你选择的端口）
Odoo database sandbox
Odoo login admin
Odoo API key Odoo 14.0 至 19.0：.env 中 ODOO_API_KEY 的值。在 10.0 至 13.0 上留空
Odoo password (Odoo < 14 only) Odoo 10.0 至 13.0：ODOO_ADMIN_PASSWORD 的值。在 14.0 至 19.0 上留空

如果脚本的汇总信息显示沙箱没有 API key（api_key 以 none: 开头），请像在 10.0 至 13.0 上一样使用密码：在沙箱上，它在 Odoo password 字段中同样有效，尽管该字段的标题写着 Odoo < 14 only。原因就在同一份汇总信息中，下一次 sandbox up 会再次尝试创建 key。

重启 Claude 并用 odoo_version 验证。插件选项只保存一个连接：要回到生产环境，需要重新填写生产环境的值。

在沙箱中，你可以使用 Permission profile builder 来练习字段、视图和自动化，或使用 full 来练习删除。插件中的示例 docs/policy-examples/sandbox-builder.json（配置档 builder）还会开放删除和测试用户。回到生产环境时，请把配置档改回 standard（或 readonly）。参见 示例。

管理沙箱

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox status
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox down           # 停止，保留数据
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox up             # 重新启动；在 14.0+ 上缺少 API key 时会创建
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox logs
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox destroy --yes  # 删除数据库与文件

也可以用自然语言请求：/odoo-tools:deploy-local status。

更换 Odoo 版本

用 Odoo 18 创建的数据库无法被 Odoo 17 打开（反之亦然）。脚本会检测到并停止：请先运行 destroy --yes，或用 --dir 使用另一个文件夹。

模式 B：容器中的 MCP 服务器

适用于装有 Claude Code 但没有 Python 3.9+ 的电脑。它是同一个 MCP 服务器，由 Transgenia 打包为 Docker 镜像（amd64 和 arm64），连接到你现有的 Odoo：

docker pull ghcr.io/transgenia/odoo-mcp-tools:1.6.0

  1. 命令会创建 ~/.odoo-tools/mcp/odoo.env（仅你的用户可读），其中只有占位符；你在自己的编辑器中填写 URL、数据库、登录名和 API key。该文件还以注释形式带有权限策略和审计的配置行：

    # ODOO_READONLY=1            # 建议在最初几步使用
# ODOO_POLICY=standard       # 配置档：readonly、standard、builder 或 full
# ODOO_POLICY_FILE=/policy/policy.json   # 可选，以只读方式挂载
# ODOO_AUDIT_DIR=/audit      # 不设置时，审计行会写到 docker logs

    默认配置档是 standard（不删除、不做 Studio 风格的改动、不读取密钥）；full 保留 1.4 的行为。使用策略文件或审计文件夹时，请在第 2 步命令中的镜像名称之前加上 -v <策略文件的绝对路径>:/policy/policy.json:ro 和 -v <审计文件夹的绝对路径>:/audit。

    然后把插件的数据文件夹标记为容器模式。这个标记告诉插件的会话开始 hook：正在使用的是容器服务器，因此它不再把插件自带的、保持未使用状态的服务器报告为从未连接：

    ( umask 077; mkdir -p "${CLAUDE_PLUGIN_DATA}/diagnostics" && touch "${CLAUDE_PLUGIN_DATA}/diagnostics/container-mode" )

  2. 在 Claude Code 中注册它（会先向你展示命令）：

    claude mcp add odoo-tools-docker --scope user -- docker run -i --rm --env-file "$HOME/.odoo-tools/mcp/odoo.env" ghcr.io/transgenia/odoo-mcp-tools:1.6.0

  3. 重启 Claude，并用 odoo-tools-docker 服务器的 odoo_version 验证。如果插件自带的服务器也已配置，工具会出现两次：请只保留一个。撤销此模式：claude mcp remove odoo-tools-docker，以及 rm "${CLAUDE_PLUGIN_DATA}/diagnostics/container-mode"。

在 Windows 上，该文件为 %USERPROFILE%\.odoo-tools\mcp\odoo.env；请用你的编辑器创建它。

只要 container-mode 标记存在，插件的会话开始 hook 就不显示任何提示：正在使用的是容器服务器，因此插件自带的服务器保持未使用状态是预期之中的。

从沙箱到生产

沙箱用于学习和测试。要把 Odoo + AI 投入生产（托管、安全、迁移、集成、团队培训），Transgenia 通过其官方渠道提供协助部署与支持：dev@transgenia.org · WhatsApp +52 55 8034 0405。参见 支持。