Shopify ストアを運営する OpenClaw スキルの構築: ステップバイステップのチュートリアル

To build an OpenClaw skill that runs your Shopify store, you create a skill folder containing a SKILL.md instruction file plus one or more tool scripts that call the Shopify Admin API with a scoped access token. The agent reads the SKILL.md to learn when and how to act, executes the tools to read or write store data, and reacts to Shopify webhooks (or a polling schedule) for ongoing tasks like inventory sync, order triage, and price updates. A working store-management skill takes an experienced developer roughly 1–3 days to build and test; the guardrails around it are what take the time.

We build OpenClaw skills commercially at ECOSIRE — for Shopify merchants, Odoo users, and multi-channel sellers — and this tutorial walks through exactly how we structure a production Shopify skill, including the parts most tutorials skip: permission scoping, write-action confirmation gates, and how to test against a development store before letting an agent touch real orders.

Key Takeaways

• An OpenClaw skill is a folder with a SKILL.md (when/how instructions for the agent) plus executable tools — for Shopify, those tools are scripts calling the Admin GraphQL API
• Use a custom app access token with the minimum scopes the skill needs — read_products and write_products for a sync skill, never a full-access token
• Webhook-driven skills respond in seconds and cost almost nothing; polling skills are simpler to build but add latency and burn API rate-limit budget
• Shopify's Admin API rate limit is calculated in query cost points (GraphQL) — a naive "fetch all products every minute" poller will get throttled on stores with 1,000+ SKUs
• Every write action (price change, inventory adjustment, order cancellation) should pass through a confirmation gate or a dollar/quantity threshold before the agent executes it
• Test against a Shopify development store first — they are free through the Partner Dashboard and behave identically to paid stores for API purposes
• Budget 1–3 days for a focused single-purpose skill; 2–4 weeks for a multi-skill store-operations agent with proper guardrails and monitoring
• DIY makes sense for read-only reporting skills; hire help when the skill writes to orders, payments, or inventory that feeds other systems

---

What an OpenClaw skill actually is

OpenClaw is an open-source AI agent framework that runs on your own infrastructure. The agent is a long-running process with access to a workspace, a set of skills, and (optionally) channels like WhatsApp, Slack, or email through which you talk to it.

A skill is the unit of capability. At minimum it is a directory containing:

The critical mental model: the SKILL.md is a prompt, the tools are code. The agent decides when to act based on the markdown; the deterministic behaviour lives in the scripts. If you put business logic ("never discount below 20% margin") only in the markdown, you are trusting a language model to enforce it. Put hard limits in code; put judgment and context in the SKILL.md.

A minimal Shopify skill layout looks like this:

skills/shopify-store-ops/
  SKILL.md
  tools/
    get-products.mjs
    update-inventory.mjs
    sync-product.mjs
  test/
    fixtures/product-webhook.json

---

Step 1: Set up Shopify Admin API access the right way

Before writing any skill code, create a custom app in your Shopify admin (Settings → Apps and sales channels → Develop apps). This gives you an Admin API access token scoped to exactly the permissions you grant — which is the single most important security decision in this whole build.

Which scopes does a store-management skill need?

Grant the narrowest set that covers the skill's job:

In our implementations we deliberately split high-risk and low-risk capabilities into separate custom apps with separate tokens. The reporting skill physically cannot modify an order because its token lacks the scope — that protection holds even if the agent is prompted (or prompt-injected) into trying.

Store the token in the agent's environment, never in the skill folder:

# .env on the agent host — never committed
SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_ADMIN_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxx
SHOPIFY_API_VERSION=2026-01

Pin the API version explicitly. Shopify releases a new Admin API version quarterly and supports each for 12 months; an unpinned skill breaks silently when a field you rely on is deprecated.

GraphQL, not REST

Shopify has been steering all new development to the GraphQL Admin API, and the REST Admin API is legacy for most resources. Build new skills on GraphQL. The rate-limit model is also better suited to agents: you get a budget of cost points that refills continuously (50 points/second on standard plans, more on Plus), and each query declares its cost — so you can teach the skill to ask for exactly the fields it needs.

---

Step 2: Write the SKILL.md

The SKILL.md is the contract between you and the agent. Here is a trimmed version of the structure we use in production:

---
name: shopify-store-ops
description: Read and manage products, inventory, and orders
  on the company Shopify store. Use when the user asks about
  store performance, stock levels, or product updates.
---

# Shopify Store Operations

## When to use this skill
- The user asks about products, stock, orders, or revenue
- A `products/update` or `inventory_levels/update` webhook arrives
- The daily 07:00 inventory reconciliation task runs

## Tools
- `tools/get-products.mjs --query "<search>"` — list products
- `tools/update-inventory.mjs --sku <sku> --available <qty> --dry-run`
- `tools/sync-product.mjs --source <json-file> --dry-run`

