跳转到主要内容
Modal 是用于云端 sandbox 的 remote environment provider。它适合 SWE-bench 和 Terminal-Bench 这类任务元数据中已经包含兼容 registry image 的 workload。

​
官方设置入口

需求链接
创建 Modal 账号Modal signup
用户账号设置文档Modal user account setup
创建自动化 tokenModal service users
Token 配置参考Modal token config
Token 设置页面Workspace token settings

​
首次设置

  1. 从官方 signup 页面创建 Modal 账号。
  2. 在运行 AgentCompass 的机器上配置 Modal credentials。
  3. 导出 MODAL_TOKEN_ID 和 MODAL_TOKEN_SECRET，或者让 Modal CLI 把 credentials 写入 ~/.modal.toml。
  4. 先跑单个 AgentCompass task，再提高并发。
本地开发通常可以直接走 Modal CLI setup： 
modal setup
自动化 runner 或 shared workspace 推荐创建 service user token，然后放在 shell 或 CI secret store 中： 
export MODAL_TOKEN_ID="..."
export MODAL_TOKEN_SECRET="..."
AgentCompass 的 Modal 鉴权优先级是：
来源适用场景
environments.modal.token_id 和 token_secret明确把凭据放在私有 --config 文件中。
MODAL_TOKEN_ID 和 MODAL_TOKEN_SECRET推荐用于 shell session、CI 和共享脚本。
~/.modal.toml本地开发中通过 modal setup 或 modal token set 配置后的默认路径。
不要把 Modal token 提交到 config/defaults.yaml。请使用环境变量，或通过 --config 传入私有配置文件。

​
验证凭据

先用 Modal CLI 验证当前 credentials： 
modal token info
然后用 AgentCompass 跑一个 recipe-backed 单任务：

​
SWE-bench Verified

agentcompass run \
  swebench_verified \
  mini_swe_agent \
  your-model \
  --env modal \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
SWE-bench Modal recipe 会从任务元数据选择镜像，并把 workspace root 设置为 /testbed。通常不需要手动传 image 或 memory。

​
完整 benchmark 与并发

agentcompass run \
  swebench_verified \
  mini_swe_agent \
  your-model \
  --env modal \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --task-concurrency 32
如果模型 endpoint、Modal 账号限制或镜像启动时间成为瓶颈，请降低并发。

​
Provider 参数

常见 Modal 覆盖项可以放在 environments.modal 或 --env-params：
Field作用
app_name把 AgentCompass sandboxes 归到一个 Modal App 下。
environment_nameworkspace 使用 Modal Environments 时，指定 sandbox 所属 environment。
image不希望 recipe 选 image 时，手动使用 registry image。
named_image使用已发布的 Modal named image。
timeout / idle_timeout控制 sandbox 最大生命周期和 idle shutdown。
cpu, memory, gpu, region为重型任务请求资源或 placement。
env_variables向 sandbox 注入非 secret 环境变量。

​
Image 覆盖

只有明确要覆盖 recipe 行为时才使用 image 或 named_image。 
agentcompass run <benchmark> <harness> <model> --env modal --env-params '{"image":"python:3.13-slim"}'

​
相关页面