你正在使用哪种体验？
这些文档同时覆盖两种体验。如果可以看到 Settings → Personal → My Okou，请按 My Okou 的步骤操作。如果你使用带有 New agent 的 Agents 页面，请按 Legacy Agents 的步骤操作。可用性可能因成员而异；这些文档不会改变你的体验。
无论哪种体验，你都可以同时运行多个聊天或任务，重复使用工作流，并与团队共享已审核的工作成果。运行时子代理只是执行工具，不是你需要创建的独立产品配置文件。
**设置差异：**My Okou 使用 设置 → 个人 → My Okou 中的个人 说明，以及工作区 工作流。下方任何要求你选择、创建或授权某个已命名 Agent 的步骤，都仅适用于 Legacy Agents。在 My Okou 中，请使用你自己的 聊天，并按照界面显示的账户和命名权限请求进行操作。共享的 工作流 不会共享凭据；自动化 会使用其所有者的上下文和访问权限。
自定义连接器允许组织管理员注册一个不在内置目录中的 HTTPS API，或在已启用的情况下注册一个 Streamable HTTP MCP 服务器。它定义网络边界和身份验证方式。它不会自动为智能体生成完整的 API 参考。
谁来配置什么
- 组织管理员 创建、编辑和删除连接器定义。
- 成员 连接自己的密钥，或完成连接器的 OAuth 流程。
- 授权和权限 控制 Okou 可通过该连接请求哪些命名操作。Legacy Agents 也使用特定于智能体的授权。
该定义在组织内共享。成员凭据仍仅限于该成员和组织范围。
HTTP API 连接器
- 打开 Connectors → Custom，然后选择 New connector。
- 选择 HTTP API 并输入显示名称。
- 添加一个或多个 HTTPS Prefixes，每行一个。请求必须先匹配已配置的前缀，连接器才能对其授权。
- 如果 API 需要身份验证，请添加：
- API authentication：输入标头名称和包含
{{secret}}的标头模板，例如Authorization和Bearer {{secret}}。 - OAuth 2.0：输入授权 URL、令牌 URL、客户端 ID、客户端密钥、作用域以及令牌端点身份验证方法。在提供商处注册表单中显示的准确重定向 URL。
- API authentication：输入标头名称和包含
- 创建连接器。随后，每个需要它的成员都选择 Connect，并提供自己的密钥或完成 OAuth。
- 审核并授权所需的命名权限。在 Legacy Agents 中，还要选择目标智能体。
更改现有的 OAuth 定义或其客户端凭据会断开当前的 OAuth 连接。成员必须在更改后重新连接。
MCP 连接器
如果你的工作区中 MCP 显示为一种连接器类型，请输入一个 HTTPS Streamable HTTP MCP 端点，并在同一表单中配置 API 或 OAuth 身份验证。如果选择器中没有提供 MCP，则表示该工作区未启用此功能。
教会智能体使用该 API 流程
自定义连接器提供安全的网络访问和凭据注入。创建表单不会上传或自动发现 OpenAPI 文档。请在请求中向智能体提供端点、方法、参数和预期响应，或者在一个附带 API 参考文件的 工作流 中记录该流程。
使用一个窄范围、只读的请求对已知端点验证新连接器。没有通用的 Test connection 请求，因为许多 API 并未暴露有意义的根端点。
安全边界
- 仅接受 HTTPS 前缀和 MCP 端点。
- 防火墙只会将已保存的凭据注入到匹配的请求中。
- 保存的密钥在静态存储时已加密，并不会作为环境变量暴露给 agent。
- 不要在聊天消息、工作流说明或附件文件中放入密钥、令牌或客户端密钥。
- 使用所需上游作用域最小的服务凭据，以满足工作流需要。
故障排查
| 问题 | 检查 |
|---|---|
| New connector 不可用 | 只有组织管理员可以创建或编辑连接器定义。 |
| 智能体看不到连接器 | 为当前成员连接该连接器，并检查所需权限。在 Legacy Agents 中，还要授权目标智能体。 |
| 请求在到达 API 之前被阻止 | 确认请求 URL 以已配置的 HTTPS 前缀之一开头。 |
| API 返回 401 或 403 | 重新连接成员凭据，并验证上游密钥或 OAuth 作用域。 |
| OAuth 返回重定向错误 | 注册连接器表单中显示的准确重定向 URL，并验证授权 URL 和令牌 URL。 |
| 智能体猜错了端点或负载 | 将 API 流程放入工作流，并附上相关参考文件，而不要只依赖连接器名称。 |
