Eval Agent 启动配置

comet eval 会在隔离的 Docker 容器中启动你选择的 Agent。不同 Agent 的认证方式和模型协议互不兼容，不能混用。 Claude Code 走 Anthropic 兼容接口。 Codex 依赖 OpenAI Responses API。 Qoder 使用自己的登录态或 Personal Access Token。 CodeBuddy 使用自己的模型配置。本页只讲 Agent 启动前的准备项。 Eval 主任务（Bench）和 LLM-as-judge 仍分别使用 BENCH_* 与 BENCH_JUDGE_*。完整变量表见 Eval harness。

不要把真实密钥写进 Skill、manifest、公开仓库、Dockerfile 或报告。建议使用当前 shell 环境变量，或使用用户级 %USERPROFILE%.comet\eval\.env / ~/.comet/eval/.env。发布包不会包含这些文件。

用户级 `.env` 在哪里

普通用户只需要配置用户目录下的 .env，不需要拉取 Comet 源码，也不需要修改安装包里的 eval/.env：

Windows：%USERPROFILE%\.comet\eval\\.env
macOS/Linux：~/.comet/eval/.env

第一次执行 comet eval 时，如果该文件不存在，CLI 会自动创建带注释的完整模板，并在终端打印实际路径。你编辑模板后再次执行即可。 CLI 不会覆盖已存在的文件。若同名变量同时出现在模板和当前 shell，以当前 shell 为准。参数已经按主任务、Judge、Claude Code、Codex、Qoder、CodeBuddy、LangSmith、Langfuse 分组，不需要你手工重建参数表。

先选择一个 Agent

# Claude Code（默认）
comet eval ./my-skill --agent claude-code --quick --html

# OpenAI Codex
comet eval ./my-skill --agent codex --quick --html

# Qoder
comet eval ./my-skill --agent qoder --quick --html

# CodeBuddy
comet eval ./my-skill --agent codebuddy --quick --html

先在宿主机单独验证 Agent 可用，再运行 Eval。这样可以把“Agent 启动或登录失败”和“Skill 评估失败”分开排查。

Claude Code

启动前需要什么

PATH 中可执行的 claude CLI。
任选一种认证方式：首次交互式登录，或 ANTHROPIC_API_KEY。
如果使用 Anthropic 兼容代理，还需要 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL 和模型名。

首次运行 claude 会进入登录流程。如果你设置了 ANTHROPIC_API_KEY，CLI 会改为确认该 key，而不是走交互登录。使用第三方网关时，可通过 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL 指向代理。官方参考：Claude Code overview、LLM gateway。

宿主机快速验证

claude --version
claude -p "Reply with exactly OK" --output-format json

使用 Anthropic 兼容代理

BENCH_EVAL_AGENT=claude-code
BENCH_MODEL=your-anthropic-compatible-model
BENCH_BASE_URL=https://your-anthropic-gateway.example/v1
BENCH_API_KEY=your-subject-key

# 或直接使用 Claude Code 原生变量
ANTHROPIC_AUTH_TOKEN=your-subject-key
ANTHROPIC_BASE_URL=https://your-anthropic-gateway.example/v1
ANTHROPIC_MODEL=your-anthropic-compatible-model

Eval 会把通用配置映射到 Claude Code 原生变量。若同时设置了 ANTHROPIC_* 和 BENCH_*，以显式的 ANTHROPIC_* 为准。

Codex

启动前需要什么

PATH 中可执行的 codex CLI。
一个能访问 OpenAI Responses API 的 API key 或登录态。
一个与该 key 对应的模型名。
如果使用自定义 provider，需要在用户级 ~/.codex/config.toml 中声明 model_provider、base_url、env_key 和 wire_api = "responses"。

Codex 的自定义 provider 配置在用户级 config.toml。 base_url 表示 provider 地址，env_key 表示读取哪个环境变量作为 key，wire_api 需要设为 responses。不要把 Anthropic Messages 地址给 Codex。 Codex 需要的是 Responses 接口，常见形式是 <base-url>/responses。官方参考：Codex configuration reference。

宿主机快速验证

codex --version
codex exec --json --yolo "Reply with exactly OK"

自定义 Responses provider

在启动 Codex 前设置 key：

# macOS / Linux
export OPENAI_API_KEY=your-subject-key

# Windows PowerShell
$env:OPENAI_API_KEY = "your-subject-key"

用户级 ~/.codex/config.toml 示例：

model = "your-responses-model"
model_provider = "comet-eval"

