连接外部系统
连接是 MagicAI 用来集中管理外部系统凭据的模块。它解决一个问题：外部系统的账号、API Key、Webhook、Token 应该只配置一次，技能、工作流和数字员工都通过连接去访问，不要把凭据散落在节点、提示词、知识库或日志里。
什么时候需要配置连接
Section titled “什么时候需要配置连接”只要任务涉及外部系统，几乎都要先配连接：
| 场景 | 是否需要连接 |
|---|---|
| 把消息发到飞书 / 邮件 / 短信 | 是 |
| 调用业务系统 API（订单、风控、ERP） | 是 |
| 接 Webhook 回调到第三方 | 是 |
| 让 RPA 登录后台、调云数据库 | 是 |
| 让 AI 调用大模型服务（自定义 OpenAI 兼容地址） | 是 |
| 仅在桌面端做截图、点击、剪贴板操作 | 通常不需要 |
| 仅在 MagicAI 内部生成图片、视频、聊天 | 不需要 |
主流程：创建一个能被复用的连接
Section titled “主流程：创建一个能被复用的连接”步骤 1：进入连接并选择连接类型
Section titled “步骤 1：进入连接并选择连接类型”在左侧导航选 连接，点击 新建。先选好连接类型，常见有：
- HTTP / REST API：用于自定义业务接口。
- Webhook：用于接收回调或推送。
- 飞书 / 邮件 / IM 通知。
- 数据库（SQL / Zebra 等）。
- 大模型服务地址。
- 第三方平台账号（按需）。
成功标准：进入对应类型的配置表单。
步骤 2：填写凭据信息
Section titled “步骤 2：填写凭据信息”不同类型表单不同，常见字段：
- 名称：业务能看懂的名字，例如“运营飞书 通知群”，不要叫“conn1”。
- 描述：写清楚这个连接用来做什么、谁负责、是否生产。
- Endpoint / URL：例如
https://api.example.com/v1。 - 鉴权方式：API Key / Bearer Token / OAuth / Basic Auth。
- Header / Query / Body 模板：按平台要求填写。
- 超时与重试：默认值就好，必要时再改。
填写规则：
- 凭据填在“鉴权 / Secret”区域，不要写到名称、描述或自定义字段里。
- 同一个外部系统的生产 / 测试环境分开建两个连接，别共用。
- 对于 OAuth 类，按提示去对方平台授权，回到 MagicAI 完成回调。
步骤 3：点“测试连接”
Section titled “步骤 3：点“测试连接””不要等 RPA 或工作流跑起来才发现凭据错了。新建后先点 测试连接 / 发送测试请求：
- HTTP 类：发一次只读接口（例如
GET /me）。 - 通知类：往测试群 / 邮箱发一条 “这是 MagicAI 连接测试”。
- 数据库类：执行
SELECT 1。
成功标准：返回 200 / 测试消息真的收到。
步骤 4：管理可见范围与负责人
Section titled “步骤 4：管理可见范围与负责人”如果团队会一起用：
- 选择可见范围：仅自己 / 团队 / 工作空间。
- 指定负责人：凭据过期、失效、变更时由这个人维护。
- 开启变更审批（如果产品支持），生产连接尽量加审批。
步骤 5：在使用方引用这个连接
Section titled “步骤 5：在使用方引用这个连接”回到使用它的地方：
- 专业技能：在技能配置中选择刚刚的连接。
- 工作流自动化 / RPA：在 HTTP / 通知 / 数据库节点中选择该连接。
- AI 智能团队 / Agent Team：在数字员工或专家模板调用工具时引用。
成功标准：调用方看到的是“连接名”，没有再次填密码或 Token。
安全红线（一定要看）
Section titled “安全红线（一定要看）”- 不要把账号 / Token / Cookie 写进：节点说明、节点参数文本、提示词、知识库、日志、文档。
- 生产凭据不要发到群里、邮件里或截图里。
- 不要给个人账号开过大权限。一个连接只授权当前任务必需的范围。
- 轮换：定期更换 Token / 密码，旧凭据立刻在连接里替换。
- 离职 / 转岗：先把对应连接的负责人、凭据全部更新，再做后续动作。
让连接更稳的几个习惯
Section titled “让连接更稳的几个习惯”- 命名带环境。例如“CRM 测试 / API”“CRM 生产 / API”。
- 生产连接锁定权限，禁止个人账号随意编辑。
- 加超时和重试，避免下游卡住整条工作流。
- 统一回调 / Webhook 域名，方便集中维护防火墙。
- 每月例行测试一次，避免上线后才发现 Token 过期。
| 你遇到的情况 | 处理方式 |
|---|---|
| 没有创建连接的入口 | 检查账号是否有连接管理权限，必要时联系管理员 |
| 测试连接失败 401 / 403 | 鉴权方式或 Token 错；重新对照对方平台文档配置 |
| 测试连接失败 5xx 或超时 | 网络 / 内网穿透 / 防火墙问题；联系运维或对方平台 |
| 工作流报“连接不可用” | 进入连接重新测试；过期 Token 直接换新 |
| 不确定能不能放某个凭据进去 | 优先放进连接，不要放在文档、节点参数或日志里 |
- 配置完成后封装成技能：阅读 技能中心。
- 在工作流里引用：阅读 什么是工作流自动化（RPA）。
- 搭一条端到端浏览器流程：阅读 搭建浏览器 RPA 工作流。
- 让数字员工自动调用：阅读 AI 智能团队 / Agent Team。