Osmosis CLI 配置文件

Osmosis CLI 使用 TOML 文件配置 evaluation runs、training runs 和 benchmark runs。Configs 必须位于 workspace directory 内：

配置类型	必需位置	命令
Eval	`configs/eval/*.toml`	`osmosis eval submit`
Training	`configs/training/*.toml`	`osmosis train submit`
Benchmark	`configs/benchmark/*.toml`	`osmosis benchmark submit`

必需字段会以 un-commented 形式显示。可选字段在 template 文件中会被注释掉，可省略以使用平台默认值。

Eval Config

由 osmosis eval submit 使用，用于提交一次 evaluation run。平台会克隆由 origin remote 标识的 workspace repository，并在服务端针对 platform dataset 运行 rollout。

configs/eval/my-rollout.toml

[experiment]
rollout = "my-rollout"                         # Rollout directory under rollouts/
entrypoint = "main.py"                         # Entrypoint relative to rollout dir
model_path = "openai/gpt-5-mini"               # LiteLLM-style model name for the evaluation policy
dataset = "my-platform-dataset"                # Platform dataset name from `osmosis dataset list`
# branch = "my-feature"                        # 使用已 push 的分支（省略则用默认分支）
# commit_sha = "abc1234"                       # Pin code to a specific commit

[evaluation]
# Optional. Omit values to use platform defaults.
# limit = 200                                  # First N rows; omit for random 10% sample
# n = 1                                        # Evaluation attempts per row
# batch_size = 1                               # Rows evaluated per batch
# pass_threshold = 1.0                         # Minimum passing score
# agent_workflow_timeout_s = 450               # Agent workflow timeout per row
# grader_timeout_s = 150                       # Grader timeout per row

# [env]
# LOG_LEVEL = "INFO"                           # Non-secret literal env var

[secrets]
# Eval config 必填。默认 OpenAI eval 模型需要此 secret。
# 仅在 evaluation 不需要任何 secret refs 时使用 required = []。
required = ["OPENAI_API_KEY"]

`[experiment]`

字段	类型	是否必填	说明
`rollout`	`str`	Yes	`rollouts/` 下的 rollout 目录名
`entrypoint`	`str`	Yes	相对 rollout 目录的 Python entrypoint
`model_path`	`str`	Yes	evaluation policy 的 LiteLLM 风格模型名（例如 `openai/gpt-5-mini`）
`dataset`	`str`	Yes	来自 `osmosis dataset list` 的 platform dataset 名称
`branch`	`str`	No	使用该已 push 分支的当前 head。与 `commit_sha` 互斥。
`commit_sha`	`str`	No	固定到指定 commit。与 `branch` 互斥。

同时省略 branch 和 commit_sha 时，使用仓库默认分支上最新已同步的 commit。按 branch 提交时只解析一次 branch head，因此 run 会固定到得到的完整 commit SHA。

`[evaluation]`

所有字段均为可选。省略字段表示使用平台默认值。

字段	类型	取值范围	说明
`limit`	`int`	> 0	评估的行数（前 `N` 行）。省略时，平台会对 dataset 随机抽取 10% 的样本。
`n`	`int`	> 0	每行 evaluation 的尝试次数。它决定 pass@k metrics 可使用的尝试数，因此所报告的最大 `k` 不能超过 `n`。
`batch_size`	`int`	> 0	每个 batch 评估的行数
`pass_threshold`	`float`	—	样本计为通过所需达到或超过的分数；请使用 grader 输出的 score scale
`agent_workflow_timeout_s`	`float`	`30–600`	每行 `AgentWorkflow.run()` 的 timeout
`grader_timeout_s`	`float`	`30–600`	每行 `Grader.grade()` 的 timeout

`[env]` 和 `[secrets]`（eval）

evaluation run container 的可选 [env] 变量与必填 [secrets] 表。Eval config 必须包含 [secrets]——仅在 evaluation 不需要任何 secret refs 时才写 required = []。完整规则见下方的 [env] 和 [secrets]。

