企业官网建设流程全解析

open-code-review（OCR）常见问题排查实战手册：从配置启动到成本与安全

【免费下载链接】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 官方 FAQ（俄文版，pages/src/content/docs/ru/faq.md）为骨架，系统梳理这套基于 Git diff 与 LLM Agent 的混合架构代码审查工具在配置、规则过滤、审查运行、输出集成、成本控制与隐私安全六类场景下的高频问题与解法。读完你将掌握：如何快速定位并修复 LLM 端点解析、规则不生效、工具调用失败等典型故障，如何借助--preview、ocr rules check、ocr viewer等诊断命令精确定位问题根因，以及如何评估 token 成本并优化审查开销。文中所有结论均结合仓库源码（如internal/llm/resolver.go、internal/config/template/task_template.json）给出实现层面的佐证。

配置与启动

no valid LLM endpoint configured

首次运行时最常见的报错：

no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL, ~/.opencodereview/config.json, or ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/ ANTHROPIC_MODEL must be set

这说明 OCR 走完了完整的端点解析链，但没有找到一组完整的(URL, token, model)。从源码看，解析链定义在 internal/llm/resolver.go，按优先级依次尝试四个策略：OCR 配置文件（~/.opencodereview/config.json）→OCR 环境变量（OCR_LLM_*）→Claude Code 环境变量（ANTHROPIC_*）→Shell rc 文件（~/.zshrc/~/.bashrc中的ANTHROPIC_*导出）。任一步骤只要三者齐全（非 AmbientAuth 协议必须同时具备 URL、token、model）就立即采用。

任选一种补齐即可：

• 运行ocr config set llm.url …/ocr config set llm.auth_token …/ocr config set llm.model …，写入~/.opencodereview/config.json，或
• 导出OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL，或
• 若你已经在用 Claude Code，导出ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/ANTHROPIC_MODEL

之后先运行ocr llm test验证连通性，再重新发起审查。ocr llm test的实现见 cmd/opencodereview/llm_cmd.go：它会解析端点、发送一次测试对话并打印Source、URL（或 Bedrock 的 Region/Profile）、Model与✓ Connection test successful。

ocr llm test显示的不是预期的来源

OCR 采用第一组完整配置而非最后一组。因此只要配置文件里llm.*三个键齐全，环境变量就会被忽略——这是ResolveEndpointWithOptions按顺序尝试、命中即返回的设计结果（见 internal/llm/resolver.go）。

要让环境变量优先，删除配置文件中的llm.*键（可删除整个文件或手动清理），或用ocr config set切换到新值。

ocr llm test返回 401 / 403

通常是 token 缺少所需权限、已过期，或选错了供应商。Anthropic 与 OpenAI 的鉴权头和 URL 格式不同，务必保证llm.use_anthropic与实际 URL 匹配：

• Anthropic：URL 以/v1/messages结尾，use_anthropic=true；
• OpenAI / OpenAI 兼容 API：URL 以/v1/chat/completions结尾，use_anthropic=false。

另外注意，从源码看llm.protocol是比use_anthropic优先级更高的规范化协议字段（取值anthropic/anthropic-bedrock/openai/openai-responses），设置时会自动镜像回use_anthropic以保证兼容（见 cmd/opencodereview/config_cmd.go 的setConfigValue）。

not a git repository

ocr review会在当前目录执行git diff（对未跟踪文件还会用git ls-files）。若不在 Git 工作树内，程序直接退出。解决：用cd进入仓库，或显式传--repo /path/to/repo。审查命令对 Git 有硬性依赖，requireGitRepo会调用git rev-parse --git-dir校验目录归属（见 cmd/opencodereview/review_cmd.go）。

"No tool calls parsed"（本地模型 / Ollama）

[ocr] No tool calls parsed for src/foo.go, retrying... [ocr] Max tool requests reached for src/foo.go.

如果每个文件都在No tool calls parsed后反复重试、最终以 "Max tool requests reached" 结束且不产生任何评论，问题在模型而非配置。OCR 完全通过工具调用来驱动审查，因此模型必须原生支持 function calling。只在文本输出（或<think>块）里"描述"调用意图的模型，无论提示词怎么调都无法配合 OCR 工作——典型例子是deepseek-r1；而原生支持工具调用的模型（如qwen3）可以正常工作。选择 Ollama 模型时，优先挑带工具支持标签的模型。

