Xpersona
agentCLAWHUBUnverified

亚马逊-广告管理

亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 的查询与创建/修改。Sponsored Brands 同时支持 V3 Legacy 与 V4：新活动、多 Ad Group、Ad/Creative 默认走 V4，历史 Legacy 可显式走 V3，Keyword/Target 按 Campaign 结构通过版本化脚本调用 Amazon 共享 targeting 资源；禁止 V4 失败后自动回落 V3，禁止用 V3 静默截断多 Ad Group 数据。适用于查询、创建、调价、改预算、改状态及管理 SP/SB/SD 广告。本技能依赖 linkfox-amazon-ads-auth；不覆盖 Sponsored Television / DSP。

OpenClaw
View on ClawHubHomepage

Rank

62

Safety

84

Downloads

1.2k

Updated

Oct 10, 2026

Version

1.1.0

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/10/2026.

Avoid when

  • Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor
Clawhubvendor · observed Oct 10, 2026
Protocol compatibility
OpenClawcompatibility · observed Oct 10, 2026
Adoption signal
1.2K downloadsadoption · observed Oct 10, 2026
Latest release
1.1.0release · observed Aug 18, 2026
Handshake status
UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-amazon-ads-manager
  1. Install using `clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-amazon-ads-manager` in an isolated environment before connecting it to live workloads.
  2. No published capability contract is available yet, so validate auth and request/response behavior manually.
  3. Review the upstream CLAWHUB listing at https://clawhub.ai/linkfox-ai/linkfox-amazon-ads-manager before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/snapshot"

Documentation

CLAWHUB

160,000 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: linkfox-amazon-ads-manager
description: 亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 的查询与创建/修改。Sponsored Brands 同时支持 V3 Legacy 与 V4：新活动、多 Ad Group、Ad/Creative 默认走 V4，历史 Legacy 可显式走 V3，Keyword/Target 按 Campaign 结构通过版本化脚本调用 Amazon 共享 targeting 资源；禁止 V4 失败后自动回落 V3，禁止用 V3 静默截断多 Ad Group 数据。适用于查询、创建、调价、改预算、改状态及管理 SP/SB/SD 广告。本技能依赖 linkfox-amazon-ads-auth；不覆盖 Sponsored Television / DSP。
---

# Amazon Ads 广告管理

Amazon Ads 广告管理 skill，支持 list（查询）和 create / update（创建与修改）操作；经 `developerProxy` 传 `profileId`，由服务端解析 token（勿先 `storeTokens` 取 raw token）。自动处理分页、过滤字段规范化。

| 广告产品 | 覆盖实体 | 脚本子目录 | 详细参数 |
|---------|---------|-----------|---------|
| **SP** (Sponsored Products) v3 | campaigns / adGroups / keywords / negativeKeywords / productAds / targets | `scripts/sp/` | [references/api/sp.md](./references/api/sp.md) |
| **SB** V3 Legacy + V4 | V3 campaigns/keywords/targets；V4 campaigns/adGroups/ads/keywords/targets/creatives | `scripts/sb/v3/`、`scripts/sb/v4/` | [references/api/sb.md](./references/api/sb.md) |
| **SD** (Sponsored Display) v3 | campaigns / adGroups / productAds / targets / negativeTargets / creatives | `scripts/sd/` | [references/api/sd.md](./references/api/sd.md) |

**依赖 `linkfox-amazon-ads-auth`**（脚本启动时自动检查；未安装时 exit 42，stderr 打 `DEPENDENCY_MISSING`）。

### ⚠️ 多账号场景：调用前必须解析好 profileId

用户经常只说自然语言（"美国站"、"日本站"、"我的店铺"），本 skill 的所有脚本都必须拿到数字 `profileId` 才能调。按下列顺序处理，**不要跳过**：

1. 先调 `linkfox-amazon-ads-auth` 的 `authorized_stores.py` 拉出用户已授权的账号 × 站点清单。
2. 根据用户提到的站点（映射到 `countryCode`，如 美国→`US`）匹配候选 profile：
   - **只有 1 个候选** → 静默取对应 profileId，继续调用；不要把 profileId 数字播报给用户。
   - **≥ 2 个候选（同站点下多个授权账号）** → **必须向用户澄清**，用 `accountName` 问："你在美国站授权了 A 和 B 两个账号，这次用哪个？"
   - **0 个候选** → 告知用户该站点未授权，引导去 `linkfox-amazon-ads-auth` 做授权。
