把配置和密钥各放到该放的地方

你想让 CI 每题跑 5 次、本地只跑 1 次，又不想把 API key 签进仓库。NiceEval 把值分成两类，各放一处：

配置写进代码：CLI flag、experiments/ 下的 Experiment 文件、根目录的 niceeval.config.ts。跑几次、超时多久、并发多少和 Judge 用哪个模型都在这里，没有对应的环境变量。
密钥放环境变量：API key、Provider token，再加上 NO_COLOR 这类描述当前终端的设置。

所以同一个值只有一个来源。niceeval exp --dry 打印出来的就是真正生效的值，不会有环境变量在背后改掉它。CLI 与运行时文案是英语；浏览器里的 niceeval view 可以切换中英文。

配置：想让这个值活多久，就写在哪一层

先想清楚这个值要在多大范围内生效，再决定写在哪一层。同一个值出现在多层时，按 CLI flag → Experiment → 评估用例 → config → 内置默认 取，前面有值就不看后面。config 只提供默认值，不会覆盖别的层：评估用例自己声明的 timeoutMs 不会被项目默认值替换。 只想这一次不一样：写在命令上。

pnpm exec niceeval exp ci --attempts 5 --timeout 600000

这个实验一直这样：写进 Experiment 文件。

// experiments/ci.ts
import { defineExperiment } from "niceeval";
import { codexAgent } from "niceeval/agents";

export default defineExperiment({
  agent: codexAgent(),
  model: "gpt-5.4",
  attempts: 3,
  timeoutMs: 600_000,
  budget: 5,
});

agent、model、flags 只能写在这里，没有对应的 CLI flag。要换 Agent 或换模型，就复制一个 Experiment 文件。这样每次运行用的是哪个 Agent 和模型都记在结果里，事后能复现。 整个项目共享：写进 niceeval.config.ts。

import { defineConfig } from "niceeval";
import { OpenAIProvider } from "niceeval/judge";

export default defineConfig({
  judgeRuntime: OpenAIProvider({ model: "gpt-5.4-mini" }),
  maxConcurrency: 4,
  timeoutMs: 300_000,
});

`niceeval.config.ts` 能放什么

字段	放什么
`name`	项目名，显示在 `niceeval view` 顶部。可按语言给多份
`judgeRuntime`	默认裁判 Provider，由 `niceeval/judge` 的具名工厂构造
`workspace`	上传进 Sandbox 的工作区根目录
`reporters`	默认 reporter 列表（落盘、上报实验平台）
`maxConcurrency`	默认并发上限
`timeoutMs`	默认单次 attempt 超时
`telemetry`	OTLP 接收配置（`host` / `port`），OTel 接入只从这里配
`pricing`	价格表覆盖，按 model 名或 `provider/*` 通配

每个字段的类型和完整说明在 defineConfig 参考。flag 全表在 CLI 参考。

环境变量：只有密钥和终端两类

把密钥放进下面这些环境变量。这就是 NiceEval 会读的全部环境变量；每个 Agent、Sandbox 和 Judge 只认自己那几个名字，不会去读别的 key。

变量	谁在用	备注
`ANTHROPIC_API_KEY`	`claudeCodeAgent()`	工厂参数 `apiKey` 可覆盖
`ANTHROPIC_BASE_URL`	`claudeCodeAgent()`	网关地址，工厂参数 `baseUrl` 可覆盖
`CODEX_API_KEY` / `CODEX_BASE_URL`	`codexAgent()`	key 必需，代理地址可选；工厂参数 `apiKey` / `baseUrl` 可覆盖
`BUB_API_KEY` / `BUB_API_BASE`	`bubAgent()`	两者必需；工厂参数 `apiKey` / `apiBase` 可覆盖
`OPENCLAW_API_KEY` / `OPENCLAW_BASE_URL`	`openClawAgent()`	key 省略时回落 `ANTHROPIC_API_KEY`
`OPENCODE_API_KEY` / `OPENCODE_BASE_URL`	`openCodeAgent()`	key 省略时回落 `ANTHROPIC_API_KEY`
`HERMES_API_KEY` / `HERMES_API_BASE`	`hermesAgent()`	key 省略时依次回落 `OPENROUTER_API_KEY`、`ANTHROPIC_API_KEY`
`OPENAI_API_KEY`	`OpenAIProvider`	OpenAI 或显式兼容网关的默认 key
`AI_GATEWAY_API_KEY`	`VercelProvider`	Vercel AI Gateway key
`OPENROUTER_API_KEY`	`OpenRouterProvider`	OpenRouter key
`TYPESAFE_API_KEY`	`TypesafeProvider`	TypeSafe System One key
`E2B_API_KEY`	`e2bSandbox()`
`VERCEL_API_TOKEN`	`vercelSandbox()`
`VERCEL_TEAM_ID`	`vercelSandbox()`
`VERCEL_PROJECT_ID`	`vercelSandbox()`
`NO_COLOR`	CLI 输出	设了就不画颜色和框线

