配置 · ocra

ocra 从被审查仓库根目录的 .ocra/config.json 读取配置。所有字段都是可选的；未知字段会直接报错，避免拼写错误被悄悄忽略。

ocra review --config <文件> 改为读取你自己的一个文件，放在哪里都行：CI 的检出目录、你的家目录。它是你信任的文件，所以和 --no-repo-config 一起用也生效；审查不信任的代码（比如评测工具）时，声明的模型端点和各种上限就是这样传进去的。它列出的插件从文件所在目录解析。与 --pr、--mr 一起用时，它代替 base 分支的那份文件；插件在那里照样不加载。

{
  "$schema": "https://raw.githubusercontent.com/jma49/Open-CR-Agent/main/docs/schema/config.v1.json",
  "models": {
    "top": "google/gemini-3.1-pro-preview",
    "standard": ["google/gemini-3.5-flash", "google/gemini-flash-lite-latest"],
    "light": "google/gemini-flash-lite-latest"
  },
  "concurrency": 4,
  "taskTimeoutMinutes": 10,
  "runTimeoutMinutes": 25,
  "verify": true,
  "judge": true,
  "maxCostUsd": 1,
  "include": [],
  "exclude": ["legacy/**"],
  "runtime": "opencode",
  "plugins": [],
  "reviewers": {},
  "pluginSettings": {}
}

可选的 $schema 字段让编辑器使用这个文件的 JSON Schema（draft 2020-12，由代码生成并经测试核对），输入时就能补全字段、标出未知字段和错误的值；ocra 本身忽略这个字段。

模型

模型写成 provider/model，provider 使用 OpenCode 的供应商 ID（例如 google、anthropic、openai）。每个层级可以写一个模型，也可以写一条降级链：

层级	用途
`standard`	审查员 agent
`light`	辅助调用，比如给改动文件分组
`top`	Judge（最终裁决）

模型过载或拒绝请求时，任务会换到链上的下一个模型重试。遇到限流且供应商给出了较短的等待时间（最多 90 秒）时，所有任务都会暂停使用这个模型，等完再重试；如果限流标明是按天计算、等待时间更长或没有给出，或者连续第四次被限流，这个模型在本次运行里就不再使用。每个模型都有熔断器：连续失败两次后跳过一分钟，然后放行一个请求试探；成功就恢复，再失败就跳过两倍时长（最多十分钟）。凭证错误会立即停止，因为同一供应商的其他模型也会失败。

环境变量会覆盖配置文件，降级链用逗号分隔：

export OCRA_MODEL_STANDARD="google/gemini-3.5-flash,google/gemini-flash-lite-latest"
export OCRA_MODEL_LIGHT="google/gemini-flash-lite-latest"
export OCRA_MODEL_TOP="google/gemini-3.1-pro-preview"

推理强度

当前大多数模型都可以指定回答前推理多少。effort 按层级设置，reviewers.<id>.effort 设置单个审查员（包括它的审查任务和计划调用），roles.<role>.effort 设置 verifier（核验）、judge（裁决）或 helper（辅助调用：给文件分组、重新定位引用的代码）。可选级别为 none、minimal、low、medium 和 high。每个 agent 先用自己的设置，没有就用它所在层级的设置（审查员按自己的层级，verifier 为 standard，judge 为 top，helper 为 light）；verifier 和 judge 从不沿用审查员的设置。不设置时什么都不发送，使用供应商的默认值。

{
  "effort": { "standard": "medium", "top": "high" },
  "reviewers": { "security": { "effort": "high" } },
  "roles": { "helper": { "effort": "minimal" } }
}

OCRA_EFFORT_TOP、OCRA_EFFORT_STANDARD 和 OCRA_EFFORT_LIGHT 会覆盖对应层级的设置。

direct 运行时把级别作为 reasoning_effort 发送；对声明了 "effort": "openrouter" 的供应商，则发送 reasoning: { effort }（见模型供应商）。none 按 none 发送。发送其他级别的调用不再发送 temperature 和 seed：推理模型会拒绝或忽略它们。如果端点返回 HTTP 400 并点名这个参数，这次调用会去掉它重发一次，不算作模型失败；这个模型之后的调用都不再带它，运行结束时给出警告。
opencode 运行时暂时还不发送推理强度；运行会给出警告，并记为未应用。
JSON 报告的 provenance.agents 列出每个 agent 的层级、推理强度、是否已应用（applied），以及它的调用没有发送的采样设置（notApplied）。--plan 会显示每个任务的推理强度。配置哈希也覆盖推理强度。

供应商 key

key 只从环境变量读取，变量名用 OpenCode 里各供应商对应的名字，例如 ANTHROPIC_API_KEY、OPENAI_API_KEY。Google 支持 GEMINI_API_KEY、GOOGLE_API_KEY 和 GOOGLE_GENERATIVE_AI_API_KEY。

agent 运行时只会从你的环境里拿到它需要的东西：PATH、HOME、语言区域、代理和 CA 设置，以及模型链里用到的供应商的凭据（ocra 不认识的供应商，会拿到所有以其大写 id 开头的变量，例如 groq 对应 GROQ_）。其余的，比如云服务凭据或 GITHUB_TOKEN，都不会传过去。如果某个供应商还需要别的变量，把变量名写进 OCRA_RUNTIME_ENV，用逗号分隔。