Benchmark Config

由 osmosis benchmark submit 使用，用于运行已经添加到当前 workspace 的 benchmark。Benchmark config 描述 task selection、agent harness 和 model，以及 execution settings；它不引用 workspace rollout code。

configs/benchmark/terminal-bench-smoke.toml

[experiment]
benchmark = "terminal-bench-2-1"               # 来自 `benchmark list` 的 benchmark key

# 省略 [tasks] 会运行所有 tasks。
[tasks]
task_names = ["terminal-bench/git-multibranch"] # 明确指定 task 名称
# categories = ["software-engineering"]       # 合并这些类别中的 tasks
# task_set = "parity"                         # Benchmark 定义的 parity sample

[[agents]]
harness = "codex"

[agents.model]
type = "provider"
model = "openai/gpt-5.2"
api_key_secret = "OPENAI_API_KEY"             # Platform secret record 名称

# [agents.env]
# AGENT_MODE = "strict"                       # 仅供该 agent 使用的 literal env

[execution]
attempts_per_task = 1
max_concurrent_attempts = 4
timeout_multiplier = 1.0
max_retries = 0
# pass_threshold = 1.0
# 仅用于需要 judge 的 benchmark：
# judge_model = "openai/gpt-5.2"
# judge_api_key_secret = "OPENAI_API_KEY"

# verifier 自带凭据的 registry dataset：
# [verifier]
# required = ["MY_VLM_KEY"]                   # Platform secret record 名称

# [env]
# LOG_LEVEL = "info"                          # 供所有 agents 使用的 literal env

`[experiment]`（benchmark）

字段	类型	是否必填	说明
`benchmark`	`str`	Yes	已经添加到当前 workspace 的 benchmark，可填写其 key、名称或 ID。三者都按完全一致且区分大小写的方式匹配

benchmark list 会同时显示 key 和名称；两者都可以填在这里，ID 同样可以。

`[tasks]`

所有字段均为可选。省略此 section 会运行所有 tasks。同时设置 task_names 和 categories 时，两者取并集。设置 task_set 后，会使用其发布的 sample，而不使用 task_names 或 categories。

字段	类型	说明
`task_names`	`list[str]`	Benchmark manifest 中明确指定的 task 名称
`categories`	`list[str]`	包含指定类别中的所有 tasks
`task_set`	`str`	Benchmark 发布的命名 sample；当前为 `parity`

对于 HLE，我们建议设置 task_set = "parity"。仅当你确实准备提交完整 HLE benchmark 时，才省略 [tasks]。

`[[agents]]` 和 `[agents.model]`

每个 run 需要一到八个 agents。可用 harness 取决于所选 benchmark。在所有托管 benchmark 中，harness 支持的取值包括 claude-code、codex、cursor-cli、gemini-cli、mini-swe-agent、openhands、opencode 和 terminus-2。Platform 会拒绝所选 benchmark 不支持的 harness。无论哪种情况，每个 agent 都需要各自的 [[agents]] 条目：只运行官方 scaffold 的 benchmark 会拒绝所有 harness；而允许（但不强制）harness 的 benchmark 在省略该字段时会运行其官方 scaffold。benchmark info 会说明属于哪一种。

Agent 字段	是否必填	说明
`harness`	取决于 benchmark	所选 benchmark 提供的 agent harness；省略后会运行该 benchmark 的官方 scaffold（若有）
`harness_api_key_secret`	仅 `cursor-cli` 和 `mini-swe-agent`	分别填写 `CURSOR_API_KEY` 和 `MSWEA_API_KEY`，其中存放该 harness 的 credential；其他 harness 必须省略
`model`	Yes	Provider、endpoint 或 hosted model config
`env`	No	仅供该 agent 使用的 literal environment variables

