Shopify × Codex × Claude Code 连接全流程：从踩坑到跑通

先说一句：这篇文章不是翻译的官方文档，而是我自己花了两天时间，从零开始把 Shopify、Codex、Claude Code 串起来的过程记录。中间踩了不少坑——权限报错、MCP 不加载、命令找不到、搞不清楚 live theme 和 development theme 到底哪个能动——所以这篇文档会把「为什么这样做」也讲清楚，不只是贴命令。

如果你跟我差不多——不是专业程序员，但想用 AI 来管理和修改 Shopify 主题，希望 AI 能读取店铺信息、帮你写代码、同时不会把正在营业的店铺改崩——那这篇应该能帮你省下不少时间。

📑 目录

一、先理解：到底在连接什么？

很多人（包括一开始的我）以为「连接 Shopify」就是一个动作，AI 直接连上店铺，咻一下就完事了。但实际你在连接的是三个不同的层级。搞清楚这一点，后面大部分报错你都能自己判断问题出在哪一层。

层级	代表工具	作用	会直接改店铺吗？
AI 工具	Codex / Claude Code	理解需求、写代码、执行你允许的命令	❌ 不会，除非调用了 CLI/API 写入
连接工具	Shopify CLI / AI Toolkit / MCP	CLI 负责登录和主题命令；AI Toolkit/MCP 负责提供 Shopify 文档和 API 上下文	⚠️ CLI/API 写入命令会改
Shopify 店铺	xxx.myshopify.com	真实的线上店铺、主题、产品、订单	✅ 会，需要谨慎

一句话记忆：AI 是司机，Shopify CLI 是车钥匙，Shopify 店铺是真实的车。司机再聪明，能不能开车、开哪辆车、能不能上路，取决于你给的权限和命令。

二、准备工作：你需要哪些东西

准备项	为什么需要	检查方式
Shopify 后台账号	登录店铺、授权 CLI	能打开 Shopify Admin 即可
店铺 myshopify.com 域名	CLI 命令需要用它指定店铺	例如：158e15.myshopify.com
VS Code	运行 Codex / Claude Code、编辑配置	打开项目文件夹
Node.js	Shopify CLI、MCP 依赖 Node 环境	`node -v`
npm / npx	安装 CLI、启动 MCP	`npm -v`、`npx -v`
Shopify CLI	真正连接店铺主题	`shopify version`
Codex 配置文件	让 Codex 加载 Shopify Dev MCP	`~/.codex/config.toml`
备份策略	防止误改 live theme	Duplicate 活跃主题

这里有个容易搞混的地方：前台独立站域名（比如 vernailiquea.com）和 Shopify 后台域名（xxx.myshopify.com）是两回事。CLI 连接命令里填的是 myshopify.com 那个，别填错了。

三、Node.js / npm / npx 是什么？为什么绕不开它

Shopify CLI 和 Shopify Dev MCP 都是基于 Node/npm 生态运行的工具。你不用成为程序员，但需要知道这三个命令各自是干嘛的：

命令	是什么	用来做什么
`node`	Node.js 运行环境	让 JavaScript 工具能在你电脑上跑
`npm`	Node 的包管理工具	安装 Shopify CLI 等工具
`npx`	临时运行 npm 包的工具	启动 `@shopify/dev-mcp@latest` 这类 MCP 服务

在终端里分别跑一下 node -v、npm -v、npx -v，三条都返回版本号，说明基础环境没问题。如果出现 command not found，先去装 Node.js LTS 版本。

四、npm -g 的两种安装方式

安装 Shopify CLI 的常用命令是 npm install -g @shopify/cli @shopify/theme。这里的 -g 是 global 的意思，就是让 shopify 这个命令在任何文件夹里都能用，而不是只在某个项目里才能用。

但问题来了——全局安装有两条路可以走，选错了你会反复碰到权限报错。

方式一：标准系统全局安装

npm install -g @shopify/cli @shopify/theme

如果 npm 的全局目录在 /usr/local/lib/node_modules 或 /opt/homebrew 下面，普通用户没有写入权限，就可能遇到 EACCES 错误。网上很多教程会让你加 sudo——能解决一时的问题，但后面可能会留下一堆权限混乱的坑。

方式二：用户目录全局安装（我个人用这个）

思路很简单：把 npm 的全局安装目录从系统目录改成你自己的用户目录，从此跟 sudo 说再见。

# 创建你自己的 npm 全局工具目录
mkdir -p ~/.npm-global

