Adwarp

Adwarp

网站 · 文档 · 安装指南 · npm 包

Adwarp（前身为 Liam）是面向 LinkedIn Ads 和 Google Ads 的开源广告 Agent。 通过与 Claude 对话（MCP）或使用命令行来创建广告系列。专为希望根据联系人列表和简报快速创建多个广告系列、然后自行添加创意图片的市场拓展团队打造。 所有内容默认均处于关闭状态：LinkedIn 实体会创建为草稿，Google 实体则会创建为已暂停。只有明确要求 Adwarp 启用 LinkedIn 广告系列，或在 Campaign Manager 中自行启用，广告系列才会投放；Google 广告系列只能在 Google Ads 界面中启用。

非官方产品，与 LinkedIn 或 Google 无关联，也未获其认可。

涵盖创建、匹配受众（包括直接从 Salesforce 或 HubSpot 构建受众）、转化选择、效果报告/洞察、竞争对手广告情报，以及包含变更前后提升情况的变更日志。请参阅 ROADMAP.md，了解已发布内容和接下来的计划。

可以用它做什么

连接 Adwarp 后，你就可以用日常语言与助手交流。它目前可以处理的实际请求如下，大致按照广告系列的创建顺序排列：

• “我们能触达多少家美国 SaaS 公司的需求开发副总裁？”（解析定向维度，在涉及任何费用前估算触达人数）
• “将这个 CSV 上传为匹配受众。”（自动清理列、对电子邮件进行哈希处理，并保留姓名、公司和职位以供 LinkedIn 匹配人员，还会将公司域名转换为 URL）
• “从 Salesforce 构建受众：纳入所有所属账户被标记为目标的联系人。” （直接通过 SOQL 构建匹配受众）
• “将我们的 HubSpot 目标账户列表转换为 LinkedIn 受众。”（将 HubSpot 列表或搜索结果直接转换为联系人或公司的匹配受众）
• “为该受众启动一个草稿广告系列，预算为每天 100 美元，并跟踪已预约演示转化。”（一次调用即可创建广告系列组、广告系列和草稿广告）
• “我们最大的竞争对手现在投放了哪些广告？他们在主推什么优惠？”（读取公开的 Ad Library：查看任何公司的文案、格式和欧盟定向元数据）
• “再营销上个月的表现与前一个月相比如何？”（提供带有变化幅度的趋势报告）
• “这周应该暂停哪些广告？”（汇总账户数据，列出表现最佳/最差的广告并标记异常；随后暂停你选定的广告，其余广告组中的广告继续投放）
• “重写表现不佳广告的文案。”（删除并重新创建为全新草稿；LinkedIn 不会将对正在投放广告帖子的编辑应用到广告上）
• “新标题真的有帮助吗？”（查看变更日志和变更前后的提升情况）

Adwarp 会解析具体细节并返回 ID。每项功能也都对应一个 adwarp CLI 命令，可用于脚本或批量操作。

让它定期运行

Adwarp 不提供调度器。请使用你所用客户端中的调度器。 以下是一些实用的定时任务：

• “每周一上午 9 点，提取上周的效果摘要，与再前一周进行比较，并标记变化超过 20% 的项目。”（Claude Code 定时 Agent）
• “每周五，检查本周前三大竞争对手发布了哪些新广告，并总结其宣传角度。”
• “每隔几小时检查一次受众匹配状态，并在成员数达到 300 时通知我。”（匹配受众投放所需的最低人数）
• 或者完全跳过助手，直接将 CLI 加入 cron： 0 9 * * 1 adwarp report summary -p last_7_days

层级映射（两个平台的命名不一致）

LinkedIn 的名称比其他平台错开一级，这是在两者之间切换时最常见的混淆来源：

通用术语	LinkedIn 实体	Google Ads 实体	包含内容
Campaign	Campaign Group	（无）	状态、总预算/共享预算
Ad group	Campaign	Campaign	定向、预算、出价、排期、格式
（无）	（无）	Ad group	关键词及针对这些关键词的广告
Ad	Creative	Ad group ad	渲染后的广告
Audience	DMP Segment	User list	附加到定向

因此，LinkedIn 的“campaign”和 Google 的“campaign”并非同一概念：Google 的 campaign 包含预算和定向（对应 LinkedIn 的 campaign group 加上 campaign），而其 ad group 则包含关键词。

Google Ads

仅限搜索广告系列，以创建为先。目前支持的内容：