Model 类型	必填 model 字段	适用场景
`provider`	`model`, `api_key_secret`	Provider model，例如 `openai/gpt-5.2`
`endpoint`	`base_url`, `model`, `api_key_secret`	OpenAI-compatible custom endpoint；`extra_headers` 可选
`hosted`	`base_model`, `lora_model_name`	你在 Osmosis 上训练并部署的 LoRA model。`base_model` 是其训练所用的 base model，`lora_model_name` 是该 LoRA model 的名称

对于 provider 和 endpoint model，api_key_secret 是 model 的 Platform secret record 名称。harness_api_key_secret 独立于它并按 agent 设置：cursor-cli 和 mini-swe-agent 必须设置，其他 harness 设置后会被拒绝。cursor-cli 填 CURSOR_API_KEY，mini-swe-agent 填 MSWEA_API_KEY。这是各自 harness 读取的变量，填其他值会在提交时被拒绝。使用 osmosis secret set 注册 record，然后在 agent 中引用其名称。例如，Cursor CLI agent 可以使用：

[[agents]]
harness = "cursor-cli"
harness_api_key_secret = "CURSOR_API_KEY"

[agents.model]
type = "provider"
model = "openai/gpt-5.2"
api_key_secret = "OPENAI_API_KEY"

osmosis secret set CURSOR_API_KEY

若要 benchmark 你自己的 LoRA model 而不是 provider model，请使用 type = "hosted"。两个值都取自 osmosis model list --type lora：base_model 是该 LoRA 的 Base Model 列，lora_model_name 是其 Name 列。

[[agents]]
harness = "codex"

[agents.model]
type = "hosted"
base_model = "Qwen/Qwen3.6-35B-A3B"
lora_model_name = "deep-swe-agent"

提交前请先用 osmosis model deploy 部署该 LoRA model；针对未部署 model 的 run 会被拒绝，base_model 与该 LoRA model 实际训练所用的 base 不一致时同样会被拒绝。Hosted agent 不需要 api_key_secret，由 Osmosis 提供服务。

每个 agent 的 effective environment 由顶层 [env] 和该 agent 的 [agents.env] 合并而成。Provider 或 endpoint agent 的 api_key_secret 名称不能出现在该 agent 的 effective environment 中。judge_api_key_secret 名称以及任何 [verifier] 中的 secret 名称都不能出现在顶层 [env] 或任何 agent 的 [agents.env] 中。对于 cursor-cli agent，不要同时在任一 env table 中设置 CURSOR_API_KEY；对于 mini-swe-agent agent，不要设置 MSWEA_API_KEY。解析后的 harness secret 会占用对应的 destination variable。Provider 和 endpoint 的 api_key_secret 也不能引用 runner 保留的名称：DAYTONA_API_KEY、DAYTONA_API_URL、SKYPILOT_SERVICE_ACCOUNT_TOKEN 或 SKYPILOT_API_SERVER_ENDPOINT。这些属于 Platform 管理的 sandbox 基础设施，请将 model 凭据存放在其他 record 名称下。以 _OSMOSIS_ 开头的键由平台保留，[env] 和每个 [agents.env] 中都会被拒绝。

所有 secret fields 都保存 record 名称，而不是 credential value。[agents.env] 包含单个 agent 使用的 literal variables；顶层 [env] 应用于所有 agents，agent-specific value 会覆盖同名 global key。

`[execution]`

字段	类型	默认值	取值范围	说明
`attempts_per_task`	`int`	`1`	`1–10`	每个选中 task 的尝试次数
`max_concurrent_attempts`	`int`	`4`	`1–64`	同时运行的最大 attempts 数
`timeout_multiplier`	`float`	`1.0`	`> 0` and `<= 10`	应用于 benchmark task timeout 的乘数
`max_retries`	`int`	`0`	`0–5`	可重试基础设施故障的重试次数
`pass_threshold`	`float`	benchmark 默认值	`0–1`	Attempt 判定通过的最低 score
`judge_model`	`str`	benchmark 默认值	—	HLE 和 GDPVal 的可选 judge model override
`judge_api_key_secret`	`str`	—	—	judge 或 grader 使用的 Platform secret record 名称

