Composio Browser Tool 在 Zero Data Retention 项目中的兼容性问题与解决方案

原创2026-09-09 21:29:101,874 阅读
文章标签:人工智能AI Agent工具调用MCP 服务认证鉴权CLIAI 技能Agent 沙箱

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" 策略)的项目中:

  1. 在 Composio Dashboard 中创建一个新项目,或选择一个未开启 "Don't store data" 的项目;
  2. 保持该项目的日志存储设置为 Store all logs(默认值);
  3. 将涉及 Browser Tool 的 Agent 应用与连接切换到该项目。

这样做不需要改动任何 API 配置,适合 Browser Tool 与其他工具并存、且整体日志存储策略可以放宽的场景。

解决方案二:通过 Project Settings 调整日志存储配置

如果出于合规、审计或其他原因,你希望在现有项目中继续使用 Browser Tool,可以修改项目的日志/数据可见性设置,从"移除执行数据"改为"存储/展示所有日志"(在策略允许的前提下)。

通过 Dashboard 修改

在 Dashboard 中按以下路径操作:

  1. 进入 Project Settings(项目设置);
  2. 打开 Log storage configuration(日志存储配置)选项;
  3. 将设置从 "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 的部署位置与日志策略。

登录后查看全文
composio