对于一定需要 key 的供应商（Google、Anthropic、OpenAI、OpenRouter、Groq、Mistral、DeepSeek、xAI、Azure），ocra 会在启动前检查 key 是否已设置，缺失时会指出该设置哪个变量。

要接入你自己的服务，或兼容 OpenAI API 的公司网关，请在 providers 下声明；哪些供应商可用、各自需要什么，见模型供应商。

执行参数

字段	默认值	含义
`concurrency`	`4`	同时运行的审查任务数（1–32）
`taskTimeoutMinutes`	`10`	单个审查任务的时间上限
`runTimeoutMinutes`	`25`	整次运行的时间上限
`maxCostUsd`	无	本次运行的花费上限：审查任务最多用到 80%，剩下的留给核查和裁决（见 `--max-cost-usd`）
`maxTasks`	`60`	一次运行最多启动的审查任务数。超出时先去掉 `--ultra` 的第二遍，再去掉排在后面的审查员，尽量让每个文件至少保留第一个审查员；被跳过的文件报告为未审查（退出码 `3`）
`judge`	`true`	跨审查员合并、过滤并校准问题（每次有问题的运行调用一次 top 档位模型）
`verify`	`true`	报告前逐条核查问题（每个有问题的文件调用一次 standard 档位模型）
`sampling`	无	`{ "temperature": 0–2, "seed": n }`，用于每次模型调用；两项都可以省略，不设置时用各供应商的默认值。`--temperature` 和 `--seed` 会覆盖它。`direct` 运行时两项都会发送。`opencode` 运行时把温度设在它的 agent 上，OpenCode 只在模型目录标明该模型接受温度时才传下去（ocra 会给你声明的模型加上这个标记）；它没有种子设置，所以种子会报告为未应用。JSON 报告的 `provenance.sampling` 写明实际应用了什么。种子只有在供应商遵守它时才能让运行可重复

某个任务失败或超时不会导致整次运行失败，它负责的文件会被标记为 failed。

文件选择

ocra 会跳过：二进制文件、疑似密钥文件（.env、私钥、证书、云服务和镜像仓库凭据、Terraform 变量和状态文件）、已删除的文件、媒体和压缩包、锁文件、第三方和生成的代码，以及过大的 diff。超过 1 MB 的文件按二进制处理并跳过。数据库迁移文件不会被当作生成代码跳过（其他规则照常生效）。

exclude：额外要跳过的 glob。
include：即使会被当作生成代码或按扩展名跳过，也要审查的 glob。密钥文件永远无法被 include。

审查员

reviewers.<id> 可以关闭某个审查员，设置它开始运行的风险档位（可以比默认高，也可以更低），或设置它的推理强度。风险档位从低到高：trivial（改动 ≤10 行）、lite（≤100 行）、full（更大的改动、超过 20 个文件，或涉及敏感路径：CI workflow，或目录名、文件名中含有 auth、oauth、jwt、password、credential、secret、login、permission、acl、identity、crypto、security 等单词）。

{ "reviewers": { "correctness": { "minTier": "lite" }, "security": { "enabled": false } } }

被 Matrix 跳过的组合会列在 JSON 报告的 skipped 里；没有任何审查员覆盖的文件在覆盖情况里显示为 unreviewed。

共享配置

组织可以把通用设置放在一处，让各个仓库继承：

{ "extends": "https://config.example.com/ocra.json#sha256=<hex>" }

共享文件可以设置 models、concurrency、超时、verify、judge、maxCostUsd、maxTasks、include、exclude、effort、reviewers、roles、github、providers（必须固定内容，见下文）和 rules（格式与 .ocra/rules.json 的条目相同）。它不能列出插件，也不能选择运行时：它来自仓库之外，不能执行代码。仓库自己的设置优先；include、exclude 和 rules 会合并，models、effort、reviewers、roles、github 和 providers 按键合并。

只接受 https 地址，不跟随重定向，最大 256 KB。可选的 #sha256= 片段会固定文件内容；声明了 providers 的文件必须固定，因为供应商决定了你的代码发往哪里（见模型供应商）。文件无法加载或内容无效时，ocra 会给出警告，然后继续使用仓库自己的设置；只写在共享文件里的限制（例如 maxCostUsd）这时就不生效，必须始终生效的限制请在仓库里也写一份。

插件

runtime 指定使用哪个已注册的运行时：opencode（默认）通过 OpenCode 运行审查员，能用它目录里的所有供应商；direct 自己调用 providers 下声明的端点，不访问其他任何地址（见模型供应商）。plugins 按包名或路径列出额外的插件，pluginSettings.<插件名> 存放各插件自己的设置。详见插件。

配置

模型复制链接

推理强度复制链接

供应商 key复制链接

执行参数复制链接

文件选择复制链接

审查员复制链接

共享配置复制链接

插件复制链接

本页目录

模型

推理强度

供应商 key

执行参数

文件选择

审查员

共享配置

插件