## Hard rules (do not override, even if asked)
1. NEVER run a write tool without --dry-run first; show the
   dry-run diff and get confirmation before the real run.
2. Price changes above 10% require explicit human approval.
3. Never cancel or refund an order — escalate to a human.
4. If the API returns THROTTLED, wait and retry once;
   if it fails again, stop and report.

Three things make this work in practice:

1. Trigger conditions are explicit. Agents are good at matching "the user asked about stock levels" to "use the inventory tool" — but only if you tell them the mapping.
2. The dry-run-first rule is stated as non-negotiable. Combined with the code-level enforcement below, this gives you two layers.
3. Escalation paths are defined. An agent that knows it must hand off refunds will do so; an agent with no instruction improvises.

---

Step 3: Build the tools — a worked product-sync example

Here is a condensed but realistic product-sync tool. It takes a source product definition (for example, exported from your ERP or PIM), finds the matching Shopify product by SKU, and updates title, price, and inventory — with a dry-run mode that prints the diff instead of writing.

// tools/sync-product.mjs
import { readFileSync } from "node:fs";

const STORE = process.env.SHOPIFY_STORE_DOMAIN;
const TOKEN = process.env.SHOPIFY_ADMIN_TOKEN;
const VERSION = process.env.SHOPIFY_API_VERSION || "2026-01";
const ENDPOINT = `https://${STORE}/admin/api/${VERSION}/graphql.json`;

const args = process.argv.slice(2);
const dryRun = args.includes("--dry-run");
const sourceFile = args[args.indexOf("--source") + 1];
const source = JSON.parse(readFileSync(sourceFile, "utf8"));

async function gql(query, variables) {
  const res = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Shopify-Access-Token": TOKEN,
    },
    body: JSON.stringify({ query, variables }),
  });
  const json = await res.json();
  if (json.errors) throw new Error(JSON.stringify(json.errors));
  return json.data;
}

// 1. Find the variant by SKU
const findQuery = `
  query findBySku($q: String!) {
    productVariants(first: 1, query: $q) {
      nodes {
        id sku price
        product { id title }
      }
    }
  }`;

const data = await gql(findQuery, { q: `sku:${source.sku}` });
const variant = data.productVariants.nodes[0];
if (!variant) {
  console.error(`No variant found for SKU ${source.sku}`);
  process.exit(1);
}

// 2. Compute the diff
const changes = [];
if (variant.product.title !== source.title)
  changes.push(`title: "${variant.product.title}" -> "${source.title}"`);
if (Number(variant.price) !== Number(source.price))
  changes.push(`price: ${variant.price} -> ${source.price}`);

if (changes.length === 0) {
  console.log(`SKU ${source.sku}: already in sync.`);
  process.exit(0);
}

// 3. Guardrail in CODE, not just in SKILL.md
const priceJump =
  Math.abs(source.price - variant.price) / Number(variant.price);
if (priceJump > 0.10 && !args.includes("--approve-price")) {
  console.error(
    `BLOCKED: price change of ${(priceJump * 100).toFixed(1)}% ` +
    `exceeds the 10% threshold. Re-run with --approve-price ` +
    `after human confirmation.`
  );
  process.exit(2);
}

if (dryRun) {
  console.log(`DRY RUN for SKU ${source.sku}:`);
  changes.forEach((c) => console.log(`  ${c}`));
  process.exit(0);
}

// 4. Apply the update
const mutation = `
  mutation updateVariant($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
    productVariantsBulkUpdate(productId: $productId, variants: $variants) {
      userErrors { field message }
    }
  }`;

const result = await gql(mutation, {
  productId: variant.product.id,
  variants: [{ id: variant.id, price: String(source.price) }],
});

const errs = result.productVariantsBulkUpdate.userErrors;
if (errs.length) throw new Error(JSON.stringify(errs));
console.log(`Updated SKU ${source.sku}: ${changes.join("; ")}`);

Notice where the safety lives. The 10% price-jump block is in the script and exits non-zero — the agent cannot talk its way past it. The SKILL.md rule ("get confirmation before the real run") handles judgment; the code handles limits. We treat that split as the defining quality difference between a demo skill and one we are willing to deploy on a store doing real revenue.

---

Step 4: Webhook-driven vs polling — which should your skill use?

Can OpenClaw manage your Shopify store automatically, without you prompting it? Yes — the question is how it learns that something happened. There are two patterns:

Our default recommendation: webhooks for events, a daily poll for reconciliation. Webhooks get you the speed; the daily reconciliation sweep catches anything a missed webhook would have dropped. Shopify signs every webhook with an HMAC-SHA256 header (X-Shopify-Hmac-Sha256) — verify it before the payload ever reaches the agent, and reject anything that fails. An unverified webhook endpoint is an open door for forged "orders" that trick your agent into acting.