Benchmark 有三种形态，可在 benchmark info 的 LLM Judge 行看到：

`LLM Judge` 行	含义
`Required (default: <model>)`	HLE 和 GDPVal。必须设置 `judge_api_key_secret`；`judge_model` 可选，省略时使用 benchmark 默认值
`API key only (pinned grader)`	BrowseComp。adapter 固定了自己的 grader，因此必须设置 `judge_api_key_secret` 且必须是 OpenAI key，同时会拒绝 `judge_model`
`–`	不使用 judge。`judge_model` 和 `judge_api_key_secret` 都会被拒绝

使用 osmosis secret set 注册该 record。

`[secrets]`

run 需要但其他字段未命名的凭据——例如 registry dataset 自身的 API key。这里只列出 record 名称，值在提交时解析。training 和 eval config 使用相同的 section 与解析顺序。

[secrets]
required = ["WEATHER_API_KEY"]

每个名称的解析顺序，命中即止：

--secrets-file <path>，每行一个 NAME=value，以 # 开头的整行会被跳过；- 表示从 stdin 读取
CLI 进程环境中同名的变量
已有 personal 或 workspace secret，由服务端解析
隐藏的交互式 prompt，仅在终端中、且仅针对仍未解析的名称

本地提供（1、2 或 4）。 CLI 读取该值，并随本次提交的 TLS 请求发送。Osmosis 会在 Run scope 下记录名称，但不会将值加入 secret store 或持久化 run config，因此每次提交都需要重新提供。 服务端解析（3）。 该名称已是 personal 或 workspace secret，平台会自行查出对应的值，本地无需提供；同名 personal secret 会覆盖 workspace secret。这里刻意不提供 --secret NAME=value 参数：argv 中的值会进入 shell history、ps 输出，以及任何启用 set -x 的 CI 日志。

# 无需传参：名称即环境变量名，已导出的值会被自动找到
osmosis benchmark submit configs/benchmark/custom.toml

# 从 dotenv 文件提供多个值
osmosis benchmark submit configs/benchmark/custom.toml --secrets-file .env.local

# training 和 eval 使用相同的参数
osmosis train submit configs/training/my-run.toml --secrets-file .env.local

# 从 secret manager 管道输入：secrets.env.tpl 中写 WEATHER_API_KEY={{ op://vault/weather/key }}，值不会落盘
op inject -i secrets.env.tpl | osmosis benchmark submit configs/benchmark/custom.toml --secrets-file - --yes

stdin 接受与文件相同的 NAME=value 行。管道输入会使 stdin 变为非交互，因此需要加 --yes 跳过提交确认。在非终端环境下，缺少值的名称会立即失败并一次性列出所有缺失名称，使 CI 一次报告完整缺口，而不是每次重试只报一个。 --secrets-file 的每一行采用 dotenv 风格的 NAME=value。名称区分大小写，并且必须通过 Python 的 str.isidentifier() 检查。CLI 会剥离开头的 export 前缀，并移除值外层一组成对的单引号或双引号。空行以及以 # 起始的行会被忽略；不支持行内注释、转义处理或多行值。

.env.run

# 注释
WEATHER_API_KEY=plain-value
export ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY="sk-...with spaces"

格式不正确的行会导致提交失败。CLI 仅报告来源与行号，不会将行内容回显到 stderr 或 JSON 错误信封，避免 secret 值通过 CI 日志泄露。

`[verifier]`

Registry dataset 声明的凭据模板无法由平台枚举，因此需要在这里列出提供这些凭据的 Platform secret record。每条 record 都以自身名称交付给 verifier，因此请按 verifier 读取的变量名来命名。最多 16 条，每个名称必须匹配 ^[A-Z][A-Z0-9_]*$。

