配置
.ocra/config.json 配置文件与环境变量。
ocra 从被审查仓库根目录的 .ocra/config.json 读取配置。所有字段都可选;未知字段直接报错,拼写错误不会被悄悄忽略。
ocra review --config <文件> 改为读取你自己的文件,放在哪里都行。它是你信任的,所以和 --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 秒时,所有任务暂停使用这个模型,等完再重试;没给出等待的限流依次暂停 15、30、60 秒。暂停期间到达的限流(比如同时运行的任务一起被拒)算作同一次暂停。按天限流、等待更长,或连续暂停三次后再次限流,这个模型在本次运行里就不再使用。每个模型都有熔断器:连续失败两次后跳过一分钟,再放行一个请求试探;成功就恢复,失败则暂停时长加倍(最多十分钟)。凭证错误立即停止,因为该供应商的其他模型也会失败。
环境变量会覆盖配置文件,降级链用逗号分隔:
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"按 agent 指定模型
reviewers.<id>.models 为单个审查员指定自己的模型或降级链(审查任务和计划调用),roles.<role>.models 为 verifier、judge 或 helper(给文件分组、重新定位引用的代码)指定。写法与层级相同。没有设置的 agent 用所在层级的链;verifier 和 judge 从不沿用审查员的链,核查因此保持独立。
{
"models": { "standard": "google/gemini-3.5-flash", "top": "google/gemini-3.1-pro-preview" },
"reviewers": { "security": { "models": ["anthropic/claude-sonnet-5-5", "google/gemini-3.5-flash"] } },
"roles": { "helper": { "models": "google/gemini-flash-lite-latest" } }
}降级、限流暂停和熔断器都按模型计算,同一个模型出现在两条链里时共用一个熔断器。审查前的检查也覆盖这些链:供应商的 key 必须已设置,自行声明的供应商的模型必须有价格,ocra-<provider>/ 模型经由 ocra Cloud。忽略 agent 模型链的插件运行时使用层级的链。JSON 报告的 provenance.agents 记录每条实际使用的链,--plan 显示每个任务的链,配置哈希也覆盖它们。
推理强度
即模型回答前推理多少: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把级别写进模型的供应商参数:OpenAI 推理模型(GPT-5、o 系列)用reasoningEffort,Claude 4 及以后和 Gemini 2.5 用思考预算(thinking budget),Gemini 3 用thinkingLevel;OpenRouter 模型和声明的供应商按各自的effort接收。思考预算取 OpenCode 目录中该模型输出上限的一定比例(minimal1/32、low1/16、medium1/4、high1/2;Claude 至少 1,024 个 token,Gemini 不超出它自己的范围),没有上限时按 32,000 个 token 计算;none关闭思考(Claude 不思考,Gemini 2.5 Flash 预算为 0)。每个模型的每个级别是独立的 OpenCode variant,共用一个模型的 agent 可以用不同级别。和direct一样,none以外的级别不带配置的temperature。其他供应商(Azure、Bedrock、Groq 等)不发送推理强度。- 模型接受哪些级别来自 ocra 内置的一张表(
@open-cr-agent/core的effortCapability),可能跟不上新模型:在opencode上,表里没为某模型列出的级别(例如 o3 的minimal、Gemini 3 的medium)或不认识的模型不带推理强度,每个 agent 警告一次。审查不会因此失败。启动时读不到 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)。各供应商的变量,以及如何在 providers 下声明你自己的端点,见模型供应商。
agent 运行时只拿到 PATH、HOME、语言区域、代理和 CA 设置,以及模型链里供应商的凭据(ocra 不认识的供应商,拿到所有以其大写 id 开头的变量,例如 GROQ_)。云服务凭据、GITHUB_TOKEN 等其余变量都不会传过去;供应商还需要的变量,写进 OCRA_RUNTIME_ENV,用逗号分隔。
对一定需要 key 的供应商(Google、Anthropic、OpenAI、OpenRouter、Groq、Mistral、DeepSeek、xAI、Azure),ocra 在启动前检查,并指出缺少的变量。
执行参数
| 字段 | 默认值 | 含义 |
|---|---|---|
concurrency | 4 | 同时运行的审查任务数(1–32) |
taskTimeoutMinutes | 10 | 单个审查任务的时间上限,最多 35791(约 24.8 天,计时器能保持的最长时间) |
runTimeoutMinutes | 25 | 整次运行的时间上限,最多 35791 |
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 只把温度传给目录标明接受温度的模型(声明的模型都标明了),种子报告为未应用。provenance.sampling 写明实际应用了什么。种子只有在供应商遵守时才能让运行可重复 |
某个任务失败或超时不会导致整次运行失败,它负责的文件会被标记为 failed。
git 及其启动的程序(ssh、凭据助手、代理)只拿到 ocra 环境变量的一部分,永远拿不到模型 key 或平台 token:所有 GIT_* 和 SSH_* 变量、PATH、HOME、XDG_CONFIG_HOME、TMPDIR、代理变量(HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY)、SSL_CERT_FILE、SSL_CERT_DIR、CURL_CA_BUNDLE,以及 Windows 上 git 需要的系统变量(PATHEXT、SYSTEMROOT、TEMP、USERPROFILE、APPDATA 等)。fetch 还会拿到凭据助手读取的变量:GH_*、GLAB_*、GITLAB_*、GCM_*、GITHUB_TOKEN 和 GITHUB_ENTERPRISE_TOKEN。如果你的环境需要给 git 传其他变量(Kerberos、Nix 的证书包),可以通过 git 自身的配置传入,例如 GIT_SSH_COMMAND 或 GIT_CONFIG_*。
文件选择
ocra 会跳过:二进制文件、疑似密钥文件(.env、私钥、证书、云服务和镜像仓库凭据、Terraform 变量和状态文件)、已删除的文件、媒体和压缩包、锁文件、第三方和生成的代码,以及过大的 diff。超过 1 MB 的文件按二进制处理并跳过。名字看起来是文本(.ts、.py 等)却按二进制跳过的文件会给出警告。审查提交区间、单个提交和 PR 时,.gitattributes 从 base 提交读取(git 2.41 及以上),被审查的改动无法把自己的文件标成二进制。数据库迁移文件从不被当作生成代码。
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)就不生效;必须始终生效的限制请在仓库里也写一份。
账户设置
登录 ocra Cloud 后,ocra review 把账户设置放在配置之下。优先级从高到低:命令行参数、配置(仓库的文件或 --config、它 extends 的共享配置、OCRA_* 环境变量)、账户设置、ocra 的默认值。
| 账户中的键 | 如何生效 |
|---|---|
runtime(opencode 或 direct)、models.<tier>、effort.<tier>、reviewers.<id>、roles.<role> | 只补充配置没有写的部分;配置中某个审查员或角色的条目整体优先 |
concurrency、taskTimeoutMinutes、runTimeoutMinutes、maxCostUsd、maxTasks、verify、judge、sampling | 只在配置没有设置时生效(sampling 算一个整体):账户可以给没有上限的运行加上限,但不能放宽限制 |
include | 合并:先是配置中的模式,再是账户的 |
exclude | 只在配置没有设置时生效:账户排除的文件既不审查,也不算作未审查,所以配置里写了 exclude(哪怕是 [])就不再采用账户的 |
rules | 追加在仓库规则和共享规则之后:最多 50 条,格式与 .ocra/rules.json 的条目相同,每条规则最多 2,000 个字符,以同样的方式嵌入提示词 |
每个键都按本文件的 schema 校验;不符合的、或当前版本不认识的键会被忽略,并给出点名它的警告,其余照常生效。模型必须是 ocra-<provider>/<model>,经由 ocra Cloud 使用其中保存的 key。账户永远不能设置 providers、extends、github(botLogin 决定信任谁的评论)或插件:ocra 会忽略并给出警告。
账户设置同样适用于 --pr 和 --mr,位于基准提交的配置之下,从不来自被审查的代码。补充了哪些会打印出来(From your ocra Cloud settings: …),--plan 列出每项设置的来源,provenance.accountSettings.version 记录所用的版本。配置哈希覆盖它和账户规则,因此未登录时哈希不变。连不上 ocra Cloud 时会给出警告,只使用配置。
插件
runtime 选择已注册的运行时:opencode(默认)或 direct(见选择运行时)。plugins 按包名或路径列出额外的插件,pluginSettings.<插件名> 存放各插件的设置。详见插件。