MintOffice

MintOffice 是 mintbot.ai 的 Brand Partner 门户。它让你能够以自有品牌转售 mintbot：你的域名、你的机器人、你的客户名单——而部署、计费通道以及每个智能体背后的基础设施，都由 mintbot 在底层负责处理。

在线的合作伙伴门户位于 mint.mintbot.ai。

本指南将带你从“我刚听说 MintOffice”，一路走到“我的第一个白标智能体已在自有 域名上线”。其中的技术环节（DNS 记录、GitHub 仓库、机器人令牌）最好交由一个 mintbot 智能体代你完成——开始之前，请先阅读 让智能体替你完成配置。

想自己搭建集成？

关于面向开发者的部分——你拥有哪些仓库、部署流程如何端到端运行，以及 智能体定制仓库与店面如何协同——请参阅 MintOffice — 技术文档。

---

你能获得什么

• 以自有域名转售每一个 mintbot 套餐（Trial、Starter、Pro、Max）—— 你的客户看到的是 agent1.yourbrand.com，而非 *.mintbot.ai。
• 使用你自己的 Telegram 机器人（@yourbrand_bot）来承载聊天流量， 或在测试阶段先借用 mintbot 的机器人。
• 自定义面向客户的价格，赚取你收取的价格与 mintbot 向你收取的价格 （MintOffice 批发底价）之间的差额。
• 一套 Brand Partner API，用于以编程方式创建订单、查询生命周期状态， 并将 webhook 回调到你自己的系统。
• 一个仪表盘，展示活跃的客户订单、机器人链路健康状况、定价、分成 以及 webhook 投递情况。

---

定价 — Brand Partner 设置费

注册一个免费试用门户账号当然是免费的——但 Brand Partner 注册才是把它 变成真正的品牌合作伙伴账号的那唯一一笔付款。你在 reception.mintbot.ai/mintoffice （开发/测试环境则为 reception.mintbot.dev/mintoffice）支付一次性设置费， 同一笔付款会解锁两个门户：

等级	价格	包含内容
免费试用（每个新合作伙伴的默认等级）	€0	10 次一次性 DEV 部署，用于测试你的门户 + 模板
Brand Partner — 上线推广价	€49 一次性 + €10/月	20 次 DEV 部署（每次含 €1 智能体额度）、首月账号管理已包含、mint.mintbot.ai + mint.mintbot.dev 两端的 Brand Partner 身份、详尽的设置向导（可由智能体全程替你完成）
Brand Partner — 标准价	€99 一次性 + €10/月	与上线推广价相同——但不含促销折扣

注册功能处于 beta 阶段

Brand Partner 结账目前已在开发/测试环境上开放 （reception.mintbot.dev/mintoffice）。 正式 .ai 结账即将开放。

设置费涵盖的内容：

• 20 次 DEV 部署，每次都是一台 24 小时一次性测试 VPS，预置 €1 的 智能体额度——足以端到端地演练你的门户与定制模板。
• 你的首月账号管理费（即下文的 €10/月 费用）——也就是说，第一个月 已经付清。
• mint.mintbot.ai 与 mint.mintbot.dev 两端的 Brand Partner 身份。

€10/月 的账号管理费：

从第二个月起，Brand Partner 账号会产生 €10/月 的账号管理费。最省心的 缴费方式是 Stripe 或 PayPal 订阅（推荐——它会自动续费）；一次性设置费 也可用银行卡或加密货币支付（通过 CCPayment 支持 BTC、XMR 等多种币种）。

如果月费逾期，你的 MintOffice 账号会进入 paused 状态：你将无法部署新 智能体，但你现有的客户智能体会继续运行。在任何东西停止之前，我们都会先 联系你，以便你恢复账号。

付款之后会发生什么：