3. **严禁**让用户直接报 profileId 数字。
4. **严禁**在歧义下"挑第一个"或"选默认"绕过澄清。

完整决策表见 `linkfox-amazon-ads-auth` SKILL.md 的 **Usage Scenarios 第 4 节**。

## Core Concepts

- **自动分页**：`fetchAll=true`（默认）跟随分页到结束或 `maxPages=50` 兜底；SP/SB V4/Target 用 `nextToken`，SB V3 GET 与 SD 用 `startIndex + count`
- **过滤器结构不统一**：不同字段需要不同写法（详见下方"过滤器结构速查"）；本 skill 已对常见写错格式做自动兜底规范化，但仍建议按速查表准确传入
- **只给 metadata，不含指标**：返回实体字段（id / 名称 / 状态 / 匹配类型 等），曝光 / 点击 / 花费 / 转化 等指标要调 `linkfox-amazon-ads-report`，按 id join
- **支持 create / update**：各模块下 `create_*.py` / `update_*.py` 脚本创建或修改实体（campaign / adGroup / keyword / target / productAd / creative / budgetRule），payload 透传 Amazon 原生格式
- **SB V3/V4 共存**：默认使用 `scripts/sb/v4/`；只有确认是 Legacy 或用户明确要求 V3 时使用 `scripts/sb/v3/`。不自动执行 V4→V3 回落；已知 Multi-Ad-Group Campaign 必须拒绝 V3
- **SB 共享 Targeting**：Amazon 的 Keyword/Target 仍使用 `sb/keywords`、`sb/targets[/list]`，没有伪造的 `/sb/v4/keywords`；V3/V4 脚本入口隔离，但底层共享官方 targeting 资源
- **SD 接口形态**：Sponsored Display 是 v3 REST endpoint，`GET /sd/<entity>` + querystring，分页用 `startIndex + count`；state / id 类过滤为逗号分隔字符串；`includeExtendedDataFields:true` 时请求 `/sd/<entity>/extended` 路径。所有过滤字段统一支持 `{"include":[...]}` 入参

## 可用脚本

### SP（28 个）
| 脚本 | 业务实体 | 操作 |
|------|---------|------|
| `sp/list_campaigns.py` | 广告活动 | 查询 |
| `sp/cr

_meta.json

{
  "ownerId": "kn7dmc1t4j28hem1twwyav85p182pb1j",
  "slug": "linkfox-amazon-ads-manager",
  "version": "1.1.0",
  "publishedAt": 1787053007211
}

references/api.md

# linkfox-amazon-ads-manager — 参数与字段参考（总览）

按 Amazon Ads 广告产品分类维护。

| 广告产品 | 脚本子目录 | 查询参考 |
|---------|-----------|---------|
| **Sponsored Products (SP)** — v3 | `scripts/sp/` | [api/sp.md](./api/sp.md) |
| **Sponsored Brands (SB)** — V3 Legacy + V4 | `scripts/sb/v3/`、`scripts/sb/v4/` | [api/sb.md](./api/sb.md) |
| **Sponsored Display (SD)** — v3 | `scripts/sd/` | [api/sd.md](./api/sd.md) |

> Sponsored Television (ST) / Amazon DSP 暂未覆盖。

## 通用约定

- 每个脚本接受一个 JSON 字符串作为唯一位置参数
- 鉴权：环境变量 `LINKFOX_AGENT_API_KEY`（或旧名 `LINKFOXAGENT_API_KEY`）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）
- API 网关地址：环境变量 `LINKFOX_TOOL_GATEWAY`（默认 `https://tool-gateway.linkfox.com`）
- 依赖 `linkfox-amazon-ads-auth`（脚本启动自动检查；缺失时 exit 42，stderr 打 `DEPENDENCY_MISSING`）

## 共用参数（SP + SB + SD 均适用）

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `profileId` | number | ✅ | — | 从 ads-auth 获取 |
| `region` | string | ✅ | — | `NA` / `EU` / `FE` |
| `fetchAll` | boolean | 否 | `true` | 自动翻页；SP/SB V4/Target 用 `nextToken`，SB V3 GET 与 SD 用 `startIndex + count` |
| `maxResults` | integer | 否 | `100` | 单页 1-100；超限上游可能静默 clamp；对应 SD 端 `count` |
| `skipDepCheck` | boolean | 否 | `false` | 跳过依赖检查 |
| `includeExtendedDataFields` | boolean | 否 | — | 返回扩展字段（部分实体）；SD 通过路径切换为 `/sd/<entity>/extended` 实现 |
| `locale` | string | 否 | — | 本地化（keywords 支持） |

