集成故障排查

如果某个集成无法连接、停止工作或无法完成任务，请使用本指南检查连接、账户访问权限和所选资源。

本页面介绍 Atoms 中常见的连接和授权问题。对于特定服务的设置、支持的操作或你应用内的配置，请先查看 连接和管理集成，然后选择对应服务的指南。

先进行这些检查

1. 检查故障发生的位置。 是智能体无法在 Chat 中使用某项服务，还是该功能仅在你的应用中失败？为 Chat 连接服务本身并不能证明你的应用已正确配置。对于仅在应用中出现的故障，请参阅 连接和管理集成。
2. 打开该集成。 在你项目的 Chat 中，打开消息输入框旁边的选项菜单，然后选择 Connectors → Add connectors。搜索并选择该服务。检查它是否已连接，或是否仍显示 Connect。某些服务会打开它们自己的管理界面。
3. 在服务本身中检查访问权限。 确认你打算连接的账户可以打开所涉及的确切文件、代码仓库、日历、属性或其他资源。
4. 在更改任何内容之前先保存错误信息。 记录准确的错误消息、时间和时区、受影响的项目或 Chat，以及最后一次成功尝试的时间。对截图中的私人信息进行遮盖处理。

打开 Chat 输入框选项，选择 Connectors (1)，然后选择 Add connectors (2) 以浏览可用的集成。

你也可以在 Settings → Connectors 中管理可用连接。选择你要检查的集成。

请妥善保管凭据。绝不要将密码、登录验证码、API 密钥、访问令牌或其他机密信息粘贴到 Chat 或支持请求中。仅在服务的登录流程或指定的安全配置字段中输入凭据。

查找你的问题

你无法找到或启动某个集成

1. 使用 Add connectors 搜索目录。Chat 菜单中的较短列表并不是完整目录。
2. 如果 Atoms 提示该功能仅在项目内可用，请打开目标项目并在那里重试。
3. 如果某个控件被禁用，请阅读其说明。如果它需要不同的角色或权限，请让项目或工作区所有者提供帮助。不要为了绕过限制而断开其他服务。

检查结果：你应该能够打开该服务的连接或管理界面。如果它仍未出现，请查看 连接和管理集成 或联系支持以确认可用性。不要认为反复尝试登录就能启用缺失的服务。

授权无法完成

1. 选择一次 Connect，然后查找该服务的登录窗口。如果你的浏览器提示弹出窗口被阻止，请允许 Atoms 网站的弹出窗口后重试。在 Chrome 中，请按照 允许特定网站弹出窗口的说明 操作；你不需要为所有网站启用弹出窗口。
2. 选择目标账户并查看请求的访问权限。在关闭该服务窗口之前，完成其授权流程。
3. 如果服务明确表示你的组织已阻止该应用或所请求的访问权限，请保存该消息并联系你的管理员。不要绕过组织策略。
4. 返回 Atoms 并重新打开该集成以检查其状态。关闭登录窗口并不表示授权已成功。

在完成授权前查看所请求的访问权限。对某个账户进行授权本身并不能证明目标资源已连接。

如果授权包含组织或工作区选择器，请确认目标选择并查看请求的权限。

检查结果：该集成显示为已连接。在使用标准布局的连接器详情页面中，Connect 会替换为 Disconnect 和 Try it out。其他服务有各自的布局。如果它仍显示 Connect 或出现错误，请记录该结果，并在进行一次全新尝试后联系支持。

连接了错误的账户

如果集成的管理界面显示了某个账户，请将其与拥有该资源或可访问该资源的账户进行比较。并非每个连接器都会显示已连接的账户，因此不要仅凭浏览器当前登录状态来判断 Atoms 正在使用哪个账户。

使用目标账户直接在服务中打开该资源。如果该账户无法访问它，请先向资源所有者申请访问权限。如果连接使用了错误的账户，请按照该服务的账户切换说明操作，或 安全地重新连接，并在授权期间明确选择正确的账户。

检查结果：一个小型、受支持的读取请求会返回目标资源。如果你仍无法确认连接的是哪个账户，请联系支持，而不是反复断开连接。

集成已连接，但智能体找不到你的数据

1. 检查连接。 在 Connectors 中打开该集成的详情，并确认它已连接。在显示相关信息时，检查所选账户或资源。
2. 检查确切资源。 使用目标账户直接在服务中打开它。确认其位置和访问权限，包括相关的正确组织、工作区、文件夹或属性。
3. 让请求更具体。 在连接器支持的情况下，指明服务名称并提供确切的资源名称或链接。先请求一个受支持的读取操作，而不是一次性搜索并更改多个资源。

例如，如果连接器支持读取文档：“使用 [service] 读取 [document name or link] 并告诉我它的标题。不要更改它。”

检查结果：智能体返回目标资源。如果直接访问有效，但智能体仍无法读取它，请检查连接器支持的能力和已授予的访问权限。只有在有证据表明存在授权问题时，才重新连接。

智能体可以读取数据，但无法更改数据

成功读取并不能证明该连接器支持所请求的更改，或拥有执行该更改的权限。

