豆包智能体API调用日志如何查看并导出报错记录？
功能定位：为什么需要单独看 API 日志
豆包智能体分身允许用户把零代码 Bot 以 API 形式暴露给外部系统，但云端并发、插件异常或参数超限都会触发 4xx/5xx。不同于聊天历史，API 调用日志记录了每次请求的 Request-ID、耗时、插件链路及返回值，是定位“用户反馈 Bot 无响应”或“账单突增”时的第一现场。2026-03 月起，控制台把「API 日志」从「分身管理-分析」子页独立为一级入口，并新增「错误聚合」视图，方便一次性拉取报错记录。
功能定位：为什么需要单独看 API 日志
入口速查：三端最短路径对照
桌面端（Win / macOS）
- 打开豆包 PC 客户端，左侧「我的分身」→ 选中目标 Bot 右上角「⋯」→「API 管理」→「调用日志」。
- 顶部即出现「日志」与「错误」双标签，默认展示近 24 h。
Web 控制台
直接登录 bot.doubao.com →「智能体」→ 点击 Bot 卡片 →「统计」→「API 日志」；若未看到该菜单，请检查账号是否具备「开发者权限」（需主账号在「设置-成员管理」里勾选）。
移动端（Android / iOS）
App 暂不支持完整日志视图，只能收到「异常告警」推送。如需深度排查，请使用「分享到 PC 打开」按钮，自动携带登录态跳转到 Web 控制台。
筛选语法：如何一次性圈出报错记录
控制台顶部提供「快捷筛选」与「高级语句」两种模式。
- 快捷：点「状态」下拉 → 勾选 4xx / 5xx → 时间范围选「自定义」→ 最大可回溯 30 天（经验性观察：超过 30 天数据会被转冷存，查询延迟升至数十秒）。
- 高级：输入
statusCode >= 400 AND plugin = "Notion"即可把 Notion 插件产生的所有报错单独列出；支持 AND、OR、NOT 及括号，字段名区分大小写。
提示：如果 Bot 启用了「自动重试」，原始失败与重试成功会生成两条日志。可在筛选里加 retry = false 只看首次失败，避免重复计数。
批量导出：控制台下载与自动化回捞
页面下载（≤1 万行）
在筛选结果页点击右上角「导出」→ 选「CSV（UTF-8）」或「JSON」→ 二次确认后即开始打包；文件会临时存放在「个人中心-下载管理」7 天，重复导出同一条件不会重复计费。
自动化回捞（>1 万行或例行巡检）
控制台提供「日志回捞任务」API（需单独申请 AK/SK）：POST /v2/bot/logExport，字段包括 botId、start、end、filter、format；任务完成后回调返回下载 URL，有效期 2 h。经验性观察：单次任务最多 100 万行，超出需分段提交。
警告：回捞任务按「扫描行数」计费，价格随存储层级浮动；建议在筛选条件里尽可能缩小时间窗口，并在非高峰（00:00–06:00 UTC+8）提交，避免排队。
字段释义：快速读懂 CSV 列
| 列名 | 示例值 | 说明 |
|---|---|---|
| requestId | c77d9f8a… | 全局唯一，可在 Bot 代码里打印到 response header，方便用户自助排障。 |
| statusCode | 429 | HTTP 状态；豆包业务码在 responseBody 的 code 字段。 |
| duration | 1208 | 毫秒级耗时，含插件链路；若 >3 s 会被标记慢查询。 |
| pluginChain | ["Notion", "Jira"] | 按调用顺序记录，可用于定位哪一步失败。 |
| retryCount | 2 | 自动重试次数，达到 3 次仍失败则写入「错误聚合」。 |
典型场景：用导出的报错记录做三件事
1. 聚合统计——快速发现「高频插件」
把 CSV 拖到 Excel → 插入透视表 → 行字段选 pluginChain，值字段选 requestId（计数）；经验性观察：约 70% 的 4xx 集中在「飞书多维表」插件，原因是 token 过期未刷新。可在插件配置里打开「自动续租」开关，把失败率从可见高位降到个位数。
2. 关联追踪——把 requestId 回写到自己的后台
如果你的前端也打印了 requestId，当用户投诉「Bot 返回空白」时，可直接在导出的日志里筛选，确认是插件超时还是参数非法，避免反复询问用户复现步骤。
2. 关联追踪——把 requestId 回写到自己的后台
3. 合规留档——敏感行业需留存 6 个月日志
金融客户可在回捞任务里选「Parquet + 加密」格式，下载后上传至自有 OSS；豆包侧 30 天后冷存，但加密文件落入客户桶即满足合规，且不再产生额外计费。
例外与边界：四种情况导不出记录
- Bot 已删除：日志保留 7 天，之后物理清理，无法回捞。
- 子账号无「开发者权限」：只能看到「用量曲线」，无法进入「API 日志」页；需主账号在「组织-权限模板」里勾选「查看日志」。
- 筛选结果 >100 万行：页面导出按钮置灰，必须改用回捞任务分段。
- 回调地址为内网：回捞任务完成后，下载 URL 仅在外网有效，内网服务器需通过 NAT 或代理拉取。
验证与回退：确保下载文件完整
控制台会在导出完成时返回 SHA-256 校验值；可用命令行 sha256sum export.csv 比对，防止因网络中断造成文件截断。若校验失败，可在「下载管理」点击「重新生成」，系统会复用原任务缓存，无需再次计费。
故障排查：最常见的三条报错
| 现象 | 可能原因 | 验证/处置 |
|---|---|---|
| 导出按钮灰色 | 结果 >1 万行且未通过高级认证 | 申请 AK/SK 后改用回捞任务。 |
| CSV 中文乱码 | Excel 默认用 ANSI 打开 | 用「数据-自文本」指定 UTF-8。 |
| 回捞任务状态「排队中」>2 h | 整点批量任务高峰 | 取消后于 00:00-06:00 重新提交。 |
适用/不适用场景清单
- 适用：日调用 >1 k 次、插件链路 ≥2 级、需向审计部门提供原始日志的企业 Bot。
- 不适用：仅内部测试、调用量 <100 次/日，且无需留存证明的临时分身；此时用「聊天历史」足矣。
最佳实践 5 条（检查表）
- 在 Bot 代码里始终返回自定义 requestId，方便后续关联。
- 每周一定期导出上周 5xx，建立内部 SLA 看板。
- 为高频插件打开「自动续租」与「超时重试」，减少 4xx。
- 回捞任务使用 Parquet 格式，节省 60% 存储空间。
- 删除 Bot 前先用「日志归档」任务把近 30 天数据拉到本地，避免 7 天后不可恢复。
FAQ：豆包 API 日志导出常见疑问
回捞任务收费规则？
按扫描行数阶梯计价，冷存数据单价高于热存；每日 00:00–06:00 提交可享 7 折排队优先。
能否只导出字段的一部分？
目前不支持列裁剪，导出后可在本地脚本里删除无关字段；官方已列入需求池，尚无明确排期。
日志会保存多久？
热存 30 天，冷存 180 天；Bot 删除后热存缩短为 7 天，冷存立即清空。
收尾：下一步行动
豆包智能体API调用日志查看与导出报错记录的核心价值，是让你把「用户抱怨」翻译成「可观测指标」。读完本文，建议你立即打开控制台，用「statusCode >= 400」跑一遍近 7 天数据，确认插件失败率是否高于 1%；若超出，先打开「自动续租」与「超时重试」，再安排每周一回捞任务，把日志拉进内部 BI。坚持四周，你会发现外部投诉量可见下降，同时账单也不再出现「突增」惊吓。