## 输出格式

```json
{
  "success": true,
  "apiVersion": "V3 | V4",
  "amazonResourceVersion": "V4 | V3_SHARED_TARGETING | V3.2_SHARED_TARGETING | SHARED",
  "<entityKey>": [ /* 实体数组 */ ],
  "total": 157,
  "pagesFetched": 2,
  "truncated": false
}
```

客户端过滤时（SP productAds 的 asinFilter/skuFilter）额外带 `serverTotalBeforeClientFilter` + `clientSideFilters`。

SB 输出中的两个版本字段含义不同：`apiVersion` 表示调用入口和 Campaign 结构意图；`amazonResourceVersion` 表示实际 Amazon 资源传输版本。V4 Keyword/Target 入口使用 Amazon 共享 V3/V3.2 targeting 路径，不代表自动回落。

失败：
```json
{
  "error": "Upstream HTTP 401",
  "httpStatus": 401,
  "body": "...",
  "pagesFetched": 0
}
```

## 通用错误码

| httpStatus / exit | 含义 | 建议 |
|-------------------|------|------|
| 200 | 成功 | — |
| 400 | 入参结构错 | 核对对应 adProduct 的过滤器结构（api/sp.md / api/sb.md / api/sd.md） |
| 401 | accessToken 过期 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |
| 402 | 积分或余额不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |
| 403 | profileId 无权限 | 核对 profileId 归属 |
| 429 | 限流 | 间隔 2-5s 重试 |
| exit 42 | 依赖 skill 未安装 | 先装 `linkfox-amazon-ads-auth` |

---

## Feedback API

与上面的工具 API **base URL 不同**：

```bash
curl -X POST https://skill-api.linkfox.com/api/v1/public/feedback \
  -H "Content-Type: application/json" \
  -d '{"skillName":"linkfox-amazon-ads-manager","sentiment":"POSITIVE",
       "category":"OTHER","content":"实体查询结果与预期一致"}'
```

- `sentiment`: `POSITIVE` / `NEUTRAL` / `NEGATIVE`
- `category`: `BUG` / `COMPLAINT` / `SUGGESTION` / `OTHER`

references/api/sb-coexistence.md

# Sponsored Brands V3 / V4 共存与路由

## 版本边界

| 调用入口 | 适用结构 | 用途 |
|---|---|---|
| `scripts/sb/v4/` | `LEGACY` 或 `MULTI_AD_GROUP` | 默认入口；新建活动、多广告组、Ad/Creative 管理 |
| `scripts/sb/v3/` | 仅 `LEGACY` | 历史活动兼容 |
| `scripts/sb/*.py` | 同 V4 | 旧路径兼容；新调用应迁到 `scripts/sb/v4/` |

新业务默认使用 V4。只有用户明确要求 V3，或已确认 Campaign 为 Legacy 时，才使用 V3。

## 不自动回落

脚本不执行 `V4 失败 → V3 重试`。Amazon 返回非 2xx 时，保留状态码和响应体交给调用方判断。原因：

1. API 版本不等于 Campaign 结构；
2. Multi-Ad-Group Campaign 无法无损转换成 V3；
3. 自动回落会掩盖权限、参数或资源状态错误；
4. V3 读取 V4 活动可能造成多 Ad Group 数据截断。

当顶层参数或 `payload` 内出现 `campaignStructure=MULTI_AD_GROUP` / `isMultiAdGroupsEnabled=true`（含 `"true"`/`1` 等写法）时，V3 脚本会在发请求前返回：

```json
{
  "code": "SB_V4_CAMPAIGN_NOT_SUPPORTED",
  "message": "This campaign uses the Sponsored Brands V4 multi-ad-group structure. Use scripts/sb/v4 instead of V3."
}
```

脚本没有本地 Campaign 数据库；如果调用方未提供结构信息，无法仅凭 `campaignId` 可靠判断结构。因此 Agent 应先用 V4 `list_campaigns.py` 查询 `isMultiAdGroupsEnabled`，再决定是否允许使用 V3。

## Amazon 路径与脚本版本不是一回事

Amazon 的 Campaign / Ad Group / Ad 主资源有明确 V4 路径：

```text
sb/v4/campaigns/**
sb/v4/adGroups/**
sb/v4/ads/**
```

但 Keyword 与 Product Target 仍使用共享资源路径：