1. 请参阅 连接和管理集成 或连接器的 What you can do 列表（如果显示）。确认所请求的操作受支持。
2. 检查已连接账户是否被允许对该确切资源进行该更改。仅向资源所有者或管理员申请所需的最小访问权限。
3. 阅读任何错误或确认请求。如果需要额外授权，请按照该服务记录的流程操作。重新连接无法添加连接器本身不支持的操作。

在重试写入之前：检查目标位置，确认第一次尝试是否已经创建或更改了某些内容。仅凭失败响应并不足以证明没有发生任何更改。在确认上一次结果之前，不要重复付款、发送消息、发送邀请或创建记录。

检查结果：受支持的更改在合适的测试资源上成功执行，并且你已直接在服务中确认结果。对于支付或其他真实工作流，请使用该服务特定的测试说明，而不要进行真实交易。

之前可用的连接已停止工作

检查自上次成功请求以来发生了哪些变化：账户、其对资源的访问权限、组织的应用策略，或连接的授权状态。

1. 在 Atoms 中重新打开该集成，并检查它是否仍处于已连接状态。
2. 尝试直接在服务中打开该资源。如果访问权限已被移除，请与资源所有者或管理员解决此问题。
3. 如果错误提示授权已过期、被撤销或无效，请按照 安全地重新连接 操作。如果错误与服务中断、限制或不支持的操作有关，请先处理这些原因。

检查结果：一个小型读取请求再次成功。如果相同错误仍然存在，请保存该错误以及最后一次成功的时间，并联系支持。

结果已过时，或请求持续失败

1. 将结果与服务本身进行比较。确认相关的账户、资源、日期范围、筛选条件和时区。请让智能体获取当前值，而不是依赖对话中较早的回答。
2. 如果出现明确的超时或服务不可用错误，请查看该服务的官方状态页或帮助页面。如果错误给出了重试时间，请等到那个时间；在限制或中断持续期间，不要反复发送请求。
3. 保存任何尚未发送的文本，刷新 Atoms，然后重新检查连接器状态。刷新页面并不等同于重新授权账户。
4. 重试一个小型读取请求。在重试任何会更改外部数据的操作之前，请先检查目标位置中之前的结果。

检查结果：最新结果与服务中的目标资源一致。如果结果仍然不正确，请向支持提供预期值和实际值以及时间戳。不要假设所有集成都以相同频率更新。

安全地重新连接

当授权无效或链接了错误账户时再重新连接——而不是把它作为每次请求失败后的第一步。

断开连接之前：完成或暂停依赖该连接的任务，检查任何待处理外部写入的结果，并确保你可以使用所需访问权限再次登录。断开连接会使该连接不可用，直到重新连接为止。请查看 连接和管理集成 了解任何额外影响；不要认为断开连接会撤销之前的更改或取消已发送的工作。

1. 打开该服务的连接详情。如果它有自己的账户管理界面，请按照该集成的说明操作。
2. 在标准连接器详情页面中，准备好后选择 Disconnect，然后选择 Connect。不要假设断开连接前一定会有额外确认。
3. 选择目标账户并完成授权。查看所请求的权限。
4. 返回 Atoms 并确认已连接状态。
5. 在恢复原始任务之前，先执行下面的恢复检查。

如果相同错误再次出现，请停止重新连接，并将错误信息以及已完成的检查一并提交给支持。

验证问题已解决

1. 请求对一个你可以直接验证的资源执行一个受支持的只读操作。如果你使用 Try it out，请在发送前查看建议的提示词。
2. 将响应与服务本身进行比较。确认正确的资源、账户上下文和请求结果——而不仅仅是已连接指示。
3. 如果你的任务需要进行更改，请使用合适的测试资源或该服务记录的测试工作流，并在目标位置验证结果。

检查连接状态和所选资源。仅凭已连接指示并不能证明预期数据可用或是最新的。

确认组织和项目，然后打开 Dashboard 检查资源而不进行更改。断开连接不是此检查的一部分。

如果检查通过，请恢复你的任务。如果 Chat 可用，但该功能在你的应用内仍然失败，请参阅 连接和管理集成 或 构建和预览故障排查。检查故障发生的环境；Chat 请求成功并不能证明应用配置正确。

获取帮助

如果问题仍然存在，请使用 获取支持 并附上以下内容：

• 集成名称和你的 Atoms 账户邮箱。
• 受影响的项目或 Chat 链接，以及故障发生在 Chat 中还是你的应用中。对于应用，请说明受影响的环境。
• 目标服务账户和资源，仅使用调查所需的非机密标识符。
• 准确的错误信息、日期、时间和时区；如果知道，也请附上最后一次成功的时间。
• 复现步骤、预期结果、实际结果，以及已经尝试过的检查。
• 你的浏览器和设备，以及经过遮盖处理的截图或简短录屏（如有帮助）。

对于写入失败，请说明目标位置显示的是更改已完成、没有更改，还是结果未知。请从所有附件中移除密码、登录验证码、API 密钥、Token 以及无关的私人数据。