第 2 章 · 01 配置

第 2 章 · 01 配置

本节摘要:配置是 OCR 用稳的前提。本节讲透三件事:一是配置文件 ~/.opencodereview/config.json 的三种编辑方式(交互式 TUI、ocr config set 命令、手动编辑);二是如何选 provider——OCR 内置 14 个 provider,选中即用,也支持自定义 provider 接 Ollama / 内部网关;三是评审语言、超时、厂商专属字段等进阶项。读完你能把 LLM 端点、模型、语言调成自己想要的形态,并为第 5 章的 CI 集成打下基础。

内容来源:原项目中文文档 pages/src/content/docs/zh/configuration.md,套用体系化模板改写。

学习目标

阅读完本节,你应当能够:

1. 说明配置文件的三种编辑方式及各自适用场景。
2. 从 14 个内置 provider 中选出适合自己的一家并配置。
3. 用自定义 provider 接入 Ollama / 内部网关 / CC-Switch 等场景。
4. 调整 HTTP 超时与评审语言。
5. 通过 extra_body 发送厂商专属字段(如关闭 thinking-mode)。
6. 用 ocr llm test 验证配置并解读常见错误。

一、配置文件与三种编辑方式

配置文件统一位于 ~/.opencodereview/config.json,你有三种方式编辑它:

┌─────────────────────────────────────────────────────────────────┐
│  交互式 TUI  —— ocr config provider / ocr config model          │
│                  带引导菜单,适合首次/换模型                       │
│  命令行      —— ocr config set <key> <value>                    │
│                  适合脚本与 CI,可复现                              │
│  手动编辑    —— 直接改 JSON(不推荐)                              │
│                  下次 ocr config set 会重新格式化                 │
└─────────────────────────────────────────────────────────────────┘
​

💡 建议:本地首次配置用交互式 TUI 一步到位;CI 或要版本化团队配置时用 ocr config set 写成脚本;手动编辑只在调 timeout_sec 这类 set 不支持的 key 时才用。

二、配置模型(交互式推荐)

交互式设置

ocr config provider
​

它会让你:选择一个内置或自定义 provider → 填入 API key → 挑选 model → 保存到配置文件 → 自动运行一次 ocr llm test 验证端点。

之后想换模型:

ocr config model
​

非交互式设置(CI / 无 TUI 环境)

用 ocr config set 写入同一份配置:

ocr config set provider                    anthropic
ocr config set model                       claude-opus-4-6
ocr config set providers.anthropic.api_key sk-ant-xxxxxxxxxx
​

⚠️ 注意:CI 环境没有终端交互,ocr config set 让你用一行行命令把配置写死,这对第 5 章的 GitHub Actions / GitLab CI 集成至关重要。

三、内置 provider

下列 provider 随 OCR 发布,已预置 Base URL 与协议,选中后只需填 API key。若 providers.<name>.api_key 未设置,会自动回退到对应的环境变量。

四、自定义 provider

任何不在上表中的 provider 名都视为自定义,至少要提供 url 和 protocol(protocol 取 anthropic 或 openai):

ocr config set provider                             my-gateway
ocr config set custom_providers.my-gateway.url      https://gateway.internal.com/v1
ocr config set custom_providers.my-gateway.protocol openai
ocr config set custom_providers.my-gateway.model    llama-3-70b
ocr config set custom_providers.my-gateway.api_key  "$MY_API_KEY"
​

示例:用 Ollama 跑本地模型

用 Ollama 跑本地模型,就是一个指向本地 OpenAI 兼容端点的自定义 provider:

ocr config set provider                          ollama
ocr config set custom_providers.ollama.url       http://127.0.0.1:11434/v1
ocr config set custom_providers.ollama.protocol  openai
ocr config set custom_providers.ollama.model     qwen3:32b
ocr config set custom_providers.ollama.api_key   ollama
​

⚠️ 注意:Ollama 会忽略 API key,但自定义 provider 要求非空的 api_key(自定义 provider 没有环境变量回退),所以设任意占位值即可。模型本身必须支持原生工具调用——选型前请先看第 6 章 FAQ 中的「No tool calls parsed(本地模型 / Ollama)」一节。