[model_providers.comet-eval]
name = "Comet Eval provider"
base_url = "https://your-openai-compatible-gateway.example/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
requires_openai_auth = false

在 Comet Eval 的用户级 .env 中，对应配置为：

BENCH_EVAL_AGENT=codex
OPENAI_API_KEY=your-subject-key
OPENAI_BASE_URL=https://your-openai-compatible-gateway.example/v1
OPENAI_MODEL=your-responses-model

# 也可以使用通用主任务配置；Codex 会映射到 OPENAI_*。
# BENCH_API_KEY=your-subject-key
# BENCH_BASE_URL=https://your-openai-compatible-gateway.example/v1
# BENCH_MODEL=your-responses-model

Eval 运行时会在容器内生成临时 config.toml，其中只写 env_key = "OPENAI_API_KEY"，不会落盘真实 key。你仍需要确认 provider 真实支持 Responses API。只支持 /chat/completions 或 Anthropic /messages 的地址不能直接用于 Codex。

Qoder

启动前需要什么

PATH 中可执行的 qodercli CLI。
Qoder 登录态，或 Qoder Personal Access Token（PAT）。
自动化和 Eval 推荐使用 QODER_PERSONAL_ACCESS_TOKEN。

Qoder 官方文档支持两种 CLI 登录方式：运行 qodercli 后输入 /login 进行浏览器登录或粘贴 Qoder PAT。非交互式启动可以设置 QODER_PERSONAL_ACCESS_TOKEN。PAT 在 Qoder Account → Integrations 创建。官方参考：Qoder CLI quick start、Qoder CLI authentication。

宿主机快速验证

qodercli --version
qodercli
# 在 Qoder 提示符中输入：
/login

非交互式验证可以使用：

# macOS / Linux
QODER_PERSONAL_ACCESS_TOKEN=your-qoder-pat \
  qodercli -p "Reply with exactly OK" --output-format stream-json --yolo

# Windows PowerShell
$env:QODER_PERSONAL_ACCESS_TOKEN = "your-qoder-pat"
qodercli -p "Reply with exactly OK" --output-format stream-json --yolo

Comet Eval 配置

BENCH_EVAL_AGENT=qoder
QODER_PERSONAL_ACCESS_TOKEN=your-qoder-pat
QODER_MODEL=your-qoder-model

# 或使用通用模型配置
# BENCH_MODEL=your-qoder-model

Qoder 的 PAT 只用于 Qoder 认证，不是 Anthropic/OpenAI 的 API key。不要把 ANTHROPIC_AUTH_TOKEN 或其他网关 key 填到 QODER_PERSONAL_ACCESS_TOKEN。那样会在 Qoder 启动阶段直接认证失败。当前 Eval 也不要求你为 Qoder 配置 Claude Code 的 ANTHROPIC_BASE_URL。 Eval 只在本次容器进程注入 QODER_PERSONAL_ACCESS_TOKEN，并使用隔离的临时配置目录。它不会读取或挂载宿主机的 Qoder 登录文件。

CodeBuddy

启动前需要什么

PATH 中可执行的 codebuddy CLI。
如果使用 CodeBuddy 平台登录，使用 CODEBUDDY_AUTH_TOKEN。
如果使用第三方或 OpenAI-compatible 模型，使用 CODEBUDDY_API_KEY、CODEBUDDY_BASE_URL 和该 provider 接受的模型名。

CodeBuddy 通过 --model <model-id> 选择模型。 CODEBUDDY_MODEL 可设置默认模型，CODEBUDDY_BASE_URL 可覆盖请求地址。不要把 Claude Code 的 ANTHROPIC_BASE_URL（尤其是 /anthropic 或 /messages）直接复用给 CodeBuddy。模型名也要使用 CodeBuddy 或 provider 认可的 ID，不要照搬 Claude 专用后缀。官方的宿主机模型注册文件是用户级 ~/.codebuddy/models.json 或工作区级 .codebuddy/models.json。其中 url 应填写完整的 OpenAI-compatible /chat/completions 地址，apiKey 可以写成 ${CODEBUDDY_API_KEY}，不要写真实密钥。例如：

{
  "models": [
    {
      "id": "your-model-id",
      "name": "Your Model",
      "vendor": "custom",
      "apiKey": "${CODEBUDDY_API_KEY}",
      "url": "https://your-openai-compatible-gateway.example/v1/chat/completions"
    }
  ],
  "availableModels": ["your-model-id"]
}

Eval 不会挂载宿主机 models.json 或 CodeBuddy 登录目录。它会在容器内使用临时 settings.json，并通过环境变量与 --model 传入配置。建议先在宿主机完成一次最小验证：