1. Reception 在 reception.mintbot.ai/mintoffice（如果你在测试环境则为 .dev）上处理设置付款——银行卡 / Apple Pay / Google Pay，或加密货币。
2. Reception 会立即向 mint.mintbot.ai 和 mint.mintbot.dev 发送一份 已签名的授权，将你的账号在两个门户上都翻转为 Brand Partner 身份。
3. 你会收到一封来自 pigeon@mintbot.ai 的欢迎邮件（如果你在测试环境购买， 则来自 pigeon@mintbot.dev），其中包含两个登录链接以及指向本指南的入口。
4. 从你想先开始的那个门户登录即可。如果跨环境推送因故漏掉了某个门户， 在该门户上的首次登录会向 reception 询问"这个邮箱付过款吗？"并当场 应用授权。

在我们推广 MintOffice 期间，上线推广价默认开启；它由服务器标志 MINTOFFICE_SETUP_PROMO 控制，因此你在结账时看到的价格就是你将支付的价格。

退款

14 天退款窗口，无需任何理由——如果这个等级对你的使用场景不值得， 发邮件到 support@mintbot.ai，我们会把费用退还给你。

每个智能体的批发定价（mintbot 针对你铸造的每一笔客户订单向你收取的费率） 独立于设置费，详见下文的 第 5 步 — 定价。

---

让智能体替你完成配置

大部分技术工作——购买域名、配置 DNS、创建 Telegram 机器人、fork 模板 仓库——都是机械性的。你可以手动完成，但最省心的路径是把它委派给一个 mintbot 智能体。

推荐路径

启动一个 mintbot 智能体 并对它说： “把我设置为域名 yourbrand.com 下的 MintOffice 品牌合作伙伴—— 引导我走完整个入门向导，并尽可能替我填好所有内容。”

该智能体可以访问终端、浏览器、DNS API、GitHub 认证，并掌握本指南的 内容。它会准确告诉你哪一步需要你亲自介入（例如在 Telegram 中点击 BotFather 的确认），其余的它都会处理。

你自己的 Hermes、OpenCode / OpenClaw 安装、Cursor 智能体模式，或任何其他编码智能体同样适用—— 把本页作为上下文喂给它，并告诉它目标即可。

如果你更愿意自己操作向导，下面的步骤正是智能体会替你做的事。

---

第 0 步 — 创建账号

1. 打开 mint.mintbot.ai。
2. 输入你想用作运营登录的邮箱地址。
3. 点击 Send me a sign-in link（给我发送登录链接）。
4. 打开来自 pigeon@mintbot.ai 的邮件，点击其中的魔法链接 （有效期 24 小时，仅可使用一次）。

这里没有密码——之后的每一次登录都是另一个魔法链接。这是有意为之： 密码会泄露，魔法链接不会，而且如果你设置了邮箱访问权限，智能体之后也很 容易将其自动化。

---

第 1 步 — 域名

向导的第一个问题是你的智能体将落在哪里。你有两种选择：

使用我自己的域名（推荐）使用 mintbot.ai 子域名

智能体落在你拥有的某个域名的子域名上——例如 agent1.yourbrand.com、agent2.yourbrand.com…… 这就是你的客户看到的 品牌化体验。

你需要准备：

• 顶级域名（Apex domain）——一个已注册的裸域名（不带 https://， 不带子域名）：yourbrand.com。
• DNS 提供商——目前只有 Zone.ee 有可用的后端。 Cloudflare 和手动模式仍在路线图上。
• Zone.ee API 密钥 + 用户名——从 my.zone.eu → Account settings → API keys → Create new key 处签发。当你为某个智能体配置部署时，智能体会用 它来自动创建 A 记录。

子域名编号风格

• 文字前缀 + 数字（默认）——agent1.yourbrand.com、 agent2.yourbrand.com…… 最易于人类阅读。
• 纯数字——1.yourbrand.com、2.yourbrand.com…… 简短。
• 数字，补零对齐——001.yourbrand.com…… 宽度稳定。

这个选择纯粹是外观上的——部署 worker 对这三种都没有问题。

智能体落在 *.mintbot.ai 上——无需设置，无需 DNS，但 URL 不带你的 品牌。适合先试试水；在面向客户正式上线之前，请切换到你自己的域名。

---

第 2 步 — 机器人