adwarp google auth login
adwarp google accounts list                       # proves the token and OAuth client work
adwarp google keywords "revops automation" --url https://example.com/product
adwarp google conversions list
adwarp google launch --brief examples/google-brief.json           # dry run
adwarp google launch --brief examples/google-brief.json --apply   # create it, paused
adwarp google campaigns list
adwarp google report perf keyword -p last_30_days

启动时会通过一次原子 mutate 创建预算、广告系列、地理位置和语言定向、广告组、 关键词以及响应式搜索广告：要么全部成功，要么全部失败，因此不会因故障而留下半成品广告系列。每次写入都会先在服务器端验证，这是真正的试运行，而非本地猜测。

三条固定规则已硬编码，因为这三项在 UI 中的默认设置都不合适，会悄悄浪费 B2B 预算：

• 仅限搜索网络。 关闭展示广告扩展和搜索合作伙伴。
• 仅限实际到场。“US”表示人在美国，而不是身处任何地方但搜索过相关内容的人。
• 起步使用手动 CPC。 没有转化记录时，智能出价的花费难以预测。积累数据后再在 UI 中切换。

设置

Google Ads 需要两项 LinkedIn 不需要的内容：

1. 开发者令牌，来自 Google Ads 管理器（MCC） 账号，网址为 ads.google.com/aw/apicenter。普通 客户账号无法签发令牌。通常会自动获批 Explorer 访问权限 （每天 2,880 次生产操作）。

   Explorer 不足以使用 adwarp google keywords。 Explorer 会屏蔽 KeywordPlanService，因此关键词研究需要 Basic 访问权限（每天 15,000 次 操作），需在同一页面单独申请。在 Explorer 权限下，广告系列创建和报告功能均可正常使用。

2. OAuth 客户端，来自已启用 Google Ads API 的 Google Cloud 项目。 使用“桌面应用”类型，它接受任意 localhost 重定向。

   对于同意屏幕，不要将其留在“测试”状态。该状态签发的刷新令牌会在 7 天后失效。除此之外，需要权衡以下选项：

   • 内部（仅限 Workspace 组织）是 Google OAuth 文档对单公司工具的推荐方案。最简单，无需验证，也没有 7 天有效期限制。
   • 外部 + 正式发布是申请品牌验证的前提，这项试点可将 Basic Access 审核时间从几天缩短到几小时。代价是 auth/adwords 属于敏感范围，因此已发布的外部应用可能需要完整的 OAuth 应用验证，等待时间可能比节省的时间还长。

   对于内部工具，内部选项是更好的默认选择。只有在快速通道的收益值得承担验证风险时，才选择外部选项。

然后写入 ~/.adwarp/google.json：

{
  "clientId": "....apps.googleusercontent.com",
  "clientSecret": "...",
  "developerToken": "...",
  "loginCustomerId": "1234567890",
  "defaultCustomerId": "0987654321",
  "defaultConversionActionNames": ["Demo Booked"]
}

loginCustomerId 是管理器账号，只有在通过该账号访问目标账号时才需要。运行 adwarp google auth login 即可完成设置。文档中的设置 Google Ads包含相同步骤， 以及 ADWARP_GOOGLE_* 环境变量。

软件包

• @adwarp/shared：平台中立层，包含 OAuth、凭据存储、重试策略、变更日志、周期与 KPI 计算。
• @adwarp/core：LinkedIn REST 客户端、资源模块、CSV + SHA256 哈希、Salesforce 和 HubSpot 读取器。
• @adwarp/google：Google Ads REST 客户端、GAQL 读取、原子 mutate 构建器、Search 广告系列创建。
• @adwarp/mcp：MCP 服务（本地使用 stdio；托管应用也会复用）。主要接口。
• @adwarp/cli：基于相同引擎的 adwarp CLI，用于脚本化批量运行。
• @adwarp/web：通过 Vercel 在 https://mcp.adwarp.dev/api/mcp 上通过 HTTP 托管 MCP 的 Next.js 应用。它不提供页面：其他路径会重定向到 adwarp.dev。
• adwarp：已发布的 npm 软件包。在 adwarp、adwarp-mcp 和 liam 命令后封装 CLI 和 MCP 服务。

工作原理