绕过 OCR 直接验证本地模型是否支持工具调用：

curl http://127.0.0.1:11434/v1/chat/completions -H "Content-Type: application/json" -d '{ "model": "qwen3:32b", "messages": [{"role": "user", "content": "The code below has a bug, use the report_bug tool to report it.\n\nfunc add(a, b int) int {\n return a - b\n}"}], "tools": [{"type": "function", "function": {"name": "report_bug", "description": "Report a bug in the code", "parameters": {"type": "object", "properties": {"line": {"type": "integer"}, "description": {"type": "string"}}, "required": ["description"]}}}] }'

成功标志：响应中包含结构化的tool_calls数组且函数名为report_bug；失败标志："调用"只是content里的文本。

若模型支持工具但本地推理慢，可调大 LLM 超时——见下文"超时"说明及 配置文档 的超时小节。默认每个 LLM 请求的 HTTP 超时为 300 秒，可通过providers.<name>.timeout_sec、llm.timeout_sec或环境变量OCR_LLM_TIMEOUT（整数秒，优先级最高）调整；前两个键不支持ocr config set，需直接编辑~/.opencodereview/config.json。

过滤与规则

我的文件没有被审查

运行ocr review --preview（不消耗任何 LLM token）。输出会列出所有候选文件及每个文件被保留/排除的原因：

src/foo.go modified src/foo_test.go modified (excluded: user_exclude) node_modules/lib.js added (excluded: default_path) imgs/logo.png binary (excluded: unsupported_ext)

五种排除原因对应文件过滤的各个闸门（算法位于 internal/agent/preview.go）：

其中deleted并非闸门，而是Preview()中单独计算的（新路径为/dev/null即视为删除）。默认排除列表覆盖各语言测试文件与生成文件，完整清单见 internal/config/allowlist/default_exclude_patterns.json；vendor/、node_modules/、target/等噪音目录的过滤更早，发生在 diff 层面（internal/diff/git.go）。

我的自定义规则不生效

运行ocr rules check <file-path>。该命令会输出走完整个解析链后命中的层级与glob 模式（实现见 cmd/opencodereview/rules_cmd.go）：

File: src/api/UserHandler.go Source: Project (.opencodereview/rule.json) Pattern: src/api/**/*.go Rule: …

如果显示的层级不对（例如显示 "System built-in" 而非期望的项目规则），多半是声明顺序问题：规则链按优先级依次尝试，第一个匹配的模式获胜。把更具体的规则移到rules数组前面，或修正 glob 模式。规则四层优先级从高到低为：--rule参数 > 项目配置<repoDir>/.opencodereview/rule.json> 全局配置~/.opencodereview/rule.json> 内嵌system_rules.json，详见 审查规则文档。

花括号展开不生效

OCR 使用bmatcuk/doublestar/v4支持{ts,tsx}这类展开。若匹配不到，检查是否混入了多余空格：{ts, tsx}带空格的写法不会匹配tsx。*、**、?、[abc]、{a,b,c}等 glob 语法与大小写不敏感匹配的行为，均以 审查规则文档 为准。

审查

文件显示零条评论——它真的被审查了吗？

打开 会话查看器文档（ocr viewer），找到对应会话，查看该文件的main_task轨迹：

• 存在工具调用且以task_done收尾 → 审查正常完成，确实没有发现问题；
• 存在工具调用但循环中断 → 查找对应的错误卡片；
• 完全没有main_task卡片 → 文件在审查前就被过滤掉了，回到上文"过滤与规则"章节排查。

评论显示start_line: 0和end_line: 0

OCR 无法把评论锚定到 diff 的具体行。两个常见原因：

• 模型对existing_code做了改写，而非逐字复制 diff 中的原文。提示词禁止这么做，但模型偶尔违规；
• diff 格式异常（CRLF、制表符与空格混用）破坏了滑动窗口匹配。

这条评论仍然有效，只是没有自动定位。大多数 Agent 集成（SKILL、Claude Code 插件）都会读取existing_code字段自行在文件中定位。

