open-code-review 快速上手：从安装到第一次 AI 代码审查（ocr CLI 完整指南）

open-code-review 快速上手：从安装到第一次 AI 代码审查（ocr CLI 完整指南）

【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibaba's scale. Hybrid architecture code review tool: deterministic pipelines + LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI & Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review

本指南以 open-code-review 的日本语版《クイックスタート》文档为主体，讲解如何用ocrCLI 在几分钟内完成第一次 AI 代码审查：从安装二进制、配置 LLM Provider、验证连通性，到以三种 diff 模式运行ocr review，并输出适合 CI 与 Agent 消费的 JSON 结果。读完本文，你将掌握ocr config provider、ocr config set、ocr llm test、ocr review --preview等核心命令的完整用法，并理解它们背后的源码实现。

open-code-review 是一款"确定性工程流水线 + LLM Agent"混合架构的代码审查工具：文件选择、规则解析、diff 分组由确定性代码完成，而逐文件审查、定位问题由 LLM 驱动，最终产出精确到行号的评审意见。下面的步骤在几分钟内即可走通全流程。

前提条件

开始之前请确认环境满足：

• Git ≥ 2.41：ocr review依赖 git 命令解析 diff 与 ref（源码见 internal/diff/git.go、internal/gitcmd/runner.go）；
• Node.js ≥ 18：通过 npm 安装 CLI 时需要；
• LLM API key：使用普通模式必须准备；如果采用委任模式（例如在 Claude Code 内部运行），由宿主 Agent 提供模型，则不需要 API key，可以直接跳到步骤 4。

步骤 1 —— 安装 CLI

推荐通过 npm 全局安装：

npm install -g @alibaba-group/open-code-review

安装完成后验证版本：

ocr version

ocr version会输出版本号、Git commit（如有）、平台（<GOOS>/<GOARCH>）与构建日期。如果输出 "command not found"，请确认安装目录位于$PATH中（which ocr/echo $PATH）。

除 npm 外，官方还提供 Homebrew、MacPorts、curl | sh安装脚本、GitHub Release 静态二进制、源码构建等共 6 种安装方式，完整说明见安装文档。其中 npm 安装的ocr默认会每约 18 分钟在后台检查一次更新并自动升级，可通过OCR_NO_UPDATE=1关闭，或用OCR_UPDATE_INTERVAL（分钟）调整检查间隔。

步骤 2 —— 配置 LLM

若使用委任模式（如 Claude Code 内运行），模型由宿主 Agent 提供，可跳过本步骤直接到步骤 4。

交互式配置（推荐）

ocr config provider

该命令启动交互式 TUI：选择内置或自定义 provider → 输入 API key → 选择模型 → 自动保存到配置文件，随后立即执行一次ocr llm test验证端点。对应命令实现见 cmd/opencodereview/config_cmd.go 中的configProviderCmd（交互式 TUI 代码在 provider_tui.go）。

之后想切换模型时运行：

ocr config model

非交互式配置（CI / 无 TUI 环境）

在 CI 或没有 TUI 的环境中，用ocr config set直接写入同一份配置（持久化到~/.opencodereview/config.json）：

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

配置键支持点号路径。写入时runConfigSet会按 key 校验并落盘，涉及敏感字段（如api_key、auth_token）时回显会被打码（shouldMaskConfigValue，见 config_cmd.go）。ocr config set provider <name>还会自动在providers.<name>下创建条目；切换 provider 时会清空旧 model，避免跨厂残留（setConfigValue的case "provider"分支）。其余常用键包括max_tokens、effort、language、telemetry.enabled、mcp_servers.<name>.<field>等，完整清单见 configuration.md。

内置 provider 一览

ocr config provider可直接选择的内置 provider 在 internal/llm/providers.go 的 registry 中定义，Base URL 与协议已预置，选择后只需填 API key。providers.<name>.api_key未设置时会自动回退到对应环境变量。部分内置 provider 如下：

可用ocr llm providers列出全部内置 provider（名称、协议、Base URL 三列表格，见 llm_cmd.go 的runLLMProviders）。

自定义 provider 与委任模式

表中没有的名字都视为自定义 provider，至少需要指定url与protocol（protocol可取anthropic、openai、openai-responses、anthropic-bedrock）：

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"

值得留意的是，config set对 URL 会做合法性校验（validateBaseURL），协议会用NormalizeProtocol/ValidateProtocol规范化并拒绝非法值（如将llm.protocol设为anthropic-bedrock会被明确拒绝，因为 bedrock 无 URL/Token 概念，见 config_cmd.go）。

如果你使用 Claude Code、Codex、Cursor 等订阅制 AI 编程 Agent，可以完全不配置 LLM：委任模式下ocr只负责确定性的文件筛选与规则解析，审查推理交给宿主 Agent 完成。具体做法见委任模式文档。

步骤 3 —— 测试连通性

ocr llm test

该命令以与ocr review完全相同的方式解析 LLM 端点（源码见 llm_cmd.go 的runLLMTest），从 internal/config/testconnection/task.json 加载预置测试对话并发送，随后输出：