# 告诉 npm 以后 -g 全局工具装到这里
npm config set prefix '~/.npm-global'

# 让终端以后能找到 ~/.npm-global/bin 里的命令
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 安装
npm install -g @shopify/cli @shopify/theme

注意：这仍然是「全局安装」，只是全局目录从系统目录换到了用户目录。结果是任何项目都能用 shopify 命令，但不需要 sudo。

命令	作用
`mkdir -p ~/.npm-global`	创建自己的 npm 全局工具目录
`npm config set prefix ...`	告诉 npm 以后 -g 工具安装到这个目录
`echo ... >> ~/.zshrc`	让终端能找到 ~/.npm-global/bin 里的命令
`source ~/.zshrc`	让刚写入的 PATH 配置立即生效

五、安装 Shopify CLI 并连接店铺

5.1 安装并检查

npm install -g @shopify/cli @shopify/theme
shopify version

如果你用了自定义目录（方式二），而且 AI 工具找不到 shopify 命令，直接换完整路径：

/Users/你的用户名/.npm-global/bin/shopify version

5.2 登录 Shopify 账号

新版 Shopify CLI 里，auth login 是登录账号用的，不要把 --store 参数跟在 auth login 后面。

shopify auth login

我就在这里踩坑了。一开始写了 shopify auth login --store xxx.myshopify.com，直接报 Nonexistent flag: --store。正确做法是先 auth login，然后在主题相关命令里才带 --store。

5.3 查询主题列表

shopify theme list --store 你的店铺.myshopify.com

这个命令会列出你店铺里所有主题的名称、角色和 ID。重点看 Role 这一列：

Role	含义	建议
live	正在线上给顾客访问的主题	🚫 不要直接改
unpublished	未发布 / 草稿主题	✅ 适合测试修改
development	开发主题	✅ 适合调试和测试

六、让 Codex 连接 Shopify

Codex 连接 Shopify 分两部分：一是配置 Shopify Dev MCP，让 Codex 能调用 Shopify 官方开发资源；二是让 Codex 能调用 Shopify CLI，读取主题列表和执行你确认过的命令。

6.1 配置 Shopify Dev MCP

# 创建 Codex 配置文件
mkdir -p ~/.codex
touch ~/.codex/config.toml
open ~/.codex/config.toml

在 config.toml 里面加上这几行：

[mcp_servers.shopify-dev-mcp]
command = "npx"
args = ["-y", "@shopify/dev-mcp@latest"]
enabled = true

保存后彻底重启 VS Code / Codex。然后你可以问 Codex 一句：

请确认 Shopify Dev MCP 是否可用，并列出当前可用的 MCP servers、tools 和 resources。

如果 MCP 还是不可用，排查这几个点：

config.toml 是不是在 /Users/你的用户名/.codex/config.toml 这个路径下
npx -v 能不能正常返回版本号
试试把 command = "npx" 改成 which npx 返回的完整路径
重启 VS Code（要彻底退出再打开，不是点叉号最小化）

6.2 让 Codex 找到 Shopify CLI

如果你的终端里跑 shopify 没问题，但 Codex 里说 command not found，原因通常是Codex 没读到你的 PATH 环境变量。

最简单的解决办法就是直接用完整路径：

/Users/你的用户名/.npm-global/bin/shopify version
/Users/你的用户名/.npm-global/bin/shopify theme list --store 你的店铺.myshopify.com

如果想彻底修好，可以把 PATH 写进 ~/.zprofile（GUI 应用启动时会读这个文件）：

echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

七、让 Claude Code 也连上 Shopify

VS Code 里的 Claude Code 也可以用 Shopify AI Toolkit。如果你的 Claude Code 支持插件命令，直接在对话里跑：

/plugin marketplace add Shopify/shopify-ai-toolkit

如果不支持插件命令，在终端里跑：

claude plugin install shopify-ai-toolkit@claude-plugins-official

装好后重启 Claude Code，然后用完整路径测试一下 CLI：

/Users/你的用户名/.npm-global/bin/shopify theme list --store 你的店铺.myshopify.com

八、⚠️ 动手前最重要的一步：备份 Live Theme

在让 AI 碰到你的店铺之前，先把正在营业的主题备份一份。这样哪怕 development theme 改崩了，也不会影响顾客看到的页面。这步花不了三十秒，但能帮你避开最大的坑。

后台手动备份（适合小白）

