---
title: 某个集成无法连接
summary: 一个具体的连接错误实际意味着什么，从被拒绝的 API 密钥到未验证的域名，以及如何解决它。
date: 2026-09-10
---

# 某个集成无法连接

一个具体的连接错误实际意味着什么，从被拒绝的 API 密钥到未验证的域名，以及如何解决它。

## “无效的 API 密钥：认证被远程服务拒绝”

密钥本身被你所连接的服务拒绝了，而不是被 HeartBeatAgents 拒绝。在该服务自己的网站上重新生成密钥并重试；复制粘贴错误（多余的空格、被截断的密钥）是最常见的原因。

## “域名未验证”

某些服务（尤其是邮件发送方）只允许你使用已经在其一侧验证过的域名。先在该服务自己的控制面板中验证域名；错误消息会指出已验证的域名（如果有的话），以便你确认自己指向的是正确的域名。

## “请同时填写客户端 ID 和客户端密钥”

对于自定义 OAuth 应用，两个字段在连接流程开始之前都是必填的；只填了客户端 ID（或只填了密钥）的服务描述无法完成身份验证。

## 连接超时，或“无法连接到 {host}”

这是对该特定主机的网络可达性问题，而不是身份验证问题。确认主机确实正确（自定义集成 API 主机中的拼写错误是常见原因），并且该实例所在的环境能够访问它。

## “会话已过期：请重新登录”

这具体中断的是一次 OAuth 流程，而不是你整体的 HeartBeatAgents 会话。从**设置 → 集成**重新开始连接。

## 连接测试通过，但集成对智能体仍不起作用

成功的测试只能确认凭证本身有效；它不能确认某个智能体已被授予访问权限。检查**设置 → 集成 → [该服务] → 分配给智能体**，确认你期望的智能体确实已绑定到它。

## 相关内容

- [集成指南](/zh/docs/guides/integrations-guide)：连接一个服务本应如何工作
- [自定义集成](/zh/docs/guides/custom-integrations)：自定义集成特有的验证步骤
- [智能体卡在重试循环中](/zh/docs/troubleshooting/agent-stuck-retry-loop)：一个原本正常工作的集成在对话中途开始失败时