五、超时

每个 LLM 请求都有 HTTP 超时,默认 300 秒。慢的本地模型(或大文件)可能需要更长的时间。三个配置项,作用域递增:

• providers.<name>.timeout_sec / custom_providers.<name>.timeout_sec——per-provider,单位秒。
• llm.timeout_sec——用于旧版 llm 配置段,单位秒。
• OCR_LLM_TIMEOUT 环境变量——整数秒;对每条解析路径都覆盖配置文件里的值。

ocr config set 不支持 timeout_sec key——直接编辑 ~/.opencodereview/config.json:

{
  "custom_providers": {
    "ollama": { "url": "http://127.0.0.1:11434/v1", "protocol": "openai", "timeout_sec": 900 }
  }
}
​

六、复用已有环境变量

如果你已经配好了 Claude Code 的 ANTHROPIC_*,或 OCR 自己的 OCR_LLM_* 环境变量,OCR 会自动识别,无需再写配置文件。端点解析的优先级链见第 6 章 FAQ。

七、使用 CC-Switch

如果你使用 CC-Switch 并开启了路由服务,可以将供应商的 url 配置成 CC-Switch 启动的代理地址,无需额外配置:

# Claude(Anthropic 兼容)
ocr config set providers.anthropic.url http://127.0.0.1:15721

# Codex / OpenAI 兼容 —— 将该供应商的 url 键设为代理地址
ocr config set providers.<name>.url http://127.0.0.1:15721/v1
​

api_key 可设置为任意值。extra_body(及其他按供应商字段)依然生效。

八、发送厂商专属字段

某些 provider 需要非标准的请求字段(如 Bedrock 风格的 thinking)。用 extra_body(合并进每次请求)即可发送,无需改源码:

ocr config set providers.anthropic.extra_body '{"thinking":{"type":"disabled"}}'
​

💡 技巧:在 CI 流水线里常会关掉 thinking-mode 以兼容不支持该字段的 provider——详见第 5 章 CI/CD 集成中各配方的说明。

九、配置评审语言

language 决定评审评论用哪种语言输出,未设置时默认英文:

ocr config set language 中文
ocr config set language English
​

十、验证连通性

无论用哪种方式配置,最后都用一条命令验证:

ocr llm test
​

它会打印解析出的来源、端点 URL、生效模型与模型回复,最后给出 ✓ Connection test successful 或具体错误。常见错误:

• no valid LLM endpoint configured → 端点三元组 (URL, token, model) 不完整,见第 6 章 FAQ。
• 401 / 403 → token 缺 scope、过期或厂商不匹配(Anthropic vs OpenAI 的 auth header 与 URL 格式不同)。

💡 技巧:ocr llm test 取第一个完整三元组,而非最后一个。若配置文件已有全部三个 llm.* key,环境变量会被忽略。要让环境变量生效,先删除配置 key。

本节要点回顾

1. 三方式:交互式 TUI(首次)、ocr config set(CI/脚本)、手动编辑(仅 timeout_sec 等)。
2. 内置 provider:14 家已预置 URL/协议,无 key 时自动回退环境变量。
3. 自定义 provider:需手填 url + protocol + 非空 api_key;Ollama 是典型用例。
4. 超时:默认 300 秒,providers.*.timeout_sec / llm.timeout_sec / OCR_LLM_TIMEOUT 三级。
5. 环境变量复用:ANTHROPIC_* / OCR_LLM_* 会被自动识别,无需重复配置。
6. 厂商字段:extra_body 合并进每次请求,如关 thinking-mode。
7. 语言:ocr config set language 中文 切换评审评论语言。
8. 验证:ocr llm test 是配置后必跑的一步,解析来源一目了然。

配置讲透了。下一节进入 CLI 参考,把 ocr 的每个子命令、参数与退出行为逐一列清,让你知道每条命令背后对应哪些配置 key。