两个接口都是基于相同引擎的轻量封装。每个 MCP 工具和 CLI 命令都会通过 createLinkedInAds()（core/src/client.ts）构建客户端，该方法会加载配置和自动刷新的 OAuth 令牌提供程序，然后调用类型化资源模块（campaigns.ts、audience.ts、report.ts 等），以封装 LinkedIn 的版本化 REST API（LinkedIn-Version 在配置中固定）。输入结构以 zod schema 的形式定义在 core/src/schemas.ts 中，并原样复用为 MCP 工具输入 schema，因此 CLI 和 MCP 的行为始终一致。

创建时会强制执行草稿优先的安全规则：广告系列组、广告系列和创意默认状态均为 DRAFT，上线始终需要显式请求（将 status 设为 ACTIVE、执行 campaigns update --status ACTIVE --apply，或执行 ad resume --apply）。在 Google 上，创建 schema 根本无法表示启用状态。每次写入也都会经过同一个 HTTP 关口，并追加到本地变更日志（~/.adwarp/changelog.jsonl），以便后续进行提升效果分析。

AGENTS.md 包含完整的架构说明，以及通过实时测试总结出的 LinkedIn API 注意事项（restli 编码、必填字段、DMP 受众流程）。

安装

adwarp.dev 上的安装指南也包含以下步骤，并为每个客户端提供了设置页面：Claude Code、Claude Desktop、Cursor、Codex、Gemini、CLI，以及通过你自己的端点使用的 Meta Muse 和 Grok Bot。

安装 Adwarp 有两种方式：

1. 作为 MCP 服务安装，注册到 Claude Code、Claude Desktop、Cursor、Codex 或其他能够运行本地服务的 MCP 客户端， 这样你就可以通过与助手对话来创建广告系列。可在本地运行，也可以完全跳过常驻安装， 使用自己的凭据连接到托管端点。
2. 作为终端 CLI 安装，安装全局 adwarp 命令， 通过终端、脚本或 cron 运行所有操作。

两种方式都使用你自己的 LinkedIn 开发者应用，因此凭据和广告账户都由你掌控。两者都来自同一个 npm 软件包 adwarp。前两个步骤相同：创建 LinkedIn 应用（步骤 0）并进行身份验证（步骤 1）。之后选择一种方式，也可以两种都用；它们读取相同的 ~/.adwarp 凭据。

步骤 0：创建 LinkedIn 应用（仅需一次）

1. 在 https://www.linkedin.com/developers/apps 创建应用。该应用必须关联到贵公司的 LinkedIn 专页。

2. 在 Products 选项卡中申请访问权限：

   产品	用途	是否必需？
   Advertising API	广告系列、广告、定向、报告、转化	是
   Audiences	将 CSV 联系人／公司名单上传为匹配受众	仅在上传受众时需要
   LinkedIn Ad Library	通过官方 API 获取竞争对手广告元数据	发现竞争对手时需要；不支持浏览器备用方案

3. 在 Auth 选项卡中，将 http://localhost:53682/callback 添加为授权重定向 URL，并记下你的 Client ID 和 Client Secret。

4. Advertising API 获批后，在 Products → Advertising API → View Ad Accounts 下映射你的广告账户。跳过此步骤会导致 accounts list 返回空结果。

OAuth 范围。 adwarp auth login 会请求 rw_ads（创建和编辑广告系列）、r_ads_reporting（报告）、rw_conversions（转化跟踪）和 w_organization_social（图片广告会创建一条归属于你的 LinkedIn 专页的帖子）。如果之后添加产品或范围，请重新运行 auth login；令牌刷新只会保留你最初授权的范围。

步骤 1：进行身份验证（仅需一次，两种方式均适用）

需要 Node.js 20+。

# App credentials (alternatively set ADWARP_LINKEDIN_CLIENT_ID / ADWARP_LINKEDIN_CLIENT_SECRET env vars)
mkdir -p ~/.adwarp
echo '{ "clientId": "...", "clientSecret": "...", "linkedinVersion": "202605" }' > ~/.adwarp/config.json

npx -y adwarp auth login      # opens the browser; tokens land in ~/.adwarp
npx -y adwarp accounts list   # verify, then set defaultAccountId in config.json

选项 1：安装为 MCP 服务

在 MCP 客户端中注册该服务；它会读取步骤 1 中的 ~/.adwarp 凭据。

Claude Code

claude mcp add adwarp -- npx -y adwarp mcp

Claude Desktop、Cursor 或其他可运行本地服务的 MCP 客户端，请在客户端的 MCP 配置 JSON 中添加：

