Agent/examples/research/TROUBLESHOOTING.md

故障排除指南

Cookie 文件相关问题

问题：提示"没有 Cookie 文件"或"Cookie 目录不存在"

原因

这不是云浏览器特有的问题，而是首次使用时的正常情况：

1. Agent 在执行某些任务时可能会尝试加载之前保存的 Cookie（用于保持登录态）
2. 如果这是第一次运行，.cache/.cookies 目录不存在或没有对应的 Cookie 文件
3. 工具会给出友好提示，并自动导航到目标页面

解决方案

方案 1：让 Agent 自动处理（推荐）

从 v2.0 开始，browser_load_cookies 工具已经优化：

• 找不到 Cookie 时会自动导航到目标页面
• Agent 可以继续执行任务，不会中断
• 你可以手动登录后，Agent 会继续后续操作

方案 2：预先保存 Cookie

如果你需要频繁访问需要登录的网站：

1. 首次运行时手动登录
2. 在终端按 [Enter] 暂停 Agent
3. 在浏览器中完成登录
4. 让 Agent 继续，它会自动调用 browser_export_cookies 保存 Cookie
5. 下次运行时会自动加载 Cookie，无需重复登录

方案 3：手动保存 Cookie

# 1. 启动浏览器并访问目标网站
# 2. 手动登录
# 3. 在 Python 中执行：

from agent.tools.builtin.browser.baseClass import browser_export_cookies

# 保存当前页面的 Cookie
await browser_export_cookies(name="example.com")

# Cookie 会保存到 .cache/.cookies/example.com.json

问题：云浏览器和本地浏览器的 Cookie 是否共享？

是的，Cookie 文件存储在本地文件系统（.cache/.cookies/），与浏览器类型无关：

• 云浏览器保存的 Cookie 可以在本地浏览器中使用
• 本地浏览器保存的 Cookie 可以在云浏览器中使用
• 切换浏览器模式不会丢失已保存的 Cookie

Cookie 文件位置

项目根目录/
  └── .cache/
      └── .cookies/
          ├── example.com.json
          ├── github.com.json
          └── ...

Cookie 文件格式

Cookie 文件使用 JSON 格式，符合 Chrome DevTools Protocol (CDP) 规范：

[
  {
    "name": "session_id",
    "value": "abc123...",
    "domain": ".example.com",
    "path": "/",
    "expires": 1234567890,
    "httpOnly": true,
    "secure": true
  }
]

云浏览器特定问题

问题：云浏览器连接失败

可能原因

1. browser-use 云服务未配置
2. API 密钥错误或过期
3. 网络连接问题
4. 云服务配额用尽

解决方案

1. 检查配置 ```bash

   查看 .env 文件

   cat .env

# 确认包含必要的配置（如果需要） # BROWSER_USE_API_KEY=your_key_here

2. **切换到本地浏览器**
   ```python
   # 编辑 run.py
   BROWSER_TYPE = "local"  # 改为 local

1. 查看详细日志

   # 在 run.py 中启用调试日志
   logging.basicConfig(level=logging.DEBUG)
   

   问题：云浏览器速度慢

   原因

   • 网络延迟
   • 云服务器负载高
   • 需要传输大量数据（如图片、视频）

   解决方案

   1. 使用本地浏览器（如果可以） python BROWSER_TYPE = "local"

2. 启用无头模式（减少渲染开销）

   HEADLESS = True
   

   1. 优化任务
   2. 减少不必要的页面导航
   3. 使用 API 代替浏览器操作（如果可能）

   其他常见问题

   问题：Agent 卡住不动

   可能原因

   1. 等待页面加载超时
   2. 等待元素出现超时
   3. 网络请求阻塞

   解决方案

   1. 手动接管
   2. 按 [Enter] 键暂停 Agent
   3. 检查浏览器状态

   4. 手动完成操作后继续

   5. 调整超时设置

      # 在 test.prompt 中添加
      [system]
      如果页面加载超过 30 秒，请跳过并继续下一步
      

问题：浏览器进程未正确关闭

解决方案

# Windows
taskkill /F /IM chrome.exe

# Linux/Mac
pkill -9 chrome

或者在代码中确保清理：

from agent.tools.builtin.browser.baseClass import kill_browser_session

# 在 finally 块中调用
await kill_browser_session()

获取帮助

如果以上方案都无法解决问题：

1. 查看完整日志输出
2. 检查 .trace/ 目录中的 trace 数据
3. 在 GitHub 提交 issue：https://github.com/anthropics/claude-code/issues