Dodo Payments Docs

Dodo Payments Agent Plugin

面向 AI 编码 Agent 的官方 Dodo Payments 插件。它通过统一的事实来源，为 Claude Code、Codex CLI、Cursor、VS Code / GitHub Copilot、Grok Build、Meta Muse Code、Gemini CLI、Antigravity、Junie、OpenCode 等工具安装 Dodo Payments 集成技能和两个 MCP 服务。

此插件符合 Agent Plugins 1.0.0 规范：根目录下的 plugin.json、作为 skills/ 直接子项的技能，以及 mcp.json 中的 MCP 服务。原生支持 Agent Plugins 的客户端可直接加载此插件；此仓库中的各服务提供商专用清单则是为不支持该规范的客户端生成的兼容层。

你将获得

• Dodo Payments API MCP 服务 - 实时 API 访问（支付、订阅、客户、产品、退款、许可证、用量）。通过浏览器 OAuth 进行身份验证，无需本地凭据。
• Dodo Knowledge MCP 服务 - 无需凭据。可对当前 Dodo Payments 文档进行语义搜索。
• Agent 技能 - 集成指南（见下文列出），以带有 YAML frontmatter 的 SKILL.md 文件编写。执行任务需要相关技能时，你的 Agent 会自行加载。

安装

客户端	技能	MCP	方式
Claude Code	✅	✅	Marketplace
Codex CLI / ChatGPT	✅	✅	Marketplace
Cursor（和 Grok Bot）	✅	✅	克隆
VS Code / GitHub Copilot	✅	✅	插件视图 · Copilot CLI
Grok Build	✅	✅	grok plugin install
grok.com、xAI API	—	✅	连接器 / API 工具
Meta Muse Code	✅	✅	muse plugins install
Gemini CLI	✅	✅	扩展
Google Antigravity	✅	✅	agy plugin install
JetBrains Junie	✅	✅	扩展
Kiro	✅	✅	Power
OpenCode	✅	✅	npm
Qwen Code、Devin、Goose、Factory Droid、Augment、OpenHands、OpenClaw、Hermes	✅	✅	更多客户端
Cline、Kilo、Zed、Warp、Amp、Continue、Kimi、…	✅	✅	npx skills + npx add-mcp
Claude.ai、ChatGPT、Perplexity、Mistral	—	✅	自定义连接器

Claude Code

claude plugins marketplace add dodopayments/dodo-agent-plugin
claude plugins install dodopayments@dodopayments

API MCP 服务默认使用浏览器 OAuth，因此安装时无需密钥。Agent 首次调用 Dodo 工具时，系统会提示你登录。

Codex CLI

注册 Marketplace，然后安装插件：

codex plugin marketplace add dodopayments/dodo-agent-plugin
codex plugin add dodopayments@dodopayments

验证：

codex plugin list     # dodopayments  installed, enabled
codex mcp list        # dodo-knowledge, dodopayments-api
codex mcp login dodopayments-api    # browser OAuth, only needed for the API server

你也可以在 TUI 中安装：运行 codex，输入 /plugins，选择 Dodo Payments Marketplace 和 dodopayments 插件，然后选择 Install plugin。

如果你之前添加过 Marketplace，但插件没有显示，请刷新：

codex plugin marketplace upgrade dodopayments

Cursor

手动安装：

git clone https://github.com/dodopayments/dodo-agent-plugin.git ~/.cursor/plugins/local/dodo-agent-plugin

重启 Cursor。该插件会从 skills/ 加载技能，并从 .mcp.json 加载 MCP 服务，具体配置见 .cursor-plugin/plugin.json。

Cursor 3.14.27 也能直接识别 Agent Plugins 1.0.0：其 Agent 宿主包含两个规范的 schema URL 和规范自身的 name 正则表达式，并接受 .cursor-plugin/marketplace.json 或 .claude-plugin/marketplace.json 作为市场来源。生成的 .cursor-plugin/plugin.json 作为额外保障保留，以兼容较旧版本。

在 v0.5.0 之前，此克隆会生成一个没有可用技能的插件：skills/ 中包含指向 git 子模块的符号链接，而普通的 git clone 不会获取子模块。现在，技能已作为真实文件纳入仓库，因此上述命令可按文档所述正常工作。如果你安装的是较早版本，请重新克隆。

