API 密钥
创建、绑定、停用 API 密钥，并弄清作用域与速率限制的真实生效范围
API 密钥用于在没有用户登录会话的场景调用 Clouisle。每个密钥以其创建者用户的身份认证，因此所有者的角色权限、团队成员关系都会作用在该密钥的每次请求上；密钥本身还能额外收窄到指定 Agent 或工作流。
前置条件：你的角色需要具备 API 密钥的查看与创建权限（超级管理员默认具备全部权限）。密钥只能绑定到你本人有权访问的 Agent 与工作流，否则创建或保存会被拒绝。完整权限清单见权限与角色参考。
访问 API 密钥
- 点击右上角个人资料图标。
- 在用户菜单中选择 API 密钥。
- 或直接访问
/app/api-keys。
列表每行显示：名称、状态徽章（活跃 / 已禁用 / 已过期）、密钥前缀（完整密钥的前 12 个字符）、速率限制、过期时间、上次使用时间与创建时间。页面顶部只有一个搜索框，按名称或前缀即时过滤。
可见范围由角色决定：只有超级管理员能看到并管理全部用户的密钥，其他用户只能看到自己的密钥；编辑或删除他人的密钥会被拒绝。
创建密钥
/app/api-keys），点击 创建密钥。
| 字段 | 必填 | 说明 |
|---|---|---|
| 名称 | 是 | 描述性名称，1–100 字符 |
| 速率限制 | 否 | 每分钟请求数，0 表示无限制。表单初始值为 0，见速率限制 |
| 过期时间 | 否 | 日期选择器；留空表示永不过期 |
| 允许访问的智能体 | 否 | 勾选列表，只列出已发布的 Agent，最多加载 100 个；留空 = 允许访问全部 |
| 允许访问的工作流 | 否 | 勾选列表，只列出已发布的工作流，最多加载 100 个；留空 = 允许访问全部 |
### 保存并复制密钥 | ||
| 点击 创建（编辑时为 保存）。创建成功后弹出 API 密钥已创建 对话框，完整密钥只在此时出现一次，点击复制按钮保存到密码管理器或环境变量。 |
完整密钥只显示一次。列表与详情只显示前缀（前 12 个字符），服务端也只保存不可逆的哈希，无法找回。密钥丢失只能新建。
作用域在界面上不可设置，从界面创建的密钥一律使用默认作用域；详见作用域。
编辑密钥
在列表行菜单点击编辑密钥打开对话框，可修改名称、速率限制、过期时间、活跃开关与 Agent / 工作流绑定。把绑定清空（不勾选任何项）表示放开为“全部可访问”。
编辑和删除需要所有者的身份（或超级管理员）；密钥内容（那串字符）无法修改，也没有轮换功能——轮换的做法是新建密钥、迁移调用、再停用旧密钥。
过期时间由日期选择器提交为当天 00:00:00（UTC）。选择 2026-01-01 意味着密钥在 2026-01-01 零点（UTC）起失效，而不是当天结束。
停用 / 重新激活密钥
停用会立即让密钥认证失败，但保留记录与审计历史：在列表行的 ... 菜单选择 禁用 即可停用，选择 激活 恢复使用。重复操作会提示该密钥已禁用或已激活。
删除密钥
在列表行执行删除并确认即可永久删除记录，无需先停用，且不可恢复。删除前会写入审计日志，因此事后仍能查到操作人、时间与被删密钥的前缀。
使用 API 密钥
把完整密钥放进调用方的 Authorization 头，格式与登录令牌相同：
Authorization: Bearer clou_your_api_key_here具体的请求与响应格式见 API Keys API。
认证与生效条件
密钥必须同时满足以下条件，否则调用会被拒绝（认证失败或权限不足）：
- 密钥存在且正确——拼错或有字符缺失都会失败。
- 处于启用状态——停用的密钥等同于不存在。
- 未过期——未设置过期时间表示永不过期。
- 所有者账号仍然有效——所有者被停用或处于待审批状态时，密钥一并失效。
- 绑定范围允许本次调用——绑定过 Agent 时只能调用这些 Agent；绑定过工作流时只能触发这些工作流。绑定为空表示不限制。
每次成功调用都会刷新列表中的上次使用时间，这也是排查“密钥是否还在被调用”的依据。
绑定范围真正生效的位置是调用入口：Agent 会话、iframe 嵌入（Agent 与工作流运行），以及工作流 Webhook 触发（该入口只接受 API 密钥，且要求工作流已发布并启用 Webhook 触发器）。
作用域
作用域是一组被记录下来的标签，当前不参与权限判定：
- 界面上没有该字段，从界面创建的密钥固定使用默认作用域。
- 通过管理接口写入的作用域也不做枚举校验，没有通配符语义。
- 更新时是整体替换，不存在“只增不减”规则。
不要用作用域做访问控制。真正决定权限的是密钥所有者的角色权限、团队成员关系，以及密钥的 Agent / 工作流绑定。
速率限制
速率限制按密钥保存“每分钟请求数”，0 表示无限制。
当前版本没有强制执行它：调用链路中没有任何限速逻辑，界面上看到的 1000/min 或无限制只是展示值。
另外有一个容易误判的默认值差异：服务端默认值是 1000，但创建表单的初始值是 0（无限制）。由于表单总会提交该字段，从界面创建的密钥实际是无限速，而不是 1000。
需要真正的调用约束时，请使用密钥绑定（收窄可调用的 Agent / 工作流）、过期时间与角色权限，或在上游网关自行限速。
过期提醒
系统每天 09:00 检查一次密钥到期情况，并向密钥所有者发送站内通知：
- 即将过期：启用中、未过期、且剩余
7天内的密钥；只在剩余天数正好为 7 / 3 / 1 天时发送，避免每天重复提醒。 - 已过期：启用中、且在过去 24 小时内刚过期的密钥。
通知不会改变密钥状态——过期密钥仍保持“启用”标记，只是认证时被过期时间拦下。若在过期前把密钥停用，就不会再收到过期通知。
最佳实践
✅ 推荐
- 按用途单独建密钥（生产、CI、某合作伙伴各一把），便于单独停用。
- 设置过期时间，把长期密钥换成有期限的密钥。
- 把密钥绑定到实际需要调用的 Agent / 工作流。
- 存放在密钥管理器或环境变量中，不要写进代码仓库。
- 定期按“上次使用时间”清理长期未使用的密钥。
❌ 避免
- 用一个人的密钥承载多个人的调用（权限会跟着这个人变）。
- 把密钥放进前端代码、浏览器插件或公开文档。
- 依赖作用域或速率限制做安全边界。
故障排除
密钥无法使用（认证失败）
- 确认密钥处于活跃状态：停用的密钥等同于不存在。
- 检查是否已过过期时间。
- 检查请求头格式：
Bearer clou_...，中间不要有换行或多余空格。 - 在列表里核对密钥前缀（前 12 个字符）是否与手上的密钥一致，避免拿错环境。
- 若完整密钥已丢失——只能新建，无法找回。
密钥有效但请求被拒绝（权限不足）
- 密钥可能绑定了 Agent / 工作流：确认目标资源在绑定列表内，或清空绑定后再试。
- 密钥所有者的角色权限可能不足：切换到所有者视角验证同一操作是否被允许。
- 所有者账号可能已停用或处于待审批状态，此时密钥一并失效。
列表里看不到别人的密钥
只有超级管理员能看到全部密钥；其他用户无论具备什么权限，都只能看到自己的密钥。
密钥疑似泄露
- 立即在列表里停用（比删除更快、且保留审计记录）。
- 新建密钥、更新调用方，确认旧密钥无流量后再删除。
- 在审计日志中核对创建/更新/删除与后续调用情况。
相关文档
- API Keys API — 端点、请求体、响应字段与错误码
- API 密钥参考 — 字段与默认值速查
- 智能体管理 — Agent 的发布状态决定能否被绑定
- 工作流编排 — 工作流发布与 Webhook 触发
- 审计日志 — 密钥操作的审计记录
这篇文章对你有帮助吗？