CODEBUDDY_API_KEY=your-subject-key \
CODEBUDDY_BASE_URL=https://your-openai-compatible-gateway.example/v1 \
CODEBUDDY_MODEL=your-model-id \
  codebuddy -p "Reply with exactly OK" --model your-model-id --output-format json -y

然后在用户级 Eval .env 中配置同一组值：

BENCH_EVAL_AGENT=codebuddy
CODEBUDDY_API_KEY=your-subject-key
CODEBUDDY_BASE_URL=https://your-openai-compatible-gateway.example/v1
CODEBUDDY_MODEL=your-model-id

# 也可以使用通用主任务配置；Eval 会映射到 CODEBUDDY_*。
# BENCH_API_KEY=your-subject-key
# BENCH_BASE_URL=https://your-openai-compatible-gateway.example/v1
# BENCH_MODEL=your-model-id

# 可选：覆盖 CodeBuddy 的不同模型用途。
# CODEBUDDY_SMALL_FAST_MODEL=your-fast-model-id
# CODEBUDDY_BIG_SLOW_MODEL=your-reasoning-model-id
# CODEBUDDY_CODE_SUBAGENT_MODEL=your-subagent-model-id

官方参考：CodeBuddy 模型配置、环境变量、CLI 参数。 Eval 只在当前容器进程注入凭据。临时 settings.json 用 apiKeyHelper 读取环境变量。运行结束后该配置目录会销毁，不会把真实 key 写入报告、manifest 或 Skill 工作区。

扩展自定义 Agent

非预定义的 Agent 通过用户目录下显式注册的 adapter.yaml 接入。仅仅把可执行文件放到 PATH 上不会自动启用它，也不需要 clone Comet 源码：

# macOS/Linux
~/.comet/eval/adapters/<agent-id>/adapter.yaml

# Windows
%USERPROFILE%\.comet\eval\adapters\<agent-id>\adapter.yaml

也可以在用户级 %USERPROFILE%\.comet\eval\\.env / ~/.comet/eval/.env 中设置 COMET_EVAL_ADAPTERS_DIR，覆盖默认的适配器注册目录。<agent-id> 必须是小写字母开头、只包含小写字母/数字/连字符、长度 2–32 的标识符。

`adapter.yaml` 最小完整示例

apiVersion: comet.eval.agent/v1alpha1
kind: EvalAgentAdapter
metadata:
  id: my-agent
  version: 1.0.0
runtime:
  executable: my-agent
  install:
    kind: npm
    package: my-agent
    version: latest
credentials:
  - MY_AGENT_API_KEY
  - MY_AGENT_AUTH_TOKEN
modelEnv: MY_AGENT_MODEL
baseUrlEnv: MY_AGENT_BASE_URL
capabilities:
  singleTurn: true
  resume: true
  structuredEvents: true
  telemetry: false
  skillInvocationEvidence: true

字段规则：

runtime.executable 是容器内启动的命令。npm/pip 包必须暴露这个可执行入口。 runtime.install.kind 支持 npm、pip、none。none 表示该命令已经存在于基础镜像中。
credentials 只能声明最多两个环境变量名，不能写密钥值。主 Agent 只会把这些变量转发进容器。如果用于 Judge，BENCH_JUDGE_API_KEY 映射到第一个名称，BENCH_JUDGE_AUTH_TOKEN 映射到第二个名称。
modelEnv、baseUrlEnv 是可选的自定义变量名。自定义 Agent 不会自动继承 BENCH_API_KEY、 BENCH_MODEL 或 BENCH_BASE_URL。请使用声明的变量、CLI 参数或 manifest 配置。
resume 支持 auto_user 多轮交互。structuredEvents 要求输出 JSONL。 skillInvocationEvidence 要求输出明确的 Skill 调用事件。telemetry: false 时 token/cost 可以是 N/A。真实评估至少需要 singleTurn、resume、structuredEvents 和 skillInvocationEvidence 为 true。

自定义 CLI 必须兼容 Eval 的调用约定：

<executable> -p "<prompt>" --output-format stream-json --model <model> [--resume <session-id>]

每条结构化事件写到 stdout。若要让评分器确认 Skill 被调用，输出中还要包含类似下面的 JSONL：

{"type":"skill_invocation","skill":"my-skill"}

在自动生成的用户级 .env 中补上 adapter.yaml 声明的变量：

BENCH_EVAL_AGENT=my-agent
MY_AGENT_API_KEY=your-subject-key
MY_AGENT_MODEL=your-model
MY_AGENT_BASE_URL=https://your-provider.example/v1