Kiro

Kiro 原生读取 Agent Plugins 清单，并将其加载为 Power：

git clone https://github.com/dodopayments/dodo-agent-plugin.git

将 Kiro 指向克隆的文件夹。技能从 skills/ 加载，MCP 服务从 mcp.json 加载，而 Kiro 专属的呈现方式来自 plugin.json 中的 dev.kiro 扩展命名空间。

Gemini CLI

gemini extensions install https://github.com/dodopayments/dodo-agent-plugin

仓库根目录中的 gemini-extension.json 是清单，Gemini 会自动发现与其同级的 skills/ 目录。在 Gemini CLI 0.63.0 上已验证：gemini skills list 会显示所有技能，gemini mcp list 会显示两个服务。

VS Code / GitHub Copilot

git clone https://github.com/dodopayments/dodo-agent-plugin.git

然后打开聊天视图，转到 插件，并添加克隆的文件夹。技能从 skills/ 加载，两个 MCP 服务都从 .mcp.json 加载。

VS Code 1.125.1 不会根据 Agent Plugins $schema 进行识别——其程序包中完全没有这个字符串。它的加载器会按顺序探测 .plugin/plugin.json、.claude-plugin/plugin.json，然后是根目录中的 plugin.json，以此选择清单；MCP 的默认文件则是 .mcp.json，而不是 mcp.json。由于此仓库包含生成的 .claude-plugin/plugin.json，VS Code 会通过该分支加载它。所有功能均正常——所有技能和两个 MCP 服务都可用——依靠的是兼容性清单，而非规范清单。

OpenCode

OpenCode 通过 npm 分发。将插件添加到你的 opencode.json：

{
    "$schema": "https://opencode.ai/config.json",
    "plugin": ["@dodopayments/opencode-plugin"]
}

重启 OpenCode。两个 MCP 服务（dodopayments-api、dodo-knowledge）会通过插件的 config 钩子自动注册为原生远程服务。无需手动添加 mcp 配置块。运行 opencode mcp auth dodopayments-api，即可登录 API 服务。

技能需要在本地安装程序包，并额外添加一行配置。 OpenCode 不会扫描已安装的程序包来查找技能，因此你需要自行将其指向程序包的 skills/ 目录。skills.paths 条目会相对于项目目录解析，因此程序包必须位于项目的 node_modules 中——OpenCode 自己的插件缓存并不在同一位置：

npm install --save-dev @dodopayments/opencode-plugin

{
    "$schema": "https://opencode.ai/config.json",
    "plugin": ["@dodopayments/opencode-plugin"],
    "skills": {
        "paths": ["node_modules/@dodopayments/opencode-plugin/skills"]
    }
}

也可以使用绝对路径，这样就不需要在本地安装。

运行 opencode run "List every skill available to you by name." 进行验证——你应该能看到 Included Skills 中列出的所有技能。如果技能路径不存在，系统会静默忽略，因此请务必检查，不要想当然。

0.5.0 之前的版本将这些技能描述为自动发现，但事实并非如此：OpenCode 不会扫描已安装的程序包，因此 OpenCode 用户虽然能使用 MCP 服务，却没有技能。通过插件的 config 钩子设置 config.skills 也无法解决这个问题——技能索引会在运行 config 钩子之前构建，因此不会注册任何内容。

如果你想使用本地 stdio API 服务，并提供自己的 API 密钥，而不是使用默认的远程 OAuth 服务，请在 opencode.json 中自行声明 dodopayments-api——你的配置会覆盖插件默认设置：

{
    "plugin": ["@dodopayments/opencode-plugin"],
    "mcp": {
        "dodopayments-api": {
            "type": "local",
            "command": ["npx", "-y", "dodopayments-mcp@latest"],
            "environment": {
                "DODO_PAYMENTS_API_KEY": "dodo_test_...",
                "DODO_PAYMENTS_WEBHOOK_KEY": "whsec_...",
                "DODO_PAYMENTS_ENVIRONMENT": "test_mode"
            },
            "enabled": true
        }
    }
}

已包含的技能

入门