Source: <解析所用的配置来源> URL: <端点 URL> Model: <生效的模型> <模型的回复> ✓ Connection test successful

对于 bedrock provider，由于没有配置 URL（host 由 region 决定），输出会显示 Region 与 Profile 而非 URL。该测试请求超时上限默认 30 秒。

常见错误排查：

• no valid LLM endpoint configured—— 端点未完全配置，回头检查步骤 2 的配置；
• 401 / 403—— token 错误或已过期，重新获取 API key 并写入；
• 其他非零退出 —— 网络、认证或模型名错误，错误消息会指明具体是哪一类。

步骤 4 —— 运行第一次审查

进入任意 Git 仓库，直接执行：

cd path/to/your-repo # 工作区模式 —— 审查 staged + unstaged + untracked 的改动（默认） ocr review # 分支区间 —— 审查 feature-branch 自 main 分叉以来的改动（merge-base 模式） ocr review --from main --to feature-branch # 单个 commit —— 审查该 commit 引入的 diff ocr review --commit abc123

三种模式的含义（对应 review_cmd.go 的reviewModeFromOptions）：

• 工作区模式：git diff HEAD取已跟踪改动（为空则回退git diff --staged），git ls-files --others --exclude-standard取未跟踪文件并按整文件新增处理——这正是提交前想审查的内容；
• 区间模式：计算merge-base(main, feature-branch)..feature-branch，只审查 feature 分支引入的 diff，不含 main 上后来进入的其他改动；
• Commit 模式：审查git show <commit>产生的 diff。

ocr review的完整参数（并发数调优、输出格式、audience 模式、背景上下文等）以及其余全部子命令，见 CLI 参考。核心参数速览：

先看看会审查什么：--preview

不调用 LLM，先跑一遍过滤流水线，列出将审查/被排除的文件及排除原因：

ocr review --preview # 工作区 ocr review -c abc123 --preview # commit

--preview不构建任何审查运行时（不建 session、不写 manifest），只是加载 diff 并应用过滤算法，逐文件输出WillReview与ExcludeReason（二进制、扩展名不允许、默认排除路径、用户规则排除等，实现见 internal/agent/preview.go 的whyExcluded）。--format json同样适用，方便脚本化。

面向系统的 JSON 输出

--audience agent会完全抑制人类可读的进度 UI，使 stdout 只剩 JSON / 最终摘要——这正是上游 Agent 或 CI 脚本所需要的：

ocr review --format json --audience agent > review.json

输出结构示例：

{ "status": "success", "llm": { "provider": "anthropic", "model": "claude-opus-4-6" }, "summary": { "files_reviewed": 9, "comments": 1, "total_tokens": 21344, "input_tokens": 18012, "output_tokens": 3332, "elapsed": "1m12s" }, "comments": [ { "path": "src/foo.go", "content": "Concurrent map access without a lock — wrap with sync.RWMutex.", "start_line": 42, "end_line": 47, "existing_code": "m[k] = v", "suggestion_code": "mu.Lock(); defer mu.Unlock(); m[k] = v" } ] }

顶层字段说明：status为success/completed_with_warnings/completed_with_errors/skipped；summary含 token 用量与耗时；comments始终存在（可为空）；warnings在个别子 Agent 失败时出现；session_id用于中断后--resume续跑。没有可审查文件时 JSON 模式输出status: "skipped"，让调用方区分"无改动"与"未发现问题"。注意--audience agent并不隐含--format json——两者控制不同维度（UI 抑制 vs 结构化输出），需要时组合使用。

深入：一次 review 背后发生了什么

了解内部流程有助于正确使用参数（见 cmd/opencodereview/review_cmd.go 的executeReviewContext）：

1. 解析输出与 diff：解析--from/--to/--commit三种模式，加载规则、工具配置与 git 运行器；
2. 安全校验：validateReviewRefs拒绝以-开头的 ref，防止选项注入（#112）；
3. 可选 preview：--preview在此返回，不调用 LLM；
4. 解析 LLM 端点：loadLLMRuntime结合--provider/--model与配置文件解析出最终端点，随后解析max_tokens与effort；
5. 构建 Agent：为每个文件/文件组创建子 Agent，配置文件读取、代码搜索、评论收集等工具（buildToolRegistry），可选挂载 MCP 服务器工具；
6. 运行与产出：ag.Run执行审查，冻结重试报告（RetryCollector.Freeze），最后按--format/--audience输出结果；失败时 stderr 给出 Session ID，可用--resume续跑。

后续学习路径

• 安装 —— 全部安装方式与 OCR 状态目录（~/.opencodereview/）；
• 配置 —— 全部环境变量、config key 与内置 provider 的详细说明；
• CLI 参考 —— 每个子命令、参数与输出模式；
• 评审规则 —— 定制审查内容与规则解析链；
• 集成 —— 将 OCR 嵌入 Claude Code、Agent Skill 或 CI 流水线；
• FAQ —— 已知错误与对策。

【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibaba's scale. Hybrid architecture code review tool: deterministic pipelines + LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI & Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review