```text
sb/keywords
sb/targets
sb/targets/list
```

这些共享路径可以通过 `campaignId + adGroupId` 管理多广告组活动。为让调用意图明确，本 skill 在 `sb/v3/` 和 `sb/v4/` 都提供 keyword/target 入口；两者底层调用同一 Amazon 资源：

- `sb/v3/*`：声明调用方已确认是 Legacy；
- `sb/v4/*`：声明按 V4 Campaign/Ad Group 结构管理；
- 输出中的 `amazonResourceVersion` 会标记为 `V3_SHARED_TARGETING` 或 `V3.2_SHARED_TARGETING`。

这不是 V4 自动降级，也不会在失败后切换版本。

## Creative 边界

- V3 Legacy Campaign 的 Creative 是 Campaign payload 的组成部分，没有独立的 V3 Creative CRUD 脚本。
- V4 使用 Ad 与独立 Creative Version：
  - `sb/v4/list_ads.py`
  - `sb/v4/create_ads.py`
  - `sb/v4/list_creatives.py`
  - `sb/v4/create_creatives.py`

不要伪造不存在的 `sb/v3/creatives` 或 `sb/v4/keywords` Amazon 路径。

## 决策流程

```text
新建 / 多 Ad Group / Ad / Creative
  → scripts/sb/v4/

关键词或 Target
  → 默认 scripts/sb/v4/
  → 仅在已确认 Legacy 或用户明确要求 V3 时使用 scripts/sb/v3/

V3 + MULTI_AD_GROUP
  → 拒绝并提示使用 V4

任一版本调用失败
  → 返回原错误；不自动重试另一版本
```

references/api/sb-v3.md

# Sponsored Brands V3 Legacy API

V3 仅用于历史 Legacy Campaign。共存与路由规则见 [sb-coexistence.md](./sb-coexistence.md)。

## 脚本

| 脚本 | Amazon 路径 | 方法 | 说明 |
|---|---|---|---|
| `sb/v3/list_campaigns.py` | `sb/campaigns` | GET | offset 分页查询 Legacy 活动 |
| `sb/v3/create_campaigns.py` | `sb/campaigns` | POST | 创建 Legacy 活动；新业务不推荐 |
| `sb/v3/update_campaigns.py` | `sb/campaigns` | PUT | 更新 Legacy 活动 |
| `sb/v3/list_ad_groups.py` | `sb/adGroups` | GET | 查询 Legacy 活动关联的 Ad Group |
| `sb/v3/list_keywords.py` | `sb/keywords` | GET | 查询关键词 |
| `sb/v3/create_keywords.py` | `sb/keywords` | POST | 创建关键词，最多 100 个 |
| `sb/v3/update_keywords.py` | `sb/keywords` | PUT | 更新关键词，最多 100 个 |
| `sb/v3/list_targets.py` | `sb/targets/list` | POST | nextToken 分页查询商品定向 |
| `sb/v3/create_targets.py` | `sb/targets` | POST | 创建商品定向，最多 100 个 |
| `sb/v3/update_targets.py` | `sb/targets` | PUT | 更新商品定向 |

V3 Creative 没有独立 CRUD；品牌名、标题、ASIN、素材等位于 Campaign 的 `creative` 字段中，通过 Campaign create/update 管理。

## Legacy 安全参数

V3 脚本额外接受：

| 参数 | 作用 |
|---|---|
| `campaignStructure` | 传 `MULTI_AD_GROUP` 时拒绝调用 |
| `isMultiAdGroupsEnabled` | 传 `true` 时拒绝调用 |

这些字段只用于本地保护，不会发送给 Amazon。

## GET list 参数

Campaign：

- `campaignIdFilter`
- `stateFilter`
- `nameFilter`
- `portfolioIdFilter`
- `creativeType`

Ad Group：

- `adGroupIdFilter`
- `campaignIdFilter`
- `stateFilter`
- `nameFilter`
- `creativeType`

Keyword：

- `keywordIdFilter`
- `adGroupIdFilter`
- `campaignIdFilter`
- `stateFilter`
- `matchTypeFilter`
- `keywordText`
- `creativeType`
- `locale`

ID、状态、匹配类型可传字符串、数组或 `{"include":[...]}`，脚本转换成 Amazon 所需的逗号分隔 query。分页参数为 `maxResults`、`fetchAll`、`maxPages`。

## Target list 参数

Target list 接受 Amazon 原生 `filters`，也接受顶层 Object/Array 过滤（脚本会映射为 Amazon `filters[]`）：

