OpenCodeReview 使用指南：从模型配置到 Git Diff 代码审查

在日常开发中，代码审查通常发生在提交 Pull Request 之后，但很多问题其实可以在本地提交前就发现。

OpenCodeReview 是一个面向命令行环境的 AI 代码审查工具。它可以直接分析 Git 变更、单个 Commit、分支差异，也可以脱离 Git Diff，对整个项目或指定目录进行扫描。

本文将从首次配置开始，介绍 OpenCodeReview 的常用命令、审查模式、自定义规则、历史会话以及与 Codex 等宿主 Agent 的配合方式。

一、OpenCodeReview 能做什么

安装完成后，可以通过下面的命令查看帮助：

ocr --help

主要命令包括：

命令	作用
`ocr review`	审查 Git Diff、分支差异或单个 Commit
`ocr scan`	扫描完整文件，不依赖 Git Diff
`ocr delegate`	输出审查任务描述，交给宿主 Agent 执行
`ocr rules`	查看和调试代码审查规则
`ocr config`	管理模型、供应商和其他配置
`ocr llm`	测试模型连接、查看供应商
`ocr viewer`	启动 WebUI 会话查看器
`ocr session`	查看历史审查会话
`ocr version`	查看版本信息

OpenCodeReview 最常见的使用场景有三种：

提交代码前，审查当前工作区的修改。
提交 Pull Request 前，审查当前分支相对于主分支的变化。
接手旧项目时，扫描完整目录或整个代码仓库。

二、首次配置

OpenCodeReview 需要连接一个支持工具调用的 LLM。首次使用时，建议通过交互式命令完成配置。

1. 配置模型供应商

ocr config provider

根据提示选择 OpenAI、Anthropic、DeepSeek、DashScope、Kimi，或者配置自定义兼容接口。

2. 选择模型

ocr config model

建议选择具备稳定 Tool Calling 能力的模型。某些仅支持普通文本对话的模型虽然能够返回内容，但可能无法正确执行代码读取和审查流程。

3. 设置输出语言

如果希望代码审查结果使用中文：

ocr config set language 中文

4. 测试连接

ocr llm test

只有在测试通过后，再开始正式代码审查。

OpenCodeReview 的用户级配置通常保存在：

~/.opencodereview/config.json

三、快速开始

进入一个 Git 项目：

cd /path/to/your-project

先预览本次将要审查的文件：

ocr review --preview

--preview 不会调用模型，也不会消耗 Token，适合先确认审查范围。

确认无误后执行：

ocr review

这会审查当前工作区中的代码变更，通常包括：

已暂存的修改；
未暂存的修改；
尚未被 Git 跟踪的新文件。

这是最适合日常提交前检查的命令。

四、使用 `review` 审查 Git 变更

ocr review 主要面向 Git Diff。它不会默认扫描整个项目，而是聚焦于当前修改。

1. 审查当前工作区

ocr review

适用场景：

执行 git commit 之前；
本地完成功能开发之后；
希望快速发现本次改动中的明显问题。

建议先运行：

ocr review --preview

再执行正式审查。

2. 审查当前分支相对于主分支的变化

ocr review --from origin/main --to HEAD

也可以指定本地分支：

ocr review --from main --to feature-branch

适用场景：

创建 Pull Request 或 Merge Request 之前；
检查功能分支引入的全部变化；
避免只审查最后一次 Commit，遗漏此前提交中的问题。

如果远程主分支不是 origin/main，需要根据项目实际情况替换，例如：

ocr review --from origin/master --to HEAD

3. 审查单个 Commit

审查最近一次提交：

ocr review --commit HEAD

审查指定提交：

ocr review --commit abc123

也可以使用简写：

ocr review -c abc123

适用场景：

检查某一次独立提交；
回顾历史提交；
在提交完成后进行补充审查。

4. 添加业务背景

AI 代码审查最常见的问题之一，是模型只看到了代码，却不了解业务目标。

可以通过 --background 参数补充背景：