[verifier]
required = ["MY_VLM_KEY"]

Managed benchmark 在 catalog 中已建模自身凭据，不接受此项，提交时会被拒绝。与 judge_api_key_secret 同理，这里引用的 secret 名称不能同时作为 literal key 出现在顶层 [env] 或任何 [agents.env] 中。

不要把 secret value 放进 [env]、[agents.env] 或 extra_headers。Benchmark config 使用 Osmosis fields，不是 Harbor configuration file。

Training Config

由 osmosis train submit 使用，用于提交训练任务。

configs/training/my-rollout.toml

[experiment]
rollout = "my-rollout"                         # Rollout directory under rollouts/
entrypoint = "main.py"                         # Entrypoint file name
model_path = "Qwen/Qwen3.6-35B-A3B"            # Supported base model
dataset = "my-dataset"                         # Platform dataset name
# branch = "my-feature"                        # 使用已 push 的分支（省略则用默认分支）
# commit_sha = "abc1234"                       # Pin code to a commit

[training]
# lr = 1e-6                                    # Learning rate
# total_epochs = 1                             # Training epochs
# n_samples_per_prompt = 8                     # Rollout samples per prompt
# rollout_batch_size = 32                      # Rollout batch size
# max_prompt_length = 8192                     # Max prompt tokens
# max_response_length = 8192                   # Max response tokens
# agent_workflow_timeout_s = 450               # Agent timeout per row
# grader_timeout_s = 150                       # Grader timeout per row

[sampling]
# rollout_temperature = 1.0                    # Sampling temperature
# rollout_top_p = 1.0                          # Top-p sampling

[checkpoints]
# eval_interval = 10                           # Evaluate every N rollouts
# checkpoint_save_freq = 20                    # Save checkpoint every N rollouts

# [advanced]
# 仅对已明确启用的 accounts 可用；标准 config 必须省略。

# [env]
# LOG_LEVEL = "INFO"                           # Non-secret literal env var

# [secrets]
# required = ["OPENAI_API_KEY"]                # 训练可选；若包含 [secrets]，必须有 `required`

Git Sync 是您 rollout 代码的 source of truth。CLI 会读取您传入的本地 TOML config 值，但 rollout 代码来自已同步的 workspace repository。提交代码修改前，请先 commit 并 push。设置 branch 可使用已 push 的分支，设置 commit_sha 可固定到特定已 push revision；都省略时使用默认分支。

`[experiment]`

字段	类型	是否必填	说明
`rollout`	`str`	Yes	`rollouts/` 下的 rollout 目录名
`entrypoint`	`str`	Yes	Python entrypoint 文件名，通常为 `main.py`
`model_path`	`str`	Yes	受支持 base model path
`dataset`	`str`	Yes	来自 `osmosis dataset list` 的数据集名称
`branch`	`str`	No	使用该已 push 分支的当前 head。与 `commit_sha` 互斥。
`commit_sha`	`str`	No	从 workspace repository 获取的 Git commit SHA。与 `branch` 互斥。

`[training]`

字段	类型	默认值	取值范围	说明
`lr`	`float`	platform default	—	学习率
`total_epochs`	`int`	platform default	>= 1	训练 epochs 数
`n_samples_per_prompt`	`int`	platform default	`1–12`	每个 prompt 生成的 rollout samples 数
`rollout_batch_size`	`int`	platform default	`1–64`	每个 rollout batch 处理的 prompts 数
`max_prompt_length`	`int`	platform default	`1–8192`	最大 prompt tokens
`max_response_length`	`int`	platform default	`1–10240`	最大 response tokens
`agent_workflow_timeout_s`	number	platform default	`30–600`	每行 agent rollout timeout
`grader_timeout_s`	number	platform default	`30–600`	每行 grader timeout

`[sampling]`