{
  "mcpServers": {
    "adwarp": { "command": "npx", "args": ["-y", "adwarp", "mcp"] }
  }
}

adwarp mcp 和 adwarp-mcp 命令会启动同一个服务。更喜欢使用 Docker？根目录中的 Dockerfile 会构建该服务的镜像；请参阅在 Docker 中运行。

可以通过询问只读内容来确认它能正常工作：“列出我的广告账户”或“我的账户在过去 30 天的表现如何？”

托管 MCP：使用你自己的凭据连接，无需部署

托管 MCP 服务位于

https://mcp.adwarp.dev/api/mcp

它采用多租户、自带凭据模式：你在请求标头中传入 LinkedIn 开发者应用的 详细信息，每次调用都会使用你的应用和你的广告账户执行。 服务不会为你保存任何状态：凭据只会在内存中用于调用 LinkedIn， 绝不会记录或持久化。原地址 https://liam-mcp.vercel.app/api/mcp 仍然有效，并提供相同的端点，因此现有连接无需更改。托管端点文档提供了完整参考。

标头	值	是否必需？
X-Adwarp-Linkedin-Client-Id	你的 LinkedIn 应用的 Client ID	是
X-Adwarp-Linkedin-Client-Secret	你的 LinkedIn 应用的 Client Secret	是
X-Adwarp-Linkedin-Refresh-Token	通过 auth login 获取的刷新令牌（约 365 天有效）	是
X-Adwarp-Linkedin-Account-Id	调用未指定账户时使用的数字广告账户 ID	否
X-Adwarp-Linkedin-Version	API 版本固定值（YYYYMM），默认为服务端版本	否

只需完成上面的步骤 0 和步骤 1 一次（创建 LinkedIn 应用并在本地执行 auth login；LinkedIn OAuth 授权需要在浏览器中完成，因此生成令牌是唯一的本地步骤）。 然后打印可直接运行的连接命令：

npx -y adwarp auth export --mcp
# claude mcp add --transport http adwarp https://mcp.adwarp.dev/api/mcp \
#   --header "X-Adwarp-Linkedin-Client-Id: …" \
#   --header "X-Adwarp-Linkedin-Client-Secret: …" \
#   --header "X-Adwarp-Linkedin-Refresh-Token: …" \
#   --header "X-Adwarp-Linkedin-Account-Id: …"

其他能够发送自定义标头的 MCP 客户端也可以用相同方式连接（对于不支持原生 HTTP 传输的客户端：npx mcp-remote <url> --header "X-Adwarp-Linkedin-Client-Id: …" …）。 使用只读调用（“列出我的广告账户”）进行验证；此后，连接只需一个 URL 和标头，即使是在从未克隆此代码仓库的机器上也能使用。

请了解其中的权衡：每次请求都会将你的客户端密钥和刷新令牌发送到该服务，因此只应将它们提供给你信任的部署，或者自行托管相同的端点（见下一节）。管理广告所需的相同权限范围也可以开启广告，因此请像保护广告账户密码一样保护这些凭据。

托管版的限制（均为有意设计，因为这些功能需要本地资源）：upload_audience_csv 会读取服务端上的 CSV 路径；audience_from_salesforce 需要你本地的 sf CLI； audience_from_hubspot 未在此处注册（其 HubSpot 令牌会留在你的机器上）； 竞争对手广告抓取会退化为仅使用 API 元数据（没有浏览器）；变更日志／提升工具需要本地的 ~/.adwarp/changelog.jsonl。请通过本地 MCP 服务或 CLI 运行这些功能。

在上层添加技能。 对团队而言，清晰的分工方式是：MCP 客户端配置保存凭据（上述标头），小型技能或系统提示词则保存操作手册：默认广告账户、命名规范、固定排除项，以及诸如“始终关闭受众扩展”之类的内部规则。付费广告技能提供了可用示例；复制一个，替换为你的默认设置，然后让助手按照你的规则驱动托管工具。凭据绝不能放在技能文件中。

在 Vercel 上自托管同一端点

运行自己的实例，让凭据不会接触共享基础设施，同时还能获得一个通过环境变量配置的私有租户：

