> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bubench.lexmount.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> 基于 Claude Code CLI 与 Playwright MCP 的浏览器自动化 Agent

Claude Code 是 Anthropic 官方的 Claude CLI 工具。配置 Playwright MCP 服务器后，它可以操控真实浏览器完成 Web 任务，并通过 browseruse-bench 以非交互模式（`-p`）进行基准测试。

## 工作原理

与基于 SDK 的 Agent 不同，Claude Code 以**外部子进程**方式运行：

```
bubench → claude -p "<任务>" --output-format stream-json → Playwright MCP → 浏览器
```

Agent 从 Claude Code 进程流式读取 JSON 事件，从 `browser_take_screenshot` 工具结果中提取截图，并将结构化日志写入 `api_logs/`。

## 前置条件

**1. 安装 Claude Code**

```bash theme={null}
npm install -g @anthropic-ai/claude-code
```

**2. 登录认证**

```bash theme={null}
claude auth login
```

**3. 添加 Playwright MCP（用户级别）**

使用 user scope，确保 Claude Code 在作为子进程调用时、无论工作目录在哪都能加载 MCP 服务器：

```bash theme={null}
claude mcp add playwright --scope user -- npx @playwright/mcp@latest
```

验证服务器已连接：

```bash theme={null}
claude mcp list
# playwright: npx @playwright/mcp@latest - ✓ Connected
```

## 配置

在根目录 `config.yaml` 的 `agents.claude-code` 下配置：

```yaml theme={null}
agents:
  claude-code:
    active_model: sonnet        # 当前使用的模型配置名
    models:
      sonnet:
        model_id: claude-sonnet-4-6
        api_key: $ANTHROPIC_API_KEY
      opus:
        model_id: claude-opus-4-6
        api_key: $ANTHROPIC_API_KEY
    defaults:
      max_turns: 50
      timeout: 300
      allowed_tools: "mcp__playwright*"
```

将 `active_model` 设置为默认使用的模型配置名，也可在运行时切换：

```bash theme={null}
bubench run --agent claude-code --data LexBench-Browser --model opus
```

### 配置参数说明

| 参数                       | 说明                          | 默认值                          |
| ------------------------ | --------------------------- | ---------------------------- |
| `model_id`               | Claude 模型 ID                | `claude-sonnet-4-6`          |
| `max_turns`              | 最大对话轮数（`--max-turns`）       | `50`                         |
| `timeout`                | 任务超时时间（秒）                   | `300`                        |
| `allowed_tools`          | 传给 `--allowedTools` 的工具名模式  | `mcp__playwright*`           |
| `system_prompt`          | 自定义 system prompt（覆盖默认值）    | 见下方                          |
| `playwright_mcp_command` | 启动 Playwright MCP 服务器的可执行文件 | `npx`                        |
| `playwright_mcp_args`    | 传给 MCP 启动程序的参数（包名 + 选项）     | `["@playwright/mcp@latest"]` |

### 默认 System Prompt

若未设置 `system_prompt`，Agent 使用内置提示词，涵盖三个方面：

1. **工具限制** — Claude 只能使用 `mcp__playwright__*` 工具；Bash、WebFetch、Skill、Agent 等内置工具被明确禁止。
2. **任务完成规则** — 若页面（如搜索结果）中已有足够信息，立即给出答案，不再点击进入子页；遇到验证码或访问限制时，最多重试一次后回退到已收集的数据。
3. **截图规则** — 调用 `browser_take_screenshot` 时仅传 `{"type": "png"}`，不指定 `filename`，确保图像以 base64 内联方式返回并被结果解析器捕获。

如需覆盖，在 `config.yaml` 的 `agents.claude-code.defaults` 下设置 `system_prompt`。

## 使用示例

### 基础运行

```bash theme={null}
# 运行 LexBench-Browser 前 3 个任务
bubench run \
  --agent claude-code \
  --data LexBench-Browser \
  --mode first_n \
  --count 3
```

### 运行全部任务

```bash theme={null}
bubench run \
  --agent claude-code \
  --data LexBench-Browser \
  --mode all \
  --skip-completed
```

## 评估

```bash theme={null}
bubench eval \
  --agent claude-code \
  --data LexBench-Browser \
  --model-id claude-sonnet-4-6
```

## 输出目录结构

每个任务完成后写入以下文件：

```
experiments/LexBench-Browser/All/claude-code/<model-id>/<timestamp>/tasks/<id>/
├── result.json          # AgentResult：答案、状态、指标、费用
├── stdout.txt           # claude CLI 的完整 stream-json 输出
├── stderr.txt           # Claude Code 标准错误
├── trajectory/
│   ├── screenshot-1.png # 从 browser_take_screenshot 工具结果提取
│   ├── screenshot-2.png
│   └── ...
└── api_logs/
    ├── system_prompt.txt # 使用的 system prompt
    ├── step_001.json     # 每轮：URL、工具调用、工具结果
    ├── step_002.json
    ├── ...
    └── summary.md        # 可读的逐步操作日志
```

<Note>
  截图从流式输出中的 `browser_take_screenshot` 工具结果提取。该工具必须在**不指定 `filename` 参数**的情况下调用，图像才能以内联 base64 方式返回并被解析器捕获；默认 system prompt 已强制执行此规则。Playwright MCP 的操作超时时间设置为 30 秒（高于默认 5 秒），以应对加载外部字体较慢的页面。
</Note>

## 支持的 Benchmarks

* ✅ LexBench-Browser
* ✅ Online-Mind2Web
* ✅ BrowseComp

## 常见问题

**"Executable 'claude' not found"**
Claude Code 未安装或不在 `$PATH` 中。执行 `npm install -g @anthropic-ai/claude-code` 并用 `claude --version` 验证。

**MCP 工具权限被拒绝**
Agent 运行时会自动添加 `--dangerously-skip-permissions`（非交互模式必需）以及与配置匹配的 `--allowedTools`。若工具仍被拒，用 `claude mcp list` 确认 MCP 服务器名称，并检查配置中的 `allowed_tools` 前缀是否匹配（如 `mcp__playwright*`）。

**结果中没有截图**
确认 Playwright MCP 服务器已连接（`claude mcp list`）。默认 system prompt 会指示 Claude Code 调用 `browser_take_screenshot` 且不传 `filename` 参数——若使用自定义 `system_prompt`，请保持相同规则以确保图像内联返回并被解析器捕获。若截图仍然失败，检查 `stdout.txt` 中是否有 `TimeoutError: browserBackend.callTool`——这表明页面加载外部资源较慢，可通过在 `playwright_mcp_args` 中增大 `--timeout-action` 值来解决。

**stream-json requires --verbose 错误**
Agent 已自动添加该标志。若手动运行 `claude` 时遇到此错误，请加上 `--verbose`。

## 相关链接

* [Claude Code 文档](https://docs.anthropic.com/en/docs/claude-code)
* [Playwright MCP（npm）](https://www.npmjs.com/package/@playwright/mcp)