技能	描述
dodo-best-practices	SDK 设置、环境、API 密钥，以及规范的结账到 Webhook 架构
framework-adapters	适用于 Next.js、Express、Hono、Astro、Remix、SvelteKit、Nuxt、Fastify、TanStack、Bun、Convex 的官方 @dodopayments/* 处理程序
testing-and-go-live	测试模式、测试支付方式、Webhook 测试、生产环境上线清单
dodo-mcp-usage	何时使用文档与 API MCP 服务、测试模式安全规则、身份验证、故障排查

收款

技能	描述
checkout-integration	结账会话、支付链接和叠加式结账
subscription-integration	订阅生命周期、试用、套餐变更、按比例计费、按需收费
mobile-checkout	适用于 React Native、Flutter、iOS 和 Android 的应用内结账
webhook-integration	通过 Standard Webhooks 规范接收和验证 Webhook

计费模式

技能	描述
credit-based-billing	积分权益、余额、账本、结转、超额用量、基于计量器的扣减
usage-based-billing	计量器、事件采集、聚合和按单位定价
license-keys	许可证密钥激活、验证和实例管理

目录与定价

技能	描述
product-catalog-management	产品、定价、附加项、集合、图片、数字交付
discounts-and-promotions	折扣码、适用资格、叠加使用、订阅周期限制
localized-pricing	本地化定价、自适应货币和购买力平价

客户与运营

技能	描述
customer-management	客户、自助服务门户、支付方式、电子钱包
refunds-and-disputes	退款、争议与拒付、访问权限对账

UI 与集成

技能	描述
billing-sdk	用于定价表和计费 UI 的 BillingSDK React 组件
better-auth-integration	用于客户同步、结账和门户的 @dodopayments/better-auth 插件

技能来源：dodopayments/skills，已作为实际文件引入 skills/。来源信息（上游提交和应用的转换）记录在 .skills-source.json 中。

已包含的 MCP 服务

服务	用途	身份验证
dodopayments-api	实时 API 访问（支付、订阅、客户、产品、退款、许可证、用量）	OAuth（浏览器）
dodo-knowledge	对 Dodo Payments 文档进行语义搜索	无

两个服务都通过 HTTPS 上的 Streamable HTTP 通信，每个清单都会直接连接它们——无需 npx mcp-remote 桥接，也无需 Node 依赖。规范的 mcp.json 使用规范中的 type: "streamable-http"；生成的 .mcp.json（Claude Code、Cursor、VS Code、Grok Build、Devin、Goose、Droid）使用相同端点，但将类型写作 type: "http"，这是该方言采用的名称；Muse、Antigravity、Junie 和 Gemini 则使用生成器提供的各自写法。

配置（可选，Claude Code）

如果你希望使用 API 密钥在本地运行 API MCP，而非使用远程服务，请在 Claude Code 中打开 /plugins，选择 Dodo Payments，然后选择 Configure options。填写：

• dodo_api_key - 你的 dodo_test_... 或 dodo_live_... 密钥
• dodo_webhook_key - 你的 Webhook 签名密钥
• dodo_environment - test_mode 或 live_mode

然后编辑 .mcp.json，将 dodopayments-api 指向本地 stdio 服务：

{
    "mcpServers": {
        "dodopayments-api": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "dodopayments-mcp@latest"],
            "env": {
                "DODO_PAYMENTS_API_KEY": "${user_config.dodo_api_key}",
                "DODO_PAYMENTS_WEBHOOK_KEY": "${user_config.dodo_webhook_key}",
                "DODO_PAYMENTS_ENVIRONMENT": "${user_config.dodo_environment}"
            }
        }
    }
}

运行 /reload-plugins 以在当前会话中应用更改。

启用 / 禁用单个 MCP 服务

两个 MCP 服务默认均已启用。你可以分别关闭其中任意一个。

OpenCode

npm 插件会在注册 MCP 服务前读取两个环境变量：

环境变量	作用
DODO_DISABLE_API_MCP=1	跳过注册 dodopayments-api
DODO_DISABLE_KNOWLEDGE_MCP=1	跳过注册 dodo-knowledge

真值：1、true、yes、on（不区分大小写）。在 shell 配置文件中导出变量，或直接内联设置：

DODO_DISABLE_API_MCP=1 opencode

Claude Code、Codex CLI、Cursor

这些客户端会从插件附带的静态 .mcp.json 加载 MCP 服务。如需禁用某个服务，请在自己的项目级配置中覆盖其条目，并设置 "enabled": false。

Claude Code - 编辑项目根目录下的 .mcp.json（或运行 claude mcp disable dodopayments-api）：

{
    "mcpServers": {
        "dodopayments-api": {
            "type": "http",
            "url": "https://mcp.dodopayments.com/mcp",
            "enabled": false
        }
    }
}

运行 /reload-plugins 以应用更改。

Codex CLI / Cursor - 在任何覆盖插件捆绑文件的项目级 .mcp.json 中，都可以使用相同的 enabled: false 模式。编辑后重启客户端。

Claude Code /plugin UI 中的单个 MCP 开关正在由上游跟进，见 anthropics/claude-code#27105 和 #46373。这些功能上线前，受支持的方式是使用上面的 enabled: false 覆盖项。

先试试这个提示词

插件启用后，试试：

Set up Dodo Payments webhook handlers in my Next.js app for payment.succeeded and subscription.active events.

你的 Agent 会加载 webhook-integration 技能，使用 dodo-knowledge MCP 服务获取最新的负载结构，并遵循 Standard Webhooks 规范编写带签名验证的处理程序。

本地开发

git clone https://github.com/dodopayments/dodo-agent-plugin.git
cd dodo-agent-plugin

无需子模块，也无需构建步骤——skills/ 以真实文件形式随仓库提供。

验证 Claude Code 插件和市场：

claude plugin validate .

在开发会话中直接加载插件：

claude --plugin-dir ./dodo-agent-plugin

推送前验证所有内容：

npm run verify     # generated artifacts in sync + Agent Plugins conformance

仓库结构

路径	作用
plugin.json	权威文件。 Agent Plugins v1.0.0 清单及版本的唯一依据
mcp.json	权威文件。 Agent Plugins v1.0.0 MCP 配置
skills/	权威文件。 以真实文件形式随仓库提供的技能；声明的集合位于 .skills-source.json
overlays/*.json	手动编写的提供方扩展项，无法通过封闭的规范架构表达
.claude-plugin/、.cursor-plugin/、.codex-plugin/、.muse-plugin/、.agents/、.mcp.json、gemini-extension.json、plugins/dodopayments/、providers/	生成文件。 请勿手动编辑——运行 npm run build
scripts/build.mjs	唯一的生成器（使用 --check 检查偏差）
scripts/conformance.mjs	Agent Plugins 一致性验证器
.skills-source.json	随仓库提供的技能的上游来源信息

技能在 dodopayments/skills 中编写，并随仓库提供。每周工作流会重新同步这些技能并创建 PR；如需按需运行，请触发 Sync skills from upstream 工作流。

维护者须知

该仓库已配置为在每次 GitHub Release 时发布 OpenCode npm 包。

一次性设置（此仓库已完成）：

• npm scope @dodopayments 已创建，归 Dodo Payments 所有。
• 已为 @dodopayments/opencode-plugin 配置 npm Trusted Publishing（OIDC），对应 publish-opencode.yml。仓库中未存储 npm token。

发布工作流：

1. 在 plugin.json 中更新 version（唯一真实来源）。
2. 运行 npm run build，将其同步到每个生成的清单文件。
3. 运行 npm run verify，然后提交并创建标签。
4. 创建 GitHub Release——Publish @dodopayments/opencode-plugin 工作流将通过 provenance 发布到 npm。

手动试运行：

• 使用 dry_run: true 分发工作流，在不发布的情况下验证发布流水线。

CI 检查：

• Verify 会在每个 pull request 和推送到 main 时运行：检查产物漂移、Agent Plugins 一致性、实时 JSON Schema 验证、“每项已声明技能均存在且没有符号链接”断言、针对各客户端的清单检查（Muse、Antigravity、Junie、Gemini），以及 npm 内容检查。
• 发布工作流会在发布前重新运行相同的检查。

资源

• Dodo Payments 文档
• Agent Skills 文档
• MCP Server 文档
• Skills 源代码仓库
• Discord 社区

许可证

MIT——参见 LICENSE。