豆包智能体如何为外部API配置自定义鉴权Header？

功能定位：为什么需要自定义鉴权 Header

在豆包「智能体分身」里调用外部 API 时，目标服务往往要求请求头携带非标准字段，例如 X-Shop-Key、X-Access-Signature。官方「API 动作」模块允许用户把这类 Header 写死在请求模板里，但明文存储有泄露风险，也无法按会话动态刷新 Token。于是 v7.4.2 起新增「自定义鉴权 Header」能力：把密钥托管到豆包加密仓库，由智能体在真正发请求前才拼接，全程不入日志、不回传前端，兼顾安全与可维护性。

功能定位：为什么需要自定义鉴权 Header

前置检查：账号、版本与权限

1. 账号必须完成「企业或个人实名」，否则加密仓库不可见。
2. 客户端需 ≥ v7.4.2；若仍在 v7.3，只能看到旧版「静态 Header」入口，无法开启动态签名。
3. 分身 Bot 的「外部调用」开关默认关闭，需在「高级能力」里手动启用，并阅读《API 合规承诺函》。

最短操作路径（分平台）

桌面端 Windows/macOS

1. 打开豆包 → 右上角「工作台」→ 左侧「我的智能体」。
2. 选中目标分身 →「能力」标签页 →「API 动作」→「新增动作」。
3. 在「请求配置」区域，切换到「鉴权 Header」子标签 → 点击「添加自定义字段」。
4. 输入 Header 名称（如 X-Access-Signature），选择「加密仓库」→「新建密钥」。
5. 按向导填入密钥值，设定「轮换周期」→ 保存后返回，即可在动作模板里用 {{header_X-Access-Signature}} 占位。

移动端 Android / iOS

因屏幕限制，移动端把「鉴权 Header」收在「更多-高级」折叠面板；其余步骤与桌面一致。若找不到入口，请横屏或切换「专业模式」即可展开。

动态签名脚本：当密钥需要实时计算

部分接口要求「HmacSHA256(时间戳+body, 密钥)」。豆包提供「预请求脚本」入口，支持用 JavaScript 对原文进行摘要，再把结果写入 Header。示例：

const crypto = require('crypto');
const ts = Date.now();
const sign = crypto
  .createHmac('sha256', context.keys.shopSecret)
  .update(ts + JSON.stringify(context.body))
  .digest('hex');
context.headers['X-Sign'] = sign;
context.headers['X-Ts'] = ts;

脚本执行沙箱内置 crypto、Buffer，不支持网络 IO；若需拉取公钥，请改用「密钥轮换」+「加密仓库」方案。

例外与取舍：哪些场景不建议用

• 前端公开分身：若 Bot 被发布到抖音私信，客户端 JS 可被抓包，此时 Header 即使动态计算也会被逆向，建议把敏感接口迁入服务端中转。
• 高并发支付：加密仓库有 QPS 软限（经验性观察约 1 k/s），支付链路若峰值更高，应把签名字段下沉到自有网关，豆包侧仅做透传。
• 需要双向 TLS：豆包动作层暂不支持客户端证书，若上游强制 mTLS，请改用「中转函数」方案。

故障排查：签名总是 401

现象	可能原因	验证办法
401 Unauthorized	Header 名称大小写不一致	用抓包工具对比，确认上游区分大小写
签名过期	时间戳单位是秒而非毫秒	打印 context.headers['X-Ts'] 检查位数
间歇 403	加密仓库轮换瞬间，两个副本同时生效	在「密钥历史」里关闭「双活」开关

故障排查：签名总是 401

与飞书多维表对接示例

假设每天 08:00 把昨日 GMV 写入飞书多维表，表端已开启「API 写入」并给出 X-User-Key。步骤：

1. 在豆包加密仓库建立 feishu_key，值填入飞书开放平台提供的 user_access_token，轮换周期设为 24 h。
2. 在「API 动作」里填写 URL：https://open.feishu.cn/open-apis/bitable/v1/apps/xxx/tables/xxx/records
3. Header 模板：{{header_X-User-Key}}，Content-Type 固定 application/json。
4. Body 模板引用变量：{"fields": {"GMV": "{{yesterday_gmv}}"}}，其中 yesterday_gmv 由上游「抖音电商数据」插件注入。
5. 保存后，在「定时触发」里选 08:00，运行一次测试，返回 { "code": 0 } 即成功。

经验性观察：首次写入若字段类型不匹配（文本型写数字），飞书会返回 400，此时需在多维表手动改列属性，再回豆包点击「重置字段映射」。

监控与验收：如何确认 Header 注入成功

1. 在动作编辑页右上角「调试」打开，发送一次请求，豆包会回显实际发出的 HTTP 明文（密钥值脱敏为 ***）。
2. 若需端到端验证，可在自建网关打印完整 Header，对比 X-Sign 与本地计算值是否一致。
3. 建议把「鉴权失败」指标接入 Bot 的「运行监控」面板，阈值 > 5% 自动发邮件。

常见疑问（FAQ Schema）

最佳实践 6 条速查表

1. 永远用占位符，不要把密钥写死进 JSON。
2. Header 名务必与接口文档大小写保持一致。
3. 「调试」面板看到的 *** 不等于真实长度，切勿手动补星号。
4. 若上游要求 body 也参与签名，先在脚本区组装完再算摘要，避免空格差异。
5. 密钥轮换日选择在业务低峰，并提前 1 小时把新旧值都置为有效，防止冷切换。
6. 对外提供分身模板时，把密钥字段标为「用户必填」，避免共享泄露。

收尾：下一步行动

完成上述配置后，你的豆包智能体已具备「动态鉴权」能力，可安全调用各类外部 API。建议先用飞书多维表或内部测试网关做一轮灰度，验收通过后再切换到生产 URL。若后续需要 mTLS 或双向验签，可关注官方「中转函数」内测公告（截至当前的最新版本尚未发布）。