ocr review \
  --from origin/main \
  --to HEAD \
  --background "这是支付退款功能，重点检查金额精度、重复退款和事务一致性"

简写形式：

ocr review -b "重点检查权限绕过和租户数据隔离"

业务背景越明确，审查结果通常越有针对性。

比较有效的背景信息包括：

本次修改实现了什么需求；
哪些逻辑属于高风险路径；
是否涉及支付、权限、并发或数据迁移；
是否存在必须保持兼容的旧行为；
哪些目录是自动生成代码，不需要重点审查。

5. 控制并发和超时

对于大型变更，可以根据模型供应商的限流情况调整并发：

ocr review \
  --from origin/main \
  --to HEAD \
  --concurrency 4 \
  --timeout 20

如果频繁遇到请求限流、连接中断或响应超时，可以尝试降低并发：

ocr review --concurrency 2

如果单个文件较大、模型响应较慢，则可以适当增加超时时间。

五、使用 `scan` 扫描完整文件

review 只关注 Git 变更，而 scan 会读取完整文件。

适合以下场景：

第一次接手一个项目；
对旧代码进行安全扫描；
检查没有 Git Diff 的目录；
扫描某个模块的整体设计和实现；
审查一次大范围重构后的完整代码。

1. 扫描整个项目

先预览：

ocr scan --preview

正式扫描：

ocr scan

对于大型仓库，不建议一开始直接扫描全部文件。最好先限制目录和 Token 预算。

2. 扫描指定目录

ocr scan --path src

扫描多个目录或文件：

ocr scan --path src,internal,cmd/main.go

例如，只扫描后端接口和业务层：

ocr scan --path internal/api,internal/service

3. 排除生成文件

ocr scan \
  --path src,internal \
  --exclude "**/generated/**,**/*.min.js"

常见的排除对象包括：

node_modules
vendor
dist
build
coverage
generated
*.min.js
*.map
自动生成的 API 客户端
数据库迁移生成文件

4. 限制 Token 消耗

ocr scan \
  --path src,internal \
  --max-tokens-budget 100000

在扫描大型仓库时，建议同时使用：

ocr scan \
  --path src,internal \
  --exclude "**/generated/**,**/*.min.js" \
  --max-tokens-budget 100000 \
  --preview

先查看预计扫描范围，再决定是否执行正式扫描。

六、配置 OpenAI API

如果使用 OpenAI API，可以先通过环境变量设置密钥：

export OPENAI_API_KEY="你的 API Key"

然后配置供应商和模型：

ocr config set provider openai
ocr config set model "你的模型 ID"
ocr config set language 中文

最后测试：

ocr llm test

为了避免把密钥直接写入配置文件，优先使用环境变量。

在 Zsh 中长期生效，可以写入：

echo 'export OPENAI_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

在 Bash 中可以写入：

echo 'export OPENAI_API_KEY="你的 API Key"' >> ~/.bashrc
source ~/.bashrc

七、配置第三方 OpenAI 兼容 API

如果使用第三方 OpenAI 兼容接口，可以创建一个自定义 Provider。

假设接口地址为：

https://api.example.com/v1

配置示例：

ocr config set provider my-api

ocr config set custom_providers.my-api.url \
  "https://api.example.com/v1"

ocr config set custom_providers.my-api.protocol \
  openai

ocr config set custom_providers.my-api.model \
  "你的模型 ID"

ocr config set custom_providers.my-api.api_key \
  "你的 API Key"

ocr config set language 中文

测试连接：

ocr llm test

其中：

my-api 是自定义 Provider 名称，可以自行修改；
url 是兼容接口地址；
protocol 通常设置为 openai；
model 必须填写供应商实际支持的模型 ID；
模型需要具备稳定的工具调用能力。

如果接口兼容 Anthropic 协议，也可以将协议设置为：

ocr config set custom_providers.my-api.protocol anthropic

八、连接本地 Ollama

如果希望使用本地模型，可以让 Ollama 暴露 OpenAI 兼容接口。

配置示例：

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"

然后测试：

ocr llm test