每个智能体都有一个聊天界面。默认假设使用 Telegram——Discord 和 Slack 已 搭好骨架，但尚未接通。

使用我自己的 Telegram 机器人（推荐）借用 mintbot 的机器人暂时不用机器人

你的客户与 @yourbrand_bot 聊天，从而保持品牌一致。

1. 在 Telegram 中打开 @BotFather。
2. 发送 /newbot。为机器人设置一个显示名称和一个用户名 （必须以 bot 结尾）。
3. BotFather 会返回一个形如 123456789:AA… 的令牌（至少 40 个字符）。
4. 把该令牌粘贴到向导中。

如果你想看更详细的版本，请参阅 Telegram 的 机器人教程。

客户与 @mintbot_dev_bot 聊天。用于演示很快，但没有品牌。上线之前请 切换到你自己的机器人。

完全跳过 Telegram。客户只能通过网页面板访问 智能体。你之后可以在 Settings 中添加机器人。

---

第 3 步 — 智能体定制仓库

每个智能体都由 mintbot 本身部署在一个标准的、无品牌的基础之上。要在其上 叠加你的品牌——人设、面板主题、文案，以及任何额外工具——你需要在向导 中指向一个智能体定制仓库：一个 GitHub 仓库，由智能体自己的 VPS 在 标准部署完成后克隆并运行。外观由你决定；代码归你所有。

智能体定制仓库的工作原理

仓库根目录包含两个脚本：

• install.sh——在智能体的 VPS 上仅运行一次，时机是标准部署 已经完成且智能体健康之后。这就是你应用定制的地方：主题、人设微调、 额外工具，以及任何客户特定的设置。
• update.sh——可选；在每一次基础套餐更新之后运行， 以便你能在刚更新好的基础之上重新叠加你的定制层。

mintbot 从不运行你的仓库——只有智能体自己的 VPS 才会运行它，且是在 客户自己的机器上。把你仓库的 GitHub HTTPS URL 粘贴到向导中即可； 留空则得到纯粹无品牌的基础版本。

指向我自己的智能体定制仓库（推荐）留空

创建一个在根目录含有 install.sh（以及可选的 update.sh）的仓库， 用它来应用你的 CSS / 字符串 / 人设，然后粘贴该仓库的 GitHub HTTPS URL。 智能体的 VPS 会在部署后克隆它，并运行你的脚本，把你的品牌叠加到基础 之上。

脚本出错也不会弄坏你客户的智能体

你的脚本是故障隔离的。如果 install.sh 或 update.sh 缺失、报错 或运行缓慢，部署仍会成功，基础套餐更新绝不会被阻断或回退，智能体 也会保持健康。失败会记录在 VPS 上并呈现给你——绝不会呈现给最终 客户。脚本出错的唯一后果是智能体停留在纯基础版本而非你的品牌层， 因此请先在一次 DEV 部署上测试你的仓库。

纯粹无品牌的基础样式与人设——没有智能体定制仓库。你之后可以在 Settings 中添加仓库 URL。

---

第 4 步 — API

Brand Partner API 让你能够从自己的后端编排智能体的创建，而无需使用仪表盘。 向导默认会跳过 API 设置——除非你现在就准备好集成，否则把它留到以后。

当你准备好时：

1. 在仪表盘中，打开 Settings → API access。
2. 点击 Generate key（生成密钥）。明文只显示一次——请把它存入 你的密钥管理器。
3. （可选）配置一个 webhook URL 以接收生命周期事件。
4. （可选）在你的接收端准备好验证签名之后，生成一个 webhook 签名 密钥。

完整的端点列表以及 webhook 负载结构，请参阅 Brand Partner API 参考文档。

webhook URL 与签名密钥都是可选的

两者都不是开始销售的必要条件——没有它们，仪表盘和 API 也能正常工作。 webhook URL 字段会一直保持空白，直到你有一个指向 https://<your-host>/... 的接收端；签名密钥仅在你设置了该 URL 并希望 验证 X-Mintbot-Signature 头部时才有用。两者都可以随时从 Settings → API access 添加（或轮换）。