# 作为独立 Judge 时使用独立凭据：
# BENCH_LLM_JUDGE=1
# BENCH_JUDGE_AGENT=my-agent
# BENCH_JUDGE_API_KEY=your-judge-key
# BENCH_JUDGE_MODEL=your-judge-model
# BENCH_JUDGE_BASE_URL=https://your-judge-provider.example/v1

然后先静态检查，再执行真实评估：

comet eval ./my-skill --collect --agent my-agent
comet eval ./my-skill --quick --agent my-agent --model your-model

适配器可以通过 npm/pip 包或 wrapper CLI 分发，但 adapter.yaml 目前不支持自定义参数模板、宿主机配置目录挂载或任意 Docker 指令。真实凭据只能放在每个用户自己的 .env 或当前 shell 中。

Bench 和 Judge 要分开

如果启用了 LLM-as-judge，Judge 需要自己的模型名和凭据：

BENCH_LLM_JUDGE=1
BENCH_JUDGE_MODEL=your-judge-model
BENCH_JUDGE_API_KEY=your-judge-key
BENCH_JUDGE_BASE_URL=https://your-judge-gateway.example/v1

不要因为主 Agent 能调用，就省略 BENCH_JUDGE_MODEL 或让 Judge 复用主任务配置。主任务和 Judge 可以选择不同的 Agent，但各自的认证必须匹配所选 Agent。

常见不匹配

现象	通常原因	处理方式
Claude Code 返回 401	没有 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`，或 Base URL 与模型不匹配	先运行 `claude -p` 验证，再检查 `ANTHROPIC_*`
Codex 请求返回 404	网关只实现了 Anthropic Messages 或 Chat Completions	换成支持 Responses API 的 provider，并设置 `wire_api = "responses"`
Qoder `auth.exchangeJobToken` 失败	把其他厂商 API key 当成 Qoder PAT	在 Qoder Integrations 创建并使用 Qoder PAT
CodeBuddy 返回 401/404	使用了 Claude Code 的 Anthropic 地址，或模型 ID 不被 provider 接受	改用 `CODEBUDDY_BASE_URL`、`CODEBUDDY_API_KEY` 和 provider 的模型 ID；先单独运行 `codebuddy -p`
Eval 瞬间跳过	Agent 凭据没有进入 Eval 进程	检查用户级 `.env` 或当前 shell；不要只检查 GUI 客户端的配置

CodeBuddy 的自定义模型需要使用 CodeBuddy 的 OpenAI-compatible 配置。Claude Code 的 ANTHROPIC_* 配置不会自动变成 CodeBuddy 配置。

下一步

评估快速上手 — 从 Skill 目录开始第一次评估
Eval harness — 环境变量、Docker 和任务运行机制
comet eval 命令 — CLI 选项和报告路径

快速上手（基础）

方法论：为什么评估决定 Skill 演进

真实评估实验

深入掌握（进阶）

相关命令

Eval Agent 启动配置

用户级 `.env` 在哪里

先选择一个 Agent

Claude Code

启动前需要什么

宿主机快速验证

使用 Anthropic 兼容代理

Codex

启动前需要什么

宿主机快速验证

自定义 Responses provider

Qoder

启动前需要什么

宿主机快速验证

Comet Eval 配置

CodeBuddy

启动前需要什么

扩展自定义 Agent

`adapter.yaml` 最小完整示例

Bench 和 Judge 要分开

常见不匹配

下一步

​用户级 .env 在哪里

​先选择一个 Agent

​Claude Code

​启动前需要什么

​宿主机快速验证

​使用 Anthropic 兼容代理

​Codex

​启动前需要什么

​宿主机快速验证

​自定义 Responses provider

​Qoder

​启动前需要什么

​宿主机快速验证

​Comet Eval 配置

​CodeBuddy

​启动前需要什么

​扩展自定义 Agent

​adapter.yaml 最小完整示例

​Bench 和 Judge 要分开

​常见不匹配

​下一步

用户级 `.env` 在哪里

先选择一个 Agent

Claude Code

启动前需要什么

宿主机快速验证

使用 Anthropic 兼容代理

Codex

启动前需要什么

宿主机快速验证

自定义 Responses provider

Qoder

启动前需要什么

宿主机快速验证

Comet Eval 配置

CodeBuddy

启动前需要什么

扩展自定义 Agent

`adapter.yaml` 最小完整示例

Bench 和 Judge 要分开

常见不匹配

下一步