超过 token 阈值

[ocr] WARNING: prompt tokens (94000) exceed 80% of max_tokens(200000) for src/big.sql

文件初始 prompt（规则 + diff + 变更文件列表）在模型应答前就超过了MAX_TOKENS的 80%。OCR 跳过该文件并继续，JSON 模式还会体现在warnings数组中。模板默认值定义在 internal/config/template/task_template.json：ocr review为200000，而ocr scan使用更小的58888（见 internal/config/template/scan_template.json）。

关键认知：MAX_TOKENS只约束输入 prompt，模型输出上限由独立的MAX_COMPLETION_TOKENS = 16384决定，因此调大--max-tokens不会扩大输出预算。可行的解决方案：

• 把自动生成的文件加入exclude；
• 将大型重构拆成小提交；
• 对一串小提交使用--commit模式，而不是一次性审查整个工作区。

计划阶段耗时过长，而文件很小

先执行ocr review --preview。计划阶段在满足任一条件时启动：某文件lines.changed达到PLAN_MODE_LINE_THRESHOLD（默认50），或组内文件数大于 1 且累计变更行数达到PLAN_MODE_GROUP_LINE_THRESHOLD（默认100）。这是预期行为：大 diff 需要预先规划。想单次跳过，就用更小的 diff，或临时修改内嵌模板（面向高级用户，需要覆盖--tools）。两个阈值的判定逻辑见Template.PlanRequired（internal/config/template/template.go）。

"Max tool requests reached"

[ocr] Max tool requests reached for src/foo.go.

模型用满 100 轮（MAX_TOOL_REQUEST_TIMES）工具调用仍未调用task_done。此前已产生的评论仍会被收集和展示。若多数文件都这样，通常属于以下情况之一：

• 模型不遵守"完成后调用task_done"的指令——换更强的模型（例如 Claude Opus）；
• 某工具持续返回错误而模型不断重试——查看会话 JSONL，若同一工具结果反复出现即为此类；
• 文件确实很大或上下文密集，100 轮不够——用--max-tools <n>提高上限（如--max-tools 150）。--max-tools只能向上调整：低于模板上限（100）的值不生效，1–49 会被预先提升到50，0（默认）使用模板上限100。该钳制逻辑见 cmd/opencodereview/shared_flags.go 及对应测试 cmd/opencodereview/flags_test.go；
• 模型根本不支持原生工具调用（本地模型常见）——参见上文 "No tool calls parsed"。

部分子代理失败，但命令返回码是 0

这是刻意设计。OCR 隔离单个文件的错误，避免一个问题文件中断整个 20 文件的审查。只要有任何文件成功处理，最终退出码就是0；只有所有子代理全部失败（整体失败）才返回非零。查看 JSON 模式的warnings数组或文本模式的 stderr，可以看到哪些文件处理失败。相关契约实现在reviewResultError（cmd/opencodereview/review_cmd.go）：完整/部分/跳过均视为成功，只有全部失败才落在非零路径。

CI 中审查比本地慢得多

两个常见原因：

• 模型请求频率限制——被限流时 LLM 客户端会加大间隔并重试。调低--concurrency（例如到4）可避免触碰限额；
• 缓存冷启动——若供应商支持 prompt 缓存，部署后的首次运行享受不到缓存红利，同一时间窗口内的后续运行会更快。

输出与集成

用了--audience agent仍显示进度行

确认这些内容是否来自stderr。进度类消息（警告、错误）有时会输出到 stderr，而--audience agent保证的纯净 stdout 是为了便于解析。要隐藏其余全部输出，重定向即可：ocr review --audience agent 2>/dev/null。

JSON 输出是{ "files_reviewed": 0, "comments": [] }

说明工作区里没有符合条件的文件。这是刻意为之：显式结构让调用方能够区分"无可审查内容"与"审查过但没有评论"。普通的零评论审查返回标准的空数组[]。

会话 JSONL 存在哪里？

~/.opencodereview/sessions/<path-encoded-repo-path>/<session-id>.jsonl

