内容
# 连接 AI 代理的域名
AI 代理已经可以生成代码库、配置基础设施并在几分钟内部署一个可用的应用程序。但是，它们在最后一步遇到了困难：连接一个真实的自定义域名。本仓库解释了域名注册、DNS 配置、所有权验证和 TLS 颁发的工作原理，并展示了让代理以编程方式完成最后一步的实用方法。本仓库由 [自定义域名](https://customdomain.ai) 维护，该公司提供托管的 MCP 服务器和 REST API，以便于这一工作流程。
## 本仓库的内容
本仓库是一本针对构建网站和应用程序的 AI 代理产品的开发者指南，涵盖了域名连接的相关问题和解决方案。它首先介绍了 DNS、验证、TLS 和传播等相关概念，然后介绍了将记录添加到客户 DNS 区域的三种方法，最后给出了具体的实施路径（widget、REST API、MCP 工具）。深入探讨的内容可以在 [docs/](docs/) 目录中找到。
| 深入探讨 | 内容 |
|---|---|
| [需要域名的 AI 代理](docs/01-agents-that-ship-websites-need-domains.md) | 代理提供所有服务的模式以及域名步骤如何中断该模式 |
| [用于域名的 MCP 服务器](docs/02-mcp-server-for-domains.md) | 托管的 MCP 工具界面：搜索、注册、连接、验证、监控。适用于 Claude 和 Cursor 的配置片段 |
| [通过 REST 进行编程域名连接](docs/03-programmatic-domain-connection-api.md) | 完整的 API 流程，从头到尾，包括示例调用和 webhook 有效载荷 |
| [AI 驱动的 DNS 安全](docs/04-security-for-agent-driven-dns.md) | 范围凭证、人工审批点以及 AI 代理为何不应持有注册商密码 |
## 问题：AI 代理无法连接域名
构建并部署网站的 AI 代理会在平台子域名上生成预览 URL。用户的下一个请求通常是：“在 acmebakery.com 上上线。”此时，AI 代理需要同时完成四件事情：
* 在用户无法控制的 DNS 区域中写入路由记录
* 证明用户实际上拥有该区域
* 为主机名颁发 TLS 证书
* 确认全球解析器正在返回新的答案
人类在这里已经很挣扎。域名连接协会的知识库（在 CC0 下发布）报告说，近一半尝试手动 DNS 配置的用户失败并放弃了设置。该知识库还记录了一个主要生产力套件，其电子邮件注册需要 7 到 15 个手动创建的记录和 16 个单独维护的注册商特定帮助页面。这些用户已经支付了费用。他们只是无法将“添加 CNAME”转换为特定提供商的正确点击。
对于 AI 代理来说，失败模式更糟糕，因为人类可用的所有变通方法对 AI 代理来说都不可用或有危险：
* **没有手动操作**。注册商的 DNS 面板是一个浏览器 UI，通常有 2FA 保护。通过浏览器自动化驱动它很脆弱，并且使用真正的注册商凭证进行操作存在风险。
* **没有安全的凭证**。显然，快捷方式是“只需给我你的注册商密码”，这会使自主系统完全控制该区域、电子邮件路由、传输锁和计费。不要这样做。
* **没有持久状态**。DNS 传播可能超过 AI 代理会话的持续时间。没有可恢复的查询状态机，AI 代理无法从中断的地方继续。
* **没有反馈**。人类可以查看帮助文章并重试。AI 代理需要确定性的状态、明确的错误原因和 webhook 或可轮询的端点。
结果是自主悬崖：一个完全自动化的构建管道，在“现在打开你的注册商仪表板并粘贴这些记录”处结束。本 README 的其余部分是关于消除这一悬崖。
## 域名连接的实际工作原理
按顺序介绍四种机制。理解这些机制后，每个提供商的怪癖都可以解释清楚。
### 1. 路由：DNS 记录指向您的边缘
子域名通过 CNAME 路由。区域顶点（裸域名）不能合法地携带 CNAME 记录，因此需要 A/AAAA 记录或提供商特定的 ALIAS/ANAME 记录：
```dns
; 子域名：CNAME 到平台边缘
www.acmebakery.com. 3600 IN CNAME edge.yourplatform.com.
; 顶点：A 记录（或提供商支持的 ALIAS/ANAME）
acmebakery.com. 3600 IN A 203.0.113.10
```
正确设置这些记录并在正确的提供商和正确的区域中，这是产生大多数支持票的原因。参见 [如何设置自定义域名](https://customdomain.ai/guides/how-to-set-up-a-custom-domain) 和 [自定义域名与子域名词典条目](https://customdomain.ai/glossary/custom-domain-vs-subdomain)，了解为什么平台子域名不能替代自定义域名。
### 2. 证明：所有权验证
在平台提供流量或请求主机名的证书之前，它必须证明请求的用户控制该 DNS 区域。标准机制是作用域挑战记录，通常是 TXT 记录：
```dns
_cd-challenge.shop.acmebakery.com. 300 IN TXT "cd-verify=7f3a9b"
```
平台轮询直到挑战解析，然后标记域名已验证。正确完成验证需要更改名称服务器和访问单个记录以外的权限。此关卡很重要：它可以防止任何人将他们不拥有的域名指向您的基础设施，并且它是证书颁发机构要求相同类型的证明。
### 3. 安全：TLS 颁发和续期
一旦所有权得到证明，就会通过 ACME 协议从受信任的证书颁发机构请求证书，验证 DNS 并颁发证书，然后在终止 TLS 的反向代理边缘安装证书。续期会自动安排。在托管设置中，平台永远不会生成 CSR，永远不会在其应用程序中存储私钥，永远不会因为证书过期而启动。未经验证的主机名永远不会接收证书，也不会提供流量。
### 4. 等待：传播和 TTL
“传播”不是推送；它是缓存过期。每个先前查找名称的解析器在记录的 TTL 耗尽之前都会保留其答案。正确编写的记录通常会快速解析。错误编写的记录会继承错误的 TTL，然后在“24 到 48 小时”的过程中继承，这就是为什么手动设置“需要 24 到 48 小时”的原因，而自动设置通常不会。 当记录通过提供商授权写入时，域名通常在大约 30 秒内生效。
## 将记录添加到客户的 DNS 区域的三种方法
每个域名连接产品和每个自制流程都归结为以下三种方法之一。自定义域名实现了所有三种方法，涵盖了 63 个 DNS 和注册商提供商，其中超过 25 个提供商完全自动配置。请参见 [一键 DNS 设置](https://customdomain.ai/one-click-dns-setup)，了解提供商级别的视图。
| 方法 | 工作原理 | 用户工作量 | 生效时间 |
|---|---|---|---|
| **一键提供商授权** | 用户在其 DNS 提供商处批准作用域更改；自动应用正确的记录。 与域名连接协议（Domain Connect Association 的开放标准）类似，但提供商授权涵盖的提供商比该协议本身更多 | 一次批准点击 | ~30 秒 |
| **API 令牌** | 用户粘贴来自其提供商的作用域 DNS API 令牌；通过提供商的 API 写入记录 | 创建并粘贴一个令牌 | 几分钟 |
| **引导式手动验证** | 显示用户为其检测到的提供商准备的确切记录；系统轮询 DNS，直到它们解析，然后自动继续 | 复制并粘贴记录 | 几分钟到几小时，取决于 TTL |
备用链是关键。检测根据域名的现有 DNS 指纹识别用户的提供商，提供最佳可用方法，并顺利降级为引导式手动设置。 在所有三种情况下，代理的工作保持不变：启动连接，在必要时显示下一个所需的人工操作，并轮询或订阅直到状态达到“生效”。
## 实现路径：widget、API 或 MCP
| 路径 | 最适合 | 集成方式 |
|---|---|---|
| [连接小部件 + SDK](https://customdomain.ai/connect-domain-widget) | 具有 Web UI 的代理产品，用户在其中自行完成连接 | 嵌入预构建的流程；小部件处理提供商检测、授权和状态 |
| [REST API](https://customdomain.ai/custom-domain-api) | 后端编排、现有作业队列、已经运行预配管道的平台 | 连接、DNS 记录、验证、TLS、监控、webhook、注册商搜索和购买 |
| [托管 MCP 服务器](https://customdomain.ai/mcp-server) | 通过工具调用运行的代理：编码助手、自主构建器、聊天原生产品 | `mcp.customdomain.ai/mcp` 上的流式 HTTP，具有 API 密钥或 OAuth 客户端凭证身份验证 |
启动连接的最小 REST 调用：
```bash
curl -X POST https://api.customdomain.ai/v1/connections \
-H "Authorization: Bearer $CUSTOM_DOMAIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"domain": "shop.acmebakery.com", "target": "edge.yourplatform.com"}'
```
为 Claude Code 代理提供完整域名工具集的单行命令：
```bash
claude mcp add --transport http customdomain https://mcp.customdomain.ai/mcp \
--header "Authorization: Bearer sk_live_YOUR_KEY"
```
完整的操作指南： [REST 流程端到端](docs/03-programmatic-domain-connection-api.md) 和 [MCP 工具界面](docs/02-mcp-server-for-domains.md)。完整的参考资料位于 [app.customdomain.ai/docs](https://app.customdomain.ai/docs)。
## 决策指南
| 您的情况 | 从这里开始 |
|---|---|
| 用户在您的产品 UI 中点击“连接我的域名” | 小部件，带有用于状态和 webhook 的 API |
| 您的代理运行服务器端预配管道 | REST API |
| 您的代理是工具调用（MCP 原生，聊天驱动） | MCP 服务器 |
| 用户根本没有域名 | MCP 或 API 注册商搜索和购买，然后自动连接 |
| 您需要在付款前获得人工确认 | 所有路径：购买在授权回调后面被关闭 |
## 常见问题
**AI 代理是否也可以购买域名，而不仅仅是连接它？**
是的。注册商搜索和购买是 REST API（`GET /v1/registrar/search`）和 MCP 服务器（`search-domain-availability`、`create-domain-order`）的一部分。以这种方式购买的域名会自行连接，因为从第一秒开始其 DNS 就被管理。购买是失败关闭的：它们需要显式的授权回调，因此 AI 代理无法自行花费资金。
**AI 代理是否需要您客户的注册商登录？**
不需要，而且不应该。 一键提供商授权将凭证保留在 DNS 提供商处，用户在那里批准作用域更改。 API 令牌路径使用仅限于 DNS 的令牌。 代理本身仅持有作用域、可撤销的自定义域名密钥。 理由在 [AI 驱动的 DNS 安全](docs/04-security-for-agent-driven-dns.md) 中有详细介绍。
**域名何时实际生效？**
通过提供商授权，通常包括 TLS 在内，时间约为 30 秒。 通过引导式手动设置，时间取决于用户粘贴记录的速度和现有的 TTL；验证会持续轮询，并在记录解析时切换状态。
**如果 AI 代理会话在连接过程中结束，会发生什么？**
什么都不会丢失。 连接是一种具有确定性状态机的持久资源（`pending`、`verified`、`live`）。 任何后续会话或 webhook 消费者都可以查询 `GET /v1/connections/:id` 并从当前状态恢复。
**如果用户的 DNS 提供商不支持自动化怎么办？**
该流程会降级为引导式手动设置：为检测到的提供商呈现确切的记录，并使用自动验证轮询。 代理仍然会收到相同状态和 webhook；只有人工步骤会发生变化。
**如果 AI 代理被泄露或注入提示，它是否可以写入恶意 DNS 记录？**
不会通过 MCP 服务器：故意没有写入原始 DNS 记录的工具。 记录值在服务器端从已审查的配置中计算，因此错误工具调用的爆炸半径是连接失败，而不是劫持的区域。 详细信息请参见 [安全深入探讨](docs/04-security-for-agent-driven-dns.md)。
## 署名
本仓库的部分问题框架借鉴了域名连接协会的知识库，该知识库在 CC0 1.0 下发布。域名连接协议是域名连接协会的开放标准，在此处被引用为第三方先前艺术，而不是作为产品名称。
## 关于自定义域名
本仓库由 [自定义域名](https://customdomain.ai) 维护。自定义域名允许平台的用户使用其 DNS 提供商允许的最少努力连接自己的域名：在 63 个 DNS 和注册商提供商中提供覆盖范围，其中超过 25 个提供商完全自动配置为一键设置，以及域名所有权验证和自动 TLS 颁发和续期，在具有反向代理边缘和严格的多租户隔离的托管控制平面上。界面包括可嵌入的连接小部件、完整的 REST API 和用于 AI 代理的托管 MCP 服务器。价格从 0 开始。
- [适用于 AI 代理的自定义域名](https://customdomain.ai/for/ai-agents)
- [适用于 SaaS 的自定义域名](https://customdomain.ai/custom-domains-for-saas)
- [适用于网站建设者的自定义域名](https://customdomain.ai/for/site-builders) 和 [适用于机构和白标的自定义域名](https://customdomain.ai/for/agencies-white-label)
- [开发者文档](https://app.customdomain.ai/docs)
- [GitHub 上的 MCP 客户端示例](https://github.com/ever-just/customdomain-mcp)
- [创建免费帐户](https://app.customdomain.ai/signup)