```json
{
  "profileId": 1234567890,
  "region": "NA",
  "campaignIdFilter": {"include": ["1122334455"]},
  "stateFilter": ["enabled", "paused"],
  "maxResults": 100
}
```

等价原生写法：

```json
{
  "profileId": 1234567890,
  "region": "NA",
  "payload": {
    "maxResults": 100,
    "filters": [
      {"filterType": "CAMPAIGN_ID", "values": ["1122334455"]},
      {"filterType": "TARGETING_STATE", "values": ["enabled", "paused"]}
    ]
  }
}
```

可映射字段：`campaignIdFilter`→`CAMPAIGN_ID`，`adGroupIdFilter`→`AD_GROUP_ID`，`stateFilter`→`TARGETING_STATE`，`targetIdFilter`→`TARGET_ID`，`creativeTypeFilter`→`CREATIVE_TYPE`。

## 示例

```bash
python scripts/sb/v3/list_campaigns.py '{"profileId":1234567890,"region":"NA","stateFilter":["enabled","paused"]}'

python scripts/sb/v3/list_keywords.py '{"profileId":1234567890,"region":"NA","campaignIdFilter":["1122334455"]}'

python scripts/sb/v3/update_keywords.py '{"profileId":1234567890,"region":"NA","campaignStructure":"LEGACY","payload":[{"keywordId":1,"campaignId":2,"adGroupId":3,"bid":1.2}]}'
```

写操作不会自动切换到 V4；非 2xx 原样返回。

Related agents

Same protocol, similar job.

Github ReposUpdated 1d agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW
Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW
Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.

MCPOPENCLAW
Github ReposUpdated 7mo agoRank 70

CopilotKit

The Frontend for Agents & Generative UI. React + Angular

OPENCLAW

Machine-readable data

The same record, as JSON, for agents and crawlers.

{
  "facts": [
    {
      "factKey": "vendor",
      "category": "vendor",
      "label": "Vendor",
      "value": "Clawhub",
      "href": "https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-ads-manager",
      "sourceUrl": "https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-ads-manager",
      "sourceType": "profile",
      "confidence": "medium",
      "observedAt": "2026-10-10T22:14:04.387Z",
      "isPublic": true
    },
    {
      "factKey": "protocols",
      "category": "compatibility",
      "label": "Protocol compatibility",
      "value": "OpenClaw",
      "href": "https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/contract",
      "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/contract",
      "sourceType": "contract",
      "confidence": "medium",
      "observedAt": "2026-10-10T22:14:04.387Z",
      "isPublic": true
    },
    {
      "factKey": "traction",
      "category": "adoption",
      "label": "Adoption signal",
      "value": "1.2K downloads",
      "href": "https://clawhub.ai/linkfox-ai/linkfox-amazon-ads-manager",
      "sourceUrl": "https://clawhub.ai/linkfox-ai/linkfox-amazon-ads-manager",
      "sourceType": "profile",
      "confidence": "medium",
      "observedAt": "2026-10-10T22:14:04.387Z",
      "isPublic": true
    },
    {
      "factKey": "latest_release",
      "category": "release",
      "label": "Latest release",
      "value": "1.1.0",
      "href": "https://clawhub.ai/linkfox-ai/linkfox-amazon-ads-manager",
      "sourceUrl": "https://clawhub.ai/linkfox-ai/linkfox-amazon-ads-manager",
      "sourceType": "release",
      "confidence": "medium",
      "observedAt": "2026-08-18T11:36:47.211Z",
      "isPublic": true
    },
    {
      "factKey": "handshake_status",
      "category": "security",
      "label": "Handshake status",
      "value": "UNKNOWN",
      "href": "https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/trust",
      "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/trust",
      "sourceType": "trust",
      "confidence": "medium",
      "observedAt": null,
      "isPublic": true
    }
  ],
  "events": [
    {
      "eventType": "release",
      "title": "Release 1.1.0",
      "description": "Update from 1.0.5 to 1.1.0",
      "href": "https://clawhub.ai/linkfox-ai/linkfox-amazon-ads-manager",
      "sourceUrl": "https://clawhub.ai/linkfox-ai/linkfox-amazon-ads-manager",
      "sourceType": "release",
      "confidence": "medium",
      "observedAt": "2026-08-18T11:36:47.211Z",
      "isPublic": true
    }
  ]
}

Record generated Oct 10, 2026.

Sponsored

Ads related to 亚马逊-广告管理 and adjacent AI workflows.