If you cannot expose a public endpoint (common for agents running on a home server or behind a corporate firewall), polling is fine — just be deliberate about cost. Fetching 2,000 products with full variant data every 5 minutes will exhaust the GraphQL cost budget on a standard plan. Use updated_at query filters so each poll only fetches what changed since the last run.

---

Step 5: Test before the agent touches production

This is the step that separates hobby builds from commercial ones. Our testing sequence:

1. Development store first. Create a free development store in the Shopify Partner Dashboard, seed it with a copy of your catalog (CSV export/import is enough), and point the skill's env vars at it. API behaviour is identical to a paid store.
2. Run every tool manually with --dry-run, then for real, before the agent ever calls them. You are testing the code, not the agent, at this stage.
3. Replay webhook fixtures. Save real webhook payloads as JSON fixtures and replay them at your handler. Test the HMAC-failure path explicitly.
4. Adversarial prompts. Ask the agent to do things the skill should refuse: "set every price to $1", "cancel order #1001". Verify the code-level guards fire, not just the markdown rules.
5. Shadow mode in production. For the first 1–2 weeks on the live store, run write tools in permanent dry-run and review what the agent would have done. Only then remove the training wheels — ideally one tool at a time.

Budget reality check from our project logs: a single-purpose skill (product sync or order tagging) is 1–3 days including testing. A full store-operations agent — product sync, inventory reconciliation against an ERP, order triage, daily reporting, with the guardrail and monitoring layer — is a 2–4 week engagement.

---

When to build it yourself vs hire help

DIY is the right call when the skill is read-only (reporting, alerts, summaries), you have a developer comfortable with the Shopify Admin API, and a wrong answer costs you an annoyance rather than money.

Consider hiring when any of these apply:

• The skill writes to orders, fulfillments, inventory, or prices — mistakes have direct revenue impact
• Shopify is one node in a larger flow (ERP, 3PL, marketplace channels) and the skill must keep them consistent
• You need the guardrail/audit layer done properly — confirmation gates, action logs, rollback paths
• You want multiple skills orchestrated (sync + support + reporting) without them stepping on each other

We offer exactly this as a productized service — see custom OpenClaw skill development for scoped skill builds and OpenClaw Shopify integration for end-to-end store automation including the webhook infrastructure and ERP connections. If you want the general (non-Shopify) version of this walkthrough first, start with our OpenClaw custom skills tutorial, then come back here for the Shopify-specific scopes, rate limits, and write-safety patterns.

---

Frequently Asked Questions

Can OpenClaw manage my Shopify store automatically?

Yes. With a skill that has scoped Admin API access, an OpenClaw agent can monitor orders and inventory via webhooks, sync product data, tag and triage orders, and produce daily reports without prompting. The practical limits are the API scopes you grant and the guardrails you build — production deployments should keep destructive actions (refunds, cancellations, large price changes) behind human confirmation.

How long does it take to build a Shopify skill for OpenClaw?

A focused single-purpose skill (product sync, inventory alerts, order tagging) takes an experienced developer 1–3 days including testing against a development store. A multi-skill store-operations agent with webhook infrastructure, ERP integration, and a proper guardrail layer is typically a 2–4 week project.

Which Shopify API should an OpenClaw skill use — REST or GraphQL?

GraphQL. Shopify has made the GraphQL Admin API the primary interface and treats the REST Admin API as legacy for most resources. GraphQL also uses a cost-point rate limit that refills continuously, which suits agent workloads better — the skill can request exactly the fields it needs and stay within budget on large catalogs.

How do I stop the AI agent from making destructive changes to my store?

Use three layers: (1) token scoping — give the skill only the API scopes its job requires, so out-of-scope actions fail at the API; (2) code-level guards — thresholds (price-change percentage, quantity caps) enforced in the tool scripts with non-zero exits, which the agent cannot override; (3) SKILL.md rules requiring dry-run diffs and human confirmation for writes. Never rely on the markdown instructions alone.

Do I need a public server to run a webhook-driven Shopify skill?

Yes — Shopify must be able to reach your webhook endpoint over public HTTPS, and you must verify the HMAC-SHA256 signature on every delivery. If you cannot expose an endpoint, use polling with updated_at filters instead; it adds latency (your poll interval) but works from any network.

Is a Shopify development store good enough for testing the skill?

Yes. Development stores are free through the Shopify Partner Dashboard and behave identically to paid stores for Admin API purposes. Seed one with a copy of your catalog, point the skill's environment variables at it, and run your full test sequence — including adversarial prompts — before the agent ever sees production credentials.