1. 在本地获取环境变量值：npx -y adwarp auth export。
2. 将 apps/web 部署到 Vercel（将项目的 Root Directory 设置为 apps/web）。
3. 在 Vercel 项目设置中，添加 auth export 输出的环境变量 （ADWARP_LINKEDIN_CLIENT_ID、ADWARP_LINKEDIN_CLIENT_SECRET、ADWARP_LINKEDIN_REFRESH_TOKEN、ADWARP_LINKEDIN_VERSION， 以及一个强密码 MCP_AUTH_TOKEN）。在 Vercel 的 Deployment Protection 设置中，为生产环境 禁用 Vercel Authentication（或添加一个保护绕过密钥）；否则 MCP 客户端无法访问该端点。
4. 你的 MCP 端点是 https://<your-app>.vercel.app/api/mcp。在请求头中携带密钥进行连接：

claude mcp add --transport http adwarp https://<your-app>.vercel.app/api/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

携带 MCP_AUTH_TOKEN 的请求会使用环境变量中的凭据（你的租户）。携带上述 X-Adwarp-Linkedin-* 请求头的请求则会使用调用方的凭据，因此，一个 自托管实例就能服务整个团队，每位成员都使用自己的 LinkedIn 应用。该应用仅提供此端点。其他路径（例如 / 和 /docs）会重定向到 adwarp.dev。

选项 2：安装终端 CLI

全局安装此软件包以使用 adwarp 命令，或者使用 npx -y adwarp <command> 运行任意单个命令：

npm install -g adwarp
adwarp accounts list

从 Liam 迁移而来？liam 仍可作为 adwarp 的别名使用：该软件包会同时安装这两个名称，因此现有脚本和 cron 作业可以继续运行。

一个不错的首次使用流程：

adwarp targeting search titles "demand generation"   # resolve targeting URNs
adwarp report summary -p last_30_days                # account rollup + flags
adwarp launch --brief examples/brief.json            # creates DRAFTS only

完整的 CLI 参考见下文。

从源码运行

适用于贡献者，或运行尚未发布的更改。还需要 git 和 pnpm。

git clone https://github.com/adwarp-dev/adwarp.git
cd adwarp
pnpm install && pnpm -r build

node packages/cli/dist/index.js accounts list
claude mcp add adwarp -- node /abs/path/adwarp/packages/mcp/dist/index.js

或粘贴此提示词，让你的助手完成设置

将整个代码块复制到 Claude（或任何能够访问终端的强大助手）中，它会一步步引导你完成上述所有操作：

You are helping me set up Adwarp, an open-source LinkedIn Ad Manager from
https://github.com/adwarp-dev/adwarp. It runs locally as an MCP server and a CLI,
both from the npm package "adwarp".
Everything it creates on LinkedIn starts as a draft, so nothing spends money until I
explicitly turn it on.

Walk me through the setup one step at a time. Run commands for me where you can,
show me exactly what to click where you cannot, and wait for my confirmation
before moving to the next step.

1. Check that Node.js 20 or newer is installed. Help me install it if it is
   missing.
2. Help me create a LinkedIn developer app at
   https://www.linkedin.com/developers/apps (it must be associated with my
   company's LinkedIn Page):
   a. On the Products tab, request access to the "Advertising API" product.
      This is the only required product; approval can take a while.
   b. Optional: also request "Audiences" if I want to upload CSV contact or
      company lists as matched audiences.
   c. Optional: also request "LinkedIn Ad Library" if I want competitor ad
      metadata through the official API.
   d. On the Auth tab, add http://localhost:53682/callback as an authorized
      redirect URL, and show me where the Client ID and Client Secret live.
3. Create ~/.adwarp/config.json containing my clientId, clientSecret, and
   "linkedinVersion": "202605".
4. Run "npx -y adwarp auth login". My browser opens LinkedIn's
   consent screen; after I approve, tokens are stored in ~/.adwarp/credentials.json.
5. Verify with "npx -y adwarp accounts list". If no accounts
   show up, remind me to map my ad account in the Developer Portal under
   Products > Advertising API > View Ad Accounts. Then set my account id as
   "defaultAccountId" in ~/.adwarp/config.json.
6. Register the MCP server with the assistant I use:
   - Claude Code: claude mcp add adwarp -- npx -y adwarp mcp
   - Claude Desktop or another client: add {"command": "npx", "args":
     ["-y", "adwarp", "mcp"]} under mcpServers in its config.
7. Confirm the tools load, then show me one read-only call working, for example
   list_ad_accounts or a last_30_days performance summary.

If any step fails, show me the exact error and fix it with me before moving on.

Skills