让集成智能体自行发现配置

一旦你拥有 API 密钥，智能体就可以调用 GET /api/v1/settings，一次性读取 你完整的非机密配置——域名、DNS 提供商、机器人、智能体定制仓库、 子域名模式、定价、就绪状态。任何机密都不会返回（令牌和密钥仅以 *_set 布尔值的形式出现），因此可以放心地把密钥分享给正在某台全新 服务器上安装你白标配置的智能体。

跳过样板代码——fork 参考门户

一个完整、可运行的示例店面位于 mintbot-ai/partner-portal-example。 完整的演练请见下文的 参考门户。

---

第 5 步 — 定价

向导的最后一步是你的客户为每个套餐支付的价格。MintOffice 把定价分为两种 模式——你之后可以在 Settings → Pricing 下切换：

使用默认定价（推荐）为每个等级设置自定义价格

客户看到的是 mintbot 为每个等级（Trial、Starter、Pro、Max）推荐的 价格。你赚取的合作伙伴利润就是该推荐价与批发底价之间的差额——零设置。 如果你只是想开始销售，就选这个。

你为客户在每个等级所支付的价格自行设定。批发底价之上的每一分钱都归 你所有。当你有明确的加价策略时，就选这个。

批发底价是 mintbot 针对每笔订单向你收取的费用——它是你能收取的绝对 下限。你的合作伙伴分成是每笔订单的 customer_price − wholesale_floor。向导会在你提交之前预览每个等级计算出 的利润。

自定义定价可以是部分的

即使在自定义模式下，你也不必覆盖每一个等级——让某个等级保持默认， 它就会沿用 mintbot 推荐的价格。只编辑你关心的那些等级即可。

---

上线

走完向导后，仪表盘会显示一条横幅，列出仍然缺失的所有必填信息。三个必填 字段是：

1. Telegram 机器人令牌（或另一个机器人提供商）
2. DNS API 密钥（例如 Zone.ee 密钥 + 用户名）
3. 顶级域名

智能体定制仓库 URL 是可选的——留空，你的智能体就会部署在纯粹无品牌的 基础之上。

一旦必填字段填好且 DNS 提供商检查通过，Go Live 按钮就会激活。点击它会 把你的合作伙伴状态从 onboarding → live 翻转，Brand Partner API 随即 开始接受创建订单的请求。

激活是一次单向握手

在你点击 Go Live 之前，你的账号会一直保持 onboarding 状态。在 onboarding 期间，API 会以 403 拒绝写操作（读操作保持开放，以便你检查 状态）。在你的域名 DNS 在 Zone.ee 中验证通过，并且（如果你使用定制 仓库的话）已在一次 DEV 部署上测试过你的定制仓库之前，请不要激活。

Go Live 之后：域名 + Telegram 机器人设置将锁定

一旦你的合作伙伴状态变为 live，Settings 中的 Domain 和 Telegram bot 部分将变为只读。现有的客户智能体已经指向你的顶级 域名并通过你的机器人聊天——一次悄无声息的更改会让它们在生命周期中途 成为孤儿。其他部分仍然可编辑：

部分	live 状态下可编辑吗？
域名 / DNS / 子域名模式	否——如需迁移，请联系支持团队
Telegram 机器人	否——如需迁移，请联系支持团队
智能体定制仓库	是——新智能体会克隆新的仓库 URL；现有智能体会在下一次基础更新时通过 update.sh 重新运行它
API 密钥 / webhook	是——可随时轮换
定价	是——应用于未来的订单

该锁定在 UI 中（fieldset 禁用，并附带说明原因的横幅）和服务器端 （带有 section=domain 或 section=bot 的 /settings POST 请求会 返回 403）都会强制执行。

---

Webhook + 分成

• Webhook 投递——每一个生命周期事件（订单创建、激活、过期）都会 POST 到你在 Settings 中设置的 webhook URL。仪表盘上每个合作伙伴的 Webhook 健康徽标会显示过去 24 小时的投递成功率。
• 收入台账——每一笔已付款订单都会写入一行，记录你的毛收入、你的 分成以及 mintbot 的分成。仪表盘会汇总累计总额和未结余额。
• 分成支付——会逐步累积。mintbot 团队会按合作伙伴协议手动支付； 仪表盘会跟踪已付与未付状态。