字段	类型	默认值	取值范围	说明
`rollout_temperature`	number	platform default	>= 0	rollout 期间的 sampling temperature
`rollout_top_p`	number	platform default	>= 0	Top-p 采样阈值

`[checkpoints]`

字段	类型	默认值	取值范围	说明
`eval_interval`	`int`	platform default	>= 1	每 N 个 rollout steps 评估一次
`checkpoint_save_freq`	`int`	platform default	>= 1	每 N 个 rollout steps 保存一个 LoRA checkpoint

平台会在提交时强制执行这些取值范围。它不会将取值与所选 model 或 backend 进行校验，因此不受支持的组合可能要到 provisioning 或执行阶段才会暴露。

`[advanced]`

仅供 Osmosis 明确启用的 accounts 使用的 backend-specific fields。标准 accounts 和标准 configs 必须省略 [advanced]；未启用的 account 使用时，平台会拒绝。

`[env]` 和 `[secrets]`

使用这些 sections 向 training run 或 evaluation run 期间的 rollout container 注入环境变量。同一套结构同时适用于 training 和 evaluation configs。

小节	取值	适用场景
`[env]`	存在 config 文件中的 literal strings	非 secret 配置
`[secrets].required`	平台 `environment_secret` 记录名列表	API keys 和私有凭证

[env]
LOG_LEVEL = "INFO"

[secrets]
required = ["OPENAI_API_KEY", "DATABASE_URL"]

规则：

[env] keys 必须匹配 ^[A-Z_][A-Z0-9_]*$；[secrets].required 名称必须匹配 ^[A-Z][A-Z0-9_]*$。
同一个名称不能同时出现在 [env] 和 [secrets].required 中。
[env] 中以 _OSMOSIS_ 开头的名称由平台保留，不能使用。
已有 personal 或 workspace secret record 由服务端解析，因此其值不会出现在本地 config 或 CLI 请求中。通过 --secrets-file、进程环境变量或隐藏 TTY prompt 在本地提供的值会随本次提交的 TLS 请求传输，但不会加入 Osmosis secret store 或持久化 run config。
Eval config 必须包含 [secrets]。仅在 evaluation 不需要任何 secret refs 时使用 required = []。
Training config 可以省略 [secrets]。但只要包含该 table，就必须定义 required。

Secrets 有 scope。Workspace secret 在 workspace 内共享；Personal secret 只属于您本人，且会在运行时覆盖同名的 workspace secret。提交引用 secrets 的 run 之前，先用 osmosis secret set 注册它们。

从只填写 [experiment]（以及 eval config 的 [secrets]）开始，让平台使用训练默认值。仅在需要调优训练任务时添加可选字段。

开始使用

运行

工作区

参考

Eval Config

`[experiment]`

`[evaluation]`

`[env]` 和 `[secrets]`（eval）

Benchmark Config

`[experiment]`（benchmark）

`[tasks]`

`[[agents]]` 和 `[agents.model]`

`[execution]`

`[secrets]`

`[verifier]`

Training Config

`[experiment]`

`[training]`

`[sampling]`

`[checkpoints]`

`[advanced]`

`[env]` 和 `[secrets]`

​Eval Config

​[experiment]

​[evaluation]

​[env] 和 [secrets]（eval）

​Benchmark Config

​[experiment]（benchmark）

​[tasks]

​[[agents]] 和 [agents.model]

​[execution]

​[secrets]

​[verifier]

​Training Config

​[experiment]

​[training]

​[sampling]

​[checkpoints]

​[advanced]

​[env] 和 [secrets]

Eval Config

`[experiment]`

`[evaluation]`

`[env]` 和 `[secrets]`（eval）

Benchmark Config

`[experiment]`（benchmark）

`[tasks]`

`[[agents]]` 和 `[agents.model]`

`[execution]`

`[secrets]`

`[verifier]`

Training Config

`[experiment]`

`[training]`

`[sampling]`

`[checkpoints]`

`[advanced]`

`[env]` 和 `[secrets]`