这里的 api_key 可以是占位值，因为本地 Ollama 通常不会验证该字段。

需要注意的是，本地模型能否正常完成审查，主要取决于：

是否支持 Tool Calling；
是否能稳定遵循工具调用格式；
上下文窗口是否足够大；
模型是否具备较好的代码理解能力；
本机内存和显存是否足够。

如果测试能够通过，但正式审查经常出现工具调用解析失败，通常说明模型或兼容接口对 Tool Calling 的支持不完整。

九、自定义代码审查规则

OpenCodeReview 支持在项目中定义审查规则。

在仓库根目录创建：

.opencodereview/rule.json

示例：

{
  "exclude": [
    "**/generated/**",
    "**/*.min.js"
  ],
  "rules": [
    {
      "path": "src/api/**/*.go",
      "rule": "重点检查参数校验、权限控制、事务边界和错误信息泄露。"
    },
    {
      "path": "src/**/*.{ts,tsx}",
      "rule": "重点检查未处理的 Promise、XSS、状态竞争和空值访问。"
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "重点检查 SQL 注入、参数绑定错误、全表更新和缺少查询条件。"
    }
  ]
}

规则文件适合用来固化团队规范，例如：

API 层必须检查身份认证和权限；
数据库操作必须关注事务边界；
支付代码必须检查金额精度和幂等性；
前端代码必须检查 XSS 和未处理 Promise；
多租户系统必须检查租户数据隔离；
SQL 更新和删除语句必须带条件；
日志中不得输出密码、Token 或身份证号等敏感数据。

检查规则匹配结果

ocr rules check src/api/user_handler.go

该命令可以帮助确认某个文件最终匹配了哪条规则。

在规则较多时，建议经常使用它进行调试，避免路径表达式写错，导致规则没有生效。

十、输出 JSON 结果

如果希望把审查结果交给其他脚本、CI 流程或 Agent 处理，可以输出 JSON：

ocr review \
  --from origin/main \
  --to HEAD \
  --format json \
  --audience agent \
  > review-result.json

JSON 输出适合以下用途：

在 CI 中根据审查结果决定是否继续；
将问题同步到 GitHub、GitLab 或内部平台；
交给其他 Agent 自动修复；
生成统一格式的代码质量报告；
对审查结果做统计和归档。

十一、查看历史会话

OpenCodeReview 会保存代码审查会话。

查看会话列表：

ocr session list

查看指定会话：

ocr session show <session-id>

启动 WebUI：

ocr viewer

然后在浏览器中打开：

http://localhost:5483

WebUI 更适合查看较长的审查结果、历史记录和不同文件中的问题。

十二、恢复中断的审查

如果分支审查或 Commit 审查中途失败，可以尝试恢复已有会话：

ocr session list

找到 Session ID 后执行：

ocr review \
  --from origin/main \
  --to HEAD \
  --resume <session-id>

恢复功能适合文件较多、审查时间较长的任务。

在重新执行前，最好确认：

当前代码没有发生大范围变化；
使用的分支范围与原会话一致；
模型和 Provider 配置没有被更换。

十三、委托给 Codex 或其他宿主 Agent

除了让 OpenCodeReview 直接调用 LLM，还可以使用 delegate 模式。

ocr delegate preview --from origin/main --to HEAD

或者为指定文件生成审查任务：

ocr delegate rule src/main.go src/handler.go

在这种模式下：

OpenCodeReview 负责识别文件、Diff 和审查规则；
Codex、Claude Code 或其他宿主 Agent 负责真正阅读代码；
OpenCodeReview 本身不一定需要单独配置 LLM。

这种方式适合已经在使用 AI 编程 Agent 的用户，可以减少重复配置模型供应商。

十四、推荐的日常使用流程

提交代码前

git status
ocr review --preview
ocr review -b "说明本次修改的目标和重点风险"

确认问题后修改代码，再运行测试：

npm test

或：

go test ./...

最后提交：

git add .
git commit

创建 Pull Request 前

git fetch origin