想让 Judge 从别的变量名读 key，在配置里写明变量名：

import { OpenAIProvider } from "niceeval/judge";

export default defineConfig({
  judgeRuntime: OpenAIProvider({
    model: "gpt-5.4-mini",
    baseUrl: "https://gateway.example.com/v1",   // 网关地址是配置，写在这里
    apiKeyEnv: "MY_GATEWAY_KEY",                  // key 是密钥，读这个环境变量
  }),
});

网关地址也不方便签入仓库时，在配置里自己读环境变量即可。配置本身就是代码，读取时 .env 已经加载完：

export default defineConfig({
  judgeRuntime: OpenAIProvider({
    model: "gpt-5.4-mini",
    baseUrl: process.env.MY_GATEWAY_URL,   // 变量名自己起，自己读
    apiKeyEnv: "MY_GATEWAY_KEY",
  }),
});

区别只在于：变量名是你的项目定的，不是 NiceEval 内置一个名字然后到环境里猜。本地开发时，把密钥放进当前目录的 .env。CLI 启动时会自动加载它，不会覆盖已经存在的环境变量，你不用每次 export：

# .env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

.env 只用来放密钥，不是第二个配置文件。往里写 NICEEVAL_TIMEOUT 这类变量不会有任何效果。CI 里同样只传密钥：

- run: pnpm exec niceeval exp ci --junit .niceeval/junit.xml
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

想调这些值时写到哪一层

配置项没有环境变量层，所以下面每一项都只有这几个位置可写：

要调什么	写在哪
每条评估用例跑几次	`--attempts`，或 experiment 的 `attempts`
单次 Attempt 的超时	`--timeout`，或 experiment / config 的 `timeoutMs`
花费上限	`--budget`，或 experiment 的 `budget`
并发上限	`--max-concurrency`，或 config 的 `maxConcurrency`
Judge 模型与端点	config 或 Experiment 的具名 Provider；Eval 可用 `judge` 字符串只换模型
OTel 接收地址	config 的 `telemetry: { host, port }`

每个 Judge Provider 只读自己的默认 key 变量，或工厂 apiKeyEnv 显式指定的变量。它不会借用其它 Provider 或被测应用的 key。

接着看

defineConfig 参考

每个配置字段的类型与完整说明。

CLI 参考

命令、flag 全表与退出码。

写 experiment

哪些值属于一次具体运行。

CI 集成

在 CI 里传 secrets。

开始使用

接入你的应用

评估 Coding Agent

写好评估用例

实验与对比

看结果与迭代

提速：并发与复用

基础设施与 CI

问题排查

把配置和密钥各放到该放的地方

配置：想让这个值活多久，就写在哪一层

`niceeval.config.ts` 能放什么

环境变量：只有密钥和终端两类

想调这些值时写到哪一层

接着看

defineConfig 参考

CLI 参考

写 experiment

CI 集成

​配置：想让这个值活多久，就写在哪一层

​niceeval.config.ts 能放什么

​环境变量：只有密钥和终端两类

​想调这些值时写到哪一层

​接着看

defineConfig 参考

CLI 参考

写 experiment

CI 集成

配置：想让这个值活多久，就写在哪一层

`niceeval.config.ts` 能放什么

环境变量：只有密钥和终端两类

想调这些值时写到哪一层

接着看