工作区密钥
让 token 和机密 URL 远离决策——以 {{secrets.NAME}} 引用的工作区密钥、谁可以管理它们、它们如何存储和遮蔽,以及更改何时生效。
API token、密码和机密 URL(例如 Slack 或 n8n 的 webhook URL)不应该放在决策里:schema 带有版本、会显示在编辑器中,并随每次部署一起存储。请把它们保存在工作区密钥(secrets)中,并按名称引用。
添加密钥
在 设置 → 目的地 → 密钥 中输入名称和值,然后点击添加密钥(对于已存在的名称则点击替换)。
- 名称使用 UPPER_SNAKE_CASE:以大写字母开头,之后是大写字母、数字和
_,最多 64 个字符——CRM_TOKEN、SLACK_WEBHOOK。 - 值为 1 到 4,096 个字符,且只写:保存后,应用只显示名称、最后 4 个字符(仅对管理员)和修改时间——从不显示值。
- 一个工作区最多保存 50 个密钥。
使用密钥
在目的地需要的地方写入 {{secrets.NAME}}:
| 位置 | 示例 |
|---|---|
| 请求头的值 | Authorization: Bearer {{secrets.CRM_TOKEN}} |
| 完整 URL | 将 {{secrets.SLACK_WEBHOOK}} 作为 API 请求或 webhook 的 URL |
http 请求体 | {"api_key": {{secrets.MAILER_KEY}}} |
密钥可以作为 URL 的开头——即整个 URL——或请求头、请求体的一部分。密钥不能用于固定回复、LLM 提示词和输入,或智能体指令:这些文本会返回给调用方或发送给模型。
谁可以做什么
| 查看者 | 成员 | 管理员 | 所有者 | |
|---|---|---|---|---|
| 查看密钥名称(用于编写模板) | — | ✓ | ✓ | ✓ |
| 查看最后 4 个字符 | — | — | ✓ | ✓ |
| 添加、替换和删除密钥 | — | — | ✓ | ✓ |
| 显示和轮换签名密钥 | — | — | ✓ | ✓ |
它们如何受到保护
- 使用 AES-256-GCM 静态加密。值永远不会离开 API,除非是在它们被渲染进的那个请求中。
- 从不出现在决策 schema、API 响应、执行日志或 Playground 中:预览会在其位置显示
••••,投递日志只保留每个请求经过遮蔽的预览——方法、URL、请求头和请求体大小。 - 在投递仍可能需要时,带有密钥的完整请求会被加密存储——参见投递与重试。
更改何时生效
密钥在决策运行时读取:Dcision 用当前值渲染请求,并将其加密存储,供各次尝试使用。
- 新值或更改后的值从下一次运行开始生效。已在队列中的投递——及其重试——保留渲染时的请求。
- 引用了不存在密钥的目的地会立即投递失败,并提示 "Set the secret CRM_TOKEN in Settings → Destinations, then resend."——不会发送任何内容。由于请求是在没有该密钥的情况下渲染的,请添加密钥并重新运行决策:重新发送那次投递会以同样的方式失败。处于
sync模式的智能体会返回"status": "failed"并给出同样的建议。 - 删除密钥后,使用它的目的地会一直失败,直到重新设置它。
签名密钥
除了这些密钥之外,每个工作区还有一个签名密钥(whsec_…),用于为其所有投递签名。管理员和所有者可以在 设置 → 目的地 → 签名密钥 中显示和轮换它——参见验证签名和轮换签名密钥。