---

参考门户

如果你不想从零搭建店面，可以 fork 官方示例： mintbot-ai/partner-portal-example。 它采用 MIT 许可，基于 FastAPI + SQLite + Docker，附带一套虚构的 "AcmeAI" 品牌（你可以替换掉），并端到端覆盖了完整的闭环：

• 带套餐卡片的着陆页，
• /buy 表单 → POST /api/v1/orders → Stripe 结账跳转，
• 致谢 / 取消返回页，
• 带 HMAC 签名验证器 的 POST /webhooks/mintoffice，
• 采用 HTTP Basic 认证的 /admin 事件浏览器，
• /healthz 存活探针。

设置演练

1. Fork 该仓库，以便你能把品牌化改动保存在 git 中：

   git clone https://github.com/mintbot-ai/partner-portal-example.git
   cd partner-portal-example
   cp .env.example .env
   

2. 用你 MintOffice 仪表盘中的值填写 .env：

   变量	这里填什么
   PARTNER_BRAND	客户可见的品牌名称（同时用作 Stripe 行项目标签）。
   MINTOFFICE_API_URL	正式环境用 https://mint.mintbot.ai，测试环境用 https://mint.mintbot.dev。
   MINTOFFICE_API_KEY	来自 Settings → API access 的 API 密钥（格式为 mo_live_…）。
   MINTOFFICE_WEBHOOK_SECRET	webhook 签名密钥，在同一仪表盘中创建时只显示一次。
   PUBLIC_BASE_URL	你的门户将运行所在的 HTTPS URL（用于构建 Stripe 的 success_url / cancel_url）。
   ADMIN_USERNAME / ADMIN_PASSWORD	/admin 上的 Basic 认证关卡。请使用一个长的随机密码。

3. 运行它——Docker 是最简单的路径；裸机部署也可以：

   Docker本地 Python

   docker compose up --build
   

   pip install -e .
   uvicorn app.main:app --reload
   

4. 通过 HTTPS 暴露它——对于 Stripe 跳转 URL 和 webhook URL，MintOffice 都会拒绝 http://（私有 IP 和 localhost 会被 SSRF 防护拦截）。 对于本地开发，请使用 Cloudflare Tunnel、Tailscale Funnel 或 ngrok。 对于生产环境，请部署到你自己的主机上。

5. 把你的合作伙伴行指向该门户——回到仪表盘：

   • 把 Webhook URL 设置为 https://<your-host>/webhooks/mintoffice。
   • 这就完成了。从 /buy 下一个测试订单，然后看着事件到达 /admin。

重新品牌化

默认模板假装自己是 AcmeAI。有三个接触点：

• .env 中的 PARTNER_BRAND——会流入 Stripe、头部、页脚。
• app/templates/base.html——颜色 / 强调色的 CSS 变量。
• app/templates/*.html——文案与每页布局。各语种翻译（爱沙尼亚语、 西班牙语……）以这些文件的 fork 形式存在。

在与你的智能体相同的 VPS 上快速部署

示例门户足够小，可以与你的 MintOffice 部署智能体一起运行。如果你已经 有一台 mintbot 智能体 VPS，就对它说： "把 partner-portal-example 作为 webhook 接收端部署到 https://portal.<my-domain>/ 下，用 GET /api/v1/settings 填入 MINTOFFICE_API_KEY 和 MINTOFFICE_WEBHOOK_SECRET，并在我的合作伙伴行 上设置 webhook URL。" 该智能体拥有文档和 API 密钥路径，能够端到端 完成这件事。

---

Brand Partner API

关于以编程方式创建智能体、轮询状态以及 webhook 事件，请参阅 Brand Partner API 参考文档。关于更广泛的架构 （你的店面、API、部署 worker 以及每个客户的智能体 VPS 如何协同），请参阅 MintOffice — 技术文档。