> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbi.build/llms.txt > Use this file to discover all available pages before exploring further. # 配置参考 > 每个 orbi.toml 设置的作用和默认值是什么? # 配置参考 Orbi 从部署 home 读取 `orbi.toml`；设置 `ORBI_CONFIG` 可选择其他文件。相对路径相对该文件解析。启动 tick 前运行 `orbi check` 校验配置。 ## 仓库与路径 | Key | Type | Default | Allowed values | Meaning | | --------------------- | ----- | ---------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source_repos` | 字符串列表 | 必填 | 非空 `owner/repo` | 每个 tick 扫描的一个 `owner/repo` 任务池。多个条目会因当前执行层只有一个 checkout 而 fail fast；多仓库 workspace 尚未提供（Issue #133） | | `repo_dir` | 路径 | `.` | 任意路径 | 交付 checkout：Runner 交付 Issue 的仓库。任务 worktree 从它冻结的 `origin/` SHA 创建，PR 对它打开，slot 锁在 `/.orbi/slots/`。自举模式下它就是 orbi checkout 自身；外部单仓库模式（Issue #330）下是外部用户仓库 X | | `deploy_home` | 路径 | `repo_dir` | 任意路径，必须存在 | orbi **源码** checkout（Issue #330）：editable CLI 安装来源（自更新）、`systemd/` unit 模板、`labels.toml`、prompt 默认（`prompts/prompt.md`、`prompts/prompt_review.md` 未设置时）。缺省 = `repo_dir`（自举模式，行为不变）。`repo_dir` 是外部仓库 X 时把它设为 orbi checkout。必须是非空字符串；目录不存在会启动 fail fast | | `workspace_root` | 路径 | `..` | 任意路径 | 包含任务 worktree 和 agent 可修改仓库的目录 | | `base_branch` | 字符串 | `main` | 任意非空字符串 | 交付 base 分支；每个任务 worktree 都从冻结的 `origin/` SHA 创建 | | `git_transport` | 字符串 | `ssh` | `ssh \| https` | 交付 checkout 的传输方式（Issue #580）。`ssh`（默认）：git 数据操作走 `git@github.com:owner/repo.git`，用机器的 SSH key；setup 会把 HTTPS origin 迁移过去。`https`：origin 保持 `https://github.com/.git`，`git ls-remote`/fetch/push 的凭据走 `gh` credential helper（`gh auth login --with-token`）——无 SSH 私钥的纯 token sandbox 路线。其他值直接让配置加载失败 | | `engine_source_track` | 字符串 | `main` | `main`、`branch:`、`release`、`tag:` 或 `sha:<40-hex>` | engine source 更新通道（Issue #535，host/deploy-only——仓库的 `.github/orbi.toml` 永远不允许携带）：每次 service 启动时 deploy home checkout 跟随的源。缺省/`main`：fast-forward `origin/main`（#535 之前 dogfood 的行为）——开发主线，每次提交都变。`branch:`：fast-forward `origin/`。`release`（别名 `stable`）：最新正式 semver tag（排除 pre-release），detached——跟随最新已发布版本，只在发版时变化。`tag:`/`sha:<40-hex>`：精确锁定，detached——不改值就永不移动，版本变更永远是一次有意操作（要求可复现的部署用它锁定）；回滚就是把值改回去。checkout 脏、tag/SHA 缺失或任何不可验证状态都会以结构化行让启动失败（见[运维](/zh/operations)） | | `allow_stale_runner` | 布尔值 | `false` | `true \| false` | Runner 执行代码新鲜度门禁的离线逃生口（Issue #525）：领取任何 Issue 之前，Runner 必须证明自己执行的代码与配置的 engine source 通道一致——即 `engine_source_track`（Issue #535），缺省 `origin/main`，绝不是交付 `base_branch`（editable 安装看 import 所在 checkout 的 `HEAD`；非 editable 看安装版本与最新 release tag——全部是本地 git 读操作）。落后或无法证明时输出结构化 `runner_source_stale` 行（事实 + 修复命令）并 fail fast。`true` 把同一行降级为告警放行，供离线/受限网络机器继续运行——绝不跳过检查。非法值立即失败 | ## 调度 | Key | Type | Default | Allowed values | Meaning | | ----------------------- | ----- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `max_concurrency` | 整数 | `1` | `1`–`5` | 本机并发 Orbi 任务数和启用的 Runner timer 数（`1`..`5`，即 `MAX_RUNNER_INSTANCES` 声明上限——Issue #827；实际能稳定跑几条取决于 CPU/内存峰值，调高前先实测） | | `unit_name` | 字符串或空 | 未设置 | 字母、数字、`-`、`_` | 可选的部署专用 systemd unit 前缀。 | | `active_milestone` | 字符串或空 | 未设置 | 任意非空字符串 | 新领取扫描的领取范围（Issue #139）：当前活跃的 GitHub Milestone 标题（如 `v0.2.0`）。设置后 p0/bug/普通三个 ready 扫描只领取该 Milestone 的 Issue（`milestone:""` 限定词直接进 gh 搜索查询——其他 Milestone 或无 Milestone 的 Issue 永远进不了队列）；`ai-ready` 仍是执行开关，领取顺序（p0 → bug → 普通）不变，P0 不跨 Milestone，恢复态（已开 PR、在途重启）不受 Milestone 限制。唯一例外是外部接管扫描（Issue #842 决策 D1）：第五条、排最后的 ready 扫描不带 Milestone 限定，带正文标记 `<!-- orbi:external-pr:N -->` 的外部 triage 票始终可被认领——外部贡献不属于任何版本的范围，绝不能阻塞发版门禁。未设置 = 所有 `ai-ready` Issue 都可领取（#139 之前的行为）。用 `orbi milestone set <title>` 推进（见[运维](/zh/operations)；Runner 下一 tick 发布 `ORBI_ACTIVE_MILESTONE` variable） | | `auto_next_milestone` | 布尔值 | `true` | `true \| false` | 当前 Milestone 关闭且队列为空时是否自动推进。`false` 保持 `active_milestone` 不变，记录待确认告警并创建一个不带 `ai-ready` 或 `p0`、不会被领取的确认 Issue；人工推进后旧通知会自动关闭。非法值立即失败 | | `worktree_retain_hours` | 数字 | `72` | 有限正数 | tick 开头任务 worktree 回收的保留窗口（Issue #760，仅宿主/部署侧——仓库的 `.github/orbi.toml` 不可携带）：已关闭超过该小时数的任务 worktree 会被自动移除（OPEN 的票和有活跃 run 的现场绝不触碰）。机制与 `worktree_reclaimed` journal 行：[运维](/zh/operations)。必须是有限正数小时，否则启动 fail fast | ## 模型 provider | Key | Type | Default | Allowed values | Meaning | | -------------------------- | ------ | ------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pi_providers` | 路径或空 | 未设置 | provider JSON 文件路径 | 指向 Pi `models.json` 形状 JSON 文件的路径，为每个 run 向 Pi 目录添加或覆盖 provider（Issue #157）。未设置 = Pi 原样使用自己的 agent 目录（第 4 步） | | `pi_provider` | 字符串或空 | 未设置 | 任意非空字符串 | 每个 run 选用的 provider id（Issue #119）——以 `--provider` 传给 Pi；设置 `pi_providers` 文件时必须已在其中定义 | | `pi_model` | 字符串或空 | 未设置 | 任意非空字符串 | 选中 provider 内的 model id——以 `--model` 传给 Pi；必须存在于该 provider 的 `models` 列表 | | `pi_thinking` | 字符串或空 | 未设置 | `off \| minimal \| low \| medium \| high \| xhigh \| max` | 以 `--thinking` 传给 Pi 的思考级别（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`） | | `pi_extensions` | 表列表 | `[]` | 锁定的 `npm:`/git 来源或已有本地路径 | 可重复的 extension 表：`source` 必须是锁定版本的 `npm:`/git 来源或配置文件相对的现有本地路径；`enabled` 默认开启，`env` 只注入当前 Pi 子进程。每次运行都传入 `--no-extensions`，不会发现全局 Pi extension。 | | `review_pi_provider` | 字符串或空 | 未设置 | 任意非空字符串 | 评审会话的 provider 覆盖；未设置时回落到 `pi_provider` | | `review_pi_model` | 字符串或空 | 未设置 | 任意非空字符串 | 评审会话的模型覆盖；未设置时回落到 `pi_model` | | `review_pi_thinking` | 字符串或空 | 未设置 | 同 `pi_thinking` | 评审会话的思考级别覆盖；未设置时回落到 `pi_thinking` | | `model_wait_probe_url` | URL 或空 | 未设置 | 非空 `http://` 或 `https://` URL | 模型吞请求探针（Issue #233）：模型的 `/slots` 端点（如 `http://127.0.0.1:18082/slots`，agent 面向的端口——local-llm-kv-cache 代理从 llama.cpp 透传该端点）。Pi 冻结在 `model_wait` 时 Runner 探测它，所有 slot 持续 `model_wait_probe_seconds` 宽限空闲时快速杀掉 Pi 会话。字段语义（吞请求现场、旁路边界）：[运维](/zh/operations) 的 `model_wait_swallowed` journal 行。未设置 = 探针禁用（#233 之前的行为）。必须是非空 `http://`/`https://` URL，否则启动 fail fast | | `model_wait_probe_seconds` | 数字 | `60` | 有限正数 | 吞请求探针的持续空闲宽限（Issue #233）：`model_wait` 期间“所有 slot 空闲”状态需持续多少秒才判定请求被吞并杀掉 Pi。必须是有限正数，否则启动 fail fast | | `model_wait_dead_seconds` | 数字 | `1800` | 有限正数 | 模型请求挂死阈值（Issue #228）：`model_wait` 静默多少秒后 Runner 杀掉 Pi 会话并 fail fast。字段语义（完整事件之间的静默、慢生成边界）：[运维](/zh/operations) 的 `model_wait_dead` journal 行。必须是有限正数，否则启动 fail fast | 这三行 `review_pi_*` 配置让独立评审运行在与实现不同的模型上——见 [Reviewing with a different model](/zh/workflow)。 ## Prompt 与上下文 | Key | Type | Default | Allowed values | Meaning | | -------------------- | ---- | -------------------------- | ---------------- | -------------------------------------------------------------- | | `prompt` | 路径 | `prompts/prompt.md` | 任意路径 | 实现者 prompt 模板（`{{SOURCE_REPO}}` 等占位符由 Runner 渲染） | | `prompt_review` | 路径 | `prompts/prompt_review.md` | 任意路径 | PR 后独立审查 session 的 review prompt 模板 | | `skills` | 路径列表 | `[]` | 绝对、`~` 或相对配置文件路径 | 可选 Pi skill 路径（绝对、`~`，或相对配置文件） | | `context_files` | 路径列表 | `[]` | 路径 | 可选 Markdown 上下文文件，以路径形式注入 prompt | | `attribution_footer` | 布尔值 | `true` | `true \| false` | 在 Orbi 创建的 PR 正文和 Release notes 末尾追加一行回链；设为 `false` 可关闭，必须是布尔值 | ## 交付行为 | Key | Type | Default | Allowed values | Meaning | | --------------------------------- | ----- | ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dispatch_label` | 字符串或空 | 未设置 → `ai-ready` | 任意非空字符串 | 仓库策略使用的 ready 标签，见[仓库配置](/zh/workflow)。 | | `human_review_gate` | 布尔值 | `false` | `true \| false` | 人工验收门禁（Issue #763，仅宿主/部署侧——仓库的 `.github/orbi.toml` 不可携带）：`true` 时每个交付在 PR 打开时向 Issue 发一条验收清单（栏一：本次 run 已验证的证据——真实测试结果与覆盖层；栏二：按改动路径生成的机器验不了的最小集合——业务意图、UI 视觉与文案、外部环境、证据缺失）。栏二非空时评审轮次在任何 Pi session 之前短路：票回 `ai-ready`（opened-PR 标签保留作 resume 锚）、槽位释放，此后每个 tick 只花一次 label 读——等待绝不消耗评审轮次预算。人用只有人能打的 `ai-human-review` 标签确认清单，下一 tick 照常评审/合并（`--match-head-commit` 零改动）。栏二为空是目标状态：清单明写无需人工介入，交付不要求标签直接通过。默认关闭：关闭时交付/评审/merge/release 与之前逐字节一致。必须是布尔值，否则配置加载立即失败 | | `issue_comments_limit` | 整数 | `20` | 正整数 | 受信任评论注入上限（Issue #745，仅宿主/部署侧——仓库的 `.github/orbi.toml` 不可携带）：`{{ISSUE_COMMENTS}}` 占位符注入多少条受信任评论（OWNER/MAINTAINER/MEMBER/COLLABORATOR 或 runner 自己的 App——与恢复现场同一套 `authorAssociation` 信任判据），按时间正序、保留最新。超出上限时丢弃更早的，并在注入内容里标明省略条数——绝不静默截断。模板不含该占位符时不发起任何评论读取（#745 之前的行为）。必须是正整数，否则启动 fail fast | | `release_ci_wait_seconds` | 数字 | `1800` | 有限正数 | release 门禁 CI 上限（Issue #268）：release 状态机在 tick 内等待 release commit 上 pending（queued/in\_progress）检查的最长时间，超时以独立原因失败——它只是 release 机的纯上限保护，绝不是交付等待机制（Issue #788 已移除交付路径的 CI 等待：pending 检查把交付顺延到下一 tick）。等待期间以 `release_waiting_ci` journal 行和进度评论更新可见；最终结论说了算。必须是有限正数，否则启动 fail fast | | `release_deliveries_wait_seconds` | 数字 | `1800` | 有限正数 | release 等待未完成交付的上限。 | ## Steering Steering 让 Runner 轮询 Issue 中的受信任修正，并带着修正重启正在进行的交付。`steering_max_rounds` 限制重启次数，避免交付被无限重定向。轮询失败属于纯旁路：会记录日志，但绝不会让交付失败。 详见 Operations 中的 [`delivery_steered`、`steering_limit_reached`、`steering_poll_failed`](/zh/operations) 行。 | Key | Type | Default | Allowed values | Meaning | | ----------------------- | ---- | ------- | --------------- | ---------------------- | | `steering_enabled` | 布尔值 | `true` | `true \| false` | 启用受信任的 Issue 修正轮询。 | | `steering_poll_seconds` | 数字 | `60.0` | 有限正数 | Steering 轮询间隔。 | | `steering_max_rounds` | 整数 | `3` | 非负整数 | 每个交付最多重启的 Steering 次数。 | ## Health | Key | Type | Default | Allowed values | Meaning | | ------------------- | ----- | ------- | ----------------- | ----------------------------------------------------------------------- | | `health_alert_repo` | 字符串或空 | 未设置 | 任意非空 `owner/repo` | 接收 Runner crash-loop/stale-pickup 健康 Issue；未设置时从 deploy-home origin 推导。 |