这 17 个付费广告技能将 Adwarp 的工具转化为实用指南：需要获取哪些数据、如何评估、重要的阈值，以及最终列出按优先级排序的行动方案的报告。它们也可通过 CSV 导出文件运行，无需安装 Adwarp。分析类技能只读取数据；会更改账户的技能则会在你确认后创建草稿或暂停的实体。

• **LinkedIn Ads：**账户审计、效果评估、支出分析、潜在客户驱动因素、暂停规则、受众规模评估、受众运营、ABM 构建、受控启动、广告库拆解
• **Google Ads：**账户审计、搜索广告系列构建、搜索词
• **两个平台：**每周报告、每日健康检查、实验提升、预算进度

npx skills add adwarp-dev/paid-ads-skills

过去放在 skills/ 下的 11 个 adwarp-* 技能已更名并迁移至此处。它们的文件夹现在会指向新技能，因此现有安装仍可正常使用。所有迁移详情请参阅技能文档。

工具（MCP）

工具参考列出了所有工具及其输入，以及它们是否适用于托管端点。

• 账户： list_ad_accounts
• 定向： list_targeting_facets、search_targeting（对某个定向维度进行输入提示，以获取实体 URN）、 list_facet_entities、estimate_audience（结构化规范）。用自然语言描述 （“美国 SaaS 公司中的需求生成副总裁”），Adwarp 会解析定向维度，并在创建广告系列前估算覆盖人数。
• 受众： upload_audience_csv（自动清理 CSV：规范化列名、删除无法匹配的列、对电子邮件进行哈希处理、将公司域名转换为网站 URL；支持联系人和公司名单）、audience_from_salesforce（将 SOQL 转为匹配的受众）、 audience_from_hubspot（将 HubSpot 列表或搜索转为匹配的受众，仅本地可用）、get_audience_status
• 转化： list_conversions（选择现有的 insight-tag 转化进行跟踪）。 create_campaign 和 launch_from_brief 接受 conversionIds 或 conversionName，并会回退到配置中的 defaultConversionName。
• 广告系列： create_campaign_group、create_campaign、create_text_ad、create_image_ad； list_campaigns（账户结构：广告系列组及其广告组，包括草稿；与报告不同，报告只显示有支出的实体）、list_ads、delete_ad （移除创意内容，并尽力删除其 Direct Sponsored Content 帖子）、update_ad （暂停、恢复或归档单个广告；ACTIVE 会开始产生支出，因此只有在明确请求时才会设置）。LinkedIn 的编辑器会忽略在线广告的帖子编辑，因此如需更改文案，请重新创建：delete_ad + create_image_ad。
• 编排器： launch_from_brief（一次调用即可创建受众、广告系列组、广告系列和草稿创意）
• 报告： performance_summary（账户汇总 + 最佳/最差表现 + 标记）、get_performance （任意层级的实体 KPI）、performance_trend（按周/月统计并显示变化）。KPI：CTR、 CPC、CPM、CPL、转化率、单次转化成本。层级：campaign_group、campaign、creative。
• 竞争对手情报： inspect_competitor_ads 使用官方 Ad Library API 获取 元数据，并在 auto 模式下可选用远程工作器获取创意文案和截图。 API 失败时，CLI 和 MCP 代码都不会启动本地浏览器，也不会改用抓取方式。 请同时提供 advertiser 和 companyId，以便在将创意加入队列前筛选范围较广的 API 匹配结果。 api 模式仅提供元数据。auto 模式最多将 10 条广告加入队列，并返回缓存结果或任务 状态；使用 get_competitor_creatives / adwarp creative-status <ids> 读取已完成的任务。 工作器会持久化缓存、队列、滚动预算和阻止状态。部署和配置请参阅 远程创意工作器。
• 变更日志与提升效果： log_ad_change（记录变更）、list_ad_changes、compute_lift （计算每项已记录变更前后的效果）。Adwarp 会自动记录其进行的每项变更； 请参阅下文的变更日志与提升效果。

定向规范

结构化定向使用映射到实体 URN 的简短定向维度名称（使用 search_targeting 解析 URN）。同一定向维度内的 URN 采用 OR 逻辑；不同定向维度之间采用 AND 逻辑；排除的定向维度采用 OR 逻辑。

{ "include": { "locations": ["urn:li:geo:103644278"], "seniorities": ["urn:li:seniority:7"], "titles": ["urn:li:title:26587"] },
  "exclude": { "industries": ["urn:li:industry:47"] } }

CLI 参考