仓库路径经过编码：/和\替换为-，:替换为_（例如/Users/foo/my-repo→Users-foo-my-repo）。编码逻辑见 internal/session/persist.go 的encodeRepoPath。用ocr viewer浏览会话；要清空历史，删除该目录即可，下次运行 OCR 会重新创建编码路径。

性能与成本

如何统计 token 成本？

开启遥测：

ocr config set telemetry.enabled true ocr config set telemetry.exporter console ocr review

LLM 调用不产生独立 span，而是以指标形式记录。关注：

• ocr.llm.tokens_used（计数器，标签model+type）
• ocr.llm.requests_total（计数器，标签model+status）
• ocr.llm.request_duration_seconds（直方图，标签model）

console 导出器会在运行过程中输出这些聚合。要做监控面板，切换到 OTLP 导出器并把数据送入你的指标栈，参见 遥测文档。

为什么我的审查这么贵？

主要的成本杠杆：

• 计划阶段：单文件变更 50 行以上、或多文件组累计 100 行以上会触发，每个组多一次 LLM 调用。调低阈值可降成本，调高则让小型 PR 更快；
• 主循环轮数：默认 2 轮（medium预设）。--effort low保留 1 轮，成本约减半；--effort high（3 轮）发现更多问题但更贵。low/medium/high与 1/2/3 轮的映射见 internal/config/template/effort.go；
• MAX_TOOL_REQUEST_TIMES = 100足够大：每轮都用满的模型会产生更长的对话（消耗更多 token），3 轮内收尾的模型更省；反过来，如果你用--max-tools提高上限来规避报错，每个文件的成本会近似线性增长；
• 记忆压缩本身就是一次 LLM 调用，长任务会额外支付压缩轮次的成本。

如何减少 LLM 调用次数？

• 配置include列表，让 OCR 跳过不必要的文件；
• 用--effort low把主循环压到 1 轮；
• 若账户按峰值负载计费，降低--concurrency；
• 传--background：更完整的上下文有时能让模型不再额外发起file_read/code_search。

隐私与安全

OCR 会把我的代码发出去吗？

OCR 只把你配置的 LLM 端点发送diff（以及工具按需读取的片段）。其他数据不会离开本机：会话 JSONL 与规则文件只存在本地。

若启用了遥测，content_logging参数会穿透配置层，但当前不控制任何代码分支：无论该参数取何值，prompt 和响应内容都不会导出给收集器。请把它视为保留参数，生产环境保持false。详见 遥测文档 的 content logging 一节。对应配置结构见 cmd/opencodereview/config_cmd.go 中的TelemetryConfig（content_logging字段）。

能否在发送 LLM 前隐藏密钥？

没有内置的脱敏功能。推荐流程：

1. 不把密钥提交进仓库（通用规则）；
2. 把确定含密钥的文件加入exclude；
3. 用git diff --no-textconv过滤器或提交前掩码，避免密钥进入 diff。

"掩码规则"功能在规划中，可关注仓库 Issues 跟踪进展。

杂项

变更日志在哪里？

在仓库的 Releases 页面：每个 release 都包含由 Conventional Commits 生成的发布说明。

OCR 支持 Git 之外的其他版本控制系统吗？

不支持。diff 提供方是在外部进程中调用git的。SVN、Mercurial 等需要新的 provider 实现，仓库中已有关于 Hg 支持的议题。

为什么二进制叫opencodereview，而 CLI 叫ocr？

Releases 中发布的静态二进制以项目名命名（opencodereview）；NPM 封装会将其安装为ocr以便使用。从源码构建得到的是dist/opencodereview，把它复制为ocr放到$PATH目录即可。

如何卸载 OCR？

npm uninstall -g @alibaba-group/open-code-review # NPM 安装 sudo rm /usr/local/bin/ocr # 二进制安装 rm -rf ~/.opencodereview # 全部状态

OCR 不会在~/.opencodereview之外写入数据（NPM 下载的二进制除外），因此删除该目录即可清空历史、配置与自定义规则。

参见

• 配置文档 —— LLM 端点解析与全部配置键说明
• 审查规则文档 —— 文件过滤与规则解析链
• 会话查看器文档 —— 回放历史审查会话
• 遥测文档 —— token 用量与 LLM 指标

【免费下载链接】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