打开 Shopify Admin → Online Store → Themes
找到当前 Live theme，点右侧的 ... → Duplicate
复制完后重命名成类似：LIVE BACKUP before AI edit 2026-05-17

用 CLI 备份

shopify theme duplicate --store 你的店铺.myshopify.com --theme 主题ID --name "LIVE BACKUP before AI edit 2026-05-17"

duplicate 本身是安全的备份动作，但执行前最好让 AI 先告诉你它要做什么——确认它复制的是 live theme，而不是去覆盖或发布主题。

九、权限设置与安全边界

这部分很重要，但很容易被忽略。

AI 工具的「完全访问权限」不等于 Shopify 全部权限

Codex / Claude Code 里的 Full Access（完全访问权限），意思是它能执行命令、读项目文件、调用可用工具。这不等于它能随便改你的 Shopify 店铺所有数据。

Shopify 店铺的权限来自几个维度：

CLI 登录 → 决定了能不能操作主题
theme 命令 → 能读取 / 修改主题代码
store auth → 能不能读产品、订单等店铺数据
Admin API Token → 更细粒度的 API 权限

什么时候才需要 store auth？

如果你只是修改主题，一开始不需要产品 Admin API 授权。只有当你需要 AI 帮你读产品、分析数据的时候，才给只读权限：

shopify store auth --store 你的店铺.myshopify.com --scopes read_products

注意参数是 --scopes（复数），不是 --scope。另外也别一上来就给 write_products、write_orders 这种写入级权限。

十、实际配置速查

下面是我自己这套环境的具体配置，替换成你自己的信息就能用：

项目	示例值	说明
店铺域名	158e15.myshopify.com	CLI 使用的店铺连接域名
CLI 路径	/Users/你的用户名/.npm-global/bin/shopify	CLI 安装在自定义用户目录
Live Theme ID	189164650818	🚫 正在上线，禁止直接修改
Development Theme ID	189015261506	✅ 可用于测试修改

只读检查命令：

shopify version
shopify theme list --store 你的店铺.myshopify.com

推荐写入前的提示词：

我的 Shopify 店铺是 xxx.myshopify.com。禁止修改 live theme：xxx。只允许操作 development theme：xxx。任何写入 Shopify 的操作前，必须先列出命令、作用、影响文件和风险，并等待我确认。

十一、常见报错速查

这些是我实际操作中遇到的报错，以及花了时间才找到的解决方法：

现象	原因	解决方法
`npm error EACCES`	npm 缓存或全局目录权限混乱	`sudo chown -R $(whoami) ~/.npm`，或改用 ~/.npm-global
`permission denied: /usr/local/lib/node_modules`	普通用户不能写系统 npm 全局目录	使用 sudo 或设置 npm prefix 到用户目录
Codex 里 `command not found: shopify`	Codex 没读取到你的 PATH	用完整路径，或写入 ~/.zprofile 后重启 VS Code
`auth login --store` 报 Nonexistent flag	auth login 不支持 –store 参数	先 `shopify auth login`，再 `theme list --store`
MCP resources/tools 为空	Codex 没加载 MCP 配置或 npx 不可用	检查 config.toml、`npx -v`、重启 VS Code
`store execute` 提示 No stored app authentication	店铺数据 API 未授权	运行 `shopify store auth --store xxx --scopes read_products`
Finder 看不到 .codex 文件夹	点开头的文件夹是隐藏文件	Finder 按 `Command + Shift + .`

十二、可复用提示词模板

这几个模板你直接复制就能用，把里面的店铺信息和路径替换掉就行：

模板一：只读检查

请只读检查 Shopify 连接状态：
1. 运行 shopify version
2. 运行 shopify theme list –store xxx.myshopify.com
3. 告诉我当前 live theme 和 development theme 分别是什么
4. 不要执行任何写入操作

模板二：先备份再动手

请先备份当前 live theme，不要修改任何代码。需要备份的 live theme ID：xxx。请准备执行 theme duplicate。执行前先告诉我命令作用和风险，等我确认后再执行。

模板三：长期安全规则

安全规则：
1. 不要修改 live theme。
2. 不要 publish 任何主题。
3. 不要 delete 任何主题。
4. 不要修改产品、订单、客户、库存，除非我明确要求。
5. 任何写入 Shopify 的操作前，必须先告诉我具体命令、作用、影响文件和风险，并等待我确认。
6. 查询主题列表、读取主题结构、查 Shopify 文档可以直接进行。
7. 如果要修改代码，只能操作 development theme。

