Composio Browser Tool 在 Zero Data Retention 项目中的兼容性问题与解决方案
Composio Browser Tool 在 Zero Data Retention 项目中的兼容性问题与解决方案
Browser Tool 是 Composio 平台中依赖持久浏览器配置(persistent browser profiles)来维持会话状态的工具,它天然要求执行日志与状态数据得以保留,因此与开启了 Zero Data Retention(ZDR,零数据保留)或"移除执行数据"策略的项目不兼容。本文将基于 Composio 官方支持知识库,解释这一限制的成因、ZDR 日志存储机制的工作原理,并给出 Dashboard 与 API 两种完整的修复方案,帮助你在合规约束下正确部署 Browser Tool。
本文以 docs/kb/source/toolkits/browser_tool/public.md 为骨架展开,仓库中对应指南版本见 docs/content/kb/guide/toolkits-browser-tool.mdx,同主题文章见 docs/kb/articles/toolkits-browser-tool.md。
问题概述:Browser Tool 为什么依赖持久配置
Browser Tool 的核心工作方式是:通过持续存在的浏览器配置文件(browser profile)保存登录态、Cookie、本地存储与会话信息,从而让同一"浏览器实例"跨多次工具调用保持上下文连续性。这是它区别于无状态工具的关键设计——一旦配置文件或相关状态被清除,浏览器会话就会中断,后续调用将丢失登录态。
因此,Browser Tool 对项目的日志与数据保留策略有硬性要求:项目必须允许存储执行数据,Browser Tool 才能正常工作。
Zero Data Retention(ZDR)项目为什么会破坏 Browser Tool
ZDR(Zero Data Retention)是对应于"零数据保留"策略的项目配置,其核心是不存储工具调用的请求参数(request arguments)与响应数据(response data)。这一策略通过项目的 Log storage(日志存储) 设置实现:
- Store all logs(默认):Composio 在审计日志中完整保存每次工具调用的请求与响应 payload。
- Don't store data:Composio 不存储工具调用的请求参数与响应数据,只保留审计记录——即"哪个工具在何时运行、是否成功、相关 ID 与耗时"等元数据。
从 docs/content/docs/security/data-retention.mdx 可以看到,该设置对应的就是关联文档中提到的"移除执行数据"(removal of execution data)策略。当项目处于该模式下,Browser Tool 所需的浏览器配置与会话状态会被视为"执行数据"而不予保留,导致工具无法维持会话,行为不符合预期。
需要注意,该设置并不移除 user_id 等审计元数据。正如 docs/content/kb/guide/dashboard-log-storage.mdx 所说明的:"Don't store data" 只会移除新日志行的 payload 内容,新的工具执行仍然会出现在 Tool Logs 中,并带有工具名、状态、时间戳、耗时及相关标识符等审计信息。
解决方案一:将 Browser Tool 迁移到未启用 ZDR 的项目
最简单的做法是将 Browser Tool 的使用迁移到一个未启用 ZDR(即采用默认 "Store all logs" 策略)的项目中:
- 在 Composio Dashboard 中创建一个新项目,或选择一个未开启 "Don't store data" 的项目;
- 保持该项目的日志存储设置为 Store all logs(默认值);
- 将涉及 Browser Tool 的 Agent 应用与连接切换到该项目。
这样做不需要改动任何 API 配置,适合 Browser Tool 与其他工具并存、且整体日志存储策略可以放宽的场景。
解决方案二:通过 Project Settings 调整日志存储配置
如果出于合规、审计或其他原因,你希望在现有项目中继续使用 Browser Tool,可以修改项目的日志/数据可见性设置,从"移除执行数据"改为"存储/展示所有日志"(在策略允许的前提下)。
通过 Dashboard 修改
在 Dashboard 中按以下路径操作:
- 进入 Project Settings(项目设置);
- 打开 Log storage configuration(日志存储配置)选项;
- 将设置从 "Don't store data" 切换为 Store all logs。
该设置位于 "Project Settings / Log storage configuration",即 docs/content/docs/security/data-retention.mdx 中描述的 Settings → General → Log storage 配置区域。
通过 API 修改
关联文档明确指出对应的 API 设置为 log_visibility_setting: show_all。该字段在项目配置接口(PATCH /api/v3/org/project/config)中维护。仓库 docs/content/changelog/01-08-26-mcp-api-key-enforcement.mdx 展示了包含该字段的完整项目配置响应示例:
{
"require_mcp_api_key": true,
"is_2FA_enabled": true,
"mask_secret_keys_in_connected_account": true,
"log_visibility_setting": "show_all"
}
其中 log_visibility_setting 即日志可见性设置,取值为 show_all 时表示存储并展示所有日志(与 Dashboard 的 "Store all logs" 对应)。参考该变更日志中的调用方式,可通过如下请求调整设置(请将示例中的 API 地址与密钥替换为你的实际项目环境):
curl -X PATCH "https://backend.composio.dev/api/v3/org/project/config" \
-H "Content-Type: application/json" \
-H "x-api-key: ak_your_api_key" \
-d '{"log_visibility_setting": "show_all"}'
调整完成后,Browser Tool 的持久浏览器配置文件即可被正常保存与复用,会话状态得以维持。
重要注意事项:设置变更只影响新调用
在切换日志存储策略时,需要注意以下几点(依据 docs/content/docs/security/data-retention.mdx 与 docs/content/kb/guide/dashboard-log-storage.mdx):
- 切换是向前生效的:选择 "Don't store data" 会停止为新调用存储 payload,但不会删除已存储的旧日志;已有日志会在一年保留期结束后自动过期删除(工具执行与触发器事件日志默认保留至多一年)。
- 恢复 "Store all logs" 不会回填:切换回存储模式后,只会从切换时刻起存储新 payload,期间未存储的调用数据无法事后恢复。
- 审计行仍然存在:即使开启 "Don't store data",新的工具执行仍会以审计元数据的形式出现在 Tool Logs 中。
- 验证方式:修改设置后,运行一次新的工具调用并检查对应日志行。如果新请求/响应内容仍不可见,说明设置尚未生效,需要确认项目是否正确应用了变更。
合规边界与更严格的零数据保留需求
从 docs/content/kb/guide/platform-compliance-data-handling.mdx 可以确认:标准套餐不保证端到端的零数据保留或零训练。每项目的 "Don't store data" 设置只是减少了 Composio 的存储内容,并不约束第三方提供商对数据的保留与处理。
如果你的组织需要合同级的零数据保留(contractual zero-data-retention)、无训练条款、DPA 或安全审查条款,这些属于 Enterprise 定制范畴(详见 docs/content/kb/guide/platform-routing.mdx)。换句话说:
- 需求仅是"日常降低数据存储" → 使用项目级 "Don't store data" 或
log_visibility_setting设置即可,但需接受 Browser Tool 在此类项目中的兼容性限制; - 需求是"合同保证的零保留/合规条款" → 应通过 Enterprise 通道显式约定,而不是依赖项目级设置;
- 需要 Browser Tool 正常工作 → 项目必须采用存储/展示全部日志的策略(
log_visibility_setting: show_all)。
总结
| 场景 | 推荐做法 |
|---|---|
| 需要在 ZDR 项目中使用 Browser Tool | 将 Browser Tool 迁移到未启用 ZDR 的项目 |
| 想在现有项目继续使用 Browser Tool | 在 Project Settings / Log storage configuration 中改为 Store all logs,或通过 API 设置 log_visibility_setting: show_all |
| 需要合同级零数据保留条款 | 走 Enterprise 通道约定,而不是依赖项目级日志设置 |
Browser Tool 与 Zero Data Retention 的冲突本质上是"持久会话状态"与"不留存执行数据"两种策略的天然矛盾。理解 log_visibility_setting 与日志保留机制的细节,能帮助你在满足合规要求的同时,正确规划 Browser Tool 的部署位置与日志策略。