CommerceAgentBench 评估 AI 智能体完成长期任务能力的基准测试平台

📋 准备工作

在开始部署前，请确保你的系统满足以下要求并准备好必要信息：

核心依赖：
- Docker：需要支持 linux/amd64 容器。在 Apple Silicon (M1/M2) 的 Mac 上，Docker Desktop 可以通过模拟运行，但性能会受影响。
- Python：版本 3.11 或更新版本。
API 密钥：
- 至少一个被评估模型的 API 密钥（例如，用于测试的模型，如 gemini-3.5-flash）。
- 一个用作 LLM 评判官 (Judge) 的 API 密钥。项目标准评判官是 gemini-3.1-pro-preview，你需要有权限调用它。
网络：需要能够拉取 Docker 镜像和访问指定的 API 服务。

🚀 部署步骤

整个过程分为四个主要阶段。

第一阶段：安装 Python 包与环境

打开终端，克隆项目仓库并进入目录：

1 2	git clone https://github.com/Accio-org/CommerceAgentBench.git cd CommerceAgentBench

创建并激活 Python 虚拟环境（推荐）：

1
2
3

python3 -m venv .venv
source .venv/bin/activate  # 在 Linux/macOS
# .venv\Scripts\activate   # 在 Windows

以可编辑模式安装基准测试的 Python 包及其依赖：
1
python -m pip install -e .
验证安装是否成功，列出可用的任务：
1
commerce-agent-bench list
如果命令运行并显示任务列表，则安装成功。

第二阶段：拉取核心运行环境镜像

CommerceAgentBench 将测试环境、工具和被测智能体（如 OpenClaw）打包在一个 Docker 镜像中。必须拉取项目指定的、版本固定的镜像以确保结果可复现。

执行以下命令拉取 v1.3.1 版本所需的镜像：

1 2	docker pull --platform linux/amd64 \ acciolyk/accio_bench@sha256:1e9cf5c72a56794175b7d06ece036b92e296e6b7e9e9a7fa244026f6acea3859

说明：该镜像包含 OpenClaw 运行时、浏览器栈和所有模拟的领域服务。--platform linux/amd64 参数在 Apple Silicon Mac 上必需。

第三阶段：配置 API 密钥与模型

你需要将 API 密钥设置为环境变量，并在配置文件中指定要测试的模型。

设置环境变量（以 Gemini 为例）：

1 2	export GEMINI_API_KEY="你的Gemini_API密钥" # 如果使用其他提供商，请设置对应的变量，如 OPENAI_API_KEY, ANTHROPIC_API_KEY 等

（可选）配置评判官模型：项目默认使用 gemini-3.1-pro-preview 作为 LLM 评判官。如果需要更改，可以在运行命令时通过 --llm-judge-model 参数指定。
了解模型配置文件：项目在 configs/ 目录下提供了多种模型接入方式的配置文件（如 openclaw_native_google_direct.yaml）。这些文件定义了如何连接不同提供商的 API。

第四阶段：运行基准测试

你可以选择运行单个任务进行快速测试，或运行完整任务集进行评估。

1. 运行单个任务（冒烟测试）

此命令会运行一个名为 api-amazon-margin-floor-audit 的 API 任务，使用 Gemini Flash 模型，并将当前运行标记为 smoke：

commerce-agent-bench run api-amazon-margin-floor-audit \
  --harness openclaw \
  --image acciolyk/accio_bench@sha256:1e9cf5c72a56794175b7d06ece036b92e296e6b7e9e9a7fa244026f6acea3859 \
  --platform linux/amd64 \
  --openclaw-model google/gemini-3.5-flash \
  --openclaw-image-model google/gemini-3.5-flash \
  --openclaw-models-config configs/native_google_direct_models.json \
  --llm-judge-provider gemini \
  --llm-judge-model gemini-3.1-pro-preview \
  --run-id smoke

如果成功，会在 runs/smoke/ 目录下生成结果文件。

2. 运行任务集（完整评估）

要运行基准测试的完整任务集（107个任务），使用以下命令：

1
2
3

commerce-agent-bench run \
  --config configs/openclaw_native_google_direct.yaml \
  --run-id "openclaw-$(date +%Y%m%d-%H%M%S)"

--config：指定使用哪个模型配置。如果你使用其他提供商（如 OpenRouter），需更换对应的 .yaml 文件。
--run-id：为本次运行设置一个唯一的标识符，结果会保存在 runs/ 目录下以该 ID 命名的文件夹中。
限制运行：建议先用 --limit 1 参数测试单任务，确认环境无误后再运行全集。

📊 理解结果与输出

每次运行后，结果会保存在 runs/<run_id>/ 目录下：

summary.json 和 summary.md：包含总体通过率等关键指标。
report.html：一个可视化的报告页面。
tasks/<task-id>/：每个任务的详细输出，包括：
- manifest.json：任务元数据。
- agent/：智能体的操作轨迹（trajectory）。
- verifier/：评判官给出的评分细节。
- workspace/outputs/：智能体生成的文件。
- screenshots/：浏览器任务中的截图。

⚙️ 进阶配置与重要概念

评判官（Judge）：负责评估任务结果，独立于被测试的智能体。保持使用标准模型（gemini-3.1-pro-preview）以确保结果可比性。
可复现性（Reproducibility）：要获得与他人可比的结果，必须固定以下四个要素：
1. 任务集：domain_v1_all（107个任务）。
2. 任务定义：当前 Git 仓库的特定版本（如 v1.3.1）。
3. Harness：项目中的 openclaw 运行器。
4. 运行时镜像：上面拉取的特定 digest 的 Docker 镜像。
提供商路由：项目支持多种 API 接入方式，包括原生 Google Gemini、DashScope (Qwen)、OpenRouter 等，以及“自带端点”（BYO Endpoint）。具体配置可参考 configs/ 目录下的文件。

🔧 故障排查与注意事项

Docker 平台错误：在 Apple Silicon Mac 上运行，务必在 docker pull 和 run 命令中添加 --platform linux/amd64。
API 配额与费用：运行完整基准测试会消耗大量的 API Token，请确保你的账户有足够配额并注意费用。
环境变量未生效：确认在运行 commerce-agent-bench 命令的同一终端会话中，已正确 export 了所有必需的 API 密钥。
镜像拉取失败：检查网络连接，或尝试配置 Docker 镜像加速器。
任务失败：可以查看 runs/<run-id>/tasks/<task-id>/ 下的日志文件进行详细诊断。