本手冊適用於未曾寫過 Liquid、想以 Claude Code 或 Codex 從零建立 Shopify 商店的開發者。 內容涵蓋 Full Agentic Dev 工作流、MCP 生態系，以及社群實戰中常見的操作錯誤與對策。 完成後可取得一份可直接使用的 CLAUDE.md、可重複執行的安裝腳本，以及保護正式環境的安全設定。
Shopify 在 2025–2026 年連續推出三項變動，將 AI 代理人整合納入核心開發與銷售流程。
2025 年 12 月,Winter '26 Edition 發布。 Shopify 把官方 Dev MCP Server 內建到平台,讓 AI 代理人第一次能用結構化的方式存取 GraphQL Admin API、Storefront API 與 Liquid 文件。這場改版含 150 + 項 AI 功能,Shopify 自己稱為「The Renaissance」。
2026 年 3 月 24 日,Agentic Storefronts 全面啟用。 美國境內合資格商家被預設打開:5.6 M 間商店同時在 ChatGPT、Microsoft Copilot、Google AI Mode、Gemini App 裡變得可購買。麥肯錫預估 2030 年全球代理人商務將達到 5 兆美元規模。
2026 年 4 月 9 日,Shopify AI Toolkit 開源(MIT License)。 一鍵把 Dev MCP、Admin GraphQL、Liquid 驗證、UI Extensions 校驗等16 項 Agent Skills裝進 Claude Code、Codex、Cursor、Gemini CLI、VS Code。
對開發者的實際影響有三點：第一，不需要記憶 GraphQL 欄位，代理人在寫程式前會先用 Dev MCP 驗證 schema。第二，不需要切換視窗，代理人在終端機裡即可改主題、跑 mutation、推上線。第三，Shopify 工程副總 Farhan Thawar 指出：「2026 年沒搞懂怎麼駕馭代理人的人就會被甩開。」
Claude Code 與 Codex 不是替代關係，關鍵問題是：哪一段工作要交給哪個元件？ 以下四個元件在完整工作流中各有角色。
Anthropic 出品、終端機原生 (terminal-native) 的代理人 CLI。讀整個 repo、跑 shell、做 git 操作。1M token context 能裝得下整套 Dawn theme,適合改 Liquid、寫 Hydrogen、做大型重構。
OpenAI 的對應品,讀 AGENTS.md 而非 CLAUDE.md,設定走 TOML(~/.codex/config.toml)。Subagent、Hook、Skill 都有,且支援把自己當成 MCP server 給別的代理人呼叫。
本機跑、不需 auth。提供文件搜尋、GraphQL Admin/Storefront schema 即時校驗、Liquid 範本驗證。所有寫程式的代理人請務必接上。
每間商店自動擁有 /api/mcp 端點,讓 ChatGPT、Claude.ai、Perplexity 的購物代理人能搜商品、加購物車、走結帳。不是你要呼叫的,是你要被呼叫的。
用 shopify store auth + shopify store execute(3.93.0 起),代理人能直接讀寫商品、訂單、metafield。--allow-mutations 預設關閉,寫操作要明確開啟。
GeLi2001 等社群成員維護的 Admin MCP,直接接 Shopify Admin GraphQL。比 Shopify 官方更直接,但維護不保證,適合熟練後玩自動化。
先決條件:Node.js 18+、終端機 (Terminal / iTerm2 / Warp)、一個 Shopify Partner 帳號。沒 Partner 帳號?去 partners.shopify.com 免費註冊,順便開一個 Dev Store(永遠不要在正式店做第一次練習)。
# 1. 安裝 Claude Code(全域) $ npm install -g @anthropic-ai/claude-code # 2. 在任意目錄啟動,瀏覽器會自動開 OAuth $ claude ✓ Signed in as you@example.com (Max subscription) # 3. 一鍵裝 Shopify AI Toolkit(最推薦的方式) claude> /plugin marketplace add Shopify/shopify-ai-toolkit claude> /plugin install shopify-plugin@shopify-ai-toolkit ✓ 7 tools available · auto-update enabled # 4. 如果你只想要 Dev MCP(不要整包 toolkit) $ claude mcp add --transport stdio shopify-dev-mcp \ -- npx -y @shopify/dev-mcp@latest # 5. 驗證 claude> /mcp ✓ shopify-dev-mcp · connected
# 1. 安裝 Codex CLI $ npm install -g @openai/codex # 2. 認證(ChatGPT OAuth 或 API key) $ codex login # 3. 用內建 plugin 流程裝 Shopify Toolkit $ codex codex> /plugins # 搜尋 "Shopify" → Add to Codex # 4. 或手動寫進 ~/.codex/config.toml $ cat >> ~/.codex/config.toml << 'EOF' [mcp_servers.shopify-dev] command = "npx" args = ["-y", "@shopify/dev-mcp@latest"] EOF $ codex mcp list shopify-dev · stdio · ready
# Shopify CLI 3.x — theme dev、app dev、store auth/execute 都靠它 $ npm install -g @shopify/cli@latest # 替正式店做唯讀授權(代理人從這把開始用 GraphQL) $ shopify store auth --store your-store.myshopify.com \ --scopes read_products,read_orders,read_customers,read_inventory # 跑一個唯讀查詢驗證 $ shopify store execute \ --store your-store.myshopify.com \ --query 'query { shop { name email currencyCode } }' { "shop": { "name": "Your Store", ... } } # 寫操作要明確加 flag — 千萬不要 alias 掉這個 flag $ shopify store execute --allow-mutations \ --query 'mutation { productCreate(input: { title: "Test" }) { product { id } } }'
前 10 個 session 全部對著 dev store 操作。安裝、prompt 練習、subagent 設計都應先在 dev store 完成。Shopify scope 是對整類資源授權：write_products 不是「允許改這三個商品」，而是「允許改店裡每一個商品」。
CLAUDE.md（Claude Code 讀取）、AGENTS.md（Codex、Cursor、Gemini CLI 共用標準）放在專案根目錄。
這份檔案是代理人的專案說明書、守則與風格指南。若未正確設定，代理人可能發明不存在的 Liquid filter、將 metafield 寫入 client-side JS，或 commit settings_data.json 覆蓋線上客製化內容。
# Project · {store-name} ## Stack - Shopify Online Store 2.0 theme (Dawn-based) - Shopify CLI 3.x · Node 20 - Theme check enforced, zero errors required ## Rules — non-negotiable 1. Never push to a live theme. Use development themes. 2. Never commit config/settings_data.json. 3. Before marking ANY task complete, run shopify theme check and confirm 0 errors. 4. Prefer {% render %} over {% include %}. 5. Themes only READ metafields — never write. 6. Always check existence: {% if product.metafields.custom.x != blank %} ## Conventions - Branch names: feature/, fix/, chore/ prefixes - One logical change per commit, imperative mood - Translation keys via locales/, no hard-coded strings ## When in doubt - ASK clarifying questions BEFORE editing. - Validate every GraphQL query via shopify-dev-mcp first. - If 16KB metafield limit hit, flag it — don't truncate. ## House style - Brand voice: warm, expert, no hype. - Currency: NTD primary, USD secondary.
社群有開源版本可直接套用。Karim Tarek 在 GitHub 維護一份 Shopify Theme CLAUDE.md，涵蓋前端最佳實踐，drop 到專案根目錄即可使用。
以下不是工程進度表，而是給初次做電商的人的逐日對話範本，可直接貼給代理人執行。
安裝 Node、Claude Code 或 Codex、Shopify CLI。註冊 Partner 帳號，開一間 development store。將 CLAUDE.md 放入專案根目錄。第一個 prompt 不要寫程式，請代理人讀整個 repo 並回報對專案的理解。將不正確的部分補進 CLAUDE.md。
「請從 Shopify CLI 用 dawn 為 base 初始化一個 theme,把它的目錄結構解釋給我聽,然後幫我做三件事:1) 改 logo 與 favicon 的 placeholder; 2) 設定品牌色 CSS variable; 3) 把 hero section 的 placeholder 內容換成符合 {你的品牌敘述} 的文案。每一步請先說會改哪些檔案再動手。」
準備一份 CSV(欄位:title, description, price, sku, vendor, tags, variant_options, images_urls)。叫代理人:「用 Admin GraphQL productCreate mutation 把這份 CSV 匯入 dev store。每筆寫 SEO-optimized description。商品標題要自然語言化(給 AI 購物代理人吃),不要走品牌系列命名。匯入完用 shopify store execute 查回來,告訴我有幾筆失敗。」
定義 product.specifications(JSON metafield)、product.care_instructions(rich text)、product.materials(list)。叫代理人把這些 metafield 從 admin 建好、批次 populate、再在 product page section 渲染出來。這一步是 AI 購物代理人能找到你商品的關鍵。
每一個 section 是一個 Liquid 檔加一份 schema。叫代理人:「把 hero 改成可以接 image_picker、richtext、url 三種 setting 的 reusable section。然後在 templates/index.json 加入這個 section 並讓我可以在 theme editor 拖拉。改完跑 shopify theme check,把所有錯誤跟警告一併修掉。」
這段大部分在 admin UI 設定,代理人協助確認 checklist。請代理人:「用 shopify store execute 把以下事項都檢查一遍並列出尚未設定的:payment gateway 啟用、shipping zones、tax registration、refund policy、privacy policy、cookie banner、abandoned cart email。每一項給我具體要去哪裡開啟。」
建立一個叫 theme-performance-auditor 的 subagent(放在 .claude/agents/),指定它能跑 Lighthouse、讀輸出、提出具體 Liquid 改動,並再跑一次驗證進步幅度。pair with shopify theme check --performance。
編輯 robots.txt,確認 GPTBot、ClaudeBot、PerplexityBot 都被允許爬取。送商品到 Shopify Catalog。在 Search Console、Bing Webmaster 註冊 sitemap。每一間商店都自動擁有 /api/mcp,你不用做什麼,但要驗證它回得正常。
shopify theme push --unpublished 預覽。把 GA4、GTM、Klaviyo 接好(都可用 MCP 或代理人寫腳本完成)。發布。之後每週固定請代理人跑一份 30 分鐘的健檢:低庫存商品、缺 alt text 圖片、未回應評論、購物車放棄序列觸發率。
有效 prompt 的三個要素：(1) 先計畫、後執行；(2) 給驗證手段，不只給目標；(3) 明訂 stopping condition。以下四份範本對應不同開發階段，可直接套用。
[ROLE] 你是 Shopify 主題開發資深工程師,熟悉 Online Store 2.0、Liquid、theme app extensions、Shopify CLI 3.x。 [CONTEXT] 我有一間賣 {台灣手沖咖啡器具} 的 dev store({store.myshopify.com}),預計上架 {40} 個 SKU,客單價約 {NT$1,500–4,000}。目標市場:{台灣 + 日本},語系:{zh-TW 主要、ja 次要}。 [TASK] 替我從 Dawn 為 base 初始化一個 theme,並完成以下: 1. 設定 brand color tokens(CSS var)為 {#1A1A1A, #C77B3E, #F4F1EA} 2. 設定 typography(display: {Fraunces},body: {Noto Sans TC}) 3. 客製 hero section:支援 image / video / no media 三種模式 4. 客製 product card:顯示金額、評星、metafield {custom.origin} 與 {custom.brewing_method} 5. 建立 zh-TW 與 ja locale 檔,所有 hard-coded 字串都搬進 translation key [CONSTRAINTS] - 每改一個檔案前先說「我即將改哪幾個檔、為什麼」 - 所有 Liquid 用 shopify-dev-mcp 驗證過再寫 - {% render %} 優先,禁用 {% include %} - 完工前跑 shopify theme check,0 errors 才回報完成 [STOP CONDITION] - 全部跑通 + theme check 0 errors + 在 dev store 可預覽 - 給我一份 README 描述每個自訂 section 的 setting [BEGIN] 先 plan 再 execute,plan 階段請等我說 "go" 才動手。
[ROLE] 你是 Shopify 商品資料工程師。 [CONTEXT] CSV 檔在 {./data/products-2026Q3.csv},欄位:{sku, title_zh, title_en, price, vendor, tags, weight_g, variant_color, image_urls}。共 {40} 筆。 [TASK] 1. 用 shopify-dev-mcp 驗證 productCreate / productVariantsBulkCreate 的最新 schema 2. 對每筆商品產生: - 自然語言化 product title(給 AI 購物代理人吃,不要用品牌系列名) - 80–120 字 SEO description(含 1 個 primary keyword + 2 個 long-tail) - 4 個 metafield: custom.origin / custom.brewing_method / custom.material / custom.gift_ready (boolean) 3. 用 Admin GraphQL bulk operation 一次寫入 4. 失敗筆數獨立輸出到 {./logs/failed-{timestamp}.json} [GUARDRAILS] - GraphQL rate cost 上限 1000/min,自動 throttle - 寫描述前先讀 CLAUDE.md 裡的「品牌語氣」段落 - 如果同 SKU 已存在,印出比對結果讓我選 skip 或 update,不要直接覆蓋 [VERIFICATION] - 跑完後 query 回來確認筆數 - 抽 3 筆完整印出來給我審 [BEGIN] 先 plan、列出會用到的 mutation 與 estimated cost,等我說 "go"。
[GOAL] 我想做一個「{訂閱式咖啡豆配送}」功能,但我不知道用 metafields、theme app extension、checkout extension、還是 Shopify Subscription App 比較好。 [TASK] 請用 AskUserQuestion 工具訪談我,把這些挖出來: - 技術實作偏好(我能接受的複雜度) - UX/UI(顧客買的時候會看到什麼) - Edge cases(換貨、暫停、跳過一期) - 我沒想到的取捨 不要問顯而易見的問題,挑硬的問。 訪談結束後,寫一份完整 spec 到 {./SPEC-subscription.md}。 [ENDING] spec 完成後 → 不要動手實作。 告訴我:「請開新 session,把 SPEC 當 input 來執行。」
[ROLE] 你是執行 Shopify Admin mutation 的 careful operator。 [TASK] 把所有標籤含 {summer-2026} 的商品, variant 售價 ≥ NT$1,500 的部分,變動價格為原價 85%。 [NON-NEGOTIABLE] 1. 先 dry-run:列出 affected products 與 affected variants 2. 計算每筆 old_price → new_price,輸出成 CSV 給我審 3. 等我打字確認 "EXECUTE" 才真的跑 mutation 4. 跑的時候用 productVariantsBulkUpdate(不是逐筆),分批 batch 5. 跑完後輸出:成功筆數、失敗筆數、失敗原因 6. 失敗的部分產生 rollback 指令(原價 list) 7. 全程用 --allow-mutations,完事後請我手動關掉 [STOP IF] - dry-run 顯示 affected variants > {500} - 任何 variant 的 new_price 算出來 < {50}(可能是資料錯)
以下內容來自 r/ClaudeAI、r/Shopify、r/ChatGPTCoding 開發者的實際回報，以及 Talk Shop、Charle、Flagship 等代理商的 post-mortem，官方文件未收錄。
write_products 的瞬間,代理人可以改店裡每一個商品。Talk Shop 社群統計:十次中有一次代理人會誤解你的指令邊界。--dangerously-bypass-approvals-and-sandbox(yolo mode)用在正式店。git reset --hard 才有救。/init 命令會讓 Claude Code 掃整個專案、寫一份 CLAUDE.md 草稿。即使你已經有 CLAUDE.md,在大重構前讓它重做一次能補上你漏掉的脈絡。Control + V(不是 Cmd + V)貼圖到 Claude Code。「分析這頁 UI 並建議改進」會比文字描述精準十倍。/clear 重開，將現況記錄進 status.md 後再開下一個 session。list.product_reference 跟 list.single_line_text_field 該何時用。每個 subagent 是 .claude/agents/{name}.md,YAML frontmatter 寫好 scope / tools / personality。commit 進 repo 給整個團隊用。
codex mcp serve 讓 Claude Code 能呼叫 Codex。兩個不同模型互相審查同一段程式，可降低錯誤率。features.multi_agent = true 才會啟用 spawn_agent、send_input、resume_agent。預設是開的,但低於 stable 之前手動確認一次。project_root_markers = [".git", "pnpm-workspace.yaml"] 讓 Codex 知道從哪一層讀 AGENTS.md。PreToolUse 攔截危險 bash 指令，PostToolUse 自動跑 theme check。Anthropic 官方 best practices 有完整範例。把 settings_data.json 推上 git。 這個檔案存的是商家在 theme editor 改過的客製化(顏色、圖片、文字)。一推就把線上實際內容覆蓋掉。永遠 .gitignore 它,除非你有刻意設計的 sync 策略。
讓代理人直接 push 到 live theme。 永遠用 shopify theme push --unpublished 推到一個預覽 theme,從 admin 切換 preview 確認後再 publish。CLAUDE.md 第一條就該寫:Never push to a live theme。
用 client-side JS 改 metafield。 主題只能讀 metafield,不能寫。代理人偶爾會試圖在 JS 裡 fetch admin API 來改,這會洩漏 admin token 並違反 Shopify 政策。寫 metafield 一律走 Admin API + server side。
動態組 metafield key。 看起來聰明:product.metafields["custom"][key]。Liquid 不允許 runtime 組 key,會無聲失敗。一律 product.metafields.custom.tagline 這種 dot notation。
GraphQL rate limit 撞牆。 Standard plan 的 Admin API 上限是 1000 cost points / minute。批次操作上百筆時,代理人會直接全打過去 → throttled error。CLAUDE.md 加一條:「批次 mutation 必須 throttle、batch、retry on 429」。
對 Liquid 用 ChatGPT 一般 prompt。 Liquid 在公開語料裡少,模型沒接 Dev MCP 時很容易發明不存在的 filter(product.featured_variant 就是典型幻覺)。務必掛 shopify-dev-mcp,讓代理人寫前先查 schema。
把 --allow-mutations 設成預設。 這個 flag 是給「agent 互動式探索」的安全網。如果你 alias 成永遠開啟,等於拿掉所有安全護欄。每次有寫意圖再開,跑完手動關。
沒有 audit log 就動正式店。 Shopify AI Toolkit 沒有 toolkit 層級的操作記錄。代理人改了什麼、何時改、誰下指令,出包要回溯很痛。建議自己包一層:每次 mutation 寫入 ./logs/{date}/ops.jsonl。
商店上線後，依目標可向三個方向延伸：規模化、功能深化或產品化。
當 Liquid theme 撐不住你想做的互動深度時,用 Hydrogen(Remix-based 的 Shopify 框架)+ Oxygen 部署。Claude Code 的 Hydrogen subagent 能直接寫 routes、queries、components,且 Shopify Storefront MCP 從 2026.1.4 起內建到 Hydrogen。
要做 dynamic pricing、特殊 discount logic、checkout 客製,走 Shopify Functions(Wasm)+ Custom App。Claude Code 用 shopify app create scaffold,寫 Polaris React UI,跑 prisma migrate,全程不離終端機。TinyTwo 的 ReviewMate 案例(從零用 Claude Code 寫一個 production review app)是最佳參考。
當你有 5 + 間商店要管時,把 Composio Tool Router 或社群 admin MCP 接進 Claude Code。一個自然語言指令打到 Claude → 並行操作多店:「把所有店裡標籤含 holiday-2026 的商品庫存歸零並下架。」
學習重點不在 Liquid 語法，在於如何定義問題、選擇代理人、驗收輸出。