所有命令也可通过 npx -y adwarp <cmd> 使用。CLI 文档 列出了完整命令，包括 Google Ads 命令。

adwarp auth login                         # OAuth, stores tokens in ~/.adwarp
adwarp auth export                        # print env vars for a self-hosted (Vercel) server
adwarp auth export --mcp                  # print the hosted-MCP connect command with your headers
adwarp accounts list                      # list accessible ad accounts
adwarp targeting search <facet> <query>   # typeahead a facet for entity URNs
adwarp targeting estimate <facet> <urns…> # audience size for one facet's URNs
adwarp audience upload -n <name> -f <csv> # clean + upload a CSV as a matched audience
adwarp audience upload -n <name> -f <csv> --dry-run   # preview the cleaned CSV, no upload
adwarp audience from-salesforce -n <name> -q "<SOQL>"   # Salesforce query -> matched audience
adwarp audience from-hubspot -n <name> --list <id> [--dry-run]   # HubSpot list -> matched audience
adwarp audience from-hubspot -n <name> --filter <prop>:<op>:<value> [-t company]   # HubSpot search -> matched audience
adwarp audience status <segmentId>        # matching status + resolved size
adwarp conversions list                   # account conversions (pick one to track)
adwarp campaigns list [--group <id>] [--all]   # campaign groups + ad groups, drafts included
adwarp ad list <campaignId>               # ads in an ad group (id, status, name), drafts included
adwarp ad delete <creativeId>             # delete an ad (creative + its DSC post)
adwarp ad pause <creativeId> [--apply]    # pause a single ad, previews unless --apply
adwarp ad resume <creativeId> [--apply]   # set an ad ACTIVE again (starts spend), previews unless --apply
adwarp ad archive <creativeId> [--apply]  # archive an ad, previews unless --apply
adwarp report summary [-p <period>]       # account rollup: totals, top performers, flags
adwarp report perf <level> [--parent <id>] # per-entity KPI rows
adwarp report trend <level> <id> [-b weekly|monthly]  # trend with deltas
adwarp launch --brief <brief.json>        # audience + group + campaign + draft creatives
adwarp competitor ads <advertiser>        # any company's ads from the public Ad Library
                                        #   <advertiser> = name, company id, or company URL
                                        #   -k <keyword> -c <countries> -e auto|api -m <max> --json
                                        #   --company-id <id> --copy-max <n> (remote sample, max 10)
adwarp changelog list [-t <type>] [-i <id>]           # recorded ad changes, newest first
adwarp changelog add -t <type> -i <id> -f <field> --after <v> [-l <label>]   # log a change made elsewhere
adwarp lift <level> <id> [-w <days>]      # before-vs-after performance for each recorded change

时间段：last_7_days、last_30_days、last_90_days、month_to_date、last_month。

在适用情况下，--account 默认为配置中的 defaultAccountId。

变更日志与提升幅度

Adwarp 会以只追加的方式记录对广告实体所做的每项变更，让你衡量变更的提升幅度：比较变更前后两个时间窗口内的效果差异。

• 存储位置：~/.adwarp/changelog.jsonl（每行一个 JSON 对象）。这是无需任何设置的本地纯文本文件。使用 ADWARP_CHANGELOG_PATH 覆盖路径。
• **自动记录：**Adwarp 对广告组、广告系列或创意执行的每次创建或更新都会自动记入日志（在唯一的 HTTP 关口捕获，因此不会遗漏）。
• **手动记录：**记录在 Adwarp 之外（例如在 Campaign Manager 中）所做的变更，或附加假设；可使用 adwarp changelog add / log_ad_change 工具。使用 -l/--label 命名测试（例如 "outcome-led headline test"），并使用 --tags 对相关变更分组。
• 提升幅度：adwarp lift <level> <entityId>（或 compute_lift）会读取该实体的日志，并针对每项变更，将变更前 --window 天（默认 14 天）与变更后的相同时间窗口进行比较，报告变更前后的 KPI 及各项指标的差值（CTR、CPC、转化率、单次转化成本等）。对于近期变更，变更后的时间窗口会缩短并标记为 partial。

这是变更前后的方向性比较，并非受控实验。结果会受到季节性、LinkedIn 在编辑后的学习阶段以及任何同期预算变更的干扰，因此请将差值视为参考信号。设置 ADWARP_NO_CHANGELOG=1 可停用自动记录；托管部署也会停用日志记录（文件系统为只读）。

配置