ocr review \
  --from origin/main \
  --to HEAD \
  --background "说明需求、兼容要求、关键业务风险"

如果修改范围较大，可以先降低并发：

ocr review \
  --from origin/main \
  --to HEAD \
  --concurrency 4

接手旧项目时

不要一开始直接扫描整个仓库。建议分模块进行：

ocr scan --path src/auth --preview
ocr scan --path src/auth

然后继续扫描：

ocr scan --path src/payment
ocr scan --path src/api
ocr scan --path src/database

这种方式比一次扫描整个项目更容易控制成本，也更方便分析结果。

十五、常见问题

1. `ocr llm test` 失败

优先检查：

ocr config

然后确认：

API Key 是否正确；
Base URL 是否包含正确的 /v1 路径；
模型 ID 是否真实存在；
Provider 协议是否设置正确；
网络是否可以访问模型接口；
第三方接口是否完整支持 Tool Calling。

2. 出现工具调用解析错误

常见原因是模型不支持原生工具调用，或者第三方兼容接口只实现了普通聊天接口。

可以尝试：

更换明确支持 Tool Calling 的模型；
更换 Provider；
使用官方接口进行对比测试；
检查代理或中转接口是否修改了响应格式；
使用 ocr llm test 验证基础连接。

3. 审查结果过于泛泛

可以增加业务背景：

ocr review -b "这是多租户权限模块，重点检查越权访问、租户 ID 透传和管理员权限边界"

也可以创建项目规则文件：

.opencodereview/rule.json

AI 审查效果通常取决于上下文质量。只提供代码，不提供业务目标，模型往往只能给出通用建议。

4. Token 消耗太高

可以采用以下方法：

使用 --preview 先确认文件范围；
使用 scan --path 限制目录；
排除生成代码和依赖目录；
使用 --max-tokens-budget；
只审查当前分支相对于主分支的变化；
避免重复扫描没有修改的完整文件；
将大型项目拆成多个模块分别审查。

5. 请求频繁被限流

降低并发：

ocr review --concurrency 2

或者缩小审查范围：

ocr scan --path src/payment

如果使用第三方 API，还需要检查供应商的 RPM、TPM 和并发限制。

十六、命令速查表

# 查看帮助
ocr --help

# 配置供应商
ocr config provider

# 选择模型
ocr config model

# 设置中文输出
ocr config set language 中文

# 测试模型
ocr llm test

# 预览当前工作区审查范围
ocr review --preview

# 审查当前工作区
ocr review

# 审查分支差异
ocr review --from origin/main --to HEAD

# 审查单个 Commit
ocr review --commit HEAD

# 添加业务背景
ocr review -b "重点检查权限和数据一致性"

# 扫描整个项目
ocr scan

# 扫描指定目录
ocr scan --path src

# 扫描多个目录
ocr scan --path src,internal,cmd

# 排除生成文件
ocr scan --exclude "**/generated/**,**/*.min.js"

# 查看规则匹配
ocr rules check src/api/user_handler.go

# 查看历史会话
ocr session list

# 查看指定会话
ocr session show <session-id>

# 启动 WebUI
ocr viewer

# 查看版本
ocr version

十七、总结

OpenCodeReview 最有价值的地方，不是代替人工 Code Review，而是把代码审查提前到本地开发阶段。

对于个人开发者，可以在提交代码前快速检查本次修改；对于团队，可以通过 .opencodereview/rule.json 固化权限、安全、数据库和业务规则；对于大型项目，则可以结合 review、scan、JSON 输出和历史会话，建立更完整的自动化审查流程。

日常使用时，记住下面几个命令基本就够了：

ocr review --preview
ocr review -b "说明本次修改的目标和风险"
ocr review --from origin/main --to HEAD
ocr scan --path src
ocr viewer

建议始终把 AI 审查作为补充手段。涉及支付、权限、安全、并发、数据迁移和基础设施配置的修改，仍然需要人工复核、自动化测试和实际运行验证。

项目地址

GitHub：

https://github.com/alibaba/open-code-review

技术小站