# Shoplazza AI Toolkit 排错

> 排查 Shoplazza AI Toolkit 的常见问题：智能体未认证、缺少 scope、技能没加载或用错业务域，以及 CLI 不认的参数。

AI 智能体通过 Toolkit 操作 Shoplazza 时的常见问题及解决办法。

## 智能体说未认证

技能通过 Shoplazza CLI 操作，CLI 需要自己登录。运行：

```shell
shoplazza auth status
```

若显示无店铺或 token 过期，重新认证：

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders
```

## "缺少 scope"报错

CLI 在每次调用前校验 OAuth scope。若智能体遇到 scope 报错，说明你授予的范围比任务所需窄。带上所需域重新登录——见[认证 → 作用域映射](/zh-CN/docs/app/developer-tools/shoplazza-cli/authentication#作用域映射)：

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders,customers
```

## 技能没加载 / 路由错了域

* 显式带前缀：请求以 `/shoplazza-<域>` 开头，别只依赖触发词匹配。
* 选对拥有该任务的域。注意边界：礼品卡 → `products`；按邮箱查订单 → `orders`；客户资料 → `customers`；买家退款 → `orders`。见 [Agent Skills → 选对业务域](./skills#选对业务域)。
* 按[快速开始 → 添加 Agent Skills](./get-started#2-添加-agent-skills)里对应智能体的确认方式，检查技能是否已加载。没有就用 `npx skills add Shoplazza/shoplazza-cli -g` 重装。

## 智能体用了不存在的 flag

技能文件可能漂移，CLI 自身的 help 才权威。让智能体组装命令前先核对：

```shell
shoplazza schema discounts            # 某域的命令与参数
shoplazza discounts +percent-code --help   # 某快捷命令的 flag
```

## dry-run 预览和你要的对不上

批准前仔细读被复述的命令。参数不对就修正指令、让智能体重新预览。绝不批准你看不懂 `--dry-run` 输出的写操作。

## CLI 本身异常

运行内置诊断：

```shell
shoplazza doctor
```

安装、版本与环境问题见[安装 Shoplazza CLI](/zh-CN/docs/app/developer-tools/shoplazza-cli/install) 与 CLI [错误格式](/zh-CN/docs/app/developer-tools/shoplazza-cli/reference/error-format)。

## 参见

* [安全与权限](./safety-and-permissions)
* [Agent Skills](./skills)