十三、命令速查表

目的	命令
检查 Node	`node -v`
检查 npm	`npm -v`
检查 npx	`npx -v`
创建用户全局目录	`mkdir -p ~/.npm-global`
设置 npm prefix	`npm config set prefix '~/.npm-global'`
加入 PATH	`echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc`
立即生效	`source ~/.zshrc`
安装 Shopify CLI	`npm install -g @shopify/cli @shopify/theme`
检查 CLI	`shopify version`
登录账号	`shopify auth login`
查询主题	`shopify theme list --store xxx.myshopify.com`
复制主题	`shopify theme duplicate --store xxx.myshopify.com --theme 主题ID --name "备份名称"`
只读产品授权	`shopify store auth --store xxx.myshopify.com --scopes read_products`

十四、写在后面

说实话，把这几样东西连起来比我想象中费劲。原以为「装个 CLI、配个 MCP」不就是十分钟的事吗？实际是权限问题折腾了半天，PATH 环境变量又折腾了半天，中间还因为搞不清楚 live theme 和 development theme 的区别，差点直接改线上主题。

但一旦跑通之后，确实方便很多——你不需要自己记住所有 Shopify CLI 命令，也不需要去翻文档看 theme list 的参数格式，AI 帮你处理这些，你只需要确认它要做什么就行。这对我们这种非专业开发者来说，算是一个很大的效率提升。

最后再强调一遍：在让 AI 碰你的店铺之前，先把 live theme 备份了。这步真的花不了三十秒。备份之后你心里就有底了，哪怕改坏了也能随时恢复，不至于影响到正在营业的店铺。

最终检查清单

✅ Shopify CLI 能显示版本号
✅ theme list 能列出 live / unpublished / development 主题
✅ 已经备份 live theme
✅ AI 工具知道禁止修改 live theme
✅ AI 工具只允许操作 development / unpublished theme
✅ 任何写入 Shopify 前都需要人工确认
✅ 不要把 token / API key 发给 AI 或截图公开

希望这篇能帮你少走弯路。有什么问题欢迎在评论区交流 👋

📑 目录

一、先理解：到底在连接什么？

二、准备工作：你需要哪些东西

三、Node.js / npm / npx 是什么？为什么绕不开它

四、npm -g 的两种安装方式

方式一：标准系统全局安装

方式二：用户目录全局安装（我个人用这个）

五、安装 Shopify CLI 并连接店铺

5.1 安装并检查

5.2 登录 Shopify 账号

5.3 查询主题列表

六、让 Codex 连接 Shopify

6.1 配置 Shopify Dev MCP

6.2 让 Codex 找到 Shopify CLI

七、让 Claude Code 也连上 Shopify

八、⚠️ 动手前最重要的一步：备份 Live Theme

后台手动备份（适合小白）

用 CLI 备份

九、权限设置与安全边界

AI 工具的「完全访问权限」不等于 Shopify 全部权限

什么时候才需要 store auth？

十、实际配置速查

十一、常见报错速查

十二、可复用提示词模板

模板一：只读检查

模板二：先备份再动手

模板三：长期安全规则

十三、命令速查表

十四、写在后面

最终检查清单

参考链接

评论

发送评论编辑评论

📑 目录

一、先理解：到底在连接什么？

二、准备工作：你需要哪些东西

三、Node.js / npm / npx 是什么？为什么绕不开它

四、npm -g 的两种安装方式

方式一：标准系统全局安装

方式二：用户目录全局安装（我个人用这个）

五、安装 Shopify CLI 并连接店铺

5.1 安装并检查

5.2 登录 Shopify 账号

5.3 查询主题列表

六、让 Codex 连接 Shopify

6.1 配置 Shopify Dev MCP

6.2 让 Codex 找到 Shopify CLI

七、让 Claude Code 也连上 Shopify

八、⚠️ 动手前最重要的一步：备份 Live Theme

后台手动备份（适合小白）

用 CLI 备份

九、权限设置与安全边界

AI 工具的「完全访问权限」不等于 Shopify 全部权限

什么时候才需要 store auth？

十、实际配置速查

十一、常见报错速查

十二、可复用提示词模板

模板一：只读检查

模板二：先备份再动手

模板三：长期安全规则

十三、命令速查表

十四、写在后面

最终检查清单

参考链接

评论

发送评论 编辑评论

推荐文章

发送评论编辑评论