设置

Web UI 的 设置 页编辑的是 munk serve 当前生效的 config.yaml。同一份配置也会被共享本地编排主机的 CLI、MCP 等入口使用。

第一次不必填满所有字段。先配好全局 Provider，再按实际工作流按需打开下面的模块。

配置文件在哪里

设置页始终读写配置发现链中 当前生效 的那一份文件：

1. CLI 的 --config
2. 环境变量 MUNK_CONFIG
3. <workspace>/.munk/config.yaml
4. <Munk Test profile home>/config/config.yaml

页面顶部会显示解析后的路径。用 刷新 从磁盘重新加载，用 保存 把表单写回该文件。

shared 与 local 分层

config.yaml 使用两个顶层区块：

运行时生效配置是 deep_merge(shared, local)。云端 Pull 只会替换 shared，并保留本机 local。旧的扁平文件仍可读取；在设置页保存（或成功 Pull）后，会重写为上述分层结构。

模块说明

全局 Provider

这是整个产品默认使用的模型连接。

• 只能选择一个生效 Provider：openai_compatible 或 gemini。
• 两个 Provider 区块都可以保留在配置里作为备用，但运行时只会使用当前选中的那一个。
• 常见字段包括接口地址、模型 ID、API Key，以及超时、额外请求头、Vertex AI 等高级选项。

首次上手时，把生效 Provider 的 base_url / model / api_key（或 Gemini 对应字段）填好并保存，就足够生成 plan 和跑 case。

Agent Overrides

每个角色都可以选择不继承全局 Provider，改用自己的模型配置：

角色未启用 override 时，会自动回退到全局 Provider。只有当某个角色需要不同模型、接口或密钥时，再单独开启。

编排策略

控制 Judge 给出结论后的 case 级重试策略：

• 允许自动重试多少次
• failed / inconclusive 是否可以进入重试分支
• 重试额度用尽后，是直接结束还是升级处理

适合在不稳定 UI 流程上提高容错，或在 CI 中收紧为更快失败。

代理

让外部 Python 与 LLM 请求走本地 HTTP / SOCKS 代理。

当你的网络必须通过代理才能访问模型服务时再开启。本机地址默认直连，也可以维护一份 no-proxy 白名单。

iOS Bridge

为 iOS 真机 bridge 配置 sudo 启动，主要用于 iOS 18+ 的 tunnel 创建。

只有在本机创建设备 tunnel 需要提权时，才开启 sudo 启动。密码会写入 config.yaml 的 local.ios_bridge，在共享机器上请把该文件当作敏感信息处理。

完整的 iOS 真机准备流程见 iOS 真机环境准备。

测试环境

登记 TestCase.setup 在正式执行前可引用的共享资源：

• HTTP bases：具名后端地址（URL + 可选默认请求头），供 setup 的 http 步骤通过 base 引用
• Allowed executables：允许在 setup 的 command 步骤中执行的命令名

这个模块用于准备测试数据或后端状态，不负责模型路由。case 侧如何声明 setup 步骤，见 核心概念 · 测试用例。

Runtime

为 start、run case、run plan、verify change 提供共享的执行默认值。设置页按三组展示：

• Generation：模型输出规模与采样风格
• Execution Loop：步数 / 时长上限、轮询节奏与 settle 等待
• Vision：截图尺寸与感知阈值

大多数场景保持默认即可。当你发现执行过短、过慢，或视觉输入需要不同图片尺寸时，再按需调整。

推荐配置顺序

1. 先配好 全局 Provider 并保存。
2. 跑一个简单的 plan 或 case，确认模型通路可用。
3. 只有网络或设备路径需要时，再加 代理 或 iOS Bridge。
4. 当 case 需要 HTTP / exec setup 步骤时，再配置 测试环境。
5. 有真实运行反馈后，再微调 编排策略 和 Runtime。

参考 config.yaml

把下面的示例复制到 <workspace>/.munk/config.yaml（或你当前生效的配置路径），再把占位密钥和地址换成自己的值。

shared:
  provider: openai_compatible
  openai_compatible:
    base_url: https://openrouter.ai/api/v1/
    model: google/gemma-4-26b-a4b-it
    timeout_sec: 60.0
    extra_headers: {}
    output_strategy: auto
    thinking: false
  gemini:
    vertexai: false
    model: gemini-2.5-flash
    base_url: https://generativelanguage.googleapis.com/
    timeout_sec: 60.0
  agents:
    runner:
      provider: openai_compatible
      openai_compatible:
        base_url: https://openrouter.ai/api/v1/
        model: google/gemma-4-26b-a4b-it
        timeout_sec: 60.0
  runtime:
    max_tokens: 16384
    temperature: 0.2
    max_steps: 30
    max_seconds: 300.0
    interval: 0.2
    settle_timeout: 6.0
    settle_mode: ratio
    settle_ocr_only: true
    settle_ratio_threshold: 0.1
    settle_delay_sec: 1.0
    max_side: 1024
    vl_max_side: 768
    icon_conf: 0.12
    runner_include_screenshot: true
  orchestration:
    max_retry_attempts: 1
    allow_retry_on_failed: true
    allow_retry_on_inconclusive: true
    escalate_after_max_attempts: false
  test_env:
    bases:
      test_backend:
        url: http://127.0.0.1:8080
        headers:
          Accept: application/json
    allowed_exec:
    - echo
    - python
local:
  openai_compatible:
    api_key: sk-or-v1-your-api-key
  gemini:
    api_key: your-gemini-api-key
  agents:
    runner:
      openai_compatible:
        api_key: sk-or-v1-your-api-key
  proxy:
    enabled: false
    url: http://127.0.0.1:7890
  ios_bridge:
    sudo_enabled: false
    sudo_password: your-local-sudo-password

说明：

• 只保留你需要的区块即可。最小可用配置可以是 shared.provider 加上一个 Provider section，并把对应 api_key 放在 local。
• agents 是可选的；如果所有角色都继承全局 Provider，可以直接删掉。
• 密钥只放在 local。不要把真实 API Key 或 sudo 密码提交到共享仓库。
• 旧的扁平文件仍可读取；若要配合云端同步，请优先使用上面的分层格式。