本地配置位于 ~/.adwarp/config.json（权限模式为 0600，不会存入代码仓库）：

字段	用途
clientId, clientSecret	LinkedIn 应用凭据（或 ADWARP_LINKEDIN_CLIENT_ID/ADWARP_LINKEDIN_CLIENT_SECRET）
linkedinVersion	固定的 API 版本，例如 202605
defaultAccountId	命令或简报未指定广告账户时使用的账户
defaultConversionName	新广告系列未指定转化目标时自动选用的转化目标
mcpAuthToken	托管 MCP 端点的 Bearer 密钥

托管环境中的对应配置为 ADWARP_LINKEDIN_* 环境变量和 MCP_AUTH_TOKEN（参见配置）。 OAuth 令牌单独存储在 ~/.adwarp/credentials.json 中。用于 HubSpot 受众 的 HubSpot 私有应用令牌，存放在 ~/.adwarp/hubspot.json（权限模式为 0600）中，或通过 ADWARP_HUBSPOT_TOKEN 设置。

从 Liam 迁移而来？重命名前的所有名称仍然有效：~/.liads 文件夹、LIADS_* 和 GADS_* 变量，以及 X-Liads-* 请求头。参见重命名前的名称。

Salesforce 集成

Adwarp 通过调用已完成身份验证的 sf CLI（sf data query）读取 Salesforce，因此会沿用你现有的登录状态，无需新凭据。audience_from_salesforce（以及 adwarp audience from-salesforce）接受一个选择电子邮件列的 SOQL 查询，并将查询结果转化为匹配受众，从而打通从“在 Salesforce 中标记的账户”到“LinkedIn 定向”的完整流程。示例：

adwarp audience from-salesforce -n "Q3 target accounts" \
  -q "SELECT Email FROM Contact WHERE Account.Target_List__c = true AND Email != null"

HubSpot 集成

Adwarp 使用你在自己的 HubSpot 账户中创建的私有应用访问令牌读取 HubSpot，该令牌需具有 3 个只读权限范围：crm.objects.contacts.read、crm.objects.companies.read 和 crm.lists.read。将令牌放入 ~/.adwarp/hubspot.json，内容为 { "accessToken": "..." } （权限模式为 0600），或设置在 ADWARP_HUBSPOT_TOKEN 中。audience_from_hubspot（以及 adwarp audience from-hubspot）接受 HubSpot 列表 ID 或 CRM 搜索筛选条件，读取所有分页结果，并通过与 CSV 上传相同的数据清理和哈希处理，将联系人或公司转化为匹配受众，因此只有电子邮件哈希会离开你的设备。此功能仅在本地运行。 示例：

adwarp audience from-hubspot -n "Q3 target accounts" --list 123 --dry-run
adwarp audience from-hubspot -n "Marketing qualified leads" --filter lifecyclestage:EQ:marketingqualifiedlead

创建私有应用及相关限制，请参见 HubSpot 受众。

安全

• 所有广告活动/创意均以 DRAFT/PAUSED 状态创建。激活是单独且明确的步骤。
• 匹配受众需要最多 48 小时，广告活动需要约 300 名匹配成员才能投放。
• LinkedIn 不提供个人级别的广告浏览数据；交叉比对以账户/细分受众级别进行。
• 密钥绝不会进入代码仓库。本地：~/.adwarp。托管环境：Vercel 环境变量。

文档

文档位于 adwarp.dev/docs： 安装、 创建 LinkedIn 应用、 托管端点、工具、 技能、CLI、 变更日志、安全 和配置。

这些文档的源文件位于此代码仓库的 docs/ 目录中，采用纯 Markdown 格式，每个主题对应一个文件，并包含 title、description 和 order 前置元数据。网站会从 main 分支读取这些文件，因此行为发生变化时，请相应修改文档。文档文件之间的链接应保持相对路径形式（./install.md），网站会将其转换为站内页面链接。

docs/tools.json 列出了每个 MCP 工具的描述、输入架构、平台（linkedin 或 google），以及是否支持托管端点（hosted、hostedSupport 和 hostedNote）。该文件由实际的工具注册代码生成，因此切勿手动编辑。添加、删除或更改工具（包括其 zod 输入架构）后，请运行：

pnpm gen:tools   # builds @adwarp/mcp and its dependencies, then rewrites docs/tools.json

并提交生成的结果。CI 会运行同一命令；如果 docs/tools.json 发